Maven Directory Plugin
Currently the primary function of the plugin is to generate server class files
for OpenLDAP schemas. These class files contain hard coded schema objects
representing those found in the OpenLDAP files. Why bother you may ask? There
are a few reasons for
this:
-
Compiled hard coded files load into the server really fast in
theory.
-
Published schemas never really change so why do they need to be in a human
readable
form?
-
Eventually, schema changes made through LDAP will be preserved through
restarts.
-
Extra code generation phase is not that hard with a plugin
tool.
-
Schema verification can occur before deploying schemas into the
server.
-
This was really easy for now but if people don't like it we can change
it.
Properties
Property |
Optional? |
Description |
maven.ldap.server.schema.target.dir |
Yes |
Default value is
target/schema |
maven.ldap.server.schema.ownerDefault |
Yes |
Default value is
uid=admin,ou=system. |
maven.ldap.server.schema.dir |
Yes |
Default value is
src/schema. |
maven.ldap.server.schema.packageDefault |
Yes |
Default value is
org.apache.ldap.server.schema.bootstrap. |
Goals
Goal |
Description |
directory:generate |
Generates class files for OpenLDAP
schemas. |
directory:init |
Finds the required parameters needed for the goals of the
plugin. |
directory:prepare-filesystem |
Creates source output directories used to deposite schema files that are
generated. |
directory:schema |
Top level schema generating function that uses other goals to coordinate
generation. |
Take a look at how we integrate this into the directory server
build
here
.
How to Integrate Plugin Into Your Own Projects
You want to use the plugin to generate classes for your own schema. Here's a
step wise process you can follow to do that using
maven:
-
Place your schema files (i.e. *foo.schema*) with the schema extension into
$\{basedir\}/src/main/schema. If you opt to store it in another location you
must override the maven.ldap.server.schema.dir property in your
project.properties file. For each schema file add the file base name to the
maven.ldap.server.schemas property which is a space separated
list.
-
The plugin will by default generate java files within the
$\{basedir\}/target/schema directory. If you would like to generate code
elsewhere you must override the maven.ldap.server.schema.target.dir property in
your project.properties
file.
-
By default the plugin generates code in a server schema package:
org.apache.ldap.server.schema.bootstrap. If you want generated code for a schema
to be put into a package other than this, then you're going to need to set the
package property for the schema. The package property key is composed of the
following base, maven.ldap.server.schema.package. with the name of the schema
(without the extension) appended to it. So for schema file foo.schema the
following property key would be used: maven.ldap.server.schema.package.foo where
foo is the schema
name.
-
Using the same pattern above for all schema specific properties you can set
other per schema properties as well. One of these properties is the dependency
list for a schema. Schemas can obviously depend on others. The schema dependency
list is a comma separated list of other schema names. These schemas need not be
present in your project to generate the code for your schema. The dependent
schema classes must however be present within the server at start up time in
order to load and use your schema. At the end we list the default schemas
already packaged into the server's jar. You can use any one of these schemas as
dependencies needed by your schema and not worry about their presence. The
property key base for the schema dependency list is
maven.ldap.server.schema.deps. and for a foo.schema file the full key would be
maven.ldap.server.schema.deps.foo
-
Each schema has an owner associated with it. If you want the owner to be
anything other than the server's super user you may want to set the owner
property for the schema in your project.properties file. The property key base
for the schema is maven.ldap.server.schema.owner. so don't forget to append the
schema name to
it.
Once setup you can invoke maven to generate the schema sources like
so:
[akarasulu@newton dib]$ maven directory:schema
__ __
| \/ |__ _Apache__ ___
| |\/| / _` \ V / -_) ' \ ~ intelligent projects ~
|_| |_\__,_|\_/\___|_||_| v. 1.0.2
Attempting to download ldap-common-0.8.0-SNAPSHOT.jar.
Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar.
Attempting to download apacheds-protocol-0.8.0-SNAPSHOT.jar.
Attempting to download snickers-codec-0.2.0-SNAPSHOT.jar.
Attempting to download ldap-snickers-provider-0.8.0-SNAPSHOT.jar.
Attempting to download snickers-ber-0.2.0-SNAPSHOT.jar.
Attempting to download seda-0.2.0-SNAPSHOT.jar.
Attempting to download maven-directory-plugin-0.8.0-SNAPSHOT.jar.
Attempting to download ldap-common-0.8.0-SNAPSHOT.jar.
Attempting to download apacheds-shared-0.8.0-SNAPSHOT.jar.
build:start:
directory:schema:
directory:init:
directory:prepare-filesystem:
directory:generate:
[echo] Generated schema producer classes for autofs.schema
[echo] Generated schema producer classes for core.schema
[echo] Generated schema producer classes for cosine.schema
[echo] Generated schema producer classes for corba.schema
[echo] Generated schema producer classes for eve.schema
[echo] Generated schema producer classes for inetorgperson.schema
[echo] Generated schema producer classes for java.schema
[echo] Generated schema producer classes for krb5kdc.schema
[echo] Generated schema producer classes for nis.schema
[echo] Generated schema producer classes for system.schema
[echo] Generated schema producer classes for scheduleworld.schema
[touch] Creating /home/akarasulu/projects/directory/server/trunk/core/target/schema/.flagfile
BUILD SUCCESSFUL
Total time: 28 seconds
Finished at: Tue Dec 14 15:26:26 EST 2004
The example above is from the server's core project. If you would like to look
at how to use this plugin best the server
core
project.properties
file here is perhaps the best place to look. Also from the output above you can
see the schema files that are used and packaged into the server by default. This
may however change in the future to restrict the
set.
WARNING: As a last bit of advice make note that the plugin may be sensitive to
case for keywords in the OpenLDAP file. For example the prefix before an
objectClass or an attributeType must be in all lowercase. However words like
MUST, and MAY and SUP should all be in uppercase. So if plugin bombs just check
out where this happens and play with the case. Another thing to watch out for is
the order of terms. This we follow the RFC for which is pretty much the same as
the OpenLDAP format minus the objectclass and attributetype prefixes to the
descriptions. We figure the OpenLDAP parser is less complex if the prefixes are
there (where the parser is told if the description is an objectclass or
attributetype and does not have to figure this out). However I have encountered
schemas whose formats do not comply with standards in with respect to the order
of description fields and had to edit the files. This issue did not occur when
the files were from the OpenLDAP Foundation which means they do it right but
overlook schema objects that are not correctly
formated.
Functionality for the Future
-
Compile triggers and install them into the
server.
-
Compile and load stored
procedures.
-
Test stored procedures and
triggers.
-
Generate JNDI Object and State factories from
schemas.