This chapter introduces OpenDJ SDK, demonstrating how to get the software and to build a first basic directory client application.

OpenDJ SDK provides a set of modern, developer-friendly Java APIs as part of the OpenDJ product suite. The product suite includes the client SDK alongside command-line tools and sample code, a 100% pure Java directory server, and more. You can use OpenDJ SDK to create client applications for use with any server that complies with the Lightweight Directory Access Protocol (LDAP): Technical Specification Road Map, RFC 4510. OpenDJ SDK brings you easy-to-use connection management, connection pooling, load balancing, and all the standard LDAP operations to read and write directory entries. OpenDJ SDK also lets you build applications with capabilities defined in additional draft and experimental RFCs that are supported by modern LDAP servers.

Install an LDAP server such as OpenDJ directory server that you can use to test the applications you develop. Also, load sample data into your server. The sample data used in this guide are available in LDIF form at http://mcraig.org/ldif/Example.ldif.

You can either install a build or build your own from source. Before you either download a build of OpenDJ SDK, or get the source code to build your own SDK, make sure you have a Java Development Kit installed. OpenDJ SDK relies on Java 6 or later. You can check for Java 6 by running the following command. $ java -version java version "1.6.0_24" Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334-9M3326) Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode) Download the latest stable OpenDJ SDK and tools bundle. Download the latest stable version of the OpenDJ SDK documentation (javadoc). Unzip the bundle, opendj-client-tools-.zip, where you want to install the SDK. $ unzip opendj-client-tools-.zip Unpack the OpenDJ SDK documentation, opendj-sdk--javadoc.jar, under the SDK install directory. $ mkdir opendj-client-tools-/javadoc $ cd opendj-client-tools-/javadoc $ jar -xf /path/to/opendj-sdk--javadoc.jar Add the tools to your PATH. (UNIX) $ export PATH=/path/to/opendj-client-tools-/bin:$PATH (Windows) C:\>set PATH=\\path\to\opendj-client-tools-\bat:%PATH% Add the OpenDJ SDK for the APIs and Grizzly framework for the transport to your CLASSPATH, typically found under opendj-client-tools-/lib/. (UNIX) $ export CLASSPATH=/path/to/lib/grizzly-framework-2.0.0-RC3.jar:$CLASSPATH $ export CLASSPATH=/path/to/lib/opendj-sdk-.jar:$CLASSPATH (Windows) C:\>set CLASSPATH=\\path\to\lib\grizzly-framework-2.0.0-RC3.jar:%CLASSPATH% C:\>set CLASSPATH=\\path\to\lib\opendj-sdk-.jar:%CLASSPATH% Before you either download a build of OpenDJ SDK, or get the source code to build your own SDK, make sure you have a Java Development Kit installed. OpenDJ SDK relies on Java 6 or later. You can check for Java 6 by running the following command. $ java -version java version "1.6.0_24" Java(TM) SE Runtime Environment (build 1.6.0_24-b07-334-9M3326) Java HotSpot(TM) 64-Bit Server VM (build 19.1-b02-334, mixed mode) Also make sure you have Subversion (svn) and Maven (mvn) installed. Check out the source code. $ svn co https://svn.forgerock.org/opendj/trunk/opendj3 Error validating server certificate for 'https://svn.forgerock.org:443': - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: svn.forgerock.org - Valid: from Wed, 23 Feb 2011 00:30:37 GMT until Thu, 23 Feb 2012 21:00:01 GMT - Issuer: Secure Digital Certificate Signing, StartCom Ltd., IL - Fingerprint: 73:96:5c:68:2c:f3:57:0e:e9:ee:6d:74:08:1b:34:16:53:b8:bd:39 (R)eject, accept (t)emporarily or accept (p)ermanently? p ... A opendj3/pom.xml A opendj3/README Checked out revision 6777. Build the modules and install them in the local repository. $ cd opendj3/ $ mvn install [INFO] Scanning for projects... [INFO] Reactor build order: [INFO] OpenDJ Project [INFO] OpenDJ Build Tools [INFO] OpenDJ Maven Plugin [INFO] OpenDJ TestNG Support [INFO] OpenDJ Modules [INFO] OpenDJ SDK [INFO] OpenDJ Client Tools ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 15 minutes 11 seconds [INFO] Finished at: Wed Mar 16 16:07:54 CET 2011 [INFO] Final Memory: 54M/136M [INFO] ------------------------------------------------------------------------ Unzip the tools and libraries included in the file, opendj3/opendj-modules/opendj-client-tools/target/opendj-client-tools-.zip. Add the opendj-client-tools-/bin (UNIX) or opendj-client-tools-\bat (Windows) directory to your PATH. Set your CLASSPATH to include the OpenDJ SDK library, opendj-sdk-.jar, and the Grizzly framework, grizzly-framework-2.0.0-RC3.jar, under opendj-client-tools-/lib/. Find the OpenDJ SDK documentation under file:///path/to/opendj3/opendj-modules/opendj-sdk/target/apidocs/index.html. After you install OpenDJ 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. // 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. import org.opendj.sdk.*; import org.opendj.sdk.ldif.*; import org.opendj.sdk.responses.*; 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.isReference()) { // 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