Draft - How to write a simple custom partition for ApacheDS has been edited by Stefan Zoerner (Nov 16, 2008).

(View changes)

Content:
Be Careful

Work in progress. Any feedback highly appreciated!

Writing a simple custom partition for ApacheDS

On the mailing list, people ask regularly on how to write a custom partition. Please note that this is not an easy task. Nevertheless I try to give you a starting point with some simple examples.

If you simply plan to add another suffix to ApacheDS (besides example.com, for instance), it is not necessary to write any code. You can simply add some lines to the configuration.

The following is for those who plan to use another storage mechanism than the provided default.

What exactly is a partition?

Within ApacheDS, a partition is a physically distinct store for a subset of the entries contained within the server. A partition can be implemented using any storage mechanism or can even be backed in memory. The default storage mechanism for a partition is JDBM.

Implementing your own partition is basically implementing the Partition interface from the org.apache.directory.server.core.partition package.

Hello world. A minimal partition

Let's start with a minimal partition, the hello world. Minimal means here, that it is possible to add it to ApacheDS and see it with an LDAP browser. The partition ...

  • correctly implements the Partition interface
  • is pluggable in the server (embedded and declarative in the configuration)
  • is visible for clients like ldapsearch or Apache Directory Studio
  • contains one entry, which contains the famous "hello, world" message in an attribute value
  • does not support any modification operations like delete, add etc.
  • does not take account of filters in search requests, ...

The sources

Currently, the sources are checked in here

In order to build it, simply check it out and type "mvn install".

Implementing the class HelloWorldPartition

The following UML class diagram depicts the structure of the little example.

In order to be a partition, class HelloWorldPartition implements the corresponding interface from org.apache.directory.server.core.partition. It has an association to it's only entry (which will hold the "hello, world" method). This entry is created in the init life cycle method of the partition, which looks like this:

...
public void init(DirectoryService core) throws Exception {
                        
  // Create LDAP DN
  suffixDn = new LdapDN(suffix);
  suffixDn.normalize(core.getRegistries().getAttributeTypeRegistry().getNormalizerMapping());
  Rdn rdn = suffixDn.getRdn();
        
  // Create the only entry in this partition
  ServerEntry entry = new DefaultServerEntry(core
          .getRegistries(), this.suffixDn);
  entry.put(SchemaConstants.OBJECT_CLASS_AT, SchemaConstants.TOP_OC,
                SchemaConstants.ORGANIZATIONAL_UNIT_OC);        
  entry.put(SchemaConstants.OU_AT, rdn.getUpValue().toString());
  entry.put("description", "hello, world", "a minimal partition");
        
  this.helloEntry = entry;
}
...

The Partition interface requires to implement many methods for all the operations a partition should support (adding, deleting, modifying entries ...). Due to the fact, that this is a read only partition, the implementation in our case is minimalistic. Here is the delete method as an example.

...
public void delete(DeleteOperationContext opContext)
        throws LdapOperationNotSupportedException {
    throw new LdapOperationNotSupportedException(
            MODIFICATION_NOT_ALLOWED_MSG, ResultCodeEnum.UNWILLING_TO_PERFORM);
}
...

TBD: search

Using the partition

Embedded mode

package org.apache.directory.samples.partition.hello;

import org.apache.directory.server.core.DefaultDirectoryService;
import org.apache.directory.server.core.DirectoryService;
import org.apache.directory.server.ldap.LdapService;

import org.apache.directory.server.protocol.shared.SocketAcceptor;

public class Main {

    public static void main(String[] args) throws Exception {
        DirectoryService directoryService;

        SocketAcceptor socketAcceptor;
        LdapService ldapService;

        directoryService = new DefaultDirectoryService();
        directoryService.setShutdownHookEnabled(true);

        socketAcceptor = new SocketAcceptor(null);
        ldapService = new LdapService();
        ldapService.setSocketAcceptor(socketAcceptor);
        ldapService.setDirectoryService(directoryService);
        ldapService.setIpPort(10389);

        HelloWorldPartition helloPartition = new HelloWorldPartition();
        helloPartition.setSuffix("ou=helloWorld");
        helloPartition.init(directoryService);
        
        directoryService.addPartition(helloPartition);       
        
        directoryService.startup();
        ldapService.start();
    }
}

Adding it to a server.xml file

In order to use the partition in a standard installation of ApacheDS, simply add it to the server.xml configuration. Provide a "native" Spring bean like this.

server.xml
<spring:beans xmlns:spring="http://xbean.apache.org/schemas/spring/1.0" 
			  xmlns:s="http://www.springframework.org/schema/beans"
			  xmlns="http://apacheds.org/config/1.0">

  ...
   <defaultDirectoryService ...>
     ...
     <partitions>
     ...
      <s:bean 
          id="helloPartition" 
          class="org.apache.directory.samples.partition.hello.HelloWorldPartition">
        <s:property name="suffix" value="ou=helloWorld" />
      </s:bean>
    </partitions>
   ...
  </defaultDirectoryService>
...

Note that the class HelloWorldPartition has to be in the class path of the server. Withgout, starting the server leads to a ClassNotFoundException. You can copy the jar file which results from the build to the lib directory and adjust the command line parameters in the apacheds.sh script.

Verification

After adding the HelloWorldPartition to the directory service like above (embedded or via configuration in server.xml), you can browse it with an LDAP browser like the one from Apache Directory Studio. Here are some screen shots.

Of course using a command line tool works as well ...

$ ldapsearch -h localhost -p 10389 -D "uid=admin,ou=system" -w secret \\
    -b "" -s base "(objectclass=*)" namingContexts
version: 1
dn:
namingContexts: ou=system
namingContexts: ou=helloWorld
namingContexts: ou=schema
$
$ ldapsearch -h localhost -p 10389 -D "uid=admin,ou=system" -w secret \\
    -b "ou=helloWorld" -s base "(objectclass=*)"
version: 1
dn: ou=helloWorld
objectClass: organizationalUnit
objectClass: top
description: hello, world
description: a minimal partition
ou: helloWorld
$

A partition which provides some more data

The sources

Currently, the sources are checked in here

In order to build it, simply check it out and type "mvn install".

verification

After adding the SystemPropertyPartition to the directory service (embedded or via configuration in server.xml), you can browse it with an LDAP browser like the one from Apache Directory Studio. Here is a screen shot.

Here is a search with a command line tool ...

$ ldapsearch -h localhost -p 10389 -D "uid=admin,ou=system" -w secret \\
    -b "ou=os,ou=sysProps" -s one "(objectclass=*)"
version: 1
dn: ou=arch,ou=os,ou=sysprops
objectClass: organizationalUnit
objectClass: extensibleObject
objectClass: top
description: Operating system architecture
cn: os.arch
ou: arch
info: x86

dn: ou=name,ou=os,ou=sysprops
objectClass: organizationalUnit
objectClass: extensibleObject
objectClass: top
description: Operating system name
cn: os.name
ou: name
info: Windows XP

dn: ou=version,ou=os,ou=sysprops
objectClass: organizationalUnit
objectClass: extensibleObject
objectClass: top
description: Operating system version
cn: os.version
ou: version
info: 5.1

Powered by Atlassian Confluence (Version: 2.2.9 Build:#527 Sep 07, 2006) - Bug/feature request

Unsubscribe or edit your notifications preferences