SecondaryConfig (Oracle - Berkeley DB Java API)
Date: 2020-06-01

Package com.sleepycat.db

## Class SecondaryConfig

- java.lang.Object
- - com.sleepycat.db.DatabaseConfig
  - - com.sleepycat.db.SecondaryConfig

- All Implemented Interfaces:
    `java.lang.Cloneable`

      public class SecondaryConfig
      extends DatabaseConfig
      implements java.lang.Cloneable

  The configuration properties of a `SecondaryDatabase` extend those of a primary `Database`. The secondary database configuration is specified when calling `Environment.openSecondaryDatabase`.

  To create a configuration object with default attributes:

          SecondaryConfig config = new SecondaryConfig();

  To set custom attributes:

          SecondaryConfig config = new SecondaryConfig();
          config.setAllowCreate(true);
          config.setSortedDuplicates(true);
          config.setKeyCreator(new MyKeyCreator());

  NOTE: There are two situations where the use of secondary databases without transactions requires special consideration. When using a transactional database or when doing read operations only, this note does not apply.

  - If secondary is configured to not allow duplicates, when the secondary is being updated it is possible that an error will occur when the secondary key value in a record being added is already present in the database. A `DatabaseException` will be thrown in this situation.
  - If a foreign key constraint is configured with the delete action `ABORT` (the default setting), a `DatabaseException` will be thrown if an attempt is made to delete a referenced foreign key.
  In both cases, the operation will be partially complete because the primary database record will have already been updated or deleted. In the presence of transactions, the exception will cause the transaction to abort. Without transactions, it is the responsibility of the caller to handle the results of the incomplete update or to take steps to prevent this situation from happening in the first place.

  See Also:
    `Environment.openSecondaryDatabase`, `SecondaryDatabase`

