| 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