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

Class GetChangelogBatchExtendedRequest

  • All Implemented Interfaces:
    ProtocolOp, ReadOnlyLDAPRequest, java.io.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:
    Serialized Form

    • Constructor Detail

      • 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
                                        java.util.List<java.lang.String> includeBaseDNs,
                                        @Nullable
                                        java.util.List<java.lang.String> excludeBaseDNs,
                                        @Nullable
                                        java.util.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
                                        java.util.List<java.lang.String> includeBaseDNs,
                                        @Nullable
                                        java.util.List<java.lang.String> excludeBaseDNs,
                                        @Nullable
                                        java.util.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
                                        java.util.List<java.lang.String> includeBaseDNs,
                                        @Nullable
                                        java.util.List<java.lang.String> excludeBaseDNs,
                                        @Nullable
                                        java.util.Set<ChangeType> changeTypes,
                                        boolean continueOnMissingChanges,
                                        @Nullable
                                        java.lang.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
                                        java.util.List<java.lang.String> includeBaseDNs,
                                        @Nullable
                                        java.util.List<java.lang.String> excludeBaseDNs,
                                        @Nullable
                                        java.util.Set<ChangeType> changeTypes,
                                        boolean continueOnMissingChanges,
                                        @Nullable
                                        java.lang.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 Detail

      • 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 java.util.List<java.lang.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 java.util.List<java.lang.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 java.util.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 java.lang.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.

      • 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​(@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 java.lang.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.