LDAPPersistSearchControl

java.lang.Object
- netscape.ldap.LDAPControl
- - netscape.ldap.controls.LDAPPersistSearchControl

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable
```
public class LDAPPersistSearchControl
extends LDAPControl
```
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() ) {
     ...
     }
 ...
 }
 
```
See Also:

LDAPControl, LDAPEntryChangeControl, Serialized Form

Field Summary

Fields
Modifier and Type	Field	Description
`static int`	`ADD`	Change type specifying that you want to track additions of new entries to the directory.
`static int`	`DELETE`	Change type specifying that you want to track removals of entries from the directory.
`static int`	`MODDN`	Change type specifying that you want to track modifications of the DNs of entries in the directory.
`static int`	`MODIFY`	Change type specifying that you want to track modifications of entries in the directory.
`static java.lang.String`	`PERSISTENTSEARCH`

Fields inherited from class netscape.ldap.LDAPControl
m_critical, m_value, MANAGEDSAIT, PWEXPIRED, PWEXPIRING

Constructor Summary

Constructors
Constructor	Description
`LDAPPersistSearchControl()`	Default constructor
`LDAPPersistSearchControl(int changeTypes, boolean changesOnly, boolean returnControls, boolean isCritical)`	Constructs an `LDAPPersistSearchControl` object that specifies a persistent search.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods Deprecated Methods
Modifier and Type	Method	Description
`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.
`int`	`getChangeTypes()`	Gets the change types monitored by this control.
`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.
`LDAPEntryChangeControl`	`parseResponse(byte[] c)`	Deprecated. LDAPEntryChangeControl controls are now automatically instantiated.
`static LDAPEntryChangeControl`	`parseResponse(LDAPControl[] controls)`	Deprecated. LDAPEntryChangeControl controls are now automatically instantiated.
`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.
`void`	`setChangeTypes(int types)`	Sets the change types that you want monitored by this control.
`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.
`java.lang.String`	`toString()`	Return a string representation of the control for debugging

Methods inherited from class netscape.ldap.LDAPControl
clone, createControl, flattenBER, getID, getValue, isCritical, lookupControlClass, newInstance, register

Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

- Field Detail
  - ADD
```
public static final int ADD
```
    Change type specifying that you want to track additions of new entries to the directory. You can either specify this change type when constructing an LDAPPersistSearchControl or by using the setChangeTypes method.
    
    See Also:
    
    getChangeTypes(), setChangeTypes(int), Constant Field Values
  - DELETE
```
public static final int DELETE
```
    Change type specifying that you want to track removals of entries from the directory. You can either specify this change type when constructing an LDAPPersistSearchControl or by using the setChangeTypes method.
    
    See Also:
    
    getChangeTypes(), setChangeTypes(int), Constant Field Values
  - MODIFY
```
public static final int MODIFY
```
    Change type specifying that you want to track modifications of entries in the directory. You can either specify this change type when constructing an LDAPPersistSearchControl or by using the setChangeTypes method.
    
    See Also:
    
    getChangeTypes(), setChangeTypes(int), Constant Field Values
  - MODDN
```
public static final int MODDN
```
    Change type specifying that you want to track modifications of the DNs of entries in the directory. You can either specify this change type when constructing an LDAPPersistSearchControl or by using the setChangeTypes method.
    
    See Also:
    
    getChangeTypes(), setChangeTypes(int), Constant Field Values
  - PERSISTENTSEARCH
```
public static final java.lang.String PERSISTENTSEARCH
```
    See Also:
    
    Constant Field Values
- Constructor Detail
  - LDAPPersistSearchControl
```
public LDAPPersistSearchControl()
```
    Default constructor
  - LDAPPersistSearchControl
```
public LDAPPersistSearchControl(int changeTypes,
                                boolean changesOnly,
                                boolean returnControls,
                                boolean isCritical)
```
    Constructs an LDAPPersistSearchControl object that specifies a persistent search.
    Parameters:
    changeTypes - the change types to monitor. You can perform a bitwise OR on any of the following values and specify the result as the change types:
    
    LDAPPersistSearchControl.ADD (to track new entries added to the directory)
    LDAPPersistSearchControl.DELETE (to track entries removed from the directory)
    LDAPPersistSearchControl.MODIFY (to track entries that have been modified)
    LDAPPersistSearchControl.MODDN (to track entries that have been renamed)
    changesOnly - true if you do not want the server to return all existing entries in the directory that match the search criteria. (Use this if you just want the changed entries to be returned.)
    
    returnControls - true if you want the server to return entry change controls with each entry in the search results
    
    isCritical - true if this control is critical to the search operation. (If the server does not support this control, you may not want the server to perform the search at all.)
    
    See Also:
    
    LDAPControl, LDAPEntryChangeControl
- Method Detail
  - getChangeTypes
```
public int getChangeTypes()
```
    Gets the change types monitored by this control.
    
    Returns:
    
    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.
    
    See Also:
    
    setChangeTypes(int)
  - 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.
    
    Returns:
    
    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.
    
    See Also:
    
    setChangesOnly(boolean)
  - 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.
    
    Returns:
    
    true if the server includes "entry change notification" controls with the entries it sends during the persistent search.
    
    See Also:
    
    LDAPEntryChangeControl, setReturnControls(boolean)
  - setChangeTypes
```
public void setChangeTypes(int types)
```
    Sets the change types that you want monitored by this control.
    
    Parameters:
    
    types - integer representing the change types to monitor This value can be the bitwise OR of ADD, DELETE, MODIFY, and/or MODDN.
    
    See Also:
    
    getChangeTypes()
  - 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.
    
    Parameters:
    
    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.
    
    See Also:
    
    getChangesOnly()
  - 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.
    
    Parameters:
    
    returnControls - if true, the server includes "entry change notification" controls with the entries it sends during the persistent search
    
    See Also:
    
    LDAPEntryChangeControl, setReturnControls(boolean)
  - parseResponse
```
public LDAPEntryChangeControl parseResponse(byte[] c)
```
    Deprecated.
    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.
    
    Parameters:
    
    c - byte array that contains BER elements
    
    Returns:
    
    the entry change control.
  - parseResponse
```
public static LDAPEntryChangeControl parseResponse(LDAPControl[] controls)
```
    Deprecated.
    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 < returnedControls.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." );
         }
     }
     ...
 }
 ...

 
```
    Parameters:
    
    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.
    
    Returns:
    
    an LDAPEntryChangeControl object representing the entry change control sent by the server. If no entry change control was sent, this method returns null.
    
    See Also:
    
    LDAPEntryChangeControl, LDAPConnection.getResponseControls()
  - toString
```
public java.lang.String toString()
```
    Description copied from class: LDAPControl
    
    Return a string representation of the control for debugging
    
    Overrides:
    
    toString in class LDAPControl
    
    Returns:
    
    a string representation of the control.

Class LDAPPersistSearchControl

Field Summary

Fields inherited from class netscape.ldap.LDAPControl

Constructor Summary

Method Summary

Methods inherited from class netscape.ldap.LDAPControl

Methods inherited from class java.lang.Object

Field Detail

ADD

DELETE

MODIFY

MODDN

PERSISTENTSEARCH

Constructor Detail

LDAPPersistSearchControl

LDAPPersistSearchControl

Method Detail

getChangeTypes

getChangesOnly

getReturnControls

setChangeTypes

setChangesOnly

setReturnControls

parseResponse

parseResponse

toString