Chapter 11 Getting Server Information

This chapter explains how to access and modify information about your LDAP server over the LDAP protocol.

• "Understanding DSEs"
• "Getting the Root DSE"
• "Determining If the Server Supports LDAP v3"
• "Getting Schema Information"

• the naming contexts of this server (for example, "o=Airius.com")
• URLs of alternate servers to contact if this server is unavailable
• the LDAP v3 extended operations supported by this server (see Chapter 16, "Working with Extended Operations"for details)
• the LDAP v3 controls supported by this server (see Chapter 13, "Working with LDAP Controls" for details)
• the SASL mechanisms supported by this server (see Chapter 14, "Using SASL Authentication" for details)
• the versions of the LDAP protocol supported by this server (for example, 2 and 3)
• additional server-specific information

1. Turn off automatic referral handling and connect to the LDAP server (see "Creating a Connection and Setting Preferences", "Connecting to the LDAP Server", and "Enabling or Disabling Referral Handling" for details).
2. Search the directory using the following criteria:

• Set the search scope to a base search.
• Specify an empty string for the base DN.
• Use the search filter (objectclass=*).

For details on how to use Java classes to search the directory, see Chapter 6, "Searching the Directory".

If an LDAPException is thrown with a result code such as OPERATION_ERROR, PROTOCOL_ERROR, REFERRAL, or NO_SUCH_OBJECT, the LDAP server probably does not support LDAP v3.

...

import netscape.ldap.*;

import java.util.*;

...

/* Create a new connection. */

LDAPConnection ld = new LDAPConnection();

String hostname = "localhost";

int portnumber = LDAPv2.DEFAULT_PORT;



try {

   /* Connect to the LDAP server. */

   ld.connect( 3, hostname, portnumber );



   /* Get the root DSE by doing a search where:

         - The scope is SCOPE_BASE

         - The base is ""

         - The search filter is "(objectclass=*)"

   */

   int MY_SCOPE = LDAPv2.SCOPE_BASE;

   String MY_FILTER = "(objectclass=*)";

   String MY_SEARCHBASE = "";

   LDAPSearchResults res = ld.search( MY_SEARCHBASE,

      MY_SCOPE, MY_FILTER, null, false );



   /* There should be only one entry in the results (the root DSE). */

   while ( res.hasMoreElements() ) {

      LDAPEntry findEntry = (LDAPEntry)res.nextElement();



      /* Get the attributes of the root DSE. */

      LDAPAttributeSet findAttrs = findEntry.getAttributeSet();

      Enumeration enumAttrs = findAttrs.getAttributes();



      /* Iterate through each attribute. */

      while ( enumAttrs.hasMoreElements() ) {

         LDAPAttribute anAttr = (LDAPAttribute)enumAttrs.nextElement();



         /* Get and print the attribute name. */

         String attrName = anAttr.getName();

         System.out.println( attrName );



         /* Get the values of the attribute. */

         Enumeration enumVals = anAttr.getStringValues();



         /* Get and print each value. */

         if ( enumVals == null ) {

            System.out.println( "\tNo values found." );

            continue;

         }

         while ( enumVals.hasMoreElements() ) {

            String aVal = ( String )enumVals.nextElement();

            System.out.println( "\t" + aVal );

         }

      }

   }

}

catch( LDAPException e ) {

   System.out.println( "Error: " + e.toString() );

}

...

...

import netscape.ldap.*;

import java.util.*;

...

/* Create a new connection. */

LDAPConnection ld = new LDAPConnection();

String hostname = "localhost";

int portnumber = LDAPv2.DEFAULT_PORT;

boolean supportsV3 = false;



