xdocs/users/plugin.xml - directory-server - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>

 <document>
   <properties>
     <author email="akarasulu">akarasulu</author>
     <title>Plugin</title>
   </properties>
   <body>
     <section heading="h1" name="Maven Directory Plugin">
       <p>
 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:</p>
       <ol nesting="0">
         <li>
 Compiled hard coded files load into the server really fast in
 theory.</li>
         <li>
 Published schemas never really change so why do they need to be in a human
 readable
 form?</li>
         <li>
 Eventually, schema changes made through LDAP will be preserved through
 restarts.</li>
         <li>
 Extra code generation phase is not that hard with a plugin
 tool.</li>
         <li>
 Schema verification can occur before deploying schemas into the
 server.</li>
         <li>
 This was really easy for now but if people don't like it we can change
 it.</li>
       </ol>
       <subsection heading="h2" name="Properties">
         <table>
           <tr>
             <th>
 Property</th>
             <th>
 Optional?</th>
             <th>
 Description</th>
           </tr>
           <tr>
             <td>
 maven.ldap.server.schema.target.dir</td>
             <td>
 Yes</td>
             <td>
 Default value is
 target/schema</td>
           </tr>
           <tr>
             <td>
 maven.ldap.server.schema.ownerDefault</td>
             <td>
 Yes</td>
             <td>
 Default value is
 uid=admin,ou=system.</td>
           </tr>
           <tr>
             <td>
 maven.ldap.server.schema.dir</td>
             <td>
 Yes</td>
             <td>
 Default value is
 src/schema.</td>
           </tr>
           <tr>
             <td>
 maven.ldap.server.schema.packageDefault</td>
             <td>
 Yes</td>
             <td>
 Default value is
 org.apache.ldap.server.schema.bootstrap.</td>
           </tr>
         </table>
       </subsection>
       <subsection heading="h2" name="Goals">
         <table>
           <tr>
             <th>
 Goal</th>
             <th>
 Description</th>
           </tr>
           <tr>
             <td>
 directory:generate</td>
             <td>
 Generates class files for OpenLDAP
 schemas.</td>
           </tr>
           <tr>
             <td>
 directory:init</td>
             <td>
 Finds the required parameters needed for the goals of the
 plugin.</td>
           </tr>
           <tr>
             <td>
 directory:prepare-filesystem</td>
             <td>
 Creates source output directories used to deposite schema files that are
 generated.</td>
           </tr>
           <tr>
             <td>
 directory:schema</td>
             <td>
 Top level schema generating function that uses other goals to coordinate
 generation.</td>
           </tr>
         </table>
         <p>
 Take a look at how we integrate this into the directory server
 build
           <a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/">here</a>
 .
         </p>
       </subsection>
     </section>
     <section heading="h1" name="How to Integrate Plugin Into Your Own Projects">
       <p>
 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:</p>
       <ol nesting="0">
         <li>
 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.</li>
         <li>
 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.</li>
         <li>
 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.</li>
         <li>
 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</li>
         <li>
 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.</li>
       </ol>
       <p>
 Once setup you can invoke maven to generate the schema sources like
 so:</p>
       <source>[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
 </source>
       <p>
 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
         <a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/project.properties?rev=125094&amp;view=auto">project.properties</a>
 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.
       </p>
       <p>
 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.</p>
     </section>
     <section heading="h1" name="Functionality for the Future">
       <ul nesting="1">
         <li>
 Compile triggers and install them into the
 server.</li>
         <li>
 Compile and load stored
 procedures.</li>
         <li>
 Test stored procedures and
 triggers.</li>
         <li>
 Generate JNDI Object and State factories from
 schemas.</li>
       </ul>
     </section>
   </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>

	<document>
	<properties>
	<author email="akarasulu">akarasulu</author>
	<title>Plugin</title>
	</properties>
	<body>
	<section heading="h1" name="Maven Directory Plugin">
	<p>
	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:</p>
	<ol nesting="0">
	<li>
	Compiled hard coded files load into the server really fast in
	theory.</li>
	<li>
	Published schemas never really change so why do they need to be in a human
	readable
	form?</li>
	<li>
	Eventually, schema changes made through LDAP will be preserved through
	restarts.</li>
	<li>
	Extra code generation phase is not that hard with a plugin
	tool.</li>
	<li>
	Schema verification can occur before deploying schemas into the
	server.</li>
	<li>
	This was really easy for now but if people don't like it we can change
	it.</li>
	</ol>
	<subsection heading="h2" name="Properties">
	<table>
	<tr>
	<th>
	Property</th>
	<th>
	Optional?</th>
	<th>
	Description</th>
	</tr>
	<tr>
	<td>
	maven.ldap.server.schema.target.dir</td>
	<td>
	Yes</td>
	<td>
	Default value is
	target/schema</td>
	</tr>
	<tr>
	<td>
	maven.ldap.server.schema.ownerDefault</td>
	<td>
	Yes</td>
	<td>
	Default value is
	uid=admin,ou=system.</td>
	</tr>
	<tr>
	<td>
	maven.ldap.server.schema.dir</td>
	<td>
	Yes</td>
	<td>
	Default value is
	src/schema.</td>
	</tr>
	<tr>
	<td>
	maven.ldap.server.schema.packageDefault</td>
	<td>
	Yes</td>
	<td>
	Default value is
	org.apache.ldap.server.schema.bootstrap.</td>
	</tr>
	</table>
	</subsection>
	<subsection heading="h2" name="Goals">
	<table>
	<tr>
	<th>
	Goal</th>
	<th>
	Description</th>
	</tr>
	<tr>
	<td>
	directory:generate</td>
	<td>
	Generates class files for OpenLDAP
	schemas.</td>
	</tr>
	<tr>
	<td>
	directory:init</td>
	<td>
	Finds the required parameters needed for the goals of the
	plugin.</td>
	</tr>
	<tr>
	<td>
	directory:prepare-filesystem</td>
	<td>
	Creates source output directories used to deposite schema files that are
	generated.</td>
	</tr>
	<tr>
	<td>
	directory:schema</td>
	<td>
	Top level schema generating function that uses other goals to coordinate
	generation.</td>
	</tr>
	</table>
	<p>
	Take a look at how we integrate this into the directory server
	build
	<a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/">here</a>
	.
	</p>
	</subsection>
	</section>
	<section heading="h1" name="How to Integrate Plugin Into Your Own Projects">
	<p>
	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:</p>
	<ol nesting="0">
	<li>
	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.</li>
	<li>
	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.</li>
	<li>
	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.</li>
	<li>
	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</li>
	<li>
	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.</li>
	</ol>
	<p>
	Once setup you can invoke maven to generate the schema sources like
	so:</p>
	<source>[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
	</source>
	<p>
	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
	<a href="http://svn.apache.org/viewcvs.cgi/directory/apacheds/trunk/core/project.properties?rev=125094&view=auto">project.properties</a>
	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.
	</p>
	<p>
	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.</p>
	</section>
	<section heading="h1" name="Functionality for the Future">
	<ul nesting="1">
	<li>
	Compile triggers and install them into the
	server.</li>
	<li>
	Compile and load stored
	procedures.</li>
	<li>
	Test stored procedures and
	triggers.</li>
	<li>
	Generate JNDI Object and State factories from
	schemas.</li>
	</ul>
	</section>
	</body>
	</document>