Spring LDAP Packaging

Now that you have successfully downloaded the Spring LDAP framework, let’s delve into its subfolders. The libs folder contains Spring LDAP binary, source, and javadoc distribution. The LDAP framework is packaged into six different components. Table 3-1 provides a brief description of each component. The docs folder contains the javadoc for the API and the reference guide in different formats.

Along with Spring Framework, you need additional jar files for compiling and running applications using Spring LDAP. Table 3-2 lists some of these dependent jars files along with a description of why they are used.

Downloading Spring LDAP Source

The Spring LDAP project uses Git as their source control system. The source code can be downloaded from https://github.com/SpringSource/spring-ldap.

Spring LDAP source code can provide valuable insights into the framework architecture. It also includes a rich test suite that can serve as additional documentation and help you understand the framework. I strongly recommend that you download and look at the source code. The Git repository also holds a sandbox folder that contains several experimental features that may or may not make it into the framework.

Installing Maven

To install Maven, simply download the latest version from http://maven.apache.org/download.html. Once the download is complete, unzip the distribution to a local directory on your machine. Then make the following modifications to your development box:

• Add a M2_HOME environment variable pointing to the maven installation directory.
• Add a MAVEN_OPTS environment variable with the value of – Xmx512m.
• Add to the Path environment variable the M2_HOME/bin value.

This completes Maven installation. You can verify the installation by running the following command on your command line:

$  mvn  –v

This command should output information similar to the following:

Apache Maven 3.1.0 (893ca28a1da9d5f51ac03827af98bb730128f9f2; 2013-06-27 20:15:32-0600)
Maven home: c:	oolsmaven
Java version: 1.6.0_35, vendor: Sun Microsystems Inc.
Java home: C:Javajdk1.6.0_35jre
Default locale: en_US, platform encoding: Cp1252
OS name: "windows 7", version: "6.1", arch: "x86", family: "windows"

Spring LDAP Archetypes

To jump-start Spring LDAP development, this book uses the following two archetypes:

• practical-ldap-empty-archetype: This archetype can be used to create an empty Java project with all the required LDAP dependencies.
• practical-ldap-archetype: Similar to the above archetype, this archetype creates a Java project with all the required LDAP dependencies. Additionally, it also includes Spring LDAP configuration files, sample code, and dependencies to run an in-memory LDAP server for testing purposes.

Before you can use the archetypes to create a project, you need to install them. If you have not already done so, download the accompanying source/download files from Apress. In the downloaded distribution, you will find practical-ldap-empty-archetype-1.0.0.jar and practical-ldap-archetype-1.0.0.jar archetypes. Once you have the jar files downloaded, run the following two commands at the command line:

mvn  install:install-file 
     -DgroupId=com.inflinx.book.ldap 
     -DartifactId=practical-ldap-empty-archetype 
     -Dversion=1.0.0 
     -Dpackaging=jar
     -Dfile=<JAR_LOCATION_DOWNLOAD>/practical-ldap-empty-archetype-1.0.0.jar
 
mvn  install:install-file 
     -DgroupId=com.inflinx.book.ldap 
     -DartifactId=practical-ldap-archetype 
     -Dversion=1.0.0 
     -Dpackaging=jar
     -Dfile=< JAR_LOCATION_DOWNLOAD >/practical-ldap-archetype-1.0.0.jar

These maven install commands will install the two archetypes in your local maven repository. Creating a project using one of these archetypes simply involves running the following command:

C:practicalldapcode>mvn archetype:generate
-DarchetypeGroupId=com.inflinx.book.ldap 
-DarchetypeArtifactId=practical-ldap-empty-archetype 
-DarchetypeVersion=1.0.0 
-DgroupId=com.inflinx.ldap 
-DartifactId=chapter3 
-DinteractiveMode=false

Notice that this command is executed inside the directory c:/practicalldap/code. The command instructs maven to use the archetype practical-ldap-empty-archetype and generate a project named chapter3. The generated project directory structure is shown in Figure 3-4.

This directory structure has a src folder that holds all the code and any associated resources such as XML files. The target folder contains the generated classes and build artifacts. The main folder under src usually holds the code that eventually makes its way to production. The test folder contains the related test code. Each of these two folders contains java and resources subfolders. As name suggests, the java folder contains Java code and the resources folder usually contains configuration xml files.

The pom.xml file in the root folder holds the configuration information needed by Maven. For example, it contains information about all the dependent jar files that are required for compiling the code (see Listing 3-1).

Listing 3-1.

<dependencies>
    <dependency>
        <groupId>org.springframework.ldap</groupId>
        <artifactId>spring-ldap-core</artifactId>
        <version>${org.springframework.ldap.version}</version>
        <scope>compile</scope>
    </dependency>
</dependencies>

The pom.xml snippet in Listing 3-1 indicates that the project will need the spring-ldap-core.jar file during its compilation.

Maven requires a group id and artifact id to uniquely identify a dependency. A group id is usually unique to a project or organization and is similar to the concept of a Java package. The artifact id is usually the name of the project or a generated component of the project. The scope determines the phase during which the dependency should be included in the classpath. Here are few possible values:

• test: A test scope indicates that the dependency should be included in the classpath only during testing process. JUnit is an example of such dependency.
• provided: The provided scope indicates that the artifact should be included in the classpath during compilation only. Provided scope dependencies are usually available at runtime via JDK or application container.
• compile: A compile scope indicates that the dependency should be included in the classpath at all times.

An additional section in the pom.xml file contains information about the plug-ins that Maven can use to compile and build the code. One such plug-in declaration is displayed in Listing 3-2. It instructs Maven to use the compiler plug-in of version 2.0.2 to compile Java code. The finalName indicates the name of the generated artifact. In this case, it would be chapter3.jar.

Listing 3-2.

<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin
            </artifactId>
            <version>2.0.2</version>
            <configuration>
                <source>1.6</source>
                <target>1.6</target>
            </configuration>
        </plugin>
     </plugins>
     <finalName>chapter3</finalName>
</build>

To build this generated application, simply run the following command from the command line. This command cleans the target folder, compiles the source files, and generates a jar file inside the target folder.

mvn  clean  compile package

This setup, along with a text editor, is enough to start developing and packaging Java-based LDAP applications. However, it is a no-brainer that you can be more productive developing and debugging applications using a graphical IDE. There are several IDEs, with Eclipse, NetBeans, and IntelliJ IDEA being the most popular. For this book you will be using Spring Tool Suite, an Eclipse-based IDE from Spring Source.

Setting Up Spring IDE

STS is a free, Eclipse-based development environment that provides the best tool support for developing Spring-based applications. The following are some of its features:

• Wizards for creating Spring projects and Spring beans
• Integrated support for Maven
• Templates based on best practices for project and file creation
• Spring bean and AOP pointcut visualization
• Spring ROO shell integration for rapid prototyping
• Task-based user interface that provides guided assistance through tutorials
• Support for Groovy and Grails

In this section you will look at installing and setting up the STS IDE.

1. Download and initiate the STS installer from the Spring Tool Suite web site at www.springsource.com/developer/sts. The installation file for Windows is spring-tool-suite-3.3.0.RELEASE-e4.3-win32-installer.exe. Double-click the install file to start the installation (Figure 3-5).

   

   Figure 3-5. Installer home screen

2. Read and accept the License Agreement and click the Next button.
3. On the Target Path screen, choose an installation directory.
4. Leave the default selection and then click the Next button (see Figure 3-6).

   

   Figure 3-6. Installation packages

5. On the following screen, provide the path to the JDK installation and click the Next button.
6. This will begin the installation; wait for the file transfer to complete.
7. Click the Next button on the following two screens to complete the installation.

Creating Projects Using STS

In the earlier “Spring LDAP Archetype” section you used the practical-ldap-empty-archetype archetype to generate a project from command line. Now let’s look at generating the same project using STS.

1. From the File menu, select New Project. It will launch the New Project wizard (see Figure 3-7). Select the Maven Project option and click the Next button.

   

   Figure 3-7. New Project wizard

2. Uncheck “Use default Workspace location” and enter the path for the newly generated project, and then select the Next button (see Figure 3-8).

   

   Figure 3-8. Project path setup

3. On the Select an Archetype screen (see Figure 3-9), click “Add Archetype.” This step assumes that you have already installed the archetype as mentioned in the earlier section. Fill the Add Archetype dialog with the details shown in Figure 3-9 and press OK. Do the same for the other archetype.

   

   Figure 3-9. Archetype details

4. Enter ldap in the Filter field and select the practical-ldap-empty-archetype. Click the Next button (see Figure 3-10).

   

   Figure 3-10. Archetype selection

5. On the following screen, provide the information about the newly created project and click the Finish button (see Figure 3-11).

This will generate a project with the same directory structure that you saw earlier. However, it also creates all the IDE-specific files such as .project and .classpath and adds all the dependent Jars to the project’s classpath. The complete project structure is shown in Figure 3-12.

Installing Apache Directory Studio

The Apache Directory Studio is a popular, open source LDAP browser that can help you browse LDAP directories very easily. To install Apache Directory Studio, download the installer file from

http://directory.apache.org/studio/downloads.html.

The Studio installation can be done by following these steps.

1. On Windows, start the installation by double-clicking the install file (this will bring up the install screen).
2. Read and accept the license agreements to continue.
3. Choose your preferred installation directory, and select “Install” (see Figure 3-16).

   

   Figure 3-16. Apache installation directory selection

4. You will be shown the status of the installation and file transfer.
5. After all the files have been transferred, click the Finish button to complete the installation.

Once the installation is complete, the next step is to create a connection to the newly installed OpenDJ LDAP server. Before you can proceed, make sure your OpenDJ server is running. Here are the steps to set up the new connection.

1. Launch ApacheDS server. In Windows, click the Apache Directory Studio.exe file.
2. Launch the New Connection wizard by right-clicking in the “Connections” section and selecting “New Connection.”

   

   Figure 3-17. Creating a new connection

3. On the Network Parameter screen, enter the information displayed in Figure 3-18. This should match the OpenDJ information you entered during OpenDJ installation.

   

   Figure 3-18. LDAP connection network parameters

4. On the Authentication screen, enter “cn=Directory Manager” as Bind DN or user and “opendj” as password (see Figure 3-19).

   

   Figure 3-19. LDAP connection authentication

5. Accept the defaults in the Browser Options section and select the Finish button.

Loading Test Data

In the previous sections you installed the OpenDJ LDAP server and Apache Directory Studio for accessing the LDAP server. The final step in setting up your development/test environment is to load the LDAP server with test data.

Here are the steps for loading the test data.

1. Right-click “Root DSE” in the LDAP browser pane and select Import LDIF Import (see Figure 3-20).

   

   Figure 3-20. LDIF import

2. Browse for this patrons.ldif file (see Figure 3-21) and click the Finish button. Make sure that the “Update existing entries” checkbox is selected.

   

   Figure 3-21. LDIF import settings

3. Upon a successful import you will see the data loaded under the dc=inflinx,dc=com entry (see Figure 3-22).

Spring ApplicationContext

Central to every Spring Framework application is the notion of ApplicationContext. Implementations of this interface are responsible for creating and configuring Spring beans. The application context also acts as an IoC container and is responsible for performing the dependency injection. A Spring bean is simply a standard POJO with metadata needed to run inside the Spring container.

In a standard Spring application the ApplicationContext is configured via an XML file or Java annotations. Listing 3-6 shows a sample application context file with one bean declaration. The bean myBean is of type com.inflinx.book.ldap.SimplePojo. When the application loads the context, Spring creates an instance of SimplePojo and manages it.

Listing 3-6.

<?xml version="1.0"  encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xmlns:context="http://www.springframework.org/schema/context"
        xsi:schemaLocation="http://www.springframework.org/schema/
beans http://www.springframework.org/schema/beans/spring-beans.xsd
        http://www.springframework.org/schema/context
http://www.springframework.org/schema/context/spring-context.xsd">
 
        <bean  id="myBean" class="com.inflinx.book.ldap.SimplePojo">
        </bean>
</beans>

Spring-Powered Search Client

Our conversion of the search client implementation begins with the applicationContext.xml file as shown in Listing 3-7.

Listing 3-7.

<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:context="http://www.springframework.org/schema/context"
xsi:schemaLocation="http://www.springframework.org/schema/beans
http://www.springframework.org/schema/beans/spring-beans.xsd
http://www.springframework.org/schema/context
http://www.springframework.org/schema/context
/spring-context.xsd">

 
<bean id="contextSource"
class="org.springframework.ldap.core.support.LdapContextSource">
     <property  name="url" value="ldap://localhost:11389"  />
     <property name="userDn" value="cn=Directory  Manager" />
     <property name="password" value="opendj"  />
  </bean>
 
<bean id="ldapTemplate"
class="org.springframework.ldap.core.LdapTemplate">
     <constructor-arg ref="contextSource" />
</bean>
<context:component-scan base-package="com.inflinx.book.ldap"/>
</beans>

In the context file, you declare a contextSource bean to manage connections to LDAP server. For LdapContextSource to properly create instances of DirContext, you need to provide it with information about the LDAP server. The url property takes the fully qualified URL (ldap://server:port format) to the LDAP server. The base property can be used to specify the root suffix for all LDAP operations. The userDn and password properties are used to provide authentication information. Next, you configure a new LdapTemplate bean and inject the contextSource bean.

With all your dependencies declared in the context file, you can proceed to re-implementing the search client, as shown in Listing 3-8.

Listing 3-8.

package com.inflinx.book.ldap;
import java.util.List;
import javax.naming.NamingException;
import javax.naming.directory.Attributes;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.context.ApplicationContext;
import org.springframework.context.support. ClassPathXmlApplicationContext;
import org.springframework.ldap.core.AttributesMapper;
import org.springframework.ldap.core.LdapTemplate;
import org.springframework.stereotype.Component;
 
@Component
public class SpringSearchClient {
 
   @Autowired
   @Qualifier("ldapTemplate")
   private LdapTemplate ldapTemplate;
 
   @SuppressWarnings("unchecked")
   public List<String> search() {
      List<String> nameList = ldapTemplate.search("dc=inflinx,dc=com",
      "(objectclass=person)",
                new AttributesMapper() {
                  @Override
                  public Object mapFromAttributes(Attributes attributes)
                  throws NamingException {
                     return (String)attributes.get("cn").get();
                  }
                });
      return nameList;
   }
}

You will notice that this code is no different from the SearchClient code you saw in Listing 3-4. You just extracted the creation of LdapTemplate to an external configuration file. The @Autowired annotation instructs Spring to inject the ldapTemplate dependency. This simplifies the search client class very much and helps you focus on the search logic.

The code to run the new search client is shown in Listing 3-9. You start by creating a new instance of ClassPathXmlApplicationContext. The ClassPathXmlApplicationContext takes the applicationContext.xml file as its parameter. Then you retrieve an instance of SpringSearchClient from the context and invoke the search method.

Listing 3-9.

public static void main(String[] args){
   ApplicationContext context = new ClassPathXmlApplicationContext("classpath:applicationContext.xml");
   SpringSearchClient client = context.getBean(SpringSearchClient.class);
   List<String> names = client.search();
   for(String name: names) {
      System.out.println(name);
   }
}

Add Operation

The LdapTemplate class provides several bind methods that allow you to create new LDAP entries. The simplest among those methods is as follows:

public void bind(String dn, Object obj,  Attributes  attributes)

The first parameter to this method is the unique distinguished name of the object that needs to be bound. The second parameter is the object to be bound and is usually an implementation of the DirContext interface. The third parameter is the attribute of the object to be bound. Among the three, only the first parameter is required and you can pass a null for the rest of the two.

Listing 3-10 shows the code involved in creating a new patron entry with minimal set of information. You start the method implementation by creating a new instance of BasicAttributes class to hold the patron attributes. Single-valued attributes are added by passing the attribute name and value to the put method. To add the multi-valued attribute objectclass, you create a new instance of BasicAttribute. You then add the entry’s objectClass values to the objectClassAttribute and add it to the attributes list. Finally, you invoke the bind method on the LdapTemplate with the patron information and patron’s fully qualified DN. This adds the patron entry to LDAP server.

Listing 3-10.

public void addPatron() {
   // Set the Patron attributes
   Attributes attributes = new BasicAttributes();
   attributes.put("sn", "Patron999");
   attributes.put("cn", "New Patron999");
   // Add the multi-valued attribute
   BasicAttribute objectClassAttribute = new BasicAttribute("objectclass");
   objectClassAttribute.add("top");
   objectClassAttribute.add("person");
   objectClassAttribute.add("organizationalperson");
   objectClassAttribute.add("inetorgperson");
   attributes.put(objectClassAttribute);
   ldapTemplate.bind("uid=patron999,ou=patrons,dc=inflinx,dc=com",null, attributes);
}

Modify Operation

Consider the scenario where you want to add a telephone number to the newly added patron. To do that, LdapTemplate provides a convenient modifyAttributes method with the following signature:

public void modifyAttributes(String dn, ModificationItem[]  mods)

This variation of modifyAttributes method takes the fully qualified unique DN of the entry to be modified as its first parameter. The second parameter takes an array of ModificationItems where each modification item holds the attribute information that needs to be modified.

Listing 3-11 shows the code that adds a new telephone number to the patron.

Listing 3-11.

public void addTelephoneNumber() {
   Attribute attribute = new BasicAttribute("telephoneNumber", "801 100 1000");
   ModificationItem item = new ModificationItem(DirContext.ADD_ATTRIBUTE, attribute);
   ldapTemplate.modifyAttributes("uid=patron999," + "ou=patrons,dc=inflinx,dc=com", new ModificationItem[] {item});
}

In this implementation, you simply create a new BasicAttribute with telephone information. Then you create a new ModificationItem and pass in the ADD_ATTRIBUTE code, indicating that you are adding an attribute. Finally, you invoke the modifyAttributes method with the patron DN and the modification item. The DirContext has a REPLACE_ATTRIBUTE code that when used will replace an attribute’s value. Similarly, the REMOVE_ATTRIBUTE code will remove the specified value from the attribute.

Deleting Operation

Similar to addition and modification, LdapTemplate makes it easy to remove an entry with the unbind method. Listing 3-12 provides the code that implements the unbind method and removes a patron. As you can see, the unbind method takes the DN for the entry that needs to be removed.

Listing 3-12.

public void removePatron() {
   ldapTemplate.unbind("uid=patron999," + "ou=patrons,dc=inflinx,dc=com");
}