try {

   /* Connect to the LDAP server. */

   ld.connect( 3, hostname, portnumber );



   /* Get the root DSE by doing a search where:

         - The scope is SCOPE_BASE

         - The base is ""

         - The search filter is "(objectclass=*)"

   */

   int MY_SCOPE = LDAPv2.SCOPE_BASE;

   String MY_FILTER = "(objectclass=*)";

   String MY_SEARCHBASE = "";

   LDAPSearchResults res = ld.search( MY_SEARCHBASE,

      MY_SCOPE, MY_FILTER, null, false );



   /* There should be only one entry in the results (the root DSE). */

   while ( res.hasMoreElements() ) {

      LDAPEntry findEntry = (LDAPEntry)res.nextElement();



      /* Get the supportedLDAPVersion attribute. */

      LDAPAttribute versionAttr = 

         findEntry.getAttribute( "supportedLDAPVersion" );



      /* Check if "3" is one of the supported LDAP versions. */

      Enumeration enumVals = versionAttr.getStringValues();

      if ( enumVals == null ) {

         System.out.println( "\tNo values found." );

         continue;

      }

      while ( enumVals.hasMoreElements() ) {

         String aVal = ( String )enumVals.nextElement();

         if ( aVal.equalsIgnoreCase( "3" ) ) { 

            supportsV3 = true; 

            break; 

         }

      }

   }

}

catch( LDAPException e ) {

   System.out.println( "Error: " + e.toString() );

}

if ( supportsV3 ) {

   System.out.println( "This server supports LDAP v3." );

} else {

   System.out.println( "This server does not support LDAP v3." );

}

...

• "Overview: Schema Over LDAP"
• "Getting the Schema for an LDAP Server"
• "Working with Object Class Descriptions"
• "Working with Attribute Type Descriptions"
• "Working with Matching Rule Descriptions"
• "Example of Working with the Schema"

• objectClasses specifies the object class definitions in the schema. Each value of this attribute is an object class that is known to the server.
• attributeTypes specifies the attribute type definitions in the schema. Each value of this attribute is an attribute type that is known to the server.
• matchingRules specifies the matching rule definitions in the schema. Each value of this attribute is a matching rule that is known to the server.
• matchingRuleUse specifies the use of a matching rule in the schema. Each value of this attribute is a matching rule use description. A matching rule use description specifies the OIDs of the attributes that can be used with this extensible matching rule.

...

import netscape.ldap.*;

...

LDAPConnection ld = new LDAPConnection();



/* Construct a new LDAPSchema object to hold

   the schema that you want to retrieve. */

LDAPSchema dirSchema = new LDAPSchema();

try {

   ld.connect( hostname, portnumber, bindDN, bindPW );

   /* Get the schema from the Directory. Anonymous access okay. */

   dirSchema.fetchSchema( ld );

   ...

} catch ( Exception e ) {

   System.err.println( e.toString() );

}

...

• To get an enumeration of LDAPObjectClassSchema objects representing the object classes in the schema, invoke the getObjectClasses method.
• To get a specific object class description, invoke the getObjectClass methodand pass in the name of the object class.
• To get an enumeration of the names of object classes in the schema, invoke the getObjectClassNames method.

• an OID identifying the object class (get this by invoking the getOID method, which is inherited from the LDAPSchemaElement base class)
• a name identifying the object class (get this by invoking the getName method, which is inherited from the LDAPSchemaElement base class)
• a description of the object class (get this by invoking the getDescription method, which is inherited from the LDAPSchemaElement base class)
• the name of the parent object class (get this by invoking the getSuperior method)
• the list of attribute types that are required in this object class (get this by invoking the getRequiredAttributes method)
• the list of attribute types that are allowed (optional) in this object class (get this by invoking the getOptionalAttributes method)

• To get an enumeration of LDAPAttributeSchema objects representing the attribute types in the schema, invoke the getAttributes method.
• To get a specific attribute type description, invoke the getAttribute methodand pass in the name of the attribute type.
• To get an enumeration of the names of attribute types in the schema, invoke the getAttributeNames method.

