3.3. Getting the LDAP SDK

You can either install a build or build your own from source.

Before you either download a build of OpenDJ LDAP SDK, or get the source code to build your own SDK, make sure you have a Java Development Kit installed. See the Release Notes section on Java Environment requirements.

Procedure 3.1. To Include the SDK as a Maven Dependency

Let that expensive computer you bought do the work.

  • Include the ForgeRock repository in your list, and include the SDK as a dependency.

    <repositories>
      <repository>
        <id>forgerock-staging-repository</id>
        <name>ForgeRock Release Repository</name>
        <url>http://maven.forgerock.org/repo/releases</url>
        <snapshots>
          <enabled>false</enabled>
        </snapshots>
      </repository>
      <repository>
        <id>forgerock-snapshots-repository</id>
        <name>ForgeRock Snapshot Repository</name>
        <url>http://maven.forgerock.org/repo/snapshots</url>
        <releases>
          <enabled>false</enabled>
        </releases>
      </repository>
    </repositories>
    
    ...
    
    <dependencies>
      <dependency>
        <groupId>org.forgerock.opendj</groupId>
        <artifactId>opendj-ldap-sdk</artifactId>
        <version>4.7.0</version>
      </dependency>
    </dependencies>

Procedure 3.2. To Install the Latest SDK & Tools

  1. Download the latest OpenDJ LDAP Client Toolkit nightly build from the Nightly Builds page.

  2. Unzip the bundle, opendj-ldap-toolkit-4.7.0.zip, where you want to install the SDK.

    $ unzip opendj-ldap-toolkit-4.7.0.zip
  3. Add the tools to your PATH.

    (UNIX)
    $ export PATH=/path/to/opendj-ldap-toolkit-4.7.0/bin:$PATH
    (Windows)
    C:\>set PATH=\\path\to\opendj-ldap-toolkit-4.7.0\bat:%PATH%
  4. Add the OpenDJ LDAP SDK for the APIs, the I18N core library, and Grizzly I/O framework for the transport to your CLASSPATH, typically found under opendj-ldap-toolkit-4.7.0/lib/.

    (UNIX)
    $ export CLASSPATH=/path/to/lib/grizzly-framework-.jar:$CLASSPATH
    $ export CLASSPATH=/path/to/lib/i18n-core-.jar:$CLASSPATH
    $ export CLASSPATH=/path/to/lib/opendj-ldap-sdk-4.7.0.jar:$CLASSPATH
         
    (Windows)
    C:\>set CLASSPATH=\\path\to\lib\grizzly-framework-.jar:%CLASSPATH%
    C:\>set CLASSPATH=\\path\to\lib\i18n-core-.jar:%CLASSPATH%
    C:\>set CLASSPATH=\\path\to\lib\opendj-ldap-sdk-4.7.0.jar:%CLASSPATH%

Procedure 3.3. To Build Your Own SDK From Source

  1. Make sure you have Subversion (svn) and Maven (mvn) installed.

  2. Check out the source code.

    $ svn co https://svn.forgerock.org/opendj/trunk/opendj3
    ...
    Checked out revision XXXX.
  3. Build the modules and install them in the local repository.

    $ cd opendj3/
    $ mvn install
    [INFO] Scanning for projects...
    [INFO] ------------------------------------------------------------------------
    [INFO] Reactor Build Order:
    [INFO]
    [INFO] OpenDJ Directory Services Project
    [INFO] OpenDJ LDAP SDK
    [INFO] OpenDJ LDAP Toolkit
    [INFO] OpenDJ LDAP SDK Examples
    [INFO] OpenDJ Commons REST Adapter
    [INFO] OpenDJ Commons REST LDAP Gateway
    [INFO] OpenDJ Server 2.x Adapter
    [INFO]
           ...
    [INFO] ------------------------------------------------------------------------
    [INFO] BUILD SUCCESS
    [INFO] ------------------------------------------------------------------------
    [INFO] Total time: 2:51.315s
    [INFO] Finished at: Wed Apr 10 14:28:36 CEST 2013
    [INFO] Final Memory: 37M/382M
    [INFO] ------------------------------------------------------------------------
  4. Unzip the tools and libraries included in the file, opendj3/opendj-ldap-toolkit/target/opendj-ldap-toolkit-4.7.0.zip.

  5. Add the opendj-ldap-toolkit-4.7.0/bin (UNIX) or opendj-ldap-toolkit-4.7.0\bat (Windows) directory to your PATH.

  6. Set your CLASSPATH to include the OpenDJ LDAP SDK library, opendj-ldap-sdk-4.7.0.jar, the I18N core library, i18n-core-.jar, and the Grizzly framework, grizzly-framework-.jar under opendj-ldap-toolkit-4.7.0/lib/.

