Package com.unboundid.ldap.sdk.controls

Class ContentSyncRequestControl

  • All Implemented Interfaces:
    java.io.Serializable
    @NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ContentSyncRequestControl
extends Control
    This class provides an implementation of the LDAP content synchronization request control as defined in RFC 4533. It may be included in a search request to indicate that the client wishes to stay in sync with the server and/or be updated when server data changes.

    Searches containing this control have the potential to take a very long time to complete (and may potentially never complete if the ContentSyncRequestMode.REFRESH_AND_PERSIST mode is selected), may return a large number of entries, and may also return intermediate response messages. When using this control, it is important to keep the following in mind:
    • The associated search request should have a SearchResultListener so that entries will be made available as soon as they are returned rather than having to wait for the search to complete and/or consuming a large amount of memory by storing the entries in a list that is only made available when the search completes. It may be desirable to use an AsyncSearchResultListener to perform the search as an asynchronous operation so that the search request thread does not block while waiting for the search to complete.
    • Entries and references returned from the search should include the ContentSyncStateControl with the associated entryUUID and potentially a cookie with an updated sync session state. You should call getControl(ContentSyncStateControl.SYNC_STATE_OID) on the search result entries and references in order to retrieve the control with the sync state information.
    • The search request should be configured with an unlimited server-side time limit using SearchRequest.setTimeLimitSeconds(0), and an unlimited client-side timeout using SearchRequest.setResponseTimeoutMillis(0L).
    • The search request should be configured with an intermediate response listener using the SearchRequest.setIntermediateResponseListener method.
    • If the search does complete, then the SearchResult (or LDAPSearchException if the search ended with a non-success response) may include a ContentSyncDoneControl with updated sync state information. You should call getResponseControl(ContentSyncDoneControl.SYNC_DONE_OID) to retrieve the control with the sync state information.
    See Also:
    Serialized Form

    • Constructor Detail

      • ContentSyncRequestControl

        public ContentSyncRequestControl​(@NotNull
                                 ContentSyncRequestMode mode)
        Creates a new content synchronization request control that will attempt to retrieve the initial content for the synchronization using the provided request mode. It will be marked critical.
        Parameters:
        mode - The request mode which indicates whether to retrieve only the initial content or to both retrieve the initial content and be updated of changes made in the future. It must not be null.

      • ContentSyncRequestControl

        public ContentSyncRequestControl​(@NotNull
                                 ContentSyncRequestMode mode,
                                 @Nullable
                                 ASN1OctetString cookie,
                                 boolean reloadHint)
        Creates a new content synchronization request control that may be used to either retrieve the initial content or an incremental update. It will be marked critical. It will be marked critical.
        Parameters:
        mode - The request mode which indicates whether to retrieve only the initial content or to both retrieve the initial content and be updated of changes made in the future. It must not be null.
        cookie - A cookie providing state information for an existing synchronization session. It may be null to perform an initial synchronization rather than an incremental update.
        reloadHint - Indicates whether the client wishes to retrieve an initial content during an incremental update if the server determines that the client cannot reach convergence with the server data.

      • ContentSyncRequestControl

        public ContentSyncRequestControl​(boolean isCritical,
                                 @NotNull
                                 ContentSyncRequestMode mode,
                                 @Nullable
                                 ASN1OctetString cookie,
                                 boolean reloadHint)
        Creates a new content synchronization request control that may be used to either retrieve the initial content or an incremental update.
        Parameters:
        isCritical - Indicates whether this control should be marked critical.
        mode - The request mode which indicates whether to retrieve only the initial content or to both retrieve the initial content and be updated of changes made in the future. It must not be null.
        cookie - A cookie providing state information for an existing synchronization session. It may be null to perform an initial synchronization rather than an incremental update.
        reloadHint - Indicates whether the client wishes to retrieve an initial content during an incremental update if the server determines that the client cannot reach convergence with the server data.

      • ContentSyncRequestControl

        public ContentSyncRequestControl​(@NotNull
                                 Control control)
                          throws LDAPException
        Creates a new content synchronization request control which is decoded from the provided generic control.
        Parameters:
        control - The generic control to be decoded as a content synchronization request control.
        Throws:
        LDAPException - If the provided control cannot be decoded as a content synchronization request control.

    • Method Detail

      • getMode

        @NotNull
public ContentSyncRequestMode getMode()
        Retrieves the mode for this content synchronization request control, which indicates whether to retrieve an initial content or an incremental update.
        Returns:
        The mode for this content synchronization request control.

      • getCookie

        @Nullable
public ASN1OctetString getCookie()
        Retrieves a cookie providing state information for an existing synchronization session, if available.
        Returns:
        A cookie providing state information for an existing synchronization session, or null if none is available and an initial content should be retrieved.

      • getReloadHint

        public boolean getReloadHint()
        Retrieves the reload hint value for this synchronization request control.
        Returns:
        true if the server should return an initial content rather than an incremental update if it determines that the client cannot reach convergence, or false if it should return an e-sync refresh required result in that case.

      • getControlName

        @NotNull
public java.lang.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
                     java.lang.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.