• an OID identifying the attribute type (get this by invoking the getOID method, which is inherited from the LDAPSchemaElement base class)
• a name identifying the attribute type (get this by invoking the getName method, which is inherited from the LDAPSchemaElement base class)
• a description of the attribute type (get this by invoking the getDescription method, which is inherited from the LDAPSchemaElement base class)
• the syntax used by the attribute type (get this by invoking the getSyntax method)
• an indicator of whether the attribute type is single-valued or multi-valued (get this by invoking the isSingleValued method)

• To get an enumeration of LDAPMatchingRuleSchema objects representing the matching rules in the schema, invoke the getMatchingRules method.
• To get a specific matching rule description, invoke the getMatchingRule methodand pass in the name of the matching rule.
• To get an enumeration of the names of matching rules in the schema, invoke the getMatchingRuleNames method.

• an OID identifying the matching rule (get this by invoking the getOID method, which is inherited from the LDAPSchemaElement base class)
• a name identifying the matching rule (get this by invoking the getName method, which is inherited from the LDAPSchemaElement base class)
• a description of the matching rule (get this by invoking the getDescription method, which is inherited from the LDAPSchemaElement base class)
• the syntax of the matching rule (get this by invoking the getSyntax method, which is inherited from the LDAPAttributeSchema class)

...

import netscape.ldap.*;

import java.util.*;

...

public class GetSchema {

   public static void main( String[] args ) {

      LDAPConnection ld = new LDAPConnection();

      String hostname = "localhost";

      int portnumber = LDAPv2.DEFAULT_PORT;

      String bindDN = "cn=Directory Manager";

      String bindPW = "23skidoo";



      /* Construct a new LDAPSchema object to hold

         the schema that you want to retrieve. */

      LDAPSchema dirSchema = new LDAPSchema();

      try {

         ld.connect( hostname, portnumber, bindDN, bindPW );



         /* Get the schema from the Directory. Anonymous access okay. */

         dirSchema.fetchSchema( ld );



         /* Get and print the def. of the inetOrgPerson object class. */

         LDAPObjectClassSchema objClass = 

            dirSchema.getObjectClass( "inetOrgPerson" );

         if ( objClass != null ) 

            System.out.println( "inetOrgPerson := " + 

               objClass.toString() );



         /* Get and print the def. of the userPassword attribute. */

         LDAPAttributeSchema attrType = 

            dirSchema.getAttribute( "userpassword" );

         if ( attrType != null ) 

            System.out.println( "userPassword := " + 

               attrType.toString() );



         /* Add a new object class. */

         String[] requiredAttrs = {"cn", "mail"};

         String[] optionalAttrs = {"sn", "phoneNumber"};

         LDAPObjectClassSchema newObjClass = new LDAPObjectClassSchema(

            "newInetOrgPerson", "1.2.3.4.5.6.7", "top", "Experiment",

            requiredAttrs, optionalAttrs );



         /* Add the new object class to the schema. */

         newObjClass.add( ld );



         /* Create a new attribute type "hairColor". */

         LDAPAttributeSchema newAttrType = new LDAPAttributeSchema(

            "hairColor", "1.2.3.4.5.4.3.2.1", "Blonde, red, etc",

            LDAPAttributeSchema.cis, false );



         /* Add the new attribute type to the schema. */

         newAttrType.add( ld );



         /* Fetch schema again from the server to verify that the

            changes were made. */

         dirSchema.fetchSchema( ld );



         /* Get and print the new attribute type. */

         newAttrType = dirSchema.getAttribute( "hairColor" );

         if ( newAttrType != null )

            System.out.println( "hairColor := " + 

               newAttrType.toString() );



         /* Get and print the new object class. */

         newObjClass = dirSchema.getObjectClass( "newInetOrgPerson" );

         if ( newObjClass != null )

            System.out.println( "newInetOrgPerson := " + 

               newObjClass.toString() );



         ld.disconnect();

      } catch ( Exception e ) {

         System.err.println( e.toString() );

         System.exit( 1 );

      }

      System.exit( 0 );

   }

}

...