The Configuration API

ApacheDS provides its configuration API in the {{org.apache.ldap.server.configuration}} package. This package contains concrete configuration instruction classes that you can instantiate and specify in your JNDI environment variable. To put your configuration instruction class into the JNDI environment variable:

Properties env = new Properties();
env.setProperty( Context.INITIAL_CONTEXT_FACTORY, CoreContextFactory.class.getName() );
...

// Create a configuration instruction.
Configuration cfg = new MutableStartupConfiguration();
...

// Put the configuration instruction to the environment variable.
env.putAll( cfg.toJndiEnvironment() );

// Execute the instruction you've specified.
new InitialContext( env );

Now let's find out what kind of instruction you can give to ApacheDS.

{{StartupConfiguration}}

This instruction starts up the ApacheDS if it is not started. Here's the list of known properties:

  • {{authenticatorConfigurations}} - a collection of {{AuthenticatorConfiguration}} s. {{AuthenticatorConfiguration}} specifies {{Authenticator}} s that authenticate a user who accesses the ApacheDS DIT. (Default: <all default authenticators>)
  • {{bootstrapSchemas}} - a set of {{BootstrapSchema}} s which are loaded at the first time ApacheDS starts up (Default: <all default schemas>)
  • {{contextPartitionConfigurations}} - a collection of {{ContextPartitionConfiguration}} s. {{ContextPartitionConfiguration}} specified {{ContextPartition}} s that consist the ApacheDS DIT. (Default: no context partitions except system partition)
  • {{accessControl}} - Set to {{true}} if you want to enable access control support of the ApacheDS. (Default: {{false}})
  • {{allowAnonymousAccess}} - Set to {{true}} if you want to enable anonymous access. (Default: {{true}})
  • {{interceptorConfigurations}} - a list of {{InterceptorConfiguration}} s which will configure the initial interceptor chain of the ApacheDS (Default: <all default interceptors>)
  • {{testEntries}} - a list of {{javax.naming.directory.Attributes}} which will be added to the DIT while the ApacheDS is started up (Default: no test entries)
  • {{workingDirectory}} - a working directory the content of DIT will be stored to (Default: {{./server-work/}})

You don't need to specify any properties because all properties have the default. Please use {{MutableStartupConfiguration}} to modify any properties above.

{{ShutdownConfiguration}}

This instruction shuts down the ApacheDS if it is not already shut down. There's no property to configure.

{{SyncConfiguration}}

This instruction flushes out any I/O buffer or write cache. There's no property to configure.

{{AddContextPartitionConfiguration}}

This instruction adds a new context partition on-the-fly while the ApacheDS is running. There is only one property, 'contextPartitionConfiguration'. You can specify an appropriate {{ContextPartitionConfiguration}} to plug a context partition into the ApacheDS.

{{RemoveContextPartitionConfiguration}}

This instruction remove an existing context partition on-the-fly while the ApacheDS is running. There is only one property, 'suffix'. You can specify the suffix of the partition you want to remove from the ApacheDS.

Running and Choosing Multiple Instances

You can run multiple instances of ApacheDS by specifying {{instanceId}} to all {{Configuration}} instructions. {{InstanceId}} can be specified as a constructor parameter. Please take a look at the APi documentation (JavaDoc) for more details.

// Create a configuration instruction that affects an ApacheDS instance 'instance4'.
Configuration cfg = new MutableStartupConfiguration( "instance4" );
...

// Put the configuration instruction to the environment variable.
env.putAll( cfg.toJndiEnvironment() );

// Execute the instruction you've specified for an ApacheDS instance 'instance4'.
new InitialContext( env );

Using Spring Framework

The configuration API is designed to fit tightly with Spring Framework . Here is an example beans xml file:

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

<!DOCTYPE beans PUBLIC "-//SPRING//DTD BEAN//EN"
  "http://www.springframework.org/dtd/spring-beans.dtd">

<beans>
  <!-- JNDI environment variable -->
  <bean id="environment" class="org.springframework.beans.factory.config.PropertiesFactoryBean">
    <property name="properties">
      <props>
    	  <prop key="asn.1.berlib.provider">org.apache.ldap.common.berlib.asn1.SnickersProvider</prop>
    	  <!--prop key="asn.1.berlib.provider">org.apache.asn1new.ldap.TwixProvider</prop-->
    	  <prop key="java.naming.security.authentication">simple</prop>
    	  <prop key="java.naming.security.principal">uid=admin,ou=system</prop>
          <prop key="java.naming.security.credentials">secret</prop>
          <prop key="java.naming.ldap.attributes.binary">
            photo personalSignature audio jpegPhoto javaSerializedData userPassword
            userCertificate cACertificate authorityRevocationList certificateRevocationList
            crossCertificatePair x500UniqueIdentifier krb5Key
          </prop>
      </props>
    </property>
  </bean>
  
  <!-- StartupConfiguration to start ApacheDS -->
  <bean id="configuration" class="org.apache.ldap.server.configuration.MutableServerStartupConfiguration">
    <property name="workingDirectory"><value>apache.org</value></property>
    <property name="allowAnonymousAccess"><value>false</value></property>
    <property name="accessControlEnabled"><value>false</value></property>
    <property name="ldapPort"><value>10389</value></property>
    <property name="contextPartitionConfigurations">
      <set>
        <ref bean="apachePartitionConfiguration"/>
      </set>
    </property>

    <!-- Bootstrap schemas -->
    <property name="bootstrapSchemas">
      <set>
        <bean class="org.apache.ldap.server.schema.bootstrap.AutofsSchema"/>
        <bean class="org.apache.ldap.server.schema.bootstrap.CorbaSchema"/>
        <bean class="org.apache.ldap.server.schema.bootstrap.CoreSchema"/>

        ......

      </set>
    </property>
    
    <!-- Interceptor configurations -->
    <property name="interceptorConfigurations">
      <list>
        <bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration">
          <property name="name"><value>normalizationService</value></property>
          <property name="interceptor">
            <bean class="org.apache.ldap.server.normalization.NormalizationService" />
          </property>
        </bean>
        <bean class="org.apache.ldap.server.configuration.MutableInterceptorConfiguration">
          <property name="name"><value>authenticationService</value></property>
          <property name="interceptor">
            <bean class="org.apache.ldap.server.authn.AuthenticationService" />
          </property>
        </bean>

        ......

      </list>
    </property>
  </bean>

  <!-- Additional ContextPartitionConfiguration -->
  <bean id="apachePartitionConfiguration" class="org.apache.ldap.server.configuration.MutableContextPartitionConfiguration">
    <property name="name"><value>apache</value></property>
    <property name="suffix"><value>dc=apache,dc=org</value></property>
    <property name="indexedAttributes">
      <set>
        <value>objectClass</value>
        <value>ou</value>
        <value>uid</value>
      </set>
    </property>
    <property name="contextEntry">
      <value>
        objectClass: top
        objectClass: domain
        objectClass: extensibleObject
        dc: apache
      </value>
    </property>
  </bean>

  <!-- Custom editors required to launch ApacheDS -->
  <bean class="org.springframework.beans.factory.config.CustomEditorConfigurer">
    <property name="customEditors">
      <map>
        <entry key="javax.naming.directory.Attributes">
          <bean class="org.apache.ldap.server.configuration.AttributesPropertyEditor"/>
        </entry>
      </map>
   </property>
  </bean>
</beans>

With the XML file above, you can start up the ApacheDS with this code:

Properties env;
ServerStartupConfiguration cfg;

ApplicationContext factory = new FileSystemXmlApplicationContext( args[0] );
cfg = ( StartupConfiguration ) factory.getBean( "configuration" );
env = ( Properties ) factory.getBean( "environment" );

env.setProperty( Context.PROVIDER_URL, "" );
env.setProperty( Context.INITIAL_CONTEXT_FACTORY, CoreContextFactory.class.getName() );
env.putAll( cfg.toJndiEnvironment() );

new InitialDirContext( env );