com.unboundid.ldap.sdk.experimental
Class ActiveDirectoryDirSyncControl

java.lang.Object
  com.unboundid.ldap.sdk.Control
      com.unboundid.ldap.sdk.experimental.ActiveDirectoryDirSyncControl

All Implemented Interfaces:

DecodeableControl, java.io.Serializable

@NotMutable
@ThreadSafety(level=COMPLETELY_THREADSAFE)
public final class ActiveDirectoryDirSyncControl
extends Control
implements DecodeableControl

This class provides support for a control that may be used to poll an Active Directory Server for information about changes that have been processed. Use of this control is documented at http://support.microsoft.com/kb/891995 and at http://msdn.microsoft.com/en-us/library/ms677626.aspx. The control OID and value format are described at http://msdn.microsoft.com/en-us/library/aa366978%28VS.85%29.aspx and the values of the flags are documented at http://msdn.microsoft.com/en-us/library/cc223347.aspx.

Example

The following example demonstrates the process for using the DirSync control to identify changes to user entries below "dc=example,dc=com":

 // Create a search request that will be used to identify all users below
 // "dc=example,dc=com".
 final SearchRequest searchRequest = new SearchRequest("dc=example,dc=com",
      SearchScope.SUB, Filter.createEqualityFilter("objectClass", "User"));

 // Define the components that will be included in the DirSync request
 // control.
 ASN1OctetString cookie = null;
 final int flags = ActiveDirectoryDirSyncControl.FLAG_INCREMENTAL_VALUES |
      ActiveDirectoryDirSyncControl.FLAG_OBJECT_SECURITY;

 // Create a loop that will be used to keep polling for changes.
 while (keepLooping)
 {
   // Update the controls that will be used for the search request.
   searchRequest.setControls(new ActiveDirectoryDirSyncControl(true, flags,
        50, cookie));

   // Process the search and get the response control.
   final SearchResult searchResult = connection.search(searchRequest);
   ActiveDirectoryDirSyncControl dirSyncResponse =
        ActiveDirectoryDirSyncControl.get(searchResult);
   cookie = dirSyncResponse.getCookie();

   // Process the search result entries because they represent entries that
   // have been created or modified.
   for (final SearchResultEntry updatedEntry :
        searchResult.getSearchEntries())
   {
     // Do something with the entry.
   }

   // If the client might want to continue the search even after shutting
   // down and starting back up later, then persist the cookie now.
 }
 

See Also:

Serialized Form

Field Summary

static java.lang.String	DIRSYNC_OID The OID (1.2.840.113556.1.4.841) for the DirSync control.
static int	FLAG_ANCESTORS_FIRST_ORDER The value of the flag that indicates the server should return parent objects before child objects.
static int	FLAG_INCREMENTAL_VALUES The value of the flag that indicates that only changed values of attributes should be included in search results.
static int	FLAG_OBJECT_SECURITY The value of the flag that indicates that the client should only be allowed to view objects and attributes that are otherwise accessible to the client.
static int	FLAG_PUBLIC_DATA_ONLY The value of the flag that indicates that the server should not return private data in search results.

Constructor Summary

ActiveDirectoryDirSyncControl(boolean isCritical, int flags, int maxAttributeCount, ASN1OctetString cookie)
Creates a new DirSync control with the provided information.

ActiveDirectoryDirSyncControl(java.lang.String oid, boolean isCritical, ASN1OctetString value)
Creates a new DirSync control with settings decoded from the provided control information.

Method Summary

ActiveDirectoryDirSyncControl	decodeControl(java.lang.String oid, boolean isCritical, ASN1OctetString value) Creates a new instance of this decodeable control from the provided information.
static ActiveDirectoryDirSyncControl	get(SearchResult result) Extracts a DirSync response control from the provided result.
java.lang.String	getControlName() Retrieves the user-friendly name for this control, if available.
ASN1OctetString	getCookie() Retrieves a cookie that may be used to resume a previous DirSync search, if available.
int	getFlags() Retrieves the value of the flags that should be used for DirSync operation.
int	getMaxAttributeCount() Retrieves the maximum number of attributes to return.
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

