This chapter introduces OpenDJ LDAP SDK, demonstrating how to get the software and to build a first basic directory client application.
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.
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.
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>
Download the latest OpenDJ LDAP Client Toolkit nightly build from the Nightly Builds page.
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
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%
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%
Make sure you have Subversion (svn) and Maven (mvn) installed.
Check out the source code.
$ svn co https://svn.forgerock.org/opendj/trunk/opendj3 ... Checked out revision XXXX.
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] ------------------------------------------------------------------------
Unzip the tools and libraries included in the file,
opendj3/opendj-ldap-toolkit/target/opendj-ldap-toolkit-4.7.0.zip
.
Add the opendj-ldap-toolkit-4.7.0/bin
(UNIX) or opendj-ldap-toolkit-4.7.0\bat
(Windows) directory to your PATH.
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
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.