Schema

Attribute Type Definitions

An attribute type definition specifies the attribute's syntax and how attributes of that type are compared and sorted. The attribute types in the directory form a class hierarchy. For example, the "commonName" attribute type is a subclass of the "name" attribute type. However, not many LDAP servers support attribute subclassing.

In the schema tree, the name "AttributeDefinition" is bound to a flat context that contains DirContext objects that represent attribute type definitions in the schema. For example, if a directory supports a "commonName" attribute, then the "AttributeDefinition" context will have a binding with the name "commonName" that is bound to a DirContext object.

Each object in the "AttributeDefinition" context has the mandatory and optional attributes listed in the following table.
 

Attribute Identifier	Attribute Value Description
NUMERICOID (mandatory)	Unique object identifier (OID)
NAME	Attribute's name
DESC	Attribute's description
OBSOLETE	"true" if obsolete; "false" or absent otherwise
SUP	Name of superior attribute type from which this attribute's type is derived
EQUALITY	Name or OID of the matching rule if equality matching is allowed; absent otherwise
ORDERING	Name or OID of the matching rule if ordering matching is allowed; absent otherwise
SUBSTRING	Name or OID of the matching rule if substring matching is allowed; absent otherwise
SYNTAX	Numeric OID of the syntax of values of this type
SINGLE-VALUE	"true" if the attribute not multivalued; "false" or absent otherwise.
COLLECTIVE	"true" if the attribute is collective; "false" or absent otherwise.
NO-USER-MODIFICATION	"true" if the attribute is not user-modifiable; "false" or absent otherwise.
USAGE	Description of attribute usage

These attributes correspond to the definition of "AttributeTypeDescription" in RFC 2252. All of the attribute values are represented by the java.lang.String class. Some directories do not publish all of the schema data. For example, the Netscape Directory Server v4.1 does not publish the equality, ordering, and substring rules for its attribute definitions even though the server does support them for certain attributes. In these cases, the schema objects do not completely describe the attribute definitions.

Retrieving the Schema Object of an Attribute Type Definition

To retrieve the schema object of an attribute type definition, you look for it in the schema tree. For example, you can obtain the schema object representing the "cn" attribute by using the following code.

// Get the schema tree root
DirContext schema = ctx.getSchema("");

// Get the schema object for "cn"
DirContext cnSchema = (DirContext)schema.lookup("AttributeDefinition/cn");

If you get the attributes of the cnSchema schema object, then you will see the following.

NUMERICOID: 2.5.4.3
NAME: cn 
SYNTAX: 1.3.6.1.4.1.1466.115.121.1.15 
DESC: Standard Attribute

You can use not only lookup() to retrieve schema objects from the schema tree, but also methods such as list() or search().

Getting an Attribute's Type Definition

Given an Attribute object that represents an LDAP attribute, you can get its schema object by invoking getAttributeDefinition() on it. Thus another way of getting the schema object for "cn" is to get a "cn" attribute and then invoke getAttributeDefinition(). Here's an example.

// Get an attribute of that type
Attributes attrs = ctx.getAttributes("cn=Ted Geisel, ou=People",
    new String[]{"cn"});
Attribute cnAttr = attrs.get("cn");

// Get its attribute type definition
DirContext cnSchema = cnAttr.getAttributeDefinition();

Adding a New Attribute Type Definition

---

Before you go on: See the Object Class Definitions section for notes regarding updating the schema.

---

Adding a new attribute type definition to the schema is like adding a new entry to the directory. This is because the schema tree and schema objects are DirContext objects.

Here's an example that adds a new attribute type definition ("fooAttr") to the schema. It first declares the attributes that describe the new attribute type definition and then adds the definition to the schema by using DirContext.createSubcontext().

// Specify attributes for the schema object
Attributes attrs = new BasicAttributes(true); // Ignore case
attrs.put("NUMERICOID", "1.3.6.1.4.1.42.2.27.4.2.3.1.1.2");
attrs.put("NAME", "fooAttr");
attrs.put("DESC", "for JNDITutorial example only");
attrs.put("SYNTAX", "1.3.6.1.4.1.1466.115.121.1.15");

// Get the schema tree root
DirContext schema = ctx.getSchema("");

// Add the new schema object for "fooAttr"
DirContext newAttr = schema.createSubcontext("AttributeDefinition/fooAttr", attrs);

Some servers might modify the definition before adding it to the schema. To check the newly added definition, use a new initial context to read the definition so that any cached definition is not used.

Modifying an Attribute Type Definition

---

Note: In versions of the LDAP provider prior to the Java 2 SDK, v1.4, you cannot modify an existing attribute definition. In those releases, you must first delete the existing definition and then add the updated version.

Before you go on: See the Adding a New Object Class section for notes regarding updating the schema.

---

Modifying an existing attribute definition in the schema is like modifying an entry in the directory. Here's an example that modifies the "fooAttr" attribute definition to be single-valued by using DirContext.modifyAttributes().

// Get the schema tree root
DirContext schema = ctx.getSchema("");

// Modify the schema object for "fooAttr"
schema.modifyAttributes("AttributeDefinition/fooAttr",
    new ModificationItem[]{new ModificationItem(
	DirContext.ADD_ATTRIBUTE, 
	new BasicAttribute("SINGLE-VALUE", "true"))});

Some servers might modify the definition before performing the update on the schema or ignore the update. To check the newly updated definition, use a new initial context to read the definition so that any cached definition is not used.

Deleting an Attribute Type Definition

---

Before you go on: See the Object Class Definitions section for notes regarding updating the schema.

---

Deleting an existing attribute type definition from the schema is like deleting an entry from the directory. Here's an example that removes the attribute type definition "fooAttr" from the schema by using DirContext.destroySubcontext().

// Get the schema tree root
DirContext schema = ctx.getSchema("");

// Remove the schema object for "fooAttr"
schema.destroySubcontext("AttributeDefinition/fooAttr");

Some servers might not let you delete an attribute type definition that's being used by entries in the directory. You might be able to get around this restriction by turning off schema checking.

Schema