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

Field Summary

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

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

ContentSyncRequestControl(Control control)
Creates a new content synchronization request control which is decoded from the provided generic control.

Method Summary

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, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

SYNC_REQUEST_OID

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(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(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. 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,
                                 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.

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(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

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

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

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