Package 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, 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:

  • Field Details

  • Constructor Details

    • ActiveDirectoryDirSyncControl

      public ActiveDirectoryDirSyncControl(boolean isCritical, int flags, int maxAttributeCount, @Nullable 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(@NotNull String oid, boolean isCritical, @Nullable 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 Details

    • decodeControl

      @NotNull public ActiveDirectoryDirSyncControl decodeControl(@NotNull String oid, boolean isCritical, @Nullable 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

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

      @Nullable public static ActiveDirectoryDirSyncControl get(@NotNull 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

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