LDAPControl

java.lang.Object
- netscape.ldap.LDAPControl

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

Direct Known Subclasses:

LDAPEntryChangeControl, LDAPPasswordExpiredControl, LDAPPasswordExpiringControl, LDAPPersistSearchControl, LDAPProxiedAuthControl, LDAPSortControl, LDAPVirtualListControl, LDAPVirtualListResponse
```
public class LDAPControl
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable
```
Represents arbitrary control data that can be used with a a particular LDAP operation. LDAP controls are part of version 3 of the LDAP protocol.
LDAP controls allow you to extend the functionality of an LDAP operation. For example, you can use an LDAP control for the search operation to sort search results on an LDAP server.
An LDAP control can be either a server control or a client control:
- Server controls can be sent to the LDAP server or returned by the server on any operation.
- Client controls are intended to affect only the client side of the operation.
An LDAP control consists of the following information:
- A unique object ID (OID) that identifies the control.
- A "criticality" field, which indicates whether or not the control is critical to the operation. (If the control is critical to the operation and the server does not support the control, the server should not execute the operation.)
- Data pertaining to the control.
To determine which server controls are supported by a particular server, you need to search for the root DSE (DSA-specific entry, where DSA is another term for "LDAP server") and find the values of the supportedControl attribute. This attribute contains the object IDs (OIDs) of the controls supported by this server.
The following section of code demonstrates how to get the list of the server controls supported by an LDAP server.
```
 public static void main( String[] args )
 {
   LDAPConnection ld = new LDAPConnection();
   try {
     String MY_HOST = "localhost";
     int MY_PORT = 389;
     ld.connect( MY_HOST, MY_PORT );
     try {
       ld.authenticate( 3, "cn=Directory Manager", "23skidoo" );
     } catch( LDAPException e ) {
       System.out.println( "LDAP server does not support v3." );
       ld.disconnect();
       System.exit(1);
     }

     String MY_FILT = "(objectclass=*)";
     String MY_BASE = "";
     String getAttrs[] = { "supportedControl" };
     LDAPSearchResults res = ld.search( MY_BASE,
       LDAPConnection.SCOPE_BASE, MY_FILT, getAttrs, false );

     while ( res.hasMoreElements() ) {
       LDAPEntry findEntry = (LDAPEntry)res.nextElement();
       LDAPAttributeSet findAttrs = findEntry.getAttributeSet();
       Enumeration enumAttrs = findAttrs.getAttributes();

         while ( enumAttrs.hasMoreElements() ) {
           LDAPAttribute anAttr = (LDAPAttribute)enumAttrs.nextElement();
           String attrName = anAttr.getName();
           System.out.println( attrName );
           Enumeration enumVals = anAttr.getStringValues();

           while ( enumVals.hasMoreElements() ) {
             String aVal = ( String )enumVals.nextElement();
             System.out.println( "\t" + aVal );
           }
         }
      }
   }
   catch( LDAPException e ) {
     System.out.println( "Error: " + e.toString() );
   }
   try {
     ld.disconnect();
   }
   catch( LDAPException e ) {
     System.exit(1);
   }
   System.exit(0);
 }
 
```
If you compile and run this example against an LDAP server that supports v3 of the protocol, you might receive the following results:
```
 supportedcontrol
   2.16.840.1.113730.3.4.2
   2.16.840.1.113730.3.4.3
   2.16.840.1.113730.3.4.4
   2.16.840.1.113730.3.4.5
   1.2.840.113556.1.4.473
 
```
For more information on LDAP controls, see the Internet-Draft on the LDAP v3 protocol. (Note that this internet draft is still a work in progress. You can find the latest draft at the ASID home page.
See Also:

LDAPv3.CLIENTCONTROLS, LDAPv3.SERVERCONTROLS, LDAPConnection.search(java.lang.String, int, java.lang.String, java.lang.String[], boolean), LDAPConnection.getOption(int), LDAPConnection.setOption(int, java.lang.Object), LDAPConnection.getResponseControls(), LDAPConstraints.getClientControls(), LDAPConstraints.getServerControls(), LDAPConstraints.setClientControls(netscape.ldap.LDAPControl), LDAPConstraints.setServerControls(netscape.ldap.LDAPControl), Serialized Form

Field Summary

Fields
Modifier and Type	Field	Description
`protected boolean`	`m_critical`
`protected byte[]`	`m_value`
`static java.lang.String`	`MANAGEDSAIT`
`static java.lang.String`	`PWEXPIRED`
`static java.lang.String`	`PWEXPIRING`

Constructor Summary

Constructors
Constructor	Description
`LDAPControl()`	Default constructor for the `LDAPControl` class.
`LDAPControl(java.lang.String id, boolean critical, byte[] vals)`	Constructs a new `LDAPControl` object using the specified object ID (OID), "criticality" field, and data to be used by the control.

Method Summary

All Methods Static Methods Instance Methods Concrete Methods
Modifier and Type	Method	Description
`java.lang.Object`	`clone()`	Creates a copy of the control.
`protected static LDAPControl`	`createControl(java.lang.String oid, boolean critical, byte[] value)`	Returns a `LDAPControl` object instantiated by the Class associated by `LDAPControl.register` to the oid.
`protected byte[]`	`flattenBER(BERSequence ber)`	Create a "flattened" BER encoding from a BER, and return it as a byte array.
`java.lang.String`	`getID()`	Gets the object ID (OID) of the control.
`byte[]`	`getValue()`	Gets the data in the control.
`boolean`	`isCritical()`	Specifies whether or not the control is critical to the LDAP operation.
`protected static java.lang.Class`	`lookupControlClass(java.lang.String oid)`	Returns the `Class` that has been registered to oid.
`static LDAPControl[]`	`newInstance(byte[] data)`	Instantiates all of the controls contained within the LDAP message fragment specified by data and returns them in an `LDAPControl` array.
`static void`	`register(java.lang.String oid, java.lang.Class controlClass)`	Associates a class with an oid.
`java.lang.String`	`toString()`	Return a string representation of the control for debugging

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

- Field Detail
  - MANAGEDSAIT
```
public static final java.lang.String MANAGEDSAIT
```
    See Also:
    
    Constant Field Values
  - PWEXPIRED
```
public static final java.lang.String PWEXPIRED
```
    See Also:
    
    Constant Field Values
  - PWEXPIRING
```
public static final java.lang.String PWEXPIRING
```
    See Also:
    
    Constant Field Values
  - m_critical
```
protected boolean m_critical
```
  - m_value
```
protected byte[] m_value
```
- Constructor Detail
  - LDAPControl
```
public LDAPControl()
```
    Default constructor for the LDAPControl class.
  - LDAPControl
```
public LDAPControl(java.lang.String id,
                   boolean critical,
                   byte[] vals)
```
    Constructs a new LDAPControl object using the specified object ID (OID), "criticality" field, and data to be used by the control.
    
    Parameters:
    
    id - the object ID (OID) identifying the control
    
    critical - true if the LDAP operation should be cancelled when the server does not support this control (in other words, this control is critical to the LDAP operation)
    
    vals - control-specific data
    
    See Also:
    
    LDAPConstraints.setClientControls(netscape.ldap.LDAPControl), LDAPConstraints.setServerControls(netscape.ldap.LDAPControl)
- Method Detail
  - getID
```
public java.lang.String getID()
```
    Gets the object ID (OID) of the control.
    
    Returns:
    
    object ID (OID) of the control.
  - isCritical
```
public boolean isCritical()
```
    Specifies whether or not the control is critical to the LDAP operation.
    
    Returns:
    
    true if the LDAP operation should be cancelled when the server does not support this control.
  - getValue
```
public byte[] getValue()
```
    Gets the data in the control.
    
    Returns:
    
    the data in the control as a byte array.
  - register
```
public static void register(java.lang.String oid,
                            java.lang.Class controlClass)
                     throws LDAPException
```
    Associates a class with an oid. This class must be an extension of LDAPControl, and should implement the LDAPControl( String oid, boolean critical, byte[] value) constructor to instantiate the control.
    
    Parameters:
    
    oid - the string representation of the oid
    
    controlClass - the class that instantatiates the control associated with oid
    
    Throws:
    
    LDAPException - If the class parameter is not a subclass of LDAPControl or the class parameter does not implement the LDAPControl(String oid, boolean critical, byte[] value) constructor.
  - lookupControlClass
```
protected static java.lang.Class lookupControlClass(java.lang.String oid)
```
    Returns the Class that has been registered to oid.
    
    Parameters:
    
    oid - a String that associates the control class to a control
    
    Returns:
    
    a Class that can instantiate a control of the type specified by oid.
    
    See Also:
    
    register(java.lang.String, java.lang.Class)
  - createControl
```
protected static LDAPControl createControl(java.lang.String oid,
                                           boolean critical,
                                           byte[] value)
```
    Returns a LDAPControl object instantiated by the Class associated by LDAPControl.register to the oid. If no Class is found for the given control, or an exception occurs when attempting to instantiate the control, a basic LDAPControl is instantiated using the parameters.
    
    Parameters:
    
    oid - the oid of the control to instantiate
    
    critical - true if this is a critical control
    
    value - the byte value for the control
    
    Returns:
    
    a newly instantiated LDAPControl.
    
    See Also:
    
    register(java.lang.String, java.lang.Class)
  - newInstance
```
public static LDAPControl[] newInstance(byte[] data)
                                 throws java.io.IOException
```
    Instantiates all of the controls contained within the LDAP message fragment specified by data and returns them in an LDAPControl array. This fragment can be either the entire LDAP message or just the control section of the message.
    If an exception occurs when instantiating a control, that control is returned as a basic LDAPControl.
    
    Parameters:
    
    data - the LDAP message fragment in raw BER format
    
    Returns:
    
    an LDAPControl array containing all of the controls from the message fragment.
    
    Throws:
    
    java.lang.IOException - If the data passed to this method is not a valid LDAP message fragment.
    
    java.io.IOException
    
    See Also:
    
    register(java.lang.String, java.lang.Class)
  - clone
```
public java.lang.Object clone()
```
    Creates a copy of the control.
    
    Overrides:
    
    clone in class java.lang.Object
    
    Returns:
    
    copy of the control.
  - flattenBER
```
protected byte[] flattenBER(BERSequence ber)
```
    Create a "flattened" BER encoding from a BER, and return it as a byte array.
    
    Parameters:
    
    ber - a BER encoded sequence
    
    Returns:
    
    the byte array of encoded data.
  - toString
```
public java.lang.String toString()
```
    Return a string representation of the control for debugging
    
    Overrides:
    
    toString in class java.lang.Object
    
    Returns:
    
    a string representation of the control.

Class LDAPControl

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

MANAGEDSAIT

PWEXPIRED

PWEXPIRING

m_critical

m_value

Constructor Detail

LDAPControl

LDAPControl

Method Detail

getID

isCritical

getValue

register

lookupControlClass

createControl

newInstance

clone

flattenBER

toString