Package 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 thePersistentSearchChangeType
values.changesOnly
-- Indicates whether to only return updated entries that match the associated search criteria. If this isfalse
, 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 registeredchangeTypes
. If this istrue
, 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 theEntryChangeNotificationControl
to provide information about the type of operation that occurred. IfchangesOnly
isfalse
, 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 registeredchangeTypes
.
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 theLDAPConnection.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 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 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
All Methods Instance Methods Concrete Methods Modifier and Type Method 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
-
-
-
-
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 benull
.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 benull
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 benull
.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 benull
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, orfalse
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, orfalse
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 classControl
- Returns:
- The user-friendly name for this control, or the OID if no user-friendly name is available.
-
-