com.unboundid.ldap.sdk.controls
Class PersistentSearchRequestControl

java.lang.Object
  extended by com.unboundid.ldap.sdk.Control
      extended by com.unboundid.ldap.sdk.controls.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:

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

Field Summary
static java.lang.String PERSISTENT_SEARCH_REQUEST_OID
          The OID (2.16.840.1.113730.3.4.3) for the persistent search request control.
 
Constructor Summary
PersistentSearchRequestControl(Control control)
          Creates a new persistent search request control which is decoded from the provided generic control.
PersistentSearchRequestControl(PersistentSearchChangeType changeType, boolean changesOnly, boolean returnECs)
          Creates a new persistent search control with the provided information.
PersistentSearchRequestControl(PersistentSearchChangeType changeType, boolean changesOnly, boolean returnECs, boolean isCritical)
          Creates a new persistent search control with the provided information.
PersistentSearchRequestControl(java.util.Set<PersistentSearchChangeType> changeTypes, boolean changesOnly, boolean returnECs)
          Creates a new persistent search control with the provided information.
PersistentSearchRequestControl(java.util.Set<PersistentSearchChangeType> changeTypes, boolean changesOnly, boolean returnECs, boolean isCritical)
          Creates a new persistent search control with the provided information.
 
Method Summary
 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.
 java.util.Set<PersistentSearchChangeType> getChangeTypes()
          Retrieves the set of change types for this persistent search request control.
 java.lang.String getControlName()
          Retrieves the user-friendly name for this control, if available.
 boolean returnECs()
          Indicates whether the search result entries returned as part of this persistent search should include the entry change notification control.
 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

PERSISTENT_SEARCH_REQUEST_OID

public static final java.lang.String PERSISTENT_SEARCH_REQUEST_OID
The OID (2.16.840.1.113730.3.4.3) for the persistent search request control.

See Also:
Constant Field Values
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<PersistentSearchChangeType> getChangeTypes()
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.