Work in progress
This site is in the process of being reviewed and updated.
This page describes how to embed the server, using the trunk. It won't work with 1.5.4 as there is a problem in the way we built the apacheds-all-1.5.4.jar. A workaround is to load all the included jars, but it's a bit painful, as there are 32 jars to define (this list will be given at the end of this page}
Code for this sample :
EmbeddedADS.java
pom.xml
Embedding Apache Directory Server into an application
The idea is to use the server directly without having to communicate with a remote server, eliminating all the network layer. This is one of the reason ADS has been developed in Java : to allow such usage.
We will go through a very simple example step by step to show you how this can be done.
Setting up the environment
We first need to define a base for our project. Here is the structure we will use :
/
|
+--src
|
+--main
|
+--java : we will put all the sources into this directory
You will need some jars file in order to compile and run this sample when used with 1.5.4. If you are using the trunk, don't worry, a pom.xml with all the needed dependencies is attached.
* antlr-2.7.7.jar
* apacheds-bootstrap-extract-1.5.4.jar
* apacheds-bootstrap-partition-1.5.4.jar
* apacheds-core-1.5.4-sources.jar
* apacheds-core-avl-1.5.4.jar
* apacheds-core-cursor-1.5.4.jar
* apacheds-core-entry-1.5.4.jar
* apacheds-core-integ-1.5.4.jar
* apacheds-core-shared-1.5.4.jar
* apacheds-jdbm-1.5.4.jar
* apacheds-jdbm-store-1.5.4.jar
* apacheds-protocol-ldap-1.5.4-sources.jar
* apacheds-protocol-shared-1.5.4.jar
* apacheds-schema-bootstrap-1.5.4.jar
* apacheds-schema-registries-1.5.4.jar
* apacheds-server-integ-1.5.4.jar
* apacheds-utils-1.5.4.jar
* apacheds-xdbm-base-1.5.4.jar
* apacheds-xdbm-search-1.5.4.jar
* bcprov-jdk15-140.jar
* commons-collections-3.2.1.jar
* commons-io-1.3.2.jar
* commons-lang-2.4.jar
* junit-4.4-sources.jar
* log4j-1.2.14-sources.jar
* mina-core-1.1.7.jar
* mina-filter-ssl-1.1.7.jar
* shared-asn1-0.9.13.jar
* shared-asn1-codec-0.9.13.jar
* shared-ldap-0.9.13.jar
* shared-ldap-constants-0.9.13.jar
* slf4j-api-1.5.2-sources.jar
* slf4j-log4j12-1.5.2-sources.jar
We will also build the project using Maven 2.0.9. So we need a pom.xml to build the project. It has been attached.
Creating the application
So let's start with the code. It's quite simple : we define a class, add a main() method, and initialize the server, before using it. In the code snippet below, we have removed all the initialization part to keep only the main() method.
package org.apache.directory;
/**
* A simple exemple exposing how to embed Apache Directory Server
* inot an application.
*
* @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
* @version $Rev$, $Date$
*/
public class EmbeddedADS
{
/** The directory service */
private DirectoryService service;
/**
* Creates a new instance of EmbeddedADS. It initializes the directory service.
*
* @throws Exception If something went wrong
*/
public EmbeddedADS() throws Exception
{
init();
}
/**
* Main class. We just do a lookup on the server to check that it's available.
*
* @param args Not used.
*/
public static void main( String[] args ) //throws Exception
{
try
{
// Create the server
EmbeddedADS ads = new EmbeddedADS();
// Read an entry
Entry result = ads.service.getAdminSession().lookup( new LdapDN( "dc=apache,dc=org" ) );
// And print it if available
System.out.println( "Found entry : " + result );
}
catch ( Exception e )
{
// Ok, we have something wrong going on ...
e.printStackTrace();
}
}
}
As you can see, we first initialize the server, and immediately do a lookup to check that we can read an entry from it.
Let's focus on the initialization part now.
Initializing the server
This is done in the init() method. It will create the DirectoryService global object (service), and create a partition in which we will store the entries.
A partition is a storage point, associated with a DN, root point for this partition. It's a bit like a mounting point on Unix.
We also need a context entry associated to this DN.
Here, we will create the apache partition, associated with the 'dc=apache,dc=org' DN.
Here is the code for this method :
/**
* Initialize the server. It creates the partition, add the index, and
* inject the context entries for the created partitions.
*
* @throws Exception if there were some problems why initializing the system
*/
private void init() throws Exception
{
// Initialize the LDAP service
service = new DefaultDirectoryService();
// Disable the ChangeLog system
service.getChangeLog().setEnabled( false );
// Create a new partition named 'apache'.
Partition apachePartition = addPartition( "apache", "dc=apache,dc=org" );
// Index some attributes on the apache partition
addIndex( apachePartition, "objectClass", "ou", "uid" );
// And start the service
service.startup();
// Inject the apache root entry if it does not already exist
try
{
service.getAdminSession().lookup( apachePartition.getSuffixDn() );
}
catch ( LdapNameNotFoundException lnnfe )
{
LdapDN dnApache = new LdapDN( "dc=Apache,dc=Org" );
ServerEntry entryApache = service.newEntry( dnApache );
entryApache.add( "objectClass", "top", "domain", "extensibleObject" );
entryApache.add( "dc", "Apache" );
service.getAdminSession().add( entryApache );
}
// We are all done !
}
We disabled the ChangeLog service because it's useless in our case. As you can see, the steps to initialize the server are :
- create a new DirectoryService instance
- add a partition
- add some index
- start the service
- add the context entry
One important point : as the data are remanent, we have to check that the added context entry does not exist already before adding it. Here, we simply assume it does exist, and if not, we catch the exception we got, and create the entry.
Some helper methods have been used : addPartition and addIndex. Here they are :
/**
* Add a new partition to the server
*
* @param partitionId The partition Id
* @param partitionDn The partition DN
* @return The newly added partition
* @throws Exception If the partition can't be added
*/
private Partition addPartition( String partitionId, String partitionDn ) throws Exception
{
// Create a new partition named 'foo'.
Partition partition = new JdbmPartition();
partition.setId( partitionId );
partition.setSuffix( partitionDn );
service.addPartition( partition );
return partition;
}
/**
* Add a new set of index on the given attributes
*
* @param partition The partition on which we want to add index
* @param attrs The list of attributes to index
*/
private void addIndex( Partition partition, String... attrs )
{
// Index some attributes on the apache partition
HashSet<Index<?, ServerEntry>> indexedAttributes = new HashSet<Index<?, ServerEntry>>();
for ( String attribute:attrs )
{
indexedAttributes.add( new JdbmIndex<String,ServerEntry>( attribute ) );
}
((JdbmPartition)partition).setIndexedAttributes( indexedAttributes );
}
That's it ! (the attached code will contain the needed imports)
Building the sample
Using Maven 2.0.9, this is easy :
elecharny@elecharny-laptop:~/ws-ads-1.5.4/EmbeddedADS$ mvn clean install [INFO] Scanning for projects... [INFO] ------------------------------------------------------------------------ [INFO] Building ApacheDS Server Embedded sample [INFO] task-segment: [clean, install] [INFO] ------------------------------------------------------------------------ [INFO] [clean:clean] [INFO] Deleting directory /home/elecharny/ws-ads-1.5.4/EmbeddedADS/target [INFO] [resources:resources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:compile] [INFO] Compiling 1 source file to /home/elecharny/ws-ads-1.5.4/EmbeddedADS/target/classes [INFO] [resources:testResources] [INFO] Using default encoding to copy filtered resources. [INFO] [compiler:testCompile] [INFO] No sources to compile [INFO] [surefire:test] [INFO] No tests to run. [INFO] [jar:jar] [INFO] Building jar: /home/elecharny/ws-ads-1.5.4/EmbeddedADS/target/apacheds-embedded-sample-1.5.4.jar [INFO] [install:install] [INFO] Installing /home/elecharny/ws-ads-1.5.4/EmbeddedADS/target/apacheds-embedded-sample-1.5.4.jar to /home/elecharny/.m2/repository/org/apache/directory/server/apacheds-embedded-sample/1.5.4/apacheds-embedded-sample-1.5.4.jar [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 9 seconds [INFO] Finished at: Fri Dec 05 19:31:24 CET 2008 [INFO] Final Memory: 18M/82M [INFO] ------------------------------------------------------------------------ elecharny@elecharny-laptop:~/ws-ads-1.5.4/EmbeddedADS$
The resulting jar can be found in the target directory.
Running the sample
When the main method is run, you should obtain something like :
log4j:WARN No appenders could be found for logger (org.apache.directory.server.schema.registries.DefaultNormalizerRegistry).
log4j:WARN Please initialize the log4j system properly.
Found entry : ServerEntry
dn[n]: 0.9.2342.19200300.100.1.25=apache,0.9.2342.19200300.100.1.25=org
objectClass: extensibleObject
objectClass: domain
objectClass: top
dc: Apache
That's it !