- - ### Field Summary

    Fields
    Modifier and Type | Field | Description
    --- | --- | ---
    `static SecondaryConfig` | `DEFAULT` |

  - ### Constructor Summary

    Constructors
    Constructor | Description
    --- | ---
    `SecondaryConfig()` | Creates an instance with the system's default settings.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method | Description
    --- | --- | ---
    `boolean` | `getAllowPopulate()` | Returns whether automatic population of the secondary is allowed.
    `com.sleepycat.db.internal.Db` | `getForeignKeyDatabase()` | Returns the database used to check the foreign key integrity constraint, or null if no foreign key constraint will be checked.
    `ForeignKeyDeleteAction` | `getForeignKeyDeleteAction()` | Returns the action taken when a referenced record in the foreign key database is deleted.
    `ForeignKeyNullifier` | `getForeignKeyNullifier()` | Returns the user-supplied object used for setting single-valued foreign keys to null.
    `ForeignMultiKeyNullifier` | `getForeignMultiKeyNullifier()` | Returns the user-supplied object used for setting multi-valued foreign keys to null.
    `boolean` | `getImmutableSecondaryKey()` | Returns whether the secondary key is immutable.
    `SecondaryKeyCreator` | `getKeyCreator()` | Returns the user-supplied object used for creating single-valued secondary keys.
    `SecondaryMultiKeyCreator` | `getMultiKeyCreator()` | Returns the user-supplied object used for creating multi-valued secondary keys.
    `void` | `setAllowPopulate​(boolean allowPopulate)` | Specifies whether automatic population of the secondary is allowed.
    `void` | `setForeignKeyDatabase​(Database foreignDb)` | Defines a foreign key integrity constraint for a given foreign key database.
    `void` | `setForeignKeyDeleteAction​(ForeignKeyDeleteAction action)` | Specifies the action taken when a referenced record in the foreign key database is deleted.
    `void` | `setForeignKeyNullifier​(ForeignKeyNullifier keyNullifier)` | Specifies the user-supplied object used for setting single-valued foreign keys to null.
    `void` | `setForeignMultiKeyNullifier​(ForeignMultiKeyNullifier multiKeyNullifier)` | Specifies the user-supplied object used for setting multi-valued foreign keys to null.
    `void` | `setImmutableSecondaryKey​(boolean immutableSecondaryKey)` | Specifies whether the secondary key is immutable.
    `void` | `setKeyCreator​(SecondaryKeyCreator keyCreator)` | Specifies the user-supplied object used for creating single-valued secondary keys.
    `void` | `setMultiKeyCreator​(SecondaryMultiKeyCreator multiKeyCreator)` | Specifies the user-supplied object used for creating multi-valued secondary keys.

    - ### Methods inherited from class com.sleepycat.db.DatabaseConfig

      `cloneConfig, enableEncrypted, getAllowCreate, getBlobDir, getBlobThreshold, getBtreeComparator, getBtreeCompressor, getBtreeMinKey, getBtreePrefixCalculator, getBtreeRecordNumbers, getByteOrder, getByteSwapped, getCacheCount, getCacheSize, getChecksum, getCreateDir, getDirtyRead, getDuplicateComparator, getEncrypted, getErrorHandler, getErrorPrefix, getErrorStream, getExclusiveCreate, getExternalFileDir, getExternalFileThreshold, getFeedbackHandler, getHashComparator, getHasher, getHashFillFactor, getHashNumElements, getHeapRegionSize, getHeapsize, getMessageHandler, getMessagePrefix, getMessageStream, getMode, getMultiversion, getNoMMap, getNoWaitDbExclusiveLock, getPageSize, getPanicHandler, getPartitionDirs, getPartitionHandler, getPartitionKeys, getPartitionParts, getPassword, getPriority, getQueueExtentSize, getQueueInOrder, getReadOnly, getReadUncommitted, getRecordDelimiter, getRecordLength, getRecordNumberAppender, getRecordPad, getRecordSource, getRenumbering, getReverseSplitOff, getSliceCallback, getSliced, getSnapshot, getSortedDuplicates, getTransactional, getTransactionNotDurable, getTruncate, getType, getUnsortedDuplicates, setAllowCreate, setBlobDir, setBlobThreshold, setBtreeComparator, setBtreeCompressor, setBtreeMinKey, setBtreePrefixCalculator, setBtreeRecordNumbers, setByteOrder, setCacheCount, setCacheSize, setChecksum, setCreateDir, setDirtyRead, setDuplicateComparator, setEncrypted, setErrorHandler, setErrorPrefix, setErrorStream, setExclusiveCreate, setExternalFileDir, setExternalFileThreshold, setFeedbackHandler, setHashComparator, setHasher, setHashFillFactor, setHashNumElements, setHeapRegionSize, setHeapsize, setMessageHandler, setMessagePrefix, setMessageStream, setMode, setMsgfile, setMultiversion, setNoMMap, setNoWaitDbExclusiveLock, setPageSize, setPanicHandler, setPartitionByCallback, setPartitionByRange, setPartitionDirs, setPriority, setQueueExtentSize, setQueueInOrder, setReadOnly, setReadUncommitted, setRecordDelimiter, setRecordLength, setRecordNumberAppender, setRecordPad, setRecordSource, setRenumbering, setReverseSplitOff, setSliceCallback, setSliced, setSnapshot, setSortedDuplicates, setTransactional, setTransactionNotDurable, setTruncate, setType, setUnsortedDuplicates`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### DEFAULT

          public static final SecondaryConfig DEFAULT

  - ### Constructor Detail

    - #### SecondaryConfig

          public SecondaryConfig()

      Creates an instance with the system's default settings.

  - ### Method Detail

    - #### setAllowPopulate

          public void setAllowPopulate​(boolean allowPopulate)

      Specifies whether automatic population of the secondary is allowed.

      If automatic population is allowed, when the secondary database is opened it is checked to see if it is empty. If it is empty, the primary database is read in its entirety and keys are added to the secondary database using the information read from the primary.

      If this property is set to true and the database is transactional, the population of the secondary will be done within the explicit or auto-commit transaction that is used to open the database.

      Parameters:
        `allowPopulate` - whether automatic population of the secondary is allowed.

    - #### getAllowPopulate

          public boolean getAllowPopulate()

      Returns whether automatic population of the secondary is allowed. If `setAllowPopulate(boolean)` has not been called, this method returns false.

      Returns:
        whether automatic population of the secondary is allowed.
      See Also:
        `setAllowPopulate(boolean)`

    - #### setImmutableSecondaryKey

          public void setImmutableSecondaryKey​(boolean immutableSecondaryKey)

      Specifies whether the secondary key is immutable.

      Specifying that a secondary key is immutable can be used to optimize updates when the secondary key in a primary record will never be changed after that primary record is inserted. For immutable secondary keys, a best effort is made to avoid calling `SecondaryKeyCreator.createSecondaryKey` when a primary record is updated. This optimization may reduce the overhead of an update operation significantly if the `createSecondaryKey` operation is expensive.

      Be sure to set this property to true only if the secondary key in the primary record is never changed. If this rule is violated, the secondary index will become corrupted, that is, it will become out of sync with the primary.

      Parameters:
        `immutableSecondaryKey` - whether the secondary key is immutable.

    - #### getImmutableSecondaryKey

          public boolean getImmutableSecondaryKey()

      Returns whether the secondary key is immutable. If `setImmutableSecondaryKey(boolean)` has not been called, this method returns false.

      Returns:
        whether the secondary key is immutable.
      See Also:
        `setImmutableSecondaryKey(boolean)`

    - #### setKeyCreator

          public void setKeyCreator​(SecondaryKeyCreator keyCreator)

      Specifies the user-supplied object used for creating single-valued secondary keys.

      Unless the primary database is read-only, a key creator is required when opening a secondary database. Either a KeyCreator or MultiKeyCreator must be specified, but both may not be specified.

      Unless the primary database is read-only, a key creator is required when opening a secondary database.

      Parameters:
        `keyCreator` - the user-supplied object used for creating single-valued secondary keys.

    - #### getKeyCreator

          public SecondaryKeyCreator getKeyCreator()

      Returns the user-supplied object used for creating single-valued secondary keys.

      Returns:
        the user-supplied object used for creating single-valued secondary keys.
      See Also:
        `setKeyCreator(com.sleepycat.db.SecondaryKeyCreator)`

    - #### setMultiKeyCreator

          public void setMultiKeyCreator​(SecondaryMultiKeyCreator multiKeyCreator)

      Specifies the user-supplied object used for creating multi-valued secondary keys.

      Unless the primary database is read-only, a key creator is required when opening a secondary database. Either a KeyCreator or MultiKeyCreator must be specified, but both may not be specified.

      Parameters:
        `multiKeyCreator` - the user-supplied object used for creating multi-valued secondary keys.

    - #### getMultiKeyCreator

          public SecondaryMultiKeyCreator getMultiKeyCreator()

      Returns the user-supplied object used for creating multi-valued secondary keys.

      Returns:
        the user-supplied object used for creating multi-valued secondary keys.
      See Also:
        `setKeyCreator(com.sleepycat.db.SecondaryKeyCreator)`

    - #### setForeignKeyDatabase

          public void setForeignKeyDatabase​(Database foreignDb)

      Defines a foreign key integrity constraint for a given foreign key database.

      If this property is non-null, a record must be present in the specified foreign database for every record in the secondary database, where the secondary key value is equal to the foreign database key value. Whenever a record is to be added to the secondary database, the secondary key is used as a lookup key in the foreign database.

      The foreign database must not have duplicates allowed.

      Parameters:
        `foreignDb` - the database used to check the foreign key integrity constraint, or null if no foreign key constraint should be checked.

    - #### getForeignKeyDatabase

          public com.sleepycat.db.internal.Db getForeignKeyDatabase()

      Returns the database used to check the foreign key integrity constraint, or null if no foreign key constraint will be checked.
      Returns:
        the foreign key database, or null.
      See Also:
        `setForeignKeyDatabase(com.sleepycat.db.Database)`

    - #### setForeignKeyDeleteAction

          public void setForeignKeyDeleteAction​(ForeignKeyDeleteAction action)

      Specifies the action taken when a referenced record in the foreign key database is deleted.

      This property is ignored if the foreign key database property is null.

      Parameters:
        `action` - the action taken when a referenced record in the foreign key database is deleted.
      See Also:
        `@see #setForeignKeyDatabase`

    - #### getForeignKeyDeleteAction

          public ForeignKeyDeleteAction getForeignKeyDeleteAction()

      Returns the action taken when a referenced record in the foreign key database is deleted.
      Returns:
        the action taken when a referenced record in the foreign key database is deleted.
      See Also:
        `setForeignKeyDeleteAction(com.sleepycat.db.ForeignKeyDeleteAction)`

    - #### setForeignKeyNullifier

          public void setForeignKeyNullifier​(ForeignKeyNullifier keyNullifier)

      Specifies the user-supplied object used for setting single-valued foreign keys to null.

      This method may not be used along with `setMultiKeyCreator(com.sleepycat.db.SecondaryMultiKeyCreator)`. When using a multi-key creator, use `setForeignMultiKeyNullifier(com.sleepycat.db.ForeignMultiKeyNullifier)` instead.

      If the foreign key database property is non-null and the foreign key delete action is `NULLIFY`, this property is required to be non-null; otherwise, this property is ignored.

      WARNING: Key nullifier instances are shared by multiple threads and key nullifier methods are called without any special synchronization. Therefore, key creators must be thread safe. In general no shared state should be used and any caching of computed values must be done with proper synchronization.

      Parameters:
        `keyNullifier` - the user-supplied object used for setting single-valued foreign keys to null.
      See Also:
        `@see ForeignKeyDeleteAction#NULLIFY @see #setForeignKeyDatabase`

    - #### getForeignKeyNullifier

          public ForeignKeyNullifier getForeignKeyNullifier()

      Returns the user-supplied object used for setting single-valued foreign keys to null.
      Returns:
        the user-supplied object used for setting single-valued foreign keys to null.
      See Also:
        `setForeignKeyNullifier(com.sleepycat.db.ForeignKeyNullifier)`

    - #### setForeignMultiKeyNullifier

          public void setForeignMultiKeyNullifier​(ForeignMultiKeyNullifier multiKeyNullifier)

      Specifies the user-supplied object used for setting multi-valued foreign keys to null.

      If the foreign key database property is non-null and the foreign key delete action is `NULLIFY`, this property is required to be non-null; otherwise, this property is ignored.

      WARNING: Key nullifier instances are shared by multiple threads and key nullifier methods are called without any special synchronization. Therefore, key creators must be thread safe. In general no shared state should be used and any caching of computed values must be done with proper synchronization.

      Parameters:
        `multiKeyNullifier` - the user-supplied object used for setting multi-valued foreign keys to null.
      See Also:
        `@see ForeignKeyDeleteAction#NULLIFY @see #setForeignKeyDatabase`

    - #### getForeignMultiKeyNullifier

          public ForeignMultiKeyNullifier getForeignMultiKeyNullifier()

      Returns the user-supplied object used for setting multi-valued foreign keys to null.
      Returns:
        the user-supplied object used for setting multi-valued foreign keys to null.
      See Also:
        `setForeignMultiKeyNullifier(com.sleepycat.db.ForeignMultiKeyNullifier)`

Copyright (c) 1996, 2020 Oracle and/or its affiliates. All rights reserved.