Add your first elements to the schema

This section shows how to define custom schema elements, and how to add them to an ApacheDS 1.5.0 instance.

Motivation

The schema of an LDAP server is comprised of object classes, attributes, syntaxes and matching rules. Basically it defines which entries are allowed within the server and how the server should handle them. In contrast to the 1.0 release, ApacheDS 1.5.0 comes with a completely redesigned schema subsystem. It enables dynamic schema updates, like the creation of new attribute types or object classes at runtime (i.e. without restarting the server).

In the following text the addition of user defined schema elements to the schema is described in tutorial style.

Browsing the schema of ApacheDS

LDAPv3 servers publish their schema via LDAP. Thus it is possible to list the schema elements with standard LDAP tools. For instance it is possible to use the ldapsearch command line tool to list all object classes

$ ldapsearch -h zanzibar -p 10389 -D "uid=admin,ou=system" -w ****** \
     -b "cn=schema" -s base "(objectclass=subschema)" objectclasses
...
objectClasses: ( 2.5.6.6 NAME 'person' DESC 'RFC2256: a person' SUP top 
  STRUCTURAL MUST ( sn $ cn ) MAY ( userPassword $ telephoneNumber $ 
  seeAlso $ description ) X-SCHEMA 'core' )
...

The output contains all things which are interesting to know about an object class (required attributes, optional attributes etc.), but is not easy to read by a human user. It is therefore often appropriate to use a GUI tool to browse the schema (which basically performs the same search operations but presents the output prettily). One option is Apache Directory LDAP Studio, an Eclipse based LDAP tool set which contains a powerful graphical Schema browser:

The techniques described above work for all LDAP v3 compliant servers. The ability to browse the schema gives us a chance to check whether our future changes to the schema really took please.

The schema subsystem of ApacheDS 1.5 stores the schema elements as entries in the DIT. You can find them within a special partition with suffix ou=schema; simply browse the content with your favorite LDAP Browser. With LDAP Studio, it looks like this:

Browsing the schema like this gives a good impression of the ApacheDS implementation of the schema subsystem and an even better way to analyze effects during schema updates. But keep in mind that the storage scheme is server dependent; not all LDAP server implementations store the schema elements in the DIT.

A simple example

The goal is to add ship entries to our directory, backing the "Seven Seas" example used throughout the Basic User's Guide. Here is a sample entry in LDIF:

dn: cn=HMS Victory,ou=ships,o=sevenSeas
objectClass: top
objectClass: ship
cn: HMS Victory
numberOfGuns: 104
description: a ship of the line of the Royal Navy, built between 1759 and 1765

A new attribute type numberOfGuns and a new object class ship have to be added to the schema. There are different ways to accomplish the task. In any case, we have to add the attribute type first, because the object class refers to it.

attribute type numberOfGuns

( 1.3.6.1.4.1.18060.0.4.3.2.1 NAME 'numberOfGuns' 
  DESC 'Number of guns of a ship'  EQUALITY integerOrderingMatch 
  SYNTAX 1.3.6.1.4.1.1466.115.121.1.27 SINGLE-VALUE 
  USAGE userApplications X-SCHEMA 'other' )

object class ship

A ship entry is comprised of a mandatory value for common name (cn) of the ship, description values and the number of guns (the custom attribute described above).

( 1.3.6.1.4.1.18060.0.4.3.3.1 NAME 'ship' 
  DESC 'An entry which represents a ship' SUP top STRUCTURAL MUST cn 
  MAY ( numberOfGuns $ description ) X-SCHEMA 'other' )

Which OIDs should I use?

Using LDIF to define and load the new schema elements

Using JNDI to add the schema elements programatically

Adding the attribute type

import javax.naming.NamingException;
import javax.naming.directory.Attributes;
import javax.naming.directory.BasicAttributes;
import javax.naming.directory.DirContext;
import javax.naming.directory.InitialDirContext;

public class CreateAttributeType {

    public static void main(String[] args) throws NamingException {

        DirContext ctx = new InitialDirContext();
        DirContext schema = ctx.getSchema("");

        Attributes attrs = new BasicAttributes(true);
        attrs.put("NUMERICOID", "1.3.6.1.4.1.18060.0.4.3.2.1");
        attrs.put("NAME", "numberOfGuns");
        attrs.put("DESC", "Number of guns of a ship");
        attrs.put("SINGLE-VALUE", "true");
        attrs.put("SYNTAX", "1.3.6.1.4.1.1466.115.121.1.27");
        attrs.put("EQUALITY", "integerOrderingMatch");
        
        schema.createSubcontext("AttributeDefinition/numberOfGuns", attrs);
    }
}

Adding the object class

import javax.naming.NamingException;
import javax.naming.directory.Attribute;
import javax.naming.directory.Attributes;
import javax.naming.directory.BasicAttribute;
import javax.naming.directory.BasicAttributes;
import javax.naming.directory.DirContext;
import javax.naming.directory.InitialDirContext;

public class CreateObjectClass {

    public static void main(String[] args) throws NamingException {

        DirContext ctx = new InitialDirContext();
        DirContext schema = ctx.getSchema("");

        Attributes attrs = new BasicAttributes(true);
        attrs.put("NUMERICOID", "1.3.6.1.4.1.18060.0.4.3.3.1");
        attrs.put("NAME", "ship");
        attrs.put("DESC", "An entry which represents a ship");
        attrs.put("SUP", "top");
        attrs.put("STRUCTURAL", "true");
        
        Attribute must = new BasicAttribute("MUST");
        must.add("cn");
        attrs.put(must);
        
        Attribute may = new BasicAttribute("MAY");
        may.add("numberOfGuns");
        may.add("description");
        attrs.put(may);

        schema.createSubcontext("ClassDefinition/ship", attrs);
    }
}

Verification of the change

Using the new schema elements

Resources