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.
clone
public Object clone()
Creates a copy of the control.
createControl
protected static LDAPControl createControl(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.
oid
- the oid of the control to instantiatecritical
- true
if this is a critical controlvalue
- the byte value for the control
- a newly instantiated
LDAPControl
.
flattenBER
protected byte[] flattenBER(BERSequence ber)
Create a "flattened" BER encoding from a BER,
and return it as a byte array.
ber
- a BER encoded sequence
- the byte array of encoded data.
getID
public String getID()
Gets the object ID (OID) of the control.
- object ID (OID) of the control.
getValue
public byte[] getValue()
Gets the data in the control.
- the data in the control as a byte array.
isCritical
public boolean isCritical()
Specifies whether or not the control is critical to the LDAP operation.
true
if the LDAP operation should be cancelled when
the server does not support this control.
lookupControlClass
protected static Class lookupControlClass(String oid)
Returns the Class
that has been registered to oid.
oid
- a String that associates the control class to a control
- a
Class
that can instantiate a control of the
type specified by oid.
newInstance
public static LDAPControl[] newInstance(byte[] data)
throws 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
.
data
- the LDAP message fragment in raw BER format
- an
LDAPControl
array containing all of the controls
from the message fragment.
register
public static void register(String oid,
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.
oid
- the string representation of the oidcontrolClass
- the class that instantatiates the control associated
with oid
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.
toString
public String toString()
Return a string representation of the control for debugging
- a string representation of the control.