Adding Directory Support

Schema

The javax.naming.directory package contains the following methods (plus their java.lang.String overloads) for dealing with directory schema:

• DirContext.getSchema(Name name)
• DirContext.getSchemaClassDefinition(Name name)
• Attribute.getAttributeDefinition()
• Attribute.getAttributeSyntaxDefinition()

How an API user uses these methods is discussed in the Schema lesson.

getSchema(), getAttributeDefinition(), and getAttributeSyntaxDefinition() return a pointer to the schema tree, whereas getSchemaClassDefinition() returns a context whose children are from the schema tree. The following figure depicts the relationship between the directory tree and the schema tree.

If a context implementation does not support returning schema information, then these methods should throw an OperationNotSupportedException. Although a context implementation typically supports all or none of these four methods, it also may support only some of them. Further, some directory servers do not export all of the data required to completely populate the schema tree. Therefore a context implementation might not be able to return relevant data for all of these methods.

Implementation Strategies

A context implementation that supports schema methods should follow the recommendations in the Guideline for LDAP Service Providers when choosing the names of attributes to use to describe schema data.

A common strategy is to build an in-memory schema tree that mirrors the one depicted in the figure. More than one schema tree per context implementation might exist because getSchema() accepts a Name argument. Whether there is one or more schema trees depends on the underlying directory service and/or server configuration. An LDAP server, for example, can be configured to have different schema trees for different parts of its directory tree. An API user who invokes getSchema() on different parts of the tree would expect to get back the corresponding (possibly different) schema trees.

Each node in the tree is a DirContext and represents a schema definition. The node has associated attributes that describe the schema definition. These attributes are described in the Schema lesson. The contents of each node (name and attributes) are determined by the underlying directory service and schema information on the server. For example, one context implementation might have a built-in (fixed) schema, whereas another might fetch the schema data dynamically from the directory service.

For getSchemaClassDefinition(), you need to create a new DirContext instance and bind as children nodes that represent the named object's class definitions. For example, if the named object is of classes "top" and "person", the DirContext instance will have two child DirContext nodes, one representing the definition for "top" and the other for "person". The "top" and "person" DirContexts are nodes in the "ClassDefinition" branch of the schema tree (the one pointed to by getSchema()).

Attribute Definitions

To implement the schema methods in the Attribute interface, you need to provide a class that implements this interface or provide a subclass of BasicAttribute that overrides the two schema methods. Your context implementation, when asked to return any Attribute, will then return instances of this class. If you use an in-memory schema tree as suggested earlier in this lesson, then getAttributeDefinition() will return a node from the "AttributeDefinition" branch of the schema tree, whereas getAttributeSyntaxDefinition() will return a node from the "SyntaxDefinition" branch.

Advanced Features

The DirContext nodes returned by the schema methods are full-fledged DirContext objects. This means that they are free to implement, or not, all of the methods available in the DirContext interface.

A context implementation should support updates to the schema objects only to the extent that corresponding updates are reflected in the schema data of the underlying directory service. For example, you should never allow a DirContext to be removed from the schema tree unless the corresponding schema definition is removed from the underlying directory service.

To the degree possible, a context implementation should support basic searches (that is, single context level, attribute matches) on the schema tree. Support for the advanced search is nice, but its return on investment is not as great because the schema tree is not very deep.

Optimizations

The schema tree is typically very expensive to generate. Generating it involves first reading schema data from the directory service and parsing the data and then constructing an in-memory tree. To improve performance, a context implementation can cache the schema tree so that it can be shared by multiple contexts. Of course, such sharing should be allowed only if doing so does not compromise correctness and security.

Adding Directory Support