com.unboundid.ldap.sdk.controls

Class PersistentSearchRequestControl

java.lang.Object

com.unboundid.ldap.sdk.Control

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:

• 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

Field Summary

Fields

Modifier and Type	Field and Description
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

Constructors

Constructor and Description
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

Modifier and Type	Method and Description
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, decodeJSONControl, deregisterDecodeableControl, encode, encodeControls, equals, getOID, getValue, hashCode, hasValue, isCritical, readFrom, registerDecodeableControl, registerDecodeableControl, toJSONControl, toString, writeTo

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

PERSISTENT_SEARCH_REQUEST_OID

@NotNull
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(@NotNull
                                      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(@NotNull
                                      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(@NotNull
                                      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(@NotNull
                                      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(@NotNull
                                      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

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

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