Custom Schema

Background

ApacheDS 1.0 does not support dynamic schema updates via the LDAP protocol. This feature will be added in the future however you can still change the schema used by ApacheDS. It just requires a restart.

There are included schemas that can be loaded by ApacheDS by changing it's server.xml configuration file. This is explained in the first section below. The real goal of this wiki page however is to teach you how to write your own schema and use it with ApacheDS.

To do this properly you don't need to know much about how ApacheDS does schema. However it's good to know.

ApacheDS loads schema information from a compiled representation. OpenLDAP formated schema files are processed by a plugin called the apacheds-schema-plugin to generate a set of compiled .class files. These .class files contain producers which create the various schema elements in your custom schema. All the generated code is hardwired to generate your schema so it's pretty fast.

These classes need to be on the system classpath in order for ApacheDS to load them on startup. The included classes are automatically bundled into the core of ApacheDS. In this wiki we'll show you how to generate these classes for your schema, and have ApacheDS load them from a Jar file. We have tools to help you do this so don't worry it should be a cake walk.

Adding/Removing Included Published Schemas

If you want to use and existing optional schema included with ApacheDS you can modify the configuration of ApacheDS to load it. Here's the set of schemas available:

• Apache (mandatory)
• Apachedns
• Autofs
• Collective (mandatory)
• Corba
• Core (mandatory)
• Cosine (recommended)
• Dhcp
• Inetorgperson (recommended)
• Krb5kdc
• Misc
• Mozilla
• Nis
• Samba
• System (mandatory)

You can modify the bootstrap schemas configuration section to load any of these included schemas or not load some of them. Make sure you do not disable mandatory schemas or ApacheDS will not operate properly. Here's a look at the schema configuration section of a server.xml (ApacheDS configuration) file:

<property name="bootstrapSchemas">
      <set>
        <bean class="org.apache.directory.server.core.schema.bootstrap.AutofsSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.CorbaSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.CoreSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.CosineSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.ApacheSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.CollectiveSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.InetorgpersonSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.JavaSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.Krb5kdcSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.NisSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.SystemSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.ApachednsSchema"/>
      </set>
    </property>

To add another schema like the Samba schema just add this line for example to this section:

...
        <bean class="org.apache.directory.server.core.schema.bootstrap.ApachednsSchema"/>
        <bean class="org.apache.directory.server.core.schema.bootstrap.SambaSchema"/>
      </set>
    </property>

Creating a Maven module for your custom schema

You want to create a Maven project for your custom schema. First you want to do this because you'll probably need to make changes to your schema as you stabilize it via edit, compile, and generate (a jar file) cycles. This iterative process should be fast and should not be a hindrance.

To easily create a Maven project, we've created (just for this purpose) a Maven archetype. You'll want to checkout and install this archetype so you can use it with maven. Here's how to do that:

svn co http://svn.apache.org/repos/asf/directory/apacheds/tags/1.0.2/schema-archetype/ 
cd schema-archetype
mvn install

Once the archetype is installed you can now generate a schema project with it. Let's presume we want to generate a schema project where our schema is in a package called com.acme and the generated artifact's id is foo-schema. You can either use Maven directly to generate this project or you can use the shell script that's sitting in the schema-archetype directory you just checked out. Here's how to get Maven to generate your foo-schema project for the com.acme package and groupId:

apacheds-schema-archetype.sh com.acme foo-schema

Once you've generated with success you'll see a new foo-schema directory created. This is the maven module that will generate your schema file. From the onset we included an example schema called car.schema which has a few attributeTypes defined and a car objectClass. It's there as a placeholder. Before we go into how to customize this stuff let's look at the tree of the new project:

akarasulu@newton:~/foo-schema$ tree
.
|-- pom.xml
`-- src
    |-- main
    |   |-- java
    |   |   `-- com
    |   |       `-- acme
    |   |           `-- Dummy.java
    |   |-- resources
    |   `-- schema
    |       `-- car.schema
    `-- test
        |-- java
        |   `-- com
        |       `-- acme
        |           `-- SchemaTest.java
        `-- resources
            `-- log4j.properties

12 directories, 5 files

Let me explain what the various leaf elements here are.

• The pom.xml is the project object model file for Maven. Yall should know what this is for. Later you'll need to edit this file to take my.schema instead of the example car.schema and generate sources for it.
• The Dummy.java class is simply a placeholder. We have no sources that are not automatically generated so I added this placeholder class to the archetype to make sure Maven works right.
• car.schema is a simple example schema file. You'll most likely remove this after trying to generate it's example schema. We'll walk you through replacing this file with your own my.schema file. Take a look inside to see what's in here.
• What's this test case about? I did not ask for that! The SchemaTest test case is a simple test which embeds ApacheDS and runs it with your schema installed. Right now it works for the car schema. You'll want to change it later so it installs your schema instead and runs tests against ApacheDS life. Right now two test case methods are present in this integration test: (1) that tests to make sure the schema elements are visible in the DIT's schemaSubentry at cn=schema,ou=system; (2) another test that creates a Car entry with the example schema then re-reads it from the directory. Feel free to take a look at the test case's contents: (hint) it shows how to do integration tests with ApacheDS.
• log4j.properties are for having a logger with the embedded ApacheDS instance that is started by the schema test case. You can mess with this to see what ApacheDS is doing during your test. Just for the heck of it feel free to open it and switch debug output mode form ERROR to DEBUG. Hold on to your seat as the log statements fly by.

Compiling, and running tests on the example car.schema

Ok before replacing the car.schema with your custom my.schema file try to compile and test this example schema. Just cd into foo-schema and issue the 'mvn package' command. This will generate the car.schema classes, compile them, fire up apacheds and test that the schema is present and can be used. It will then finishs off to generate the jar file for your schema: foo-schema-1.0-SNAPSHOT.jar.

Replacing car.schema with my.schema

Ok fine the car example stuff works. Let's remove car.schema and start using our own my.schema file instead:

1. rename car.schema to my.schema for now ( you can edit the contents later )
2. on line 50 edit the pom.xml replacing the content in the <name> tag which is car in the plugin section to my
3. feel free to change the dependencies of your schema (see schema dependencies section for more info)
4. on line 62 rename CarSchema to MySchema in the TestCase file foo-schema/src/test/java/com/acme/SchemaTest.java
5. if you changed the contents of car.schema you'll want to change the test methods of the SchemaTest. Otherwise, you may want to remove the test.

Schema Dependencies

In the pom.xml you saw a section where you can list schemas which your schema depends on. As you might already know your attributeType descriptions and your objectClass descriptions may depend on objects defined in other schemas. If so you'll need to add the appropriate dependency schemas. If at any point there is a question of which schema contains your dependencies you can grep the files here:

http://misverom.notlong.com

The file containing your schema element description is the one whose name (minus the extension) you list in the dependencies section. Even though the car schema does not use any of it's dependencies we've listed a couple dependent schemas just as an example. Doing so costs nothing.

Using your new schema

Now that you can generate a jar file with your new schema you're going to want to install it within the server and use it. There are two ways you can do this depending on whether you're using ApacheDS in an embedded configuration or in a standalone installation. In both cases you need your generated jar file, foo-schema-1.0-SNAPSHOT.jar in our example, to be put on the system classpath. Also in both cases this will be easy to do.

Using your schema in an embedded configuration

In this section we presume you have added your schema jar file to the system classpath somehow for your embedding application. This might be specific to your app.

As you saw in the SchemaTest.java file, adding a schema to an embedded instance of ApacheDS is trivial. You simply have to replace the set of BootstrapSchemas that are set in the configuration object before starting up the server. Just create an instance of your new schema and add it to a MutableStartupConfiguration object like so:

MutableStartupConfiguration configuration = new MutableStartupConfiguration();
Set schemas = new HashSet();
schemas.addAll( configuration.getBootstrapSchemas() );
schemas.add( new MySchema() );
configuration.setBootstrapSchemas( schemas );
...

Using your schema with a standalone installation

First of all you want to add your jar to the ${installHome}/lib directory. This will automatically pick up your jar and add it to the classpath when the server starts.

Next you need to edit your server.xml configuration file. Open it up and goto the bootstrap schema configuration section. There you'll see several schema classes listed using their fully qualified names. You need to add your schema to the list of schemas. Here's how the stock server.xml file's bootstrap schema section should look after you add your MySchema to it:

<property name="bootstrapSchemas">
  <set>
    <bean class="org.apache.directory.server.core.schema.bootstrap.AutofsSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.CorbaSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.CoreSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.CosineSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.ApacheSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.CollectiveSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.InetorgpersonSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.JavaSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.Krb5kdcSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.NisSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.SystemSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.ApachednsSchema"/>
    <bean class="org.apache.directory.server.core.schema.bootstrap.MySchema"/>
  </set>
</property>

An that's it. You now can start up the server and your schema should be available for use. With your favorate LDAP browser now you should be able to create new entries containing your schema's objectClasses and their respective attributeTypes.