Package com.unboundid.ldap.sdk.unboundidds.extensions

Class GetChangelogBatchExtendedRequest

java.lang.Object
com.unboundid.ldap.sdk.LDAPRequest
com.unboundid.ldap.sdk.ExtendedRequest
com.unboundid.ldap.sdk.unboundidds.extensions.GetChangelogBatchExtendedRequest
All Implemented Interfaces:
ProtocolOp, ReadOnlyLDAPRequest, Serializable
@NotMutable @ThreadSafety(level=COMPLETELY_THREADSAFE) public final class GetChangelogBatchExtendedRequest extends ExtendedRequest
This class provides an implementation of an extended request which may be used to retrieve a batch of changes from a Directory Server.
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.

The changelog batch request value is encoded as follows: 
   ChangelogBatchRequest ::= SEQUENCE {
        startingPoint                      CHOICE {
             resumeWithToken          [0] OCTET STRING,
             resumeWithCSN            [1] OCTET STRING,
             beginningOfChangelog     [2] NULL,
             endOfChangelog           [3] NULL,
             changeTime               [4] OCTET STRING,
             ... },
        maxChanges                         INTEGER (0 .. maxInt),
        maxTimeMillis                      [0] INTEGER DEFAULT 0,
        waitForMaxChanges                  [1] BOOLEAN DEFAULT FALSE,
        includeBase                        [2] SEQUENCE OF LDAPDN OPTIONAL,
        excludeBase                        [3] SEQUENCE OF LDAPDN OPTIONAL,
        changeTypes                        [4] SET OF ENUMERATED {
             add          (0),
             delete       (1),
             modify       (2),
             modifyDN     (3) } OPTIONAL,
        continueOnMissingChanges           [5] BOOLEAN DEFAULT FALSE,
        pareEntriesForUserDN               [6] LDAPDN OPTIONAL,
        changeSelectionCriteria            [7] CHOICE {
             anyAttributes               [1] SEQUENCE OF LDAPString,
             allAttributes               [2] SEQUENCE OF LDAPString,
             ignoreAttributes            [3] SEQUENCE {
                  ignoreAttributes                SEQUENCE OF LDAPString
                  ignoreOperationalAttributes     BOOLEAN,
                  ... },
             notificationDestination     [4] OCTET STRING,
             ... } OPTIONAL,
        includeSoftDeletedEntryMods        [8] BOOLEAN DEFAULT FALSE,
        includeSoftDeletedEntryDeletes     [9] BOOLEAN DEFAULT FALSE,
        ... }


Example

The following example demonstrates the use of the get changelog batch to iterate across all entries in the changelog. It will operate in an infinite loop, starting at the beginning of the changelog and then reading 1000 entries at a time until all entries have been read. Once the end of the changelog has been reached, it will continue looking for changes, waiting for up to 5 seconds for new changes to arrive. 
 ChangelogBatchStartingPoint startingPoint =
      new BeginningOfChangelogStartingPoint();
 while (true)
 {
   GetChangelogBatchExtendedRequest request =
        new GetChangelogBatchExtendedRequest(startingPoint, 1000, 5000L);

   GetChangelogBatchExtendedResult result =
        (GetChangelogBatchExtendedResult)
        connection.processExtendedOperation(request);
   List<ChangelogEntryIntermediateResponse> changelogEntries =
        result.getChangelogEntries();

   startingPoint = new ResumeWithTokenStartingPoint(result.getResumeToken());
 }
