Embedding Apache DirectoryServer
This chapter explain how you should proceed to embed Apache Directory Server into your application, or to use it into unit tests.
Embedding ADS into an application
To be done ...
Using ADS for unit tests
The idea is to use ADS as an embedded server for Ldap junit tests. We will build an environment in which it will be convenient to test Ldap applications.
First steps
We have two choices : either we launch the server totally embedded, without having to communicate whith it using the Ldap Protocol, or we want to use the server as a remote server, with Ldap protocol in the middle (it can be usefull if one want to test specific applications)
Anyway, we will simply launch only one server (if one want to test referrals, it might be necessary to initialize 2 or more servers)
A unit test is a sequence in which three operations are run for each test :
- setUp() is called
- the test is launched
- tearDown() is called
Each time *setUp() is called, a new instance of the server will be initialized, and it can take some time (2 to 5 seconds, depending on your processor). If you have many tests, be aware that each run will cost you the price of the setup, the test and the teardown. This is the only guarantee that those tests are unit tests.
ApacheDS sources provide a common class to initialize the server into unit tests : AbstractServerTest. This class can be found in the apacheds-server-unit jar file. This class is very usefull, it alleviates you from the burden of initializing the server.
Creating a blank test
So let's declare the framework for a simple unit test, using a server which will be used through socket (the first free port above 1023 will be used) :
package org.apache.directory.demo;
import org.apache.directory.server.unit.AbstractServerTest;
/**
* Testcase using an embedded Apache Directory Server.
*
* @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
*/
public class DemoTest extends AbstractServerTest
{
/**
* Initialize the server.
*/
public void setUp() throws Exception
{
super.setUp();
}
/**
* Empty test just to avoid a warning to be thrown when launching the test
*/
public void testEmpty()
{
// Do nothing
}
/**
* Shutdown the server.
*/
public void tearDown() throws Exception
{
super.tearDown();
}
}
This is totally empty, we will fill the blanks now. But let's launch the test as is :
838 [main] WARN org.apache.directory.server.core.DefaultDirectoryService - ApacheDS shutdown hook has NOT been registered with the runtime. This default setting for standalone operation has been overriden. 1695 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute dynamicSubtrees does not have normalizer : using NoopNormalizer 1696 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute javaSerializedData does not have normalizer : using NoopNormalizer 1696 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute subtreeSpecification does not have normalizer : using NoopNormalizer 1696 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute byteCode does not have normalizer : using NoopNormalizer 1697 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute namingContexts does not have normalizer : using NoopNormalizer 1697 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute jpegPhoto does not have normalizer : using NoopNormalizer 1697 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute altServer does not have normalizer : using NoopNormalizer 1697 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute supportedExtension does not have normalizer : using NoopNormalizer 1697 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute userSMIMECertificate does not have normalizer : using NoopNormalizer 1701 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute subtreeMaximumQuality does not have normalizer : using NoopNormalizer 1701 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute singleLevelQuality does not have normalizer : using NoopNormalizer 1701 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute supportedSASLMechanisms does not have normalizer : using NoopNormalizer 1701 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute subtreeMinimumQuality does not have normalizer : using NoopNormalizer 1701 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute enhancedSearchGuide does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute c-FacsimileTelephoneNumber does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute supportedLDAPVersion does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute authorityRevocationList does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute cACertificate does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute supportedControl does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute userPKCS12 does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute deltaRevocationList does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute personalSignature does not have normalizer : using NoopNormalizer 1702 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute telexNumber does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute dSAQuality does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute crossCertificatePair does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute mailPreferenceOption does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute c-TelexNumber does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute audio does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute entryTtl does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute userCertificate does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute supportedAlgorithms does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute preferredDeliveryMethod does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute otherMailbox does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute teletexTerminalIdentifier does not have normalizer : using NoopNormalizer 1703 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute photo does not have normalizer : using NoopNormalizer 1704 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute searchGuide does not have normalizer : using NoopNormalizer 1704 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute facsimileTelephoneNumber does not have normalizer : using NoopNormalizer 1704 [main] WARN org.apache.directory.server.core.schema.bootstrap.BootstrapAttributeTypeRegistry - Attribute certificateRevocationList does not have normalizer : using NoopNormalizer 1756 [main] INFO org.apache.directory.server.core.partition.impl.btree.jdbm.JdbmPartition - Using the custom configured cache size of 500 for system partition 1889 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute objectClass 1928 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.5 1948 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.6 1970 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.1 1987 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.3 2008 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.7 2026 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.4 2091 [main] WARN org.apache.directory.server.core.partition.impl.btree.BTreePartition - Using default cache size of 100 for index on attribute 1.3.6.1.4.1.18060.0.4.1.2.2 2996 [main] WARN org.apache.directory.server.core.DefaultDirectoryService - You didn't change the admin password of directory service instance 'default'. Please update the admin password as soon as possible to prevent a possible security breach. 2996 [main] INFO org.apache.directory.server.jndi.ServerContextFactory - LDIF load directory not specified. No LDIF files will be loaded. 3285 [main] INFO org.apache.directory.server.jndi.ServerContextFactory - Successful bind of an LDAP Service (1024) is complete. 3409 [main] INFO org.apache.directory.server.jndi.ServerContextFactory - Unbind of an LDAP service (1024) is complete. 3409 [main] INFO org.apache.directory.server.jndi.ServerContextFactory - Sending notice of disconnect to existing clients sessions.
We can see that the server is launched, some initialization is done, then server is listening on port 104, and is immediatly shutdown.
Creating our own partition
At the moment, we have created a server which is not totally empty : one partition is created by default, the system partition. We won't use it for our tests, so we will need to create our onw partition to play with. Let's call it 'o=sevenseas' (o stands for organization)
The setUp() method will be completed with all the needed instruction to create a new partition
/**
* Initialize the server.
*/
public void setUp() throws Exception
{
// Add partition 'sevenSeas'
MutablePartitionConfiguration pcfg = new MutablePartitionConfiguration();
pcfg.setName( "sevenSeas" );
pcfg.setSuffix( "o=sevenseas" );
// Create some indices
Set<String> indexedAttrs = new HashSet<String>();
indexedAttrs.add( "objectClass" );
indexedAttrs.add( "o" );
pcfg.setIndexedAttributes( indexedAttrs );
// Create a first entry associated to the partition
Attributes attrs = new BasicAttributes( true );
// First, the objectClass attribute
Attribute attr = new BasicAttribute( "objectClass" );
attr.add( "top" );
attr.add( "organization" );
attrs.put( attr );
// The the 'Organization' attribute
attr = new BasicAttribute( "o" );
attr.add( "sevenseas" );
attrs.put( attr );
// Associate this entry to the partition
pcfg.setContextEntry( attrs );
// As we can create more than one partition, we must store
// each created partition in a Set before initialization
Set<MutablePartitionConfiguration> pcfgs = new HashSet<MutablePartitionConfiguration>();
pcfgs.add( pcfg );
configuration.setContextPartitionConfigurations( pcfgs );
// Create a working directory
File workingDirectory = new File( "server-work" );
configuration.setWorkingDirectory( workingDirectory );
// Now, let's call the upper class which is responsible for the
// partitions creation
super.setUp();
}
Ok, now the partition sevenseas should be created. How can we be sure of that ? let's write a test to replace the emptytest() method :
/**
* Test that the partition has been correctly created
*/
public void testPartition() throws NamingException
{
Hashtable<Object, Object> env = new Hashtable<Object, Object>( configuration.toJndiEnvironment() );
// Create a new context pointing to the overseas partition
env.put( Context.PROVIDER_URL, "o=sevenSeas" );
env.put( Context.SECURITY_PRINCIPAL, "uid=admin,ou=system" );
env.put( Context.SECURITY_CREDENTIALS, "secret" );
env.put( Context.SECURITY_AUTHENTICATION, "simple" );
env.put( Context.INITIAL_CONTEXT_FACTORY, "org.apache.directory.server.jndi.ServerContextFactory" );
// Let's open a connection on this partition
InitialContext initialContext = new InitialContext( env );
// We should be able to read it
DirContext appRoot = ( DirContext ) initialContext.lookup( "" );
assertNotNull( appRoot );
// Let's get the entry associated to the top level
Attributes attributes = appRoot.getAttributes( "" );
assertNotNull( attributes );
assertEquals( "sevenseas", attributes.get( "o" ).get() );
Attribute attribute = attributes.get( "objectClass" );
assertNotNull( attribute );
assertTrue( attribute.contains( "top" ) );
assertTrue( attribute.contains( "organization" ) );
// Ok, everything is fine
}
The test should succeed. Is that all ? Well, almost. As you can see, a working space has been created ( "server-work", at the end of the setup). Do we have to take care of this working space? No. It has been cleaned by the super class !
So everything is fiçne, the partition is up and running, you are ready to add more tests.
Adding your own schema
Ok, let's go deeper into the server configuration. Working with default schema is fine, but some point, you may want to use your own ObjectClasses and AttributeTypes. let's assume you have created them, and that you have been throw the process of generating the class files for it (this process is described in XXX)