Package com.unboundid.ldap.sdk.unboundidds.controls

Class TransactionSettingsRequestControl

java.lang.Object
com.unboundid.ldap.sdk.Control
com.unboundid.ldap.sdk.unboundidds.controls.TransactionSettingsRequestControl
All Implemented Interfaces:
Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class TransactionSettingsRequestControl extends Control
This class provides a request control that can be used to specify a number of settings used for any database transaction that may be associated with the associated request. It may be included in an end transaction extended request or an atomic multi-update extended request (it is not supported for use in non-atomic multi-update requests).
NOTE: This class, and other classes within the com.unboundid.ldap.sdk.unboundidds package structure, are only supported for use against Ping Identity, UnboundID, and Nokia/Alcatel-Lucent 8661 server products. These classes provide support for proprietary functionality or for external specifications that are not considered stable or mature enough to be guaranteed to work in an interoperable way with other types of LDAP servers.

This control has an OID of 1.3.6.1.4.1.30221.2.5.38. It may have a criticality of either true (in which case the server will reject the associated operation if this control is not recognized) or false (in which case the server will ignore this control if it is not recognized). It must have a value with the following encoding: 
   TransactionSettingsRequestValue ::= SEQUENCE {
        transactionName              [0] OCTET STRING OPTIONAL,
        commitDurability             [1] ENUMERATED {
             nonSynchronous                   (0),
             partiallySynchronous             (1),
             fullySynchronous                 (2),
             ... } OPTIONAL,
        backendLockBehavior          [2] ENUMERATED {
             doNotAcquire                     (0),
             acquireAfterRetries              (1),
             acquireBeforeRetries             (2),
             acquireBeforeInitialAttempt      (3),
             ... } OPTIONAL,
        backendLockTimeoutMillis     [3] INTEGER OPTIONAL,
        retryAttempts                [4] INTEGER OPTIONAL,
        txnLockTimeout               [5] SEQUENCE {
             minTimeoutMillis                 INTEGER,
             maxTimeoutMillis                 INTEGER,
             ... } OPTIONAL,
        returnResponseControl        [6] BOOLEAN DEFAULT FALSE,
        singleWriterLockBehavior     [7] ENUMERATED {
             doNotAcquire                     (0),
             acquireAfterRetries              (1),
             acquireBeforeRetries             (2),
             acquireBeforeInitialAttempt      (3),
             ... } OPTIONAL,
        scopedLockDetails            [8] SEQUENCE {
             scopeIdentifier                  [9] OCTET STRING,
             lockBehavior                     [10] ENUMERATED {
                  doNotAcquire                          (0),
                  acquireAfterRetries                   (1),
                  acquireBeforeRetries                  (2),
                  acquireBeforeInitialAttempt           (3),
                  ... },
             ... } OPTIONAL,
        returnResponseControl        [11] BOOLEAN DEFAULT FALSE,
        ... }