After you install OpenDJ LDAP SDK and configure your environment as described, if you have a directory server running import sample data, and test your configuration with a sample client application.

import org.forgerock.opendj.ldap.Connection;
import org.forgerock.opendj.ldap.LDAPConnectionFactory;
import org.forgerock.opendj.ldap.SearchScope;
import org.forgerock.opendj.ldap.responses.SearchResultEntry;
import org.forgerock.opendj.ldap.responses.SearchResultReference;
import org.forgerock.opendj.ldif.ConnectionEntryReader;
import org.forgerock.opendj.ldif.LDIFEntryWriter;

//Test.java:
//Kick the SDK tires, reading Babs Jensen's entry and displaying LDIF.
//If your LDAP server is not listening on localhost:1389, or if your
//data are different change the appropriate lines below.

class Test {
    public static void main(String[] args) {

        // Create an LDIF writer which will write the search results to stdout.

        final LDIFEntryWriter writer = new LDIFEntryWriter(System.out);
        Connection connection = null;

        try {
            // Connect and bind to the server.
            // CHANGE THIS IF SERVER IS NOT AT localhost:1389.
            final LDAPConnectionFactory factory =
                    new LDAPConnectionFactory("localhost", 1389);

            connection = factory.getConnection();
            // CHANGE THIS IF ANONYMOUS SEARCHES ARE NOT ALLOWED.
            // connection.bind(userName, password);

            // Read the entries and output them as LDIF.
            // CHANGE THIS IF NO uid=bjensen,ou=people,dc=example,dc=com EXISTS.
            final ConnectionEntryReader reader =
                    connection.search("dc=example,dc=com",
                            SearchScope.WHOLE_SUBTREE, "(uid=bjensen)", "*");
            while (reader.hasNext()) {
                if (reader.isEntry()) {
                    // Got an entry.
                    final SearchResultEntry entry = reader.readEntry();
                    writer.writeComment("Search result entry: "
                            + entry.getName().toString());
                    writer.writeEntry(entry);
                } else {
                    // Got a continuation reference.
                    final SearchResultReference ref = reader.readReference();
                    writer.writeComment("Search result reference: "
                            + ref.getURIs().toString());
                }
            }
            writer.flush();
        } catch (final Exception e) {
            // Handle exceptions...
            System.err.println(e.getMessage());
        } finally {
            if (connection != null) {
                connection.close();
            }
        }
    }
}

If all goes well, Test.java compiles without errors. The test program displays Babs Jensen's entry in LDIF.

$ javac Test.java
$ java Test
# Search result entry: uid=bjensen,ou=People,dc=example,dc=com
dn: uid=bjensen,ou=People,dc=example,dc=com
givenName: Barbara
objectClass: person
objectClass: inetOrgPerson
objectClass: organizationalPerson
objectClass: top
uid: bjensen
cn: Barbara Jensen
cn: Babs Jensen
sn: Jensen
telephoneNumber: +1 408 555 1862
roomNumber: 0209
ou: Product Development
ou: People
l: Cupertino
mail: bjensen@example.com
facsimileTelephoneNumber: +1 408 555 1992