Represents an LDAP v3 server control that specifies a persistent
search (an ongoing search operation), which allows your LDAP client
to get notification of changes to the directory. (The OID for this
control is 2.16.840.1.113730.3.4.3.) You can use this control in
conjunction with an "entry change notification" control (represented
by
LDAPEntryChangeControl
object.
To use persistent searching for change notification, you create a
"persistent search" control that specifies the types of changes that
you want to track. You include the control in a search request.
If an entry in the directory is changed, the server determines if
the entry matches the search criteria in your request and if the
change is the type of change that you are tracking. If both of
these are true, the server sends the entry to your client.
The server can also include an "entry change notification" control
with the entry. (The OID for this control is 2.16.840.1.113730.3.4.7.)
This control contains additional information about the
change made to the entry, including the type of change made,
the change number (which corresponds to an item in the server's
change log, if the server supports a change log), and, if the
entry was renamed, the old DN of the entry.
When constructing an
LDAPPersistSearchControl
object,
you can specify the following information:
- the type of change you want to track (added, modified, deleted,
or renamed entries)
- a preference indicating whether or not you want the server to
return all entries that initially matched the search criteria
(rather than only the entries that change)
- a preference indicating whether or not you want entry change
notification controls included with every entry returned by the
server
For example:
...
LDAPConnection ld = new LDAPConnection();
try {
// Connect to server.
ld.connect( 3, hostname, portnumber, "", "" );
// Create a persistent search control.
int op = LDAPPersistSearchControl.ADD |
LDAPPersistSearchControl.MODIFY |
LDAPPersistSearchControl.DELETE |
LDAPPersistSearchControl.MODDN;
boolean changesOnly = true;
boolean returnControls = true;
boolean isCritical = true;
LDAPPersistSearchControl persistCtrl = new
LDAPPersistSearchControl( op, changesOnly,
returnControls, isCritical );
// Set the search constraints to use that control.
LDAPSearchConstraints cons = ld.getSearchConstraints();
cons.setBatchSize( 1 );
cons.setServerControls( persistCtrl );
// Start the persistent search.
LDAPSearchResults res = ld.search( "o=Airius.com",
LDAPv3.SCOPE_SUB, "(cn=Barbara*)", null, false, cons );
// Loop through the incoming results.
while ( res.hasMoreElements() ) {
...
}
...
}
getChangeTypes
public int getChangeTypes()
Gets the change types monitored by this control.
- integer representing the change types to monitor.
This value can be the bitwise OR of
ADD, DELETE, MODIFY,
and/or MODDN
. If the change type is unknown,
this method returns -1.
getChangesOnly
public boolean getChangesOnly()
Indicates whether you want the server to send any existing
entries that already match the search criteria or only the
entries that have changed.
- if
true
, the server returns only the
entries that have changed. If false
, the server
also returns any existing entries that match the search criteria
but have not changed.
getReturnControls
public boolean getReturnControls()
Indicates whether or not the server includes an "entry change
notification" control with each entry it sends back to the client
during the persistent search.
true
if the server includes "entry change
notification" controls with the entries it sends during the
persistent search.
parseResponse
public LDAPEntryChangeControl parseResponse(byte[] c)
LDAPEntryChangeControl controls are now automatically
instantiated.
Takes an input byte array and extracts the ber elements, assigning
them to appropriate fields in the entry change control.
c
- byte array that contains BER elements
- the entry change control.
parseResponse
public static LDAPEntryChangeControl parseResponse(LDAPControl[] controls)
LDAPEntryChangeControl controls are now automatically
instantiated.
Returns an "entry change notification" control if the control is in
the specified array of controls. Use this method to retrieve an "entry
change notification" control included with an entry sent by the server.
You can get the controls returned by the server by using the
getResponseControls
method of the
LDAPConnection
class.
For example:
...
LDAPConnection ld = new LDAPConnection();
try {
// Connect to the server, set up the persistent search control,
// and set up the search constraints.
...
// Search the directory.
LDAPSearchResults res = ld.search( "o=Airius.com",
LDAPv3.SCOPE_SUB, "(cn=Barbara*)", attrs, false, cons );
// Determine if the server sent a control back to you.
LDAPControl[] returnedControls = ld.getResponseControls();
if ( returnedControls != null ) {
// Get the entry change control.
LDAPEntryChangeControl entryCtrl = null;
for ( int i = 0; i <32returnedControls.length; i++ ) {
if ( returnedControls[i] instanceof LDAPEntryChangeControl ) {
entryCtrl = (LDAPEntryChangeControl)returnedControls[i];
break;
}
}
if ( entryCtrl != null ) {
// Get and print the type of change made to the entry.
int changeType = entryCtrl.getChangeType();
if ( changeType != -1 ) {
System.out.print( "Change made: " );
switch ( changeType ) {
case LDAPPersistSearchControl.ADD:
System.out.println( "Added new entry." );
break;
case LDAPPersistSearchControl.MODIFY:
System.out.println( "Modified entry." );
break;
case LDAPPersistSearchControl.DELETE:
System.out.println( "Deleted entry." );
break;
case LDAPPersistSearchControl.MODDN:
System.out.println( "Renamed entry." );
break;
}
}
// Get and print the change number corresponding
// to the change.
int changeNumber = entryCtrl.getChangeNumber();
if ( changeNumber != -1 )
System.out.println( "Change log number: " + changeNumber);
// Get and print the previous DN of the entry,
// if the entry was renamed.
LDAPDN oldDN = entryCtrl.getPreviousDN();
if ( oldDN != null )
System.out.println( "Previous DN: " + oldDN );
} else {
System.out.println( "No entry change control." );
}
}
...
}
...
controls
- an array of LDAPControl
objects,
representing the controls returned by the server
with an entry. To get these controls, use the
getResponseControls
method of the
LDAPConnection
class.
- an
LDAPEntryChangeControl
object representing
the entry change control sent by the server. If no entry change
control was sent, this method returns null.
setChangeTypes
public void setChangeTypes(int types)
Sets the change types that you want monitored by this control.
types
- integer representing the change types to monitor
This value can be the bitwise OR of ADD, DELETE, MODIFY,
and/or MODDN
.
setChangesOnly
public void setChangesOnly(boolean changesOnly)
Specifies whether you want the server to send any existing
entries that already match the search criteria or only the
entries that have changed.
changesOnly
- if true
, the server returns only the
entries that have changed. If false
, the server
also returns any existing entries that match the search criteria
but have not changed.
setReturnControls
public void setReturnControls(boolean returnControls)
Specifies whether you want the server to include an "entry change
notification" control with each entry it sends back to the client
during the persistent search.
returnControls
- if true
, the server includes
"entry change notification" controls with the entries it sends
during the persistent search