See Also:

  • Field Details

  • Constructor Details

    • TransactionSettingsRequestControl

      public TransactionSettingsRequestControl(boolean isCritical, @Nullable String transactionName, @Nullable TransactionSettingsCommitDurability commitDurability, @Nullable TransactionSettingsBackendLockBehavior backendLockBehavior, @Nullable Long backendLockTimeoutMillis, @Nullable Integer retryAttempts, @Nullable Long minTxnLockTimeoutMillis, @Nullable Long maxTxnLockTimeoutMillis)
      Creates a new transaction settings request control with the provided information.
      Parameters:
      isCritical - Indicates whether the control should be considered critical.
      transactionName - The name to use for the transaction. It may be null if no client-specified transaction name is needed. If a transaction name is provided, it will be used purely for informational and/or troubleshooting purposes.
      commitDurability - The durability level that should be used when committing the associated transaction. It may be null if the server-default durability level should be used.
      backendLockBehavior - The behavior that should be used with regard to acquiring an exclusive lock for processing in the target backend. It may be null if the server-default backend lock behavior should be used.
      backendLockTimeoutMillis - The maximum length of time in milliseconds to spend attempting to acquire an exclusive backend lock if it is needed during any part of the processing. A value that of zero indicates that no timeout should be enforced. It may be null if the server will determine the backend lock timeout that should be used.
      retryAttempts - The number of times to retry the associated operations in a new transaction if the initial attempt fails. If this is null, then the server will determine the number of retry attempts to make. Note that depending on the backend lock behavior, the server may make one additional retry attempt if necessary after acquiring an exclusive backend lock.
      minTxnLockTimeoutMillis - The minimum database lock timeout that should be used for the associated transaction. If this is specified, then the first attempt will use this lock timeout, and subsequent attempts will use a timeout value between this and the maximum database lock timeout (which must also be specified). If this is null, then the server will determine the database lock timeout settings to use.
      maxTxnLockTimeoutMillis - The maximum database lock timeout that should be used for the associated transaction. If this is specified, then the minimum database lock timeout must also be specified, and this value must be greater than or equal to the minimum lock timeout. If this is null, then the server will determine the database lock timeout settings to use.

    • TransactionSettingsRequestControl

      public TransactionSettingsRequestControl(boolean isCritical, @Nullable String transactionName, @Nullable TransactionSettingsCommitDurability commitDurability, @Nullable TransactionSettingsBackendLockBehavior backendLockBehavior, @Nullable Long backendLockTimeoutMillis, @Nullable Integer retryAttempts, @Nullable Long minTxnLockTimeoutMillis, @Nullable Long maxTxnLockTimeoutMillis, boolean returnResponseControl)
      Creates a new transaction settings request control with the provided information.
      Parameters:
      isCritical - Indicates whether the control should be considered critical.
      transactionName - The name to use for the transaction. It may be null if no client-specified transaction name is needed. If a transaction name is provided, it will be used purely for informational and/or troubleshooting purposes.
      commitDurability - The durability level that should be used when committing the associated transaction. It may be null if the server-default durability level should be used.
      backendLockBehavior - The behavior that should be used with regard to acquiring an exclusive lock for processing in the target backend. It may be null if the server-default backend lock behavior should be used.
      backendLockTimeoutMillis - The maximum length of time in milliseconds to spend attempting to acquire an exclusive backend lock if it is needed during any part of the processing. A value that of zero indicates that no timeout should be enforced. It may be null if the server will determine the backend lock timeout that should be used.
      retryAttempts - The number of times to retry the associated operations in a new transaction if the initial attempt fails. If this is null, then the server will determine the number of retry attempts to make. Note that depending on the backend lock behavior, the server may make one additional retry attempt if necessary after acquiring an exclusive backend lock.
      minTxnLockTimeoutMillis - The minimum database lock timeout that should be used for the associated transaction. If this is specified, then the first attempt will use this lock timeout, and subsequent attempts will use a timeout value between this and the maximum database lock timeout (which must also be specified). If this is null, then the server will determine the database lock timeout settings to use.
      maxTxnLockTimeoutMillis - The maximum database lock timeout that should be used for the associated transaction. If this is specified, then the minimum database lock timeout must also be specified, and this value must be greater than or equal to the minimum lock timeout. If this is null, then the server will determine the database lock timeout settings to use.
      returnResponseControl - Indicates whether to return a response control with transaction-related information collected over the course of processing the associated operation.

    • TransactionSettingsRequestControl

      public TransactionSettingsRequestControl(boolean isCritical, @NotNull TransactionSettingsReqeustControlProperties properties)
      Creates a new transaction settings request control with the provided information.
      Parameters:
      isCritical - Indicates whether the control should be considered critical.
      properties - The properties to use for the request control.

    • TransactionSettingsRequestControl

      public TransactionSettingsRequestControl(@NotNull Control c) throws LDAPException
      Creates a new transaction settings request control that is decoded from the provided generic control.
      Parameters:
      c - The generic control to decode as a transaction settings request control.
      Throws:
      LDAPException - If a problem is encountered while attempting to decode the provided control as a transaction settings request control.

  • Method Details

    • getTransactionName

      @Nullable public String getTransactionName()
      Retrieves the name to assign to the associated transaction, if specified.
      Returns:
      The name to assign to the associated transaction, or null if none has been specified.

    • getCommitDurability

      @Nullable public TransactionSettingsCommitDurability getCommitDurability()
      Retrieves the commit durability that should be used for the associated transaction, if specified.
      Returns:
      The commit durability that should be used for the associated transaction, or null if none has been specified and the server should determine the commit durability.

    • getBackendLockBehavior

      @Nullable public TransactionSettingsBackendLockBehavior getBackendLockBehavior()
      Retrieves the backend exclusive lock behavior that should be used for the associated transaction, if specified.
      Returns:
      The backend exclusive lock behavior that should be used for the associated transaction, or null if none has been specified and the server should determine the backend exclusive lock behavior.

    • getSingleWriterLockBehavior

      @Nullable public TransactionSettingsBackendLockBehavior getSingleWriterLockBehavior()
      Retrieves the single-wwriter lock behavior that should be used for the associated transaction, if specified.
      Returns:
      The single-writer lock behavior that should be used for the associated transaction, or null if none has been specified and the server should determine the backend exclusive lock behavior.

    • getScopedLockDetails

      @Nullable public TransactionSettingsScopedLockDetails getScopedLockDetails()
      Retrieves details about the conditions under which the server should attempt to acquire a scoped lock.
      Returns:
      Details about the conditions under which the server should attempt to acquire a scoped lock, or null if no attempt should be made to acquire a scoped lock.

    • getBackendLockTimeoutMillis

      @Nullable public Long getBackendLockTimeoutMillis()
      Retrieves the backend lock timeout (in milliseconds) that should be used for the associated transaction, if specified.
      Returns:
      The backend lock timeout (in milliseconds) that should be used for the associated transaction, or null if none has been specified and the server should determine the backend lock timeout.

    • getRetryAttempts

      @Nullable public Integer getRetryAttempts()
      Retrieves the maximum number of times that the transaction may be retried if the initial attempt fails due to a lock conflict, if specified.
      Returns:
      The maximum number of times that the transaction may be retried if the initial attempt fails due to a lock conflict, or null if none has been specified and the server should determine the number of retry attempts.

    • getMinTxnLockTimeoutMillis

      @Nullable public Long getMinTxnLockTimeoutMillis()
      Retrieves the minimum transaction lock timeout (in milliseconds) that should be used for the associated transaction, if specified. This is the timeout value that will be used for the first attempt. Any subsequent attempts will have a lock timeout that is between the minimum and maximum timeout value.
      Returns:
      The minimum lock timeout (in milliseconds) that should be used for the associated transaction, or null if none has been specified and the server should determine the minimum transaction lock timeout.

    • getMaxTxnLockTimeoutMillis

      @Nullable public Long getMaxTxnLockTimeoutMillis()
      Retrieves the maximum transaction lock timeout (in milliseconds) that should be used for the associated transaction, if specified. The timeout to be used for any retries will be between the minimum and maximum lock timeout values.
      Returns:
      The maximum lock timeout (in milliseconds) that should be used for the associated transaction, or null if none has been specified and the server should determine the maximum transaction lock timeout.

    • replicateControl

      public boolean replicateControl()
      Indicates whether the settings in this control should be considered when the operation is replicated to other servers in the topology.
      Returns:
      true if the control settings should be replicated, or false if not.

    • returnResponseControl

      public boolean returnResponseControl()
      Indicates whether to return a response control with transaction-related information collected over the course of processing the associated operation.
      Returns:
      true if the server should return a response control with transaction-related information, or false if not.

    • getControlName

      @NotNull public String getControlName()
      Retrieves the user-friendly name for this control, if available. If no user-friendly name has been defined, then the OID will be returned.
      Overrides:
      getControlName in class Control
      Returns:
      The user-friendly name for this control, or the OID if no user-friendly name is available.

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this LDAP control to the provided buffer.
      Overrides:
      toString in class Control
      Parameters:
      buffer - The buffer to which to append the string representation of this buffer.