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

LDAP About OpenDJ LDAP 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 LDAP 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 LDAP 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 LDAP SDK also lets you build applications with capabilities defined in additional draft and experimental RFCs that are supported by modern LDAP servers.

LDAP Data Examples Data 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://opendj.forgerock.org/Example.ldif.

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. Installing With Maven 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></version> </dependency> </dependencies> Installing From download Download the latest OpenDJ LDAP Client Toolkit from the download page. Unzip the bundle, opendj-ldap-toolkit-.zip, where you want to install the SDK. $ unzip opendj-ldap-toolkit-.zip Add the tools to your PATH. (UNIX) $ export PATH=/path/to/opendj-ldap-toolkit-/bin:$PATH (Windows) C:\>set PATH=\\path\to\opendj-ldap-toolkit-\bat:%PATH% 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-/lib/. (UNIX) $ export CLASSPATH=/path/to/lib/grizzly-framework-.jar:$CLASSPATH $ export CLASSPATH=/path/to/lib/i18n-core-1.4.0.jar:$CLASSPATH $ export CLASSPATH=/path/to/lib/opendj-ldap-sdk-.jar:$CLASSPATH (Windows) C:\>set CLASSPATH=\\path\to\lib\grizzly-framework-.jar:%CLASSPATH% C:\>set CLASSPATH=\\path\to\lib\i18n-core-1.4.0.jar:%CLASSPATH% C:\>set CLASSPATH=\\path\to\lib\opendj-ldap-sdk-.jar:%CLASSPATH% Installing Build your own 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/README U opendj3 ... Checked out revision 6985. 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 Maven Build Tools [INFO] OpenDJ LDAP SDK [INFO] OpenDJ LDAP Toolkit [INFO] OpenDJ LDAP SDK Examples ... [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 56.658s [INFO] Finished at: Wed Jun 08 09:19:57 CEST 2011 [INFO] Final Memory: 27M/87M [INFO] ------------------------------------------------------------------------ Unzip the tools and libraries included in the file, opendj3/opendj-ldap-toolkit/target/opendj-ldap-toolkit-.zip. Add the opendj-ldap-toolkit-/bin (UNIX) or opendj-ldap-toolkit-\bat (Windows) directory to your PATH. Set your CLASSPATH to include the OpenDJ LDAP SDK library, opendj-ldap-sdk-.jar, the I18N core library, i18n-core-1.4.0.jar, and the Grizzly framework, grizzly-framework-.jar under opendj-ldap-toolkit-/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

Examples Java A number of OpenDJ LDAP SDK examples are available online on the OpenDJ community site. There you find samples whose excerpts are shown in this guide.