See Also:

  • Field Details

  • Constructor Details

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information. It will include all changes processed anywhere in the server, and will request that the result be returned as soon as any changes are available.
      Parameters:
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@Nullable ChangelogEntryListener entryListener, @NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information. It will include all changes processed anywhere in the server, and will request that the result be returned as soon as any changes are available.
      Parameters:
      entryListener - The listener that will be notified of any changelog entries (or other types of intermediate response) returned during the course of processing this request. It may be null if changelog entries should be collected and made available in the extended result.
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, boolean waitForMaxChanges, @Nullable List<String> includeBaseDNs, @Nullable List<String> excludeBaseDNs, @Nullable Set<ChangeType> changeTypes, boolean continueOnMissingChanges, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information.
      Parameters:
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      waitForMaxChanges - Indicates whether the server should wait for up to the maximum length of time for up to the maximum number of changes to be returned. If this is false, then the result will be returned as soon as any changes are available (after sending those changes), even if the number of available changes is less than maxChanges. Otherwise, the result will not be returned until either the maximum number of changes have been returned or the maximum wait time has elapsed.
      includeBaseDNs - A list of base DNs for entries to include in the set of changes to be returned.
      excludeBaseDNs - A list of base DNs for entries to exclude from the set of changes to be returned.
      changeTypes - The types of changes that should be returned. If this is null or empty, then all change types will be included.
      continueOnMissingChanges - Indicates whether the server should make a best-effort attempt to return changes even if the starting point represents a point that is before the first available change in the changelog and therefore the results returned may be missing changes.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@Nullable ChangelogEntryListener entryListener, @NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, boolean waitForMaxChanges, @Nullable List<String> includeBaseDNs, @Nullable List<String> excludeBaseDNs, @Nullable Set<ChangeType> changeTypes, boolean continueOnMissingChanges, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information.
      Parameters:
      entryListener - The listener that will be notified of any changelog entries (or other types of intermediate response) returned during the course of processing this request. It may be null if changelog entries should be collected and made available in the extended result.
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      waitForMaxChanges - Indicates whether the server should wait for up to the maximum length of time for up to the maximum number of changes to be returned. If this is false, then the result will be returned as soon as any changes are available (after sending those changes), even if the number of available changes is less than maxChanges. Otherwise, the result will not be returned until either the maximum number of changes have been returned or the maximum wait time has elapsed.
      includeBaseDNs - A list of base DNs for entries to include in the set of changes to be returned.
      excludeBaseDNs - A list of base DNs for entries to exclude from the set of changes to be returned.
      changeTypes - The types of changes that should be returned. If this is null or empty, then all change types will be included.
      continueOnMissingChanges - Indicates whether the server should make a best-effort attempt to return changes even if the starting point represents a point that is before the first available change in the changelog and therefore the results returned may be missing changes.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@Nullable ChangelogEntryListener entryListener, @NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, boolean waitForMaxChanges, @Nullable List<String> includeBaseDNs, @Nullable List<String> excludeBaseDNs, @Nullable Set<ChangeType> changeTypes, boolean continueOnMissingChanges, @Nullable String pareEntriesForUserDN, @Nullable ChangelogBatchChangeSelectionCriteria changeSelectionCriteria, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information.
      Parameters:
      entryListener - The listener that will be notified of any changelog entries (or other types of intermediate response) returned during the course of processing this request. It may be null if changelog entries should be collected and made available in the extended result.
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      waitForMaxChanges - Indicates whether the server should wait for up to the maximum length of time for up to the maximum number of changes to be returned. If this is false, then the result will be returned as soon as any changes are available (after sending those changes), even if the number of available changes is less than maxChanges. Otherwise, the result will not be returned until either the maximum number of changes have been returned or the maximum wait time has elapsed.
      includeBaseDNs - A list of base DNs for entries to include in the set of changes to be returned.
      excludeBaseDNs - A list of base DNs for entries to exclude from the set of changes to be returned.
      changeTypes - The types of changes that should be returned. If this is null or empty, then all change types will be included.
      continueOnMissingChanges - Indicates whether the server should make a best-effort attempt to return changes even if the starting point represents a point that is before the first available change in the changelog and therefore the results returned may be missing changes.
      pareEntriesForUserDN - The DN of a user for whom to pare down the contents of changelog entries based on the access control and sensitive attribute restrictions defined for that user. It may be null if changelog entries should not be pared down for any user, an empty string if changelog entries should be pared down to what is available to anonymous users, or a user DN to pare down entries for the specified user.
      changeSelectionCriteria - The optional criteria to use to pare down the changelog entries that should be returned. It may be null if all changelog entries should be returned.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@Nullable ChangelogEntryListener entryListener, @NotNull ChangelogBatchStartingPoint startingPoint, int maxChanges, long maxWaitTimeMillis, boolean waitForMaxChanges, @Nullable List<String> includeBaseDNs, @Nullable List<String> excludeBaseDNs, @Nullable Set<ChangeType> changeTypes, boolean continueOnMissingChanges, @Nullable String pareEntriesForUserDN, @Nullable ChangelogBatchChangeSelectionCriteria changeSelectionCriteria, boolean includeSoftDeletedEntryMods, boolean includeSoftDeletedEntryDeletes, @Nullable Control... controls)
      Creates a new get changelog batch extended request with the provided information.
      Parameters:
      entryListener - The listener that will be notified of any changelog entries (or other types of intermediate response) returned during the course of processing this request. It may be null if changelog entries should be collected and made available in the extended result.
      startingPoint - An object which indicates the starting point for the batch of changes to retrieve. It must not be null.
      maxChanges - The maximum number of changes that should be retrieved before the server should return the corresponding extended result. A value less than or equal to zero may be used to indicate that the server should not return any entries but should just return a result containing a token which represents the starting point.
      maxWaitTimeMillis - The maximum length of time in milliseconds to wait for changes. A value less than or equal to zero indicates that there should not be any wait and the result should be returned as soon as all immediately-available changes (up to the specified maximum count) have been returned.
      waitForMaxChanges - Indicates whether the server should wait for up to the maximum length of time for up to the maximum number of changes to be returned. If this is false, then the result will be returned as soon as any changes are available (after sending those changes), even if the number of available changes is less than maxChanges. Otherwise, the result will not be returned until either the maximum number of changes have been returned or the maximum wait time has elapsed.
      includeBaseDNs - A list of base DNs for entries to include in the set of changes to be returned.
      excludeBaseDNs - A list of base DNs for entries to exclude from the set of changes to be returned.
      changeTypes - The types of changes that should be returned. If this is null or empty, then all change types will be included.
      continueOnMissingChanges - Indicates whether the server should make a best-effort attempt to return changes even if the starting point represents a point that is before the first available change in the changelog and therefore the results returned may be missing changes.
      pareEntriesForUserDN - The DN of a user for whom to pare down the contents of changelog entries based on the access control and sensitive attribute restrictions defined for that user. It may be null if changelog entries should not be pared down for any user, an empty string if changelog entries should be pared down to what is available to anonymous users, or a user DN to pare down entries for the specified user.
      changeSelectionCriteria - The optional criteria to use to pare down the changelog entries that should be returned. It may be null if all changelog entries should be returned.
      includeSoftDeletedEntryMods - Indicates whether to include changelog entries that represent changes to soft-deleted entries.
      includeSoftDeletedEntryDeletes - Indicates whether to include changelog entries that represent deletes of soft-deleted entries.
      controls - The set of controls to include in the request. It may be null or empty if there should be no controls.

    • GetChangelogBatchExtendedRequest

      public GetChangelogBatchExtendedRequest(@NotNull ExtendedRequest extendedRequest) throws LDAPException
      Creates a new get changelog batch extended request from the provided generic extended request.
      Parameters:
      extendedRequest - The generic extended request to be decoded as a get changelog batch extended request.
      Throws:
      LDAPException - If the provided generic request cannot be decoded as a get changelog batch extended request.

  • Method Details

    • getStartingPoint

      @NotNull public ChangelogBatchStartingPoint getStartingPoint()
      Retrieves the starting point for the batch of changes to retrieve.
      Returns:
      The starting point for the batch of changes to retrieve.

    • getMaxChanges

      public int getMaxChanges()
      Retrieves the maximum number of changes that should be returned before the operation completes. A value of zero indicates that the server should not return any entries but should just return a result containing a token which represents the starting point.
      Returns:
      The maximum number of changes that should be returned before the operation completes.

    • getMaxWaitTimeMillis

      public long getMaxWaitTimeMillis()
      Retrieves the maximum length of time in milliseconds that the server should wait for changes to become available before returning the corresponding extended result to the client. A value of zero indicates that the server should return only those results which are immediately available without waiting.
      Returns:
      The maximum length of time in milliseconds that the server should wait for changes to become available, or 0 if the server should not wait at all.

    • waitForMaxChanges

      public boolean waitForMaxChanges()
      Indicates whether the server should wait for up to the maximum length of time for up to the maximum number of changes to be returned before sending the extended result.
      Returns:
      false if the server should return the corresponding extended result as soon as any changes are available (after sending those available changes), or true if the result should not be returned until either the maximum number of changes have been returned or the maximum wait time has elapsed.

    • getIncludeBaseDNs

      @NotNull public List<String> getIncludeBaseDNs()
      Retrieves a list of base DNs below which the server should return information about changes that have been processed. If any include base DNs are specified, then the server should return only changes to entries which reside at or below one of the include base DNs and not at or below any of the exclude base DNs. If no include or exclude base DNs are defined, then the server should return information about changes processed anywhere within the DIT.
      Returns:
      A list of the include base DNs for changes to retrieve, or an empty list if there are none.

    • getExcludeBaseDNs

      @NotNull public List<String> getExcludeBaseDNs()
      Retrieves a list of base DNs below which the server should exclude information about changes processed. If any exclude base DNs are specified, then the server should not return changes to entries which reside at or below any of the exclude base DNs, even if they are also below an include base DN (and as such, the request should not include any exclude base DNs which are at or below any include base DNs). If no include or exclude base DNs are defined, then the server should return information about changes processed anywhere within the DIT.
      Returns:
      A list of the exclude base DNs for changes to retrieve, or an empty list if there are none.

    • getChangeTypes

      @NotNull public Set<ChangeType> getChangeTypes()
      Retrieves the set of change types for changes to be returned to the client.
      Returns:
      The set of change types for changes to be returned to the client.

    • continueOnMissingChanges

      public boolean continueOnMissingChanges()
      Indicates whether the server should make a best-effort attempt to return changes to the client even if the starting point represents a time before the start of the changelog and there may be missing changes.
      Returns:
      true if the server should attempt to return as many changes as possible even if some may be missing, or false if the server should return an error if there may be missing changes.

    • getPareEntriesForUserDN

      @Nullable public String getPareEntriesForUserDN()
      Retrieves the possibly-empty DN of the user for whom changelog entries should be pared based on access control and sensitive attribute restrictions, if defined.
      Returns:
      The possibly-empty DN of the user form whom changelog entries should be pared based on access control and sensitive attribute restrictions, or null if changelog entries should not be pared based for any user.

    • getChangeSelectionCriteria

      @Nullable public ChangelogBatchChangeSelectionCriteria getChangeSelectionCriteria()
      Retrieves the change selection criteria for this get changelog batch extended request, if defined.
      Returns:
      The change selection criteria for this get changelog batch extended request, or null if none is defined.

    • includeSoftDeletedEntryMods

      public boolean includeSoftDeletedEntryMods()
      Indicates whether to include changes that represent modifications to soft-deleted entries.
      Returns:
      true if the result set should include modifications to soft-deleted entries, or false if not.

    • includeSoftDeletedEntryDeletes

      public boolean includeSoftDeletedEntryDeletes()
      Indicates whether to include changes that represent deletes of soft-deleted entries.
      Returns:
      true if the result set should include deletes of soft-deleted entries, or false if not.

    • getEntryListener

      @Nullable public ChangelogEntryListener getEntryListener()
      Retrieves the changelog entry listener that will be used for this request, if applicable.
      Returns:
      The changelog entry listener that will be used for this request, or null if the entries will be made available in the extended result.

    • process

      @NotNull public GetChangelogBatchExtendedResult process(@NotNull LDAPConnection connection, int depth) throws LDAPException
      Sends this extended request to the directory server over the provided connection and returns the associated response.
      Overrides:
      process in class ExtendedRequest
      Parameters:
      connection - The connection to use to communicate with the directory server.
      depth - The current referral depth for this request. It should always be one for the initial request, and should only be incremented when following referrals.
      Returns:
      An LDAP result object that provides information about the result of the extended operation processing.
      Throws:
      LDAPException - If a problem occurs while sending the request or reading the response.

    • duplicate

      @NotNull public GetChangelogBatchExtendedRequest duplicate()
      Creates a new instance of this LDAP request that may be modified without impacting this request.. Subclasses should override this method to return a duplicate of the appropriate type..
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Overrides:
      duplicate in class ExtendedRequest
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • duplicate

      @NotNull public GetChangelogBatchExtendedRequest duplicate(@Nullable Control[] controls)
      Creates a new instance of this LDAP request that may be modified without impacting this request. The provided controls will be used for the new request instead of duplicating the controls from this request.. Subclasses should override this method to return a duplicate of the appropriate type..
      Specified by:
      duplicate in interface ReadOnlyLDAPRequest
      Overrides:
      duplicate in class ExtendedRequest
      Parameters:
      controls - The set of controls to include in the duplicate request.
      Returns:
      A new instance of this LDAP request that may be modified without impacting this request.

    • getExtendedRequestName

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

    • toString

      public void toString(@NotNull StringBuilder buffer)
      Appends a string representation of this request to the provided buffer.
      Specified by:
      toString in interface ProtocolOp
      Specified by:
      toString in interface ReadOnlyLDAPRequest
      Overrides:
      toString in class ExtendedRequest
      Parameters:
      buffer - The buffer to which to append a string representation of this request.