* * 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: *
*
* * An LDAP control consists of the following information: *
*
*
*
*
*
* 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. *
*
* @version 1.0
* @see netscape.ldap.LDAPv3#CLIENTCONTROLS
* @see netscape.ldap.LDAPv3#SERVERCONTROLS
* @see netscape.ldap.LDAPConnection#search(java.lang.String, int, java.lang.String, java.lang.String[], boolean)
* @see netscape.ldap.LDAPConnection#getOption
* @see netscape.ldap.LDAPConnection#setOption
* @see netscape.ldap.LDAPConnection#getResponseControls
* @see netscape.ldap.LDAPSearchConstraints#getClientControls
* @see netscape.ldap.LDAPSearchConstraints#getServerControls
* @see netscape.ldap.LDAPSearchConstraints#setClientControls
* @see netscape.ldap.LDAPSearchConstraints#setServerControls
*/
public class LDAPControl implements Cloneable {
public final static String MANAGEDSAIT = "2.16.840.1.113730.3.4.2";
/* Password information sent back to client */
public final static String PWEXPIRED = "2.16.840.1.113730.3.4.4";
public final static String PWEXPIRING = "2.16.840.1.113730.3.4.5";
/**
* Default constructor for the LDAPControl class.
*/
public LDAPControl()
{
}
/**
* Constructs a new LDAPControl object using the
* specified object ID (OID), "criticality" field, and
* data to be used by the control.
*
*
* @param id The object ID (OID) identifying the control.
* @param 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).
* @param vals Control-specific data.
* @see netscape.ldap.LDAPSearchConstraints#setClientControls
* @see netscape.ldap.LDAPSearchConstraints#setServerControls
*/
public LDAPControl(String id,
boolean critical,
byte vals[]) {
m_oid = id;
m_critical = critical;
m_value = vals;
}
/**
* Gets the object ID (OID) of the control.
* @return Object ID (OID) of the control.
*/
public String getID() {
return m_oid;
}
/**
* Specifies whether or not the control is critical to the LDAP operation.
* @return true if the LDAP operation should be cancelled when
* the server does not support this control.
*/
public boolean isCritical() {
return m_critical;
}
/**
* Gets the data in the control.
* @return Returns the data in the control as a byte array.
*/
public byte[] getValue() {
return m_value;
}
/**
* Creates a copy of the control.
* @return Copy of the control.
*/
public Object clone() {
byte[] vals = null;
if ( m_value != null ) {
vals = new byte[m_value.length];
for( int i = 0; i < m_value.length; i++ )
vals[i] = m_value[i];
}
LDAPControl control = new LDAPControl( m_oid, m_critical, vals );
return control;
}
/**
* Create a "flattened" BER encoding from a BER,
* and return it as a byte array.
* @param ber A BER encoded sequence.
* @return The byte array of encoded data.
*/
protected byte[] flattenBER( BERSequence ber ) {
/* Suck out the data and return it */
ByteArrayOutputStream outStream = new ByteArrayOutputStream();
try {
ber.write( outStream );
} catch ( IOException e ) {
return null;
}
return outStream.toByteArray();
}
private String m_oid;
protected boolean m_critical = false;
protected byte[] m_value = null;
}