DIRSYNC_OID

public static final java.lang.String DIRSYNC_OID

The OID (1.2.840.113556.1.4.841) for the DirSync control.

See Also:

Constant Field Values

FLAG_OBJECT_SECURITY

public static final int FLAG_OBJECT_SECURITY

The value of the flag that indicates that the client should only be allowed to view objects and attributes that are otherwise accessible to the client.

See Also:

Constant Field Values

FLAG_ANCESTORS_FIRST_ORDER

public static final int FLAG_ANCESTORS_FIRST_ORDER

The value of the flag that indicates the server should return parent objects before child objects.

See Also:

Constant Field Values

FLAG_PUBLIC_DATA_ONLY

public static final int FLAG_PUBLIC_DATA_ONLY

The value of the flag that indicates that the server should not return private data in search results.

See Also:

Constant Field Values

FLAG_INCREMENTAL_VALUES

public static final int FLAG_INCREMENTAL_VALUES

The value of the flag that indicates that only changed values of attributes should be included in search results.

See Also:

Constant Field Values

Constructor Detail

ActiveDirectoryDirSyncControl

public ActiveDirectoryDirSyncControl(boolean isCritical,
                                     int flags,
                                     int maxAttributeCount,
                                     ASN1OctetString cookie)

Creates a new DirSync control with the provided information.

Parameters:

isCritical - Indicates whether this control should be marked critical.

flags - The value of the flags that should be used for DirSync operation. This should be zero if no special flags or needed, or a bitwise OR of the values of the individual flags that are desired.

maxAttributeCount - The maximum number of attributes to return.

cookie - A cookie that may be used to resume a previous DirSync search. This may be null if no previous cookie is available.

ActiveDirectoryDirSyncControl

public ActiveDirectoryDirSyncControl(java.lang.String oid,
                                     boolean isCritical,
                                     ASN1OctetString value)
                              throws LDAPException

Creates a new DirSync control with settings decoded from the provided control information.

Parameters:

oid - The OID of the control to be decoded.

isCritical - The criticality of the control to be decoded.

value - The value of the control to be decoded.

Throws:

LDAPException - If a problem is encountered while attempting to decode the control value as appropriate for a DirSync control.

Method Detail

decodeControl

public ActiveDirectoryDirSyncControl decodeControl(java.lang.String oid,
                                                   boolean isCritical,
                                                   ASN1OctetString value)
                                            throws LDAPException

Creates a new instance of this decodeable control from the provided information.

Specified by:

decodeControl in interface DecodeableControl

Parameters:

oid - The OID for the control.

isCritical - Indicates whether the control should be marked critical.

value - The encoded value for the control. This may be null if no value was provided.

Returns:

The decoded representation of this control.

Throws:

LDAPException - If the provided information cannot be decoded as a valid instance of this decodeable control.

getFlags

public int getFlags()

Retrieves the value of the flags that should be used for DirSync operation.

Returns:

The value of the flags that should be used for DirSync operation.

getMaxAttributeCount

public int getMaxAttributeCount()

Retrieves the maximum number of attributes to return.

Returns:

The maximum number of attributes to return.

getCookie

public ASN1OctetString getCookie()

Retrieves a cookie that may be used to resume a previous DirSync search, if available.

Returns:

A cookie that may be used to resume a previous DirSync search, or a zero-length cookie if there is none.

get

public static ActiveDirectoryDirSyncControl get(SearchResult result)
                                         throws LDAPException

Extracts a DirSync response control from the provided result.

Parameters:

result - The result from which to retrieve the DirSync response control.

Returns:

The DirSync response control contained in the provided result, or null if the result did not include a DirSync response control.

Throws:

LDAPException - If a problem is encountered while attempting to decode the DirSync response control contained in the provided result.

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.