Custom Schema

Background

ApacheDS 1.0 .x 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.

...

svn co http://svn.apache.org/repos/asf/directory/branchesapacheds/apachedstags/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:

mvn archetype:create -DarchetypeGroupId=org.apache.directory.server \
                     -DarchetypeArtifactId=apacheds-schema-archetype \
                     -DarchetypeVersion=1.0-RC4-SNAPSHOT \
                     -DgroupId=com.acme -DartifactId=foo-schema
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:

...

• 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:

...

• 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:

...