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:
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 theContentSyncRequestMode.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 anAsyncSearchResultListener
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 callgetControl(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 usingSearchRequest.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
(orLDAPSearchException
if the search ended with a non-success response) may include aContentSyncDoneControl
with updated sync state information. You should callgetResponseControl(ContentSyncDoneControl.SYNC_DONE_OID)
to retrieve the control with the sync state information.
- See Also:
- Serialized Form
-
-
Field Summary
Fields Modifier and Type Field Description static java.lang.String
SYNC_REQUEST_OID
The OID (1.3.6.1.4.1.4203.1.9.1.1) for the sync request control.
-
Constructor Summary
Constructors Constructor Description ContentSyncRequestControl(boolean isCritical, ContentSyncRequestMode mode, 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.ContentSyncRequestControl(Control control)
Creates a new content synchronization request control which is decoded from the provided generic control.ContentSyncRequestControl(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.ContentSyncRequestControl(ContentSyncRequestMode mode, 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.
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description java.lang.String
getControlName()
Retrieves the user-friendly name for this control, if available.ASN1OctetString
getCookie()
Retrieves a cookie providing state information for an existing synchronization session, if available.ContentSyncRequestMode
getMode()
Retrieves the mode for this content synchronization request control, which indicates whether to retrieve an initial content or an incremental update.boolean
getReloadHint()
Retrieves the reload hint value for this synchronization request control.void
toString(java.lang.StringBuilder buffer)
Appends a string representation of this LDAP control to the provided buffer.-
Methods inherited from class com.unboundid.ldap.sdk.Control
decode, decode, decodeControls, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toJSONControl, toString, writeTo
-
-
-
-
Field Detail
-
SYNC_REQUEST_OID
@NotNull public static final java.lang.String SYNC_REQUEST_OID
The OID (1.3.6.1.4.1.4203.1.9.1.1) for the sync request control.- See Also:
- Constant Field Values
-
-
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 benull
.
-
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 benull
.cookie
- A cookie providing state information for an existing synchronization session. It may benull
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 benull
.cookie
- A cookie providing state information for an existing synchronization session. It may benull
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, orfalse
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 classControl
- Returns:
- The user-friendly name for this control, or the OID if no user-friendly name is available.
-
-