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.