Requirements

jLDAPBeans is being developed using the J2SE 5.0 because it uses many of the improvements included in this new release of the Java Virtual Machine like Annotations and Generics.

jLDAPBeans is very easy to use. You only need to configure your JNDI environment properly and include the appropiate libraries for jLDAPBeans in your project's classpath.

Actually there is not any release of jLDAPBeans, please refer to download or cvs usage pages to get a SNAPSHOT version of jLDAPBeans. There is just one package to use: jldapbeans-lang. In future versions jLDAPBeans will be splitted in serveral packages.

Using jLDAPBeans

Do you know how to use JNDI and Java Beans? Then you know to use jLDAPBeans. Here are several examples of using JNDI and jLDAPBeans to do operations on LDAP directories:

Lookup a LDAP bean

jLDAPBeans reads information about the objectClasses of the LDAP object and maps that names to Java Class names. Then instantiates the LDAP bean and initializes its properties with the attribute values found for the name queried.

...
import javax.naming.ldap.*;
...
import net.sf.jldapbeans.commons.DcObject;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
DcObject dcObject = (DcObject) ctx.lookup("dc=example,dc=com");
List domainComponent = dcObject.getDomainComponent();
...

Bind a LDAP bean

Binding a LDAP bean involves instantiating it before proceding to store it in the LDAP directory. There is very easy to bind a simple LDAP bean (has only one STRUCTURAL objectClass) but you may need more that one class to bring up more complex LDAP beans.

Binding a simple LDAP bean
...
import javax.naming.ldap.*;
...
import net.sf.jldapbeans.commons.Organization;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
Organization org = new Organization();
org.setOrganizationName("example.com");
ctx.bind("dc=example,dc=com", org);
...
Binding a more complex LDAP bean

Here we use an auxiliary class to instantiate a complex LDAP bean: the LdapClass. More examples of how to use this special class are found below.

...
import javax.naming.ldap.*
...
import net.sf.jldapbeans.commons.Organization;
import net.sf.jldapbeans.commons.DcObject;
import net.sf.jldapbeans.lang.LdapClass;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
LdapClass ldapClass = LdapClass.merge(Organization.class, DcObject.class);
Object ldapObj = ldapClass.newInstance();
((Organization) ldapObj).setOrganizationName("example.com");
((DcObject) ldapObj).setDomainComponent("dc=example,dc=com");
ctx.bind("dc=example,dc=com", ldapObj);
...

Merging

As you can see in the above example, we used an auxiliary class to instantiate a complex bean composed of two Java Classes: Organization and DcObject.

This way of working is known Merging because we merge one, two or more LDAP bean declarations inside a single LdapClass that will be used to instantiate a object. The object instantiated can be referenced using any of the classes merged like in the above example. Following are more examples of Merging:

Merging a LdapClass with other LDAP bean declarations
...
import javax.naming.ldap.*;
...
import net.sf.jldapbeans.commons.Organization;
import net.sf.jldapbeans.commons.DcObject;
import net.sf.jldapbeans.commons.SimpleSecurityObject;
import net.sf.jldapbeans.lang.LdapClass;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
Organization org = (Organization) ctx.lookup("dc=example,dc=com");
LdapClass orgClass = LdapClass.classOf(org);
LdapClass newClass = LdapClass.merge(orgClass, SimpleSecurityObject.class);
org = (Organization) newClass.newInstance();
((SimpleSecurityObject) org).setUserPassword("secret");
...
Merging an array of LdapClasses.
...
import javax.naming.ldap.*;
...
import net.sf.jldapbeans.commons.Organization;
import net.sf.jldapbeans.commons.DcObject;
import net.sf.jldapbeans.commons.SimpleSecurityObject;
import net.sf.jldapbeans.lang.LdapClass;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
Organization org = (Organization) ctx.lookup("dc=example,dc=com");
LdapClass orgClass = LdapClass.classOf(org);
LdapClass otherClass = LdapClass.merge(DcObject.class, SimpleSecurityObject.class);
LdapClass newClass = LdapClass.merge(orgClass, otherClass);
org = (Organization) newClass.newInstance();
((SimpleSecurityObject) org).setUserPassword("secret");
...

Merging is specially useful when we need to instantiate a complex LDAP bean from scratch. For working with already instantiated beans we suggest to use Aggregation instead.

Aggregation

jLDAPBeans supports aggregation of bean classes if they are compatible. An AUXILIARY objectClass can be aggregated to any LDAP bean.

...
import javax.naming.ldap.*;
...
import net.sf.jldapbeans.commons.Organization;
import net.sf.jldapbeans.commons.DcObject;
import net.sf.jldapbeans.commons.SimpleSecurityObject;
import net.sf.jldapbeans.lang.LdapClass;
...

...
LdapContext ctx = new InitialLdapContext(..., ...);
Organization org = (Organization) ctx.lookup("dc=example,dc=com");
LdapClass.aggregate(org, SimpleSecurityObject.class);
((SimpleSecurityObject) org).setUserPassword("secret");
...

jLDAPBeans supports also aggregation between LdapClass objects if they are compatible. Here is an example of using aggregation between LdapClasses:

...
import net.sf.jldapbeans.commons.Organization;
import net.sf.jldapbeans.commons.DcObject;
import net.sf.jldapbeans.commons.SimpleSecurityObject;
import net.sf.jldapbeans.lang.LdapClass;
...

...
Organization org = ...;
DcObject dc = ...;
...
LdapClass dcClass = LdapClass.classOf(dc);
org = (Organization) LdapClass.aggregate(org, dcClass);
((DcObject) org).setDomainComponent("dc=example,dc=com");
...

Using jLDAPBeans with Tomcat