Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Embedding ApacheDS as a Web Application

Tip
titleApacheDS 1.5.5

This site was updated for ApacheDS 1.5.5.

My initial aim was to demonstrate embedding ApacheDS in a very simple, but nevertheless impressive way. I thought about embedding the server in Apache Tomcat first. But then I got a better plan: Creating a standard web application which wraps ApacheDS and can be deployed on any compliant application server. ApacheDS in a war-archive!

...

Info
titleVersion check

Although the concepts depicted below apply to all version of ApacheDS (even before 1.0), the configuration for starting and stopping the embedded server uses the style introduced with ApacheDS 1.5.45. Be sure that you use this version of the server, or a later one.

...

The ApacheDS core is comprised of JavaBeans components, and can easily be instantiated started and stopped with simple Java code. This is done by the following listener.

The class StartStopListener implements ServletContextListener and therefore contains the following two life cycle methods:

...

Code Block
java
java
titleStartStopListener.java
package org.apache.directory.samples.embed.webapp;

import java.io.File;

import javax.servlet.ServletContext;
import javax.servlet.ServletContextEvent;
import javax.servlet.ServletContextListener;

import org.apache.directory.server.core.DefaultDirectoryService;
import org.apache.directory.server.core.DirectoryService;
import org.apache.directory.server.ldap.LdapServiceLdapServer;
import org.apache.directory.server.protocol.shared.transport.SocketAcceptorTcpTransport;

/**
 * A Servlet context listener to start and stop ApacheDS.
 * 
 * @author <a href="mailto:dev@directory.apache.org">Apache Directory
 *         Project</a>
 */
public class StartStopListener implements ServletContextListener 
{

    private DirectoryService directoryService;

    private SocketAcceptorLdapServer socketAcceptorldapServer;
    private LdapService ldapService;

    /**
     * Startup ApacheDS embedded.
     */
    public void contextInitialized( ServletContextEvent evt )
    {

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

            socketAcceptorldapServer = new SocketAcceptorLdapServer(null);
            ldapService = new LdapService(ldapServer.setDirectoryService( directoryService );
            ldapServiceldapServer.setSocketAcceptorsetAllowAnonymousAccess(socketAcceptor);
            ldapService.setDirectoryService(directoryService true );

            // Set LDAP port to 10389
            ldapService.setIpPort(10389TcpTransport ldapTransport = new TcpTransport( 10389 );

            // ldapServer.setTransports( ldapTransport );

            // Determine an appropriate working directory
            ServletContext servletContext = evt.getServletContext();
            File workingDir = ( File ) servletContext
                    .getAttribute( "javax.servlet.context.tempdir" );
            directoryService.setWorkingDirectory( workingDir );

            directoryService.startup();
            ldapServiceldapServer.start();

            // Store directoryService in context to provide it to servlets etc.
            servletContext.setAttribute( DirectoryService.JNDI_KEY, directoryService );
        }
        catch ( Exception e directoryService);

        } catch (Exception e) {
            throw new RuntimeException( e );
        }
    }

    /**
     * Shutdown ApacheDS embedded.
     */
    public void contextDestroyed( ServletContextEvent evt )
    {
        try
        {
            ldapServiceldapServer.stop();
            directoryService.shutdown();
        }
        catch ( Exception e )
        {
            throw new RuntimeException( e );
        }
    }
}

Deployment descriptor

...

Code Block
xml
xml
titleweb.xml
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"
"http://java.sun.com/dtd/web-app_2_3.dtd">
<web-app>
  <display-name>ApacheDS embedded in a WebApp</display-name>
  <description>
    A simple yet portable way to run ApacheDS within a servlet
    container
  </description>

  <listener>
    <listener-class>
      org.apache.directory.samples.embed.webapp.StartStopListener
    </listener-class>
  </listener>
</web-app>

...

  </listener-class>
  </listener>
</web-app>

Packaging and Deploying the WebApp

A standard web archive (war-File) is needed in order to deploy the application to a servlet container. The easiest way to create such a web archive including all dependencies is to use an Maven archetype we provide.

Creating the WebApp using the ApacheDS Maven Archetype

We assume you have Java Subversion and Maven 2.0.9 installed on your system.

To use the archetype you'll need to check it out and install it to your local repository:

No Format

svn co http://svn.apache.org/repos/asf/directory/samples/trunk/apacheds-archetype-webapp
cd apacheds-archetype-webapp
mvn install

Then change to your preferred location to create the new project and execute following command:

No Format

mvn archetype:generate -DarchetypeGroupId=org.apache.directory.samples \
                       -DarchetypeArtifactId=apacheds-archetype-webapp \
                       -DarchetypeVersion=1.5.5-SNAPSHOT \
                       -DgroupId=org.apache.directory.samples.embed.webapp \
                       -DartifactId=ApacheDS -Dversion=1.0-SNAPSHOT 

Then change to the created directory and run the following command:

No Format

mvn package 

This creates an ApacheDS.war file below the target folder.

Run on embedded Jetty

The fastest way to run the web application is to use the Maven Jetty plugin:

No Format

mvn jetty:run

Excerpt
hiddentrue

A standard web archive (war-File) is needed in order to deploy the application to a servlet container. The Resources area at the end of this page provides a zip-File which contains the file structure. A build script for Apache Ant is included as well.

Directory layout for the sources, war file layout

The build script assumes that you have ApacheDS 1.5.

4

5 and Tomcat 6.0.18 installed locally; it uses and (in the case of ApacheDS) copies the necessary files from their lib directories to the lib directory of the web application. You will likely want to adjust the installation directories defined in the build.xml file.

Note: Within the build script, Tomcat is only used for compilation. To be more concrete, only the servlet-api.jar is needed. Other options to provide this library at build time are imaginable, especially if you plan to deploy ApacheDS on a Web Application Server other than Tomcat.

Image Modified

After building the project, the classes folder will contain the compiled class files of the two Java classes above, and a properties file to configure the logging framework log4j. The lib folder will contain all jar-Files necessary, these are

  • antlr-2.7.7.jar
  • apacheds-bootstrap-extract-1.5.4.jar
  • apacheds-bootstrap-partition-1.5.4.jar
  • apacheds-core-1.5.4.jar
  • apacheds-core-avl-1.5.4.jar
  • apacheds-core-cursor-1.5.4.jar
  • apacheds-core-entry-1.5.4.jar
  • apacheds-core-jndi-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.jar
  • apacheds-protocol-shared-1.5.4.jar
  • apacheds-schema-bootstrap-1.5.4.jar
  • apacheds-schema-registries-1.5.4.jar
  • apacheds-utils-1.5.4.jar
  • apacheds-xdbm-base-1.5.4.jar
  • apacheds-xdbm-search-1.5.4.jar
  • commons-collections-3.2.jar
  • commons-lang-2.3.jar
  • log4j-1.2.14.jar
  • mina-core-1.1.6.jar
  • mina-filter-ssl-1.1.6.jar
  • shared-asn1-0.9.12.jar
  • shared-asn1-codec-0.9.12.jar
  • shared-bouncycastle-reduced-0.9.12.jar
  • shared-ldap-0.9.12.jar
  • shared-ldap-constants-0.9.12.jar
  • slf4j-api-1.4.3.jar
  • slf4j-log4j12-1.4.3.jar

The webapp target in the build.xml file (which is the default target) packs the files for the web application together in a web archive called ApacheDS.war.

Deploying on Apache Tomcat

...

Here is a screen shot of the web based administration console of WebSphere Application Server 6.1 with the ApacheDS.war deployed and running, no changes in the deployment archive were needed.

...

To finish with, here is a simple example on how to access the server internally (Note: the servlet was already created by the maven archetype).

The following servlet, which will be deployed together with the other two classes class in the web archive, connects to ApacheDS directly, i.e. via the internal JNDI provider. No network access is needed. In the doGet method it performs a search operation against the Root DSE of the server, as the examples above do.

...

Redeploy the web application. If you point to your tomcat server with the appropriate URL (http://localhost:8080/ApacheDS/RootDse), you'll see the content of the Root DSE as depicted below:

Generate Maven Project

Excerpt
hiddentrue
To get the sample code you can either generate a maven project using the apacheds-webapp archetype or

Download the source code

Image Modified StartStopListener.java (Step 1)
Image Modified RootDseServlet.java (Step 2)
Image Modified web.xml
Image Modified ApacheDSWebApp.zip all sources including a build script for Apache Ant (build.xml)