Warning: This is a very preliminary tutorial, the user must be informed that the current implementation will evolve a lot in the near future. So will the tutorial, hopefully...
This new API has been created in order to offer a better API than what we currently use, namely JNDI or older API like LdapSDK or jldap. It benefits from some improvements brought by ApacheDS and OpenDS.
This 5-minutes tutorial will present the way to use this API when working with a LDAP server.
LDAP is a connected protocol, so you need to create a connection in order to send request and receive response from a Ldap server. This is the main point : you have to create a connection first.
Each operation can have one or more responses, and produce exceptions when something went wrong.
The API is schema ware, ie the manipulated objects will be controlled on the client side, assuming you have brought back the schema from the server, or by using a default schema configuration
In order to create a connection, you first have to provide the name of the server, and the port to use. Those parameters will be defaulted to localHost and 389 if nothing is defined.
Here is an example :
LdapConnection connection = new LdapNetworkConnection( "localhost", 389 );
It's important to note that the connection has nothing to do with being bound, and this is a major difference with JNDI, where you create some context and provide the principalDN. A Connection is just a channel opened with the server, here.
Another important thing to understand is that the connection is not explicitly opened. In fact, the bind operation will open the connection.
TODO
Now that the connection has been created, you can call the bind() method. This will create a identified connection between a client and the server. The bind operation has nothing to do with the JNDI bind, as no entry will be created.
You can bind using no identifier, and in this case, you'll create an anonymous LDAP session. This is done this way :
connection.bind();
The most common bind uses an identifier and a password. The identifier must be a DN, and the password can be encrypted. Here is an example of a bind operation :
// Don't do that ! Password in clear text = danger ! connection.bind( "ou=example, dc=com", "secret" ); // The password is encrypted, but it does not protect against a MITM attack connection.bind( "ou=example, dc=com", "{crypt}wSiewPyxdEC2c" );
We have tried to make it easy to search information in a LDAP server, as this is the most frequently used operation.
Many parameters can be used in a search. The most commonly used are :
Here is a simple search, done using only those four parameters :
EntryCursor cursor = connection.search( "ou=system", "(objectclass=*)", SearchScope.ONELEVEL, "*" ); while ( cursor.next() ) { Entry entry = cursor.get(); // Process the entry ... }
Here, we call the search operation, and we get back a cursor. Reading search result from the cursor is done with the get() method, moving forward uses the next() method.
When you are done with the operation, you can unbind. This is done by calling the unbind() method, this way :
connection.unbind();
Once you are done with the connection, don‘t forget to close it. It’s done by calling the close() method :
connection.close();
If you explicitly call the unbind() method, the connection will also be closed, and in this case, you wont have to close it explicitly.
This very limited presentation was written to give users a quick insight about how to use the API. In order to get some further information, please check the User Guide