Class PersistentSearchRequestControl

  • All Implemented Interfaces:
    java.io.Serializable

    @NotMutable
    @ThreadSafety(level=COMPLETELY_THREADSAFE)
    public final class PersistentSearchRequestControl
    extends Control
    This class provides an implementation of the persistent search request control as defined in draft-ietf-ldapext-psearch. It may be included in a search request to request notification for changes to entries that match the associated set of search criteria. It can provide a basic mechanism for clients to request to be notified whenever entries matching the associated search criteria are altered.

    A persistent search request control may include the following elements:
    • changeTypes -- Specifies the set of change types for which to receive notification. This may be any combination of one or more of the PersistentSearchChangeType values.
    • changesOnly -- Indicates whether to only return updated entries that match the associated search criteria. If this is false, then the server will first return all existing entries in the server that match the search criteria, and will then begin returning entries that are updated in an operation associated with one of the registered changeTypes. If this is true, then the server will not return all matching entries that already exist in the server but will only return entries in response to changes that occur.
    • returnECs -- Indicates whether search result entries returned as a result of a change to the directory data should include the EntryChangeNotificationControl to provide information about the type of operation that occurred. If changesOnly is false, then entry change notification controls will not be included in existing entries that match the search criteria, but only in entries that are updated by an operation with one of the registered changeTypes.
    Note that when an entry is returned in response to a persistent search request, the content of the entry that is returned will reflect the updated entry in the server (except in the case of a delete operation, in which case it will be the entry as it appeared before it was removed). Other than the information included in the entry change notification control, the search result entry will not contain any information about what actually changed in the entry.

    Many servers do not enforce time limit or size limit restrictions on the persistent search control, and because there is no defined "end" to the search, it may remain active until the client abandons or cancels the search or until the connection is closed. Because of this, it is strongly recommended that clients only use the persistent search request control in conjunction with asynchronous search operations invoked using the LDAPConnection.asyncSearch(com.unboundid.ldap.sdk.SearchRequest) method.

    Example

    The following example demonstrates the process for beginning an asynchronous search that includes the persistent search control in order to notify the client of all changes to entries within the "dc=example,dc=com" subtree.
     SearchRequest persistentSearchRequest = new SearchRequest(
          asyncSearchListener, "dc=example,dc=com", SearchScope.SUB,
          Filter.createPresenceFilter("objectClass"));
     persistentSearchRequest.addControl(new PersistentSearchRequestControl(
          PersistentSearchChangeType.allChangeTypes(), // Notify change types.
          true, // Only return new changes, don't match existing entries.
          true)); // Include change notification controls in search entries.
    
     // Launch the persistent search as an asynchronous operation.
     AsyncRequestID persistentSearchRequestID =
          connection.asyncSearch(persistentSearchRequest);
    
     // Modify an entry that matches the persistent search criteria.  This
     // should cause the persistent search listener to be notified.
     LDAPResult modifyResult = connection.modify(
          "uid=test.user,ou=People,dc=example,dc=com",
          new Modification(ModificationType.REPLACE, "description", "test"));
    
     // Verify that the persistent search listener was notified....
    
     // Since persistent search operations don't end on their own, we need to
     // abandon the search when we don't need it anymore.
     connection.abandon(persistentSearchRequestID);
     
    See Also:
    Serialized Form
    • Constructor Detail

      • PersistentSearchRequestControl

        public PersistentSearchRequestControl​(PersistentSearchChangeType changeType,
                                              boolean changesOnly,
                                              boolean returnECs)
        Creates a new persistent search control with the provided information. It will be marked critical.
        Parameters:
        changeType - The change type for which to register. It must not be null.
        changesOnly - Indicates whether the search should only return search result entries for changes made to entries matching the search criteria, or if existing matching entries in the server should be returned as well.
        returnECs - Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
      • PersistentSearchRequestControl

        public PersistentSearchRequestControl​(java.util.Set<PersistentSearchChangeType> changeTypes,
                                              boolean changesOnly,
                                              boolean returnECs)
        Creates a new persistent search control with the provided information. It will be marked critical.
        Parameters:
        changeTypes - The set of change types for which to register. It must not be null or empty.
        changesOnly - Indicates whether the search should only return search result entries for changes made to entries matching the search criteria, or if existing matching entries in the server should be returned as well.
        returnECs - Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
      • PersistentSearchRequestControl

        public PersistentSearchRequestControl​(PersistentSearchChangeType changeType,
                                              boolean changesOnly,
                                              boolean returnECs,
                                              boolean isCritical)
        Creates a new persistent search control with the provided information.
        Parameters:
        changeType - The change type for which to register. It must not be null.
        changesOnly - Indicates whether the search should only return search result entries for changes made to entries matching the search criteria, or if existing matching entries in the server should be returned as well.
        returnECs - Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
        isCritical - Indicates whether the control should be marked critical.
      • PersistentSearchRequestControl

        public PersistentSearchRequestControl​(java.util.Set<PersistentSearchChangeType> changeTypes,
                                              boolean changesOnly,
                                              boolean returnECs,
                                              boolean isCritical)
        Creates a new persistent search control with the provided information.
        Parameters:
        changeTypes - The set of change types for which to register. It must not be null or empty.
        changesOnly - Indicates whether the search should only return search result entries for changes made to entries matching the search criteria, or if existing matching entries in the server should be returned as well.
        returnECs - Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
        isCritical - Indicates whether the control should be marked critical.
      • PersistentSearchRequestControl

        public PersistentSearchRequestControl​(Control control)
                                       throws LDAPException
        Creates a new persistent search request control which is decoded from the provided generic control.
        Parameters:
        control - The generic control to be decoded as a persistent search request control.
        Throws:
        LDAPException - If the provided control cannot be decoded as a persistent search request control.
    • Method Detail

      • getChangeTypes

        public java.util.Set<PersistentSearchChangeTypegetChangeTypes()
        Retrieves the set of change types for this persistent search request control.
        Returns:
        The set of change types for this persistent search request control.
      • changesOnly

        public boolean changesOnly()
        Indicates whether the search should only return search result entries for changes made to entries matching the search criteria, or if existing matching entries should be returned as well.
        Returns:
        true if the search should only return search result entries for changes matching the search criteria, or false if it should also return existing entries that match the search criteria.
      • returnECs

        public boolean returnECs()
        Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
        Returns:
        true if search result entries returned as part of this persistent search should include the entry change notification control, or false if not.
      • 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.