Package com.unboundid.ldap.sdk.experimental

Class 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

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