Previous | Next | Trail Map | Tips for LDAP Users | Schema

Two Practical Examples

Given this facility for accessing and updating a directory's schema, what can it be used for? This section shows two examples that use the schema. The first one is a program that creates a new entry in the directory. It uses the schema to find out what attributes are required for the new entry. The second example is more ambitious. It creates an entry which may use new object classes, which in turn may use new attribute type definitions.

Using the Existing Schema

This example is called UseSchema. It accepts as a command line argument the name of the entry to create. For example, to create a new entry called "cn=TestPerson" in the "ou=People" subtree, you enter at the prompt:
java UseSchema "cn=TestPerson, ou=People"

This program starts by asking you to enter the list of object classes of the new entry. You terminate the list by hitting RETURN. Using this list of object class names, the program uses the schema to determine the list of mandatory and optional attributes required to create the new entry. This is implemented by the method getAttributeLists():

static Vector[] getAttributeLists(DirContext schema, Vector objectClasses) 
    throws NamingException {
    Vector mandatory = new Vector();
    Vector optional = new Vector();

    for (int i = 0; i < objectClasses.size(); i++) {
        String oc = (String)objectClasses.elementAt(i);
        Attributes ocAttrs = 
  	    schema.getAttributes("ClassDefinition/" + oc);
	Attribute must = ocAttrs.get("MUST");
	Attribute may = ocAttrs.get("MAY");

	if (must != null) {
	    addAttrNameToList(mandatory, must.getAll());
	}
	if (may != null) {
	    addAttrNameToList(optional, may.getAll());
	}
    }
    return new Vector[] {mandatory, optional};
}
The program looks up each object class name in the "ClassDefinition" portion of the schema tree, and extracts from that the "MUST" and "MAY" attributes, which contains lists of attribute names that an entry of that object class are to have.

After constructing the list of mandatory and optional attribute names, the program asks you to enter values for each of these attributes. (You should hit RETURN if you do not want to enter a value for an attribute). This is done in the getAttributeValues() method. It uses each attribute's schema definition to get the attribute's syntax and use that as part of the prompt for the user:

Attributes attrSchema = schema.getAttributes("AttributeDefinition/" + name);
Attribute syntax = attrSchema.get("SYNTAX");
In practice, this is not very helpful because the syntax is an OID and few users will recognize what it represents. However, you can use the attribute schema definition in more useful ways, such as displaying its description and looking up the syntax to get its description.

After getting the attributes for the new entry, the program invokes DirContext.createSubcontext()(in the API reference documentation) to create the new entry.

Augmenting the Existing Schema

In the UseSchema example, you can only enter object classes that have been defined in the schema. If you enter an object class that does not exist in the schema, the program throws a NameNotFoundException(in the API reference documentation) . The next example, AugmentSchema, allows you to enter object classes that have not been defined yet. You run the program by supplying the name of the entry to create as a command line argument:
java AugmentSchema "cn=TestPerson, ou=People"
As with the UseSchema program, you enter a list of object classes for the new entry. With the AugmentSchema program, you may enter object classes that have not yet defined. After getting this list, the program uses the checkDefinition() method to check whether the object classes have been defined. This method accepts as arguments the root of the schema tree, the list of object class names to check, the type of schema object (e.g., "ClassDefinition" or "AttributeDefinition"), and the list of attributes required for defining a schema object of that type. Here is the code for the checkDefinition() method:
static void checkDefinition(DirContext schema, Vector names,
    String schemaType, String[]schemaAttrIDs) throws NamingException, IOException {
        DirContext root = (DirContext)schema.lookup(schemaType);
        for (int i = 0; i < names.size(); i++) {
  	    String name = (String)names.elementAt(i);
	    try {
		// check if definition already exists in schema
		root.lookup(name);
    	    } catch (NameNotFoundException e) {
 	        // Get definition from user
	        Attributes schemaAttrs = getDefinition(schemaType, name, schemaAttrIDs);

	        // Add definition to schema
	        root.createSubcontext(name, schemaAttrs);
            }
	}
    }
}
For each object class that does not have a schema definition, the program creates a schema definition for it by asking you for the attributes needed to define it in the schema, such as its OID, name, and its list of mandatory and optional attributes. The program then creates an object class definition by invoking createSubcontext() on the schema tree.

After doing this for all object classes in the list, the program gets the object classes' lists of mandatory and optional attributes from the schema. It then checks these lists to make sure that they have attribute definitions in the schema, again, using checkDefinition(). For each attribute that does not have a definition in the schema, the program creates a schema definition for it by asking you for the attributes needed to define it in the schema, such as its OID, name, and syntax. The program then creates an attribute definition by invoking createSubcontext() on the schema tree.

The program gathers data for the attributes for the new entry, and then using createSubcontext to create the new entry.


Note: This example won't work with 1.0.1 version of the LDAP provider because it does not support updating the schema in this way. You need to use the workaround suggested in the Object Class Definitions and Attribute Definitions sections.

Schema: End of Lesson

What's next? Now you can:


Previous | Next | Trail Map | Tips for LDAP Users | Schema