InitialDirContext- Java SE 11 & JDK 11

Introduction

InitialDirContext is a Java class that provides a way to connect to a directory service and perform operations such as searching, adding, modifying, and deleting entries. It is part of the Java Naming and Directory Interface (JNDI) API, which is a standard way of accessing different naming and directory services.

Working with InitialDirContext

To use InitialDirContext, you need to create an instance of it by passing it a set of properties that define the connection parameters. These properties include the URL of the directory service, the username and password (if required), and other options such as the security settings and the protocol to use.

Hashtable<String, Object> env = new Hashtable<>();
env.put(Context.INITIAL_CONTEXT_FACTORY, "com.sun.jndi.ldap.LdapCtxFactory");
env.put(Context.PROVIDER_URL, "ldap://localhost:389/dc=mycompany,dc=com");
env.put(Context.SECURITY_AUTHENTICATION, "simple");
env.put(Context.SECURITY_PRINCIPAL, "cn=admin,dc=mycompany,dc=com");
env.put(Context.SECURITY_CREDENTIALS, "adminpassword");

InitialDirContext ctx = new InitialDirContext(env);

Once you have created an InitialDirContext object, you can use its methods to perform various operations on the directory service. For example, you can search for entries that match certain criteria, add new entries, modify existing entries, and delete entries.

Searching for Entries

To search for entries in a directory service using InitialDirContext, you need to create a SearchControls object that specifies the search criteria and the attributes to return. You then pass this object to the search() method of the InitialDirContext object, along with the search base (the point in the directory tree where the search should start) and the search filter (the criteria for matching entries).

SearchControls controls = new SearchControls();
controls.setSearchScope(SearchControls.SUBTREE_SCOPE);
controls.setReturningAttributes(new String[]{"cn", "mail", "telephoneNumber"});
controls.setTimeLimit(10000);

String filter = "(&(objectClass=person)(cn=John Doe))";
NamingEnumeration<SearchResult> results = ctx.search("ou=people,dc=mycompany,dc=com", filter, controls);

while (results.hasMore()) {
    SearchResult result = results.next();
    Attributes attrs = result.getAttributes();
    String name = attrs.get("cn").get().toString();
    String email = attrs.get("mail").get().toString();
    String phone = attrs.get("telephoneNumber").get().toString();
    System.out.println(name + ", " + email + ", " + phone);
}

In this example, we are searching for all entries of class "person" with the common name "John Doe" in the "ou=people,dc=mycompany,dc=com" subtree. We are returning the "cn", "mail", and "telephoneNumber" attributes and setting a time limit of 10 seconds for the search. We are then iterating over the results and printing out the values of these attributes for each matching entry.

Adding Entries

To add a new entry to a directory service using InitialDirContext, you need to create a BasicAttributes object that defines the attributes of the entry. You then create a new DirContext object for the parent entry (the one under which the new entry will be added) and call its createSubcontext() method, passing it the name of the new entry and the BasicAttributes object.

Attributes attrs = new BasicAttributes();
attrs.put(new BasicAttribute("objectClass", "person"));
attrs.put(new BasicAttribute("cn", "Jane Doe"));
attrs.put(new BasicAttribute("mail", "jane.doe@mycompany.com"));
attrs.put(new BasicAttribute("telephoneNumber", "555-1234"));

DirContext parentCtx = (DirContext)ctx.lookup("ou=people,dc=mycompany,dc=com");
parentCtx.createSubcontext("cn=Jane Doe", attrs);

In this example, we are creating a new entry of class "person" with the common name "Jane Doe" and the email address "jane.doe@mycompany.com" and phone number "555-1234". We are then creating a new DirContext object for the "ou=people,dc=mycompany,dc=com" entry and calling its createSubcontext() method to add the new entry as a subentry.

Modifying Entries

To modify an existing entry in a directory service using InitialDirContext, you need to create a ModificationItem object that specifies the attribute to modify and the type of modification (add, replace, or remove). You then create an array of ModificationItem objects and call the modifyAttributes() method of the DirContext object for the entry, passing it the array.

ModificationItem[] mods = new ModificationItem[2];
mods[0] = new ModificationItem(DirContext.REPLACE_ATTRIBUTE, new BasicAttribute("mail", "jane.doe@mynewcompany.com"));
mods[1] = new ModificationItem(DirContext.ADD_ATTRIBUTE, new BasicAttribute("description", "Marketing Manager"));

ctx.modifyAttributes("cn=Jane Doe,ou=people,dc=mycompany,dc=com", mods);

In this example, we are modifying the email address of the "Jane Doe" entry to "jane.doe@mynewcompany.com" and adding a new attribute "description" with the value "Marketing Manager". We are then calling the modifyAttributes() method of the InitialDirContext object, passing it the DN (distinguished name) of the entry and the array of ModificationItem objects.

Deleting Entries

To delete an entry from a directory service using InitialDirContext, you need to call the destroySubcontext() method of the DirContext object for the entry.

ctx.destroySubcontext("cn=Jane Doe,ou=people,dc=mycompany,dc=com");

In this example, we are deleting the "Jane Doe" entry from the "ou=people,dc=mycompany,dc=com" subtree by calling the destroySubcontext() method of the InitialDirContext object and passing it the DN of the entry.

Conclusion

InitialDirContext is a powerful and flexible class that provides a standard way of connecting to and working with directory services in Java applications. By using its methods to search, add, modify, and delete entries, you can easily manage directory data and integrate it with other systems and applications.

Whether you are building an LDAP-enabled web application, a network management tool, or a directory-enabled messaging system, InitialDirContext can help you access and manipulate directory data in a simple and efficient way.