Package com.unboundid.ldap.sdk.controls

Class ContentSyncRequestControl

java.lang.Object
com.unboundid.ldap.sdk.Control
com.unboundid.ldap.sdk.controls.ContentSyncRequestControl
All Implemented Interfaces:
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:

  • Field Details

  • Constructor Details

    • 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 Details

    • 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 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.