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)

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 !