Another Double Espresso Please!

Parallel Processing with ForkJoinPool

2012-01-31T03:11:00.000-08:00

With the release of Java 7 came the new Executor Service, ForkJoinPool. The class uses the notion of work-stealing threads which execute tasks which have been created by other tasks. Ultimately, this division of work will result in large problems becoming a series of smaller ones which will eventually result in one answer when all the tasks have completed their processing.

This post will demonstrate this new threading feature by an interpolation example. In this case, for two numbers with a given number of steps, the code will attempt to construct new points between those numbers using linear interpolation, and for simplicity using only a number of steps divisible by 2. eg for the numbers 5 and 25 with a step number of 4, the generated sequence would be:

[5.0, 10.0, 15.0, 20.0, 25.0]

The InterpolationService class below will contain an instance of the ForkJoinPool class. A ForkJoinPool instance can be created with an argument representing a target parallelism. This can either be supplied or left as the default which will be the number of processors ie Runtime.availableProcessors()

package com.city81.forkjoin;

import java.util.ArrayList;
import java.util.List;
import java.util.concurrent.ForkJoinPool;
import java.util.concurrent.ForkJoinTask;
import java.util.concurrent.RecursiveTask;

public class InterpolateService {

    private final ForkJoinPool forkJoinPool;

    public InterpolateService() {
        forkJoinPool = new ForkJoinPool();
    }

    public List<Double> interpolate(double valueOne, double valueTwo, int steps) {
        
        ForkJoinTask<List<Double>> job = forkJoinPool.submit(
            new InterpolateTask(valueOne, valueTwo, steps));
        return job.join();
    }

    private static class InterpolateTask 
        extends RecursiveTask<List<Double>> {

        private final double valueOne;
        private final double valueTwo;
        private final int steps;
        private static final int LOWEST_STEP = 2;

        protected InterpolateTask(double valueOne, double valueTwo, int steps) {

            this.valueOne = valueOne;
            this.valueTwo = valueTwo;
            this.steps = steps;
        }

        @Override
        protected List<Double> compute() {
    
            List<Double> interpolatedArray = new ArrayList<Double>();
            double interpolatedValue = interpolate(valueOne, valueTwo);
    
            if (this.steps == LOWEST_STEP) {
                interpolatedArray.add(valueOne);
                interpolatedArray.add(interpolatedValue);
                interpolatedArray.add(valueTwo);
            } else {
                InterpolateTask interpolateTask1 = 
                    new InterpolateTask(valueOne, interpolatedValue, (steps/2));
                interpolateTask1.fork();
                InterpolateTask interpolateTask2 = 
                    new InterpolateTask(interpolatedValue, valueTwo, (steps/2));
                List<Double> interpolatedArrayTask2 = 
                    interpolateTask2.compute();
                List<Double> interpolatedArrayTask1 = 
                    interpolateTask1.join();
                interpolatedArray.addAll(
                    interpolatedArrayTask1.subList(0, interpolatedArrayTask1.size() - 1));
                interpolatedArray.addAll(interpolatedArrayTask2);
            }
            // System.out.println(interpolatedArray);
            return interpolatedArray;
        }

        private double interpolate(
            double valueOne, double valueTwo) {
   
            return ((valueTwo - valueOne) / 2.0) + valueOne;
        }

    }

    public static void main(String[] args) {
        InterpolateService interpolateService = new InterpolateService();
        List<Double> interpolatedArray = interpolateService.interpolate(5,25,4);
        System.out.println(interpolatedArray);
    }

}

The InterpolationService 's only public method interpolate, takes two numbers and the number of steps. These are the parameters to construct an instance of our private static class InterpolateTask. This class implements RecursiveTask which can return a result when the compute method is called on the task. An alternative implementation (but not suitable for this example) would be RecursiveAction whose compute method returns nothing.

The constructed task is submitted to the ForkJoinPool.

The compute method is where the logic for subdividing the task resides. It decides whether the work it has to process is small enough to process now or whether it needs further division. In the case of our example, the task will determine a task small enough when the step size is 2. If not, it will create two sub tasks, dividing the step size each time.

Eventually, all tasks will be of a small enough size to be completed. This will result in the arrays being added together as the recursive task tree is traversed back up to the original task.

This is not example of how to efficiently perform linear interpolation on a set of numbers but is just one example implementation of how to use the ForkJoinPool and its associated Task classes. Over time, hopefully this post can be updated to make the above code more efficient as well gathering metrics and benchmarking against other implementations.

Spring MVC and RESTful Web Services

2012-01-27T00:38:00.000-08:00

This post is a follow up to the Spring MVC Bare Essentials post and shows how a simple RESTful web service can be implemented using Spring MVC. It'll also show the different ways in which the controller services can be implemented and how the model can be rendered.

The post will use the same classes and XML files as in the Bare Essentials post but change them to make the methods expoed by the controller RESTful.

First of all, the ExampleController class will change to use web bind annotations which will mark the class and the methods within it with URL paths.

@Controller
@RequestMapping("/controller")
public class ExampleController {

    @RequestMapping(value="message", method=RequestMethod.GET)

    public ModelAndView getMessage() {
        Message message = new Message("Spring MVC Rest Example");
        ModelAndView modelAndView = new ModelAndView(
            "example", "message", message);
        return modelAndView;
    }

}

The web.xml below shows the changes to the servlet mapping tag and in particular the url-pattern. This means our URLs will be:

http://<ip>:<port>/<app name>/example/<request mapping>

<servlet-mapping>
    <servlet-name>springMVCRESTExample</servlet-name>
    <url-pattern>/example/*</url-pattern>
</servlet-mapping>

In the servlet's context XML file, we'll auto detect the ExampleController bean by using context:component-scan and then add the BeanNameViewResolver to interpret a view name as a bean name. Finally, add a MarshallingView which will use JAX-B to marshall and unmarshall the com.city81.spring.mvc.rest.domain.Message class.


<context:component-scan base-package="com.city81.spring.mvc.rest" /> 

<bean class="org.springframework.web.servlet.view.BeanNameViewResolver" />

<bean id="example" class="org.springframework.web.servlet.view.xml.MarshallingView">
    <constructor-arg>
        <bean class="org.springframework.oxm.jaxb.Jaxb2Marshaller">
            <property name="classesToBeBound">
                <list>
                    <value>com.city81.spring.mvc.rest.domain.Message</value>
                </list>
            </property>
        </bean>
    </constructor-arg>
</bean>

Building a WAR and deploying to a container such as Tomcat would then enable you call the getMessage method of the ExampleController class with the URL:

http://<ip>:<port>/<app name>/example/controller/message

An alternative to implementing the getMessage method is to use the @ModelAttribute instead the the ModelView class as shown below:

@RequestMapping(value = "message", method = RequestMethod.GET)
public @ModelAttribute("example") Message getMessage() {
    Message message = new Message("Spring MVC Rest Example");
    return message;
}

Another alternative is to use <mvc:annotation-driven /> which was introduced in Spring 3. By adding it to the servlet's context XML file (in place of the beans BeanNameViewResolver and MarshallingView), the getMessage method can then be implemented as show below:

@RequestMapping(value="message", method = RequestMethod.GET)
public @ResponseBody Message getMessage() {
    Message message = new Message("Spring MVC Rest Example");
    return message;
}

This is a very simple example that can be built upon to use different RESTful methods. There are also different ways in which XML can be rendered in the view and also different types that can be rendered eg text. It is also worth considering Spring Roo if wanting to implement a RESTful web service. These will hopefully be covered in further posts.

Using Maven to Generate Wrapped or Non-Wrapped SOAP Bindings

2012-01-19T08:11:00.000-08:00

For a given WSDL, there are several different ways to generate Java web service code (CXF, Axis2, etc..). And depending on certain settings within the WSDL file and settings used by the relevant build tool, there are different ways of exposing those services described in the WSDL.

This post will briefly document the generating of Java code for a WSDL using Maven and the jaxws wsimport plugin. It will also show the difference in the services exposed when using wrapped and non-wrapped bindings.

Below is an extract from a pom.xml to generate the Java code:

<plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>jaxws-maven-plugin</artifactId>
    <version>1.10</version>
    <executions>
        <execution>
            <goals>
                <goal>wsimport</goal>
            </goals>
            <configuration>
                <wsdlFiles>
                    <wsdlFile>City81SOAPService.wsdl</wsdlFile>
                </wsdlFiles>
                <bindingDirectory>${basedir}/src/wsdl</bindingDirectory>
            </configuration>
            <id>generate-sources</id>
            <phase>generate-sources</phase>
        </execution>
    </executions>
    <dependencies>
         .........            
    </dependencies>
    <configuration>
        <sourceDestDir>
            ${project.build.directory}/generated-sources/jaxws-wsimport
        </sourceDestDir>
        <xnocompile>true</xnocompile>
        <verbose>true</verbose>
        <extension>true</extension>
        <catalog>${basedir}/src/jax-ws-catalog.xml</catalog>                  
    </configuration>
</plugin>

For the below WSDL file, the wsimport plugin will generate the following classes:

com\city81\soap\Balance.java
com\city81\soap\City81SOAP.java
com\city81\soap\City81SOAPImplService.java
com\city81\soap\CreateCustomer.java
com\city81\soap\CreateCustomerResponse.java
com\city81\soap\CreateCustomerResponseType.java
com\city81\soap\CreateStatus.java
com\city81\soap\ObjectFactory.java
com\city81\soap\package-info.java

<?xml version='1.0' encoding='UTF-8'?>
<wsdl:definitions name="City81SOAPService" targetNamespace=http://soap.city81.com/ xmlns:ns1=http://schemas.xmlsoap.org/wsdl/soap/http
xmlns:soap="http://schemas.xmlsoap.org/wsdl/soap/" xmlns:tns="http://soap.city81.com/"
xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/" xmlns:xsd="http://www.w3.org/2001/XMLSchema">

    <wsdl:types>
        <xsd:schema>
            <xsd:import namespace="http://soap.city81.com/" schemaLocation="City81SOAPService.xsd" />
        </xsd:schema>
    </wsdl:types>

    <wsdl:message name="createCustomer">
        <wsdl:part name="params" element="tns:createCustomer"></wsdl:part>
    </wsdl:message>
    <wsdl:message name="createCustomerResponse">
        <wsdl:part name="params" element="tns:createCustomerResponse"></wsdl:part>
    </wsdl:message>

    <wsdl:portType name="City81SOAP">
        <wsdl:operation name="createCustomer">
            <wsdl:input message="tns:createCustomer"></wsdl:input>
            <wsdl:output message="tns:createCustomerResponse"></wsdl:output>
        </wsdl:operation>
    </wsdl:portType>

    <wsdl:binding name="City81SOAPImplServiceSoapBinding" type="tns:City81SOAP">
        <soap:binding style="document" transport="http://schemas.xmlsoap.org/soap/http" />
        <wsdl:operation name="createCustomer">
            <soap:operation soapAction="http://soap.city81.com/createCustomer" />
            <wsdl:input>
                <soap:body use="literal" />
            </wsdl:input>
            <wsdl:output>
                <soap:body use="literal" />
            </wsdl:output>
        </wsdl:operation>
    </wsdl:binding>

    <wsdl:service name="City81SOAPImplService">
        <wsdl:port binding="tns:City81SOAPImplServiceSoapBinding" name="City81SOAPImplPort">
            <soap:address location=http://localhost:8080/city81-soap/soap />
        </wsdl:port>
    </wsdl:service>

</wsdl:definitions>

For the above settings, the generated City81SOAP class will be as below:

@WebService(name = "City81SOAP", targetNamespace = "http://soap.city81.com/")
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@XmlSeeAlso({
    ObjectFactory.class
})
public interface City81SOAP {

    @WebMethod(action = "http://soap.city81.com/createCustomer")
    @WebResult(name = "createCustomerResponse", targetNamespace = "http://soap.city81.com/", partName = "params")
    public CreateCustomerResponse createCustomer(@WebParam(name = "createCustomer", targetNamespace = "http://soap.city81.com/", partName = "params") CreateCustomer params);

}

The binding style as can be seen from the @SOAPBinding annotation at the head of the class is BARE ie non-wrapped. The method's args and return parameters are in each case represented as a single Java object. CreateCustomer and CreateCustomerResponse.

This has happened because in the pom.xml file, there is a bindingDirectory tag which points to a folder containing a binding.xml file. This file, shown below, has an enableWrapperStyle tag and the boolean value of false.

<bindings
    xmlns:wsdl="http://schemas.xmlsoap.org/wsdl/"
    wsdlLocation="City81SOAPService.wsdl"
    xmlns="http://java.sun.com/xml/ns/jaxws">
        <!-- Disable default wrapper style -->
        <enableWrapperStyle>false</enableWrapperStyle>        
</bindings>

If the boolean was true, or if there was no bindingDirectory tag in the pom.xml file, then the default SOAP binding style would be used ie WRAPPED. This would then result in the below generated City81SOAP class:

@WebService(name = "City81SOAP", targetNamespace = "http://soap.city81.com/")
@XmlSeeAlso({
    ObjectFactory.class
})
public interface City81SOAP {

    @WebMethod(action = "http://soap.city81.com/createCustomer")
    @RequestWrapper(localName = "createCustomer", targetNamespace = "http://soap.city81.com/", className = "com.city81.soap.CreateCustomer")
    @ResponseWrapper(localName = "createCustomerResponse", targetNamespace = "http://soap.city81.com/", className = "com.city81.soap.CreateCustomerResponse")
    public void createCustomer(

        @WebParam(name = "surname", targetNamespace = "")
        String surname,
        @WebParam(name = "firstName", targetNamespace = "")
        String firstName,
        @WebParam(name = "balance", targetNamespace = "")
        Balance balance,
        @WebParam(name = "customerId", targetNamespace = "", mode = WebParam.Mode.OUT)
        Holder<String> customerId,
        @WebParam(name = "status", targetNamespace = "", mode = WebParam.Mode.OUT)
        Holder<CreateStatus> status);

}

The method's args are now individual Java objects and the return parameters are each represented as Holder objects with a WebParam.Mode.OUT value denoting they are return objects. This means that return objects are set as opposed to actually being returned in the method's signature.

Another way to specify bindings other than using the binding.xml file is to embed the enableWrapperStyle as a child of the portType but if a WSDL is from a third party, then having to change it every time a new version of the WSDL is released is open to errors.

<wsdl:portType name="City81SOAPImplService">
    <jaxws:bindings xmlns:jaxws="http://java.sun.com/xml/ns/jaxws">
        <jaxws:enableWrapperStyle>false</jaxws:enableWrapperStyle>
    </jaxws:bindings>
    ...
</wsdl:portType>

Back to the generated interfaces, and these of course need to be implemented. For an interface with a binding type of BARE, the implemented class would look like below:

@WebService(targetNamespace = "http://soap.city81.com/", name = "City81SOAP", portName = "City81SOAPImplPort", serviceName = "City81SOAPImplService")
@SOAPBinding(style = SOAPBinding.Style.DOCUMENT, use = SOAPBinding.Use.LITERAL, parameterStyle = SOAPBinding.ParameterStyle.BARE)
public class City81SOAPImpl implements City81SOAP {    

    @Override   
    public CreateCustomerResponse createCustomer(CreateCustomer createCustomer) {      
        CreateCustomerResponse createCustomerResponse = 
            new CreateCustomerResponse();     
         .....
        return createCustomerResponse;  
    } 
}

In the case of WRAPPED binding style, the SOAPBinding annotation would include parameterStyle = SOAPBinding.ParameterStyle.WRAPPED and the createCustomer method would be as below:


    public void createCustomer(
        String surname,
        String firstName,
        Balance balance,
        Holder<String> customerId,
        Holder<CreateStatus> status) {
    
        customerId= new Holder<String>("1");
        status = new Holder<CreateStatus>(CreateStatus.CREATE_PENDING);
    }

This post shows that there are different ways to ultimately achieve the same result.

JAX-WS, JAXB and Generics

2011-11-29T06:06:00.000-08:00

When JAXB 2.1 came along it introduced a new annotation namely @XmlSeeAlso. It resolved the problem where at runtime, JAX-WS would only know about classes bound by JAXB and not sub classes of those which have been bound.

By using @XmlSeeAlso on a class, sub types of the bound class can be listed thereby allowing them to be bound also and therefore reachable by JAX-WS when marshalling and unmarshalling.

It can also be used to overcome the problem of using generics in a JAXB annotated class as the following simple example will describe. Given the below LogFile class, it will only be marshalled/unmarshalled if the T at runtime is bound.

@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
public class LogFile<T> {

    @XmlElement(name="logFileLine")
    private List<T> logFileLines;

    public LogFile() {
        logFileLines = new ArrayList<T>();
    }

    public LogFile(List<T> logFileLines) {
        this.logFileLines = logFileLines;
    }

    public List<T> getLogFileLines() {
        return logFileLines;
    }

    public void setLogFileLines(List<T> logFileLines) {
        this.logFileLines = logFileLines;
    }

    public void addLogFileLine(T logFileLine) {
        this.logFileLines.add(logFileLine);
    }

}

If LogFile contains a collection of eg Strings then this will work fine but if T is a class not bound, eg com.city81.domain.LogLine then an error similar to below will be thrown:

javax.xml.bind.MarshalException - with linked exception: [javax.xml.bind.JAXBException: class com.city81.domain.LogLine nor any of its super class is known to this context.]

To resolve this, the class LogLine needs to be included the @XmlSeeAlso annotation.


@XmlRootElement
@XmlAccessorType(XmlAccessType.FIELD)
@XmlSeeAlso(LogLine.class)
public class LogFile<T> {

    ....

}

This does of course mean you need to know what potential classes can be T before runtime but at least it means you can use Generics on JAXB annotated classes.

Using Spring Expression Language for Server Specific Properties

2011-11-17T20:09:00.000-08:00

Spring 3.0 introduced Spring Expression Language (SpEL). This post will describe how to use SpEL to load property files which are different for each server your application runs on. It also describes how server specific properties can used without having to use -D.

The problem solved was how can a WAR be deployed onto different servers without having to package up a server specific property file in each archive (or indeed bundle them all in the same WAR file.) Ideally, you would want to drop the WAR file into any environment without having to configure the container or amend the WAR, and if you wanted to change a property, you would change the property file on the server and redeploy the app (or dynamically refresh the cache of properties.)

In this example, our application needs to access a different remote server registry for each env: Dev, Test and Prod. (For ease in this example, our server names are the same as our envionments!)

Therefore we have a properties file for each env/server (dev.properties, test.properties and prod.properties). Could have a local.properties file on each server but prefixing them with a server name helps distinguish them. An example property file is shown below:

rmiRegistryHost=10.11.12.13
rmiRegistryPort=1099

We have a bean which requires these properties, so it's constructor args contain property placeholders:

<bean id="lookupService" class="com.city81.rmi.LookupService" scope="prototype">
  <constructor-arg index="0" value="${rmiRegistryHost}" /> 
  <constructor-arg index="1" value="${rmiRegistryPort}" />
</bean>

For the above bean to be loaded, the properties need to be loaded themselves and this is done via the PropertyPlaceholderConfigurer class. The location and name of the server specific property file is added as one of the locations the configurer uses to search for properties.

The file is in the same location on each server but in order to know what the name is, SpEL is used. By creating a java.net.InetAddress bean, we can access the hostName of the server the application is running on by using SpEL ie #{inetAddress.hostName}. Therefore, this config doesn't have to change between environments.


<bean id="inetAddress" class="java.net.InetAddress" factory-method="getLocalHost">
</bean>
    
<bean id="propertyBean" class="org.springframework.beans.factory.config.PropertyPlaceholderConfigurer">
    <property name="ignoreResourceNotFound" value="false"/>
    <property name="ignoreUnresolvablePlaceholders" value="false"/>
    <property name="locations">
        <list>
            <value>file:/home/city81/resources/#{inetAddress.hostName}.properties</value>
        </list>
    </property>
</bean>

This is a very specific example where the property files are prefixed with the server names but it shows how SpEL can be used to solve a problem which would have taken a lot more work pre Spring 3.0.

Spring MVC - A Bare Essentials Example Using Maven

2011-11-16T00:17:00.000-08:00

Spring's MVC is a request based framework like Struts but it clearly separates the presentation, request handling and model layers.

In this post, I'll describe how to get the most simple of examples up and running using Maven, therefore providing a basis upon which to add more features of Spring MVC like handler mappings, complex controllers, commons validator etc..

Let's start with the pom.xml file. This will package up the project as a war file and only requires three dependencies namely the artifacts spring-webmvc, servlet-api and jstl. The spring-webmvc artifact will pull in all the other required spring jars like core, web, etc.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">

    <modelVersion>4.0.0</modelVersion>
    <groupId>com.city81</groupId>
    <artifactId>spring-mvc</artifactId>
    <version>0.0.1-SNAPSHOT</version>
    <packaging>war</packaging>
    <build>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-war-plugin</artifactId>
                <version>2.1-beta-1</version>
            </plugin>
        </plugins>
    </build>
    <dependencies>
        <dependency>
            <groupId>org.springframework</groupId>
            <artifactId>spring-webmvc</artifactId>
            <version>3.0.5.RELEASE</version>
            <optional>false</optional>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>servlet-api</artifactId>
            <version>2.5</version>
            <scope>provided</scope>
        </dependency>
        <dependency>
            <groupId>javax.servlet</groupId>
            <artifactId>jstl</artifactId>
            <version>1.2</version>
        </dependency>
    </dependencies>
</project>

Note that the scope of the servlet-api is provided and therefore excluded from the war file. If deployed as part of the war, there'll be conflict with the servlet jar of the container, and there'll be an error similar to the one below when deploying to Tomcat:

INFO: Deploying web application archive spring-mvc-0.0.1-SNAPSHOT.war
15-Nov-2011 16:05:27 org.apache.catalina.loader.WebappClassLoader validateJarFile
INFO: validateJarFile(C:\apache-tomcat-6.0.33\webapps\spring-mvc-0.0.1-SNAPSHOT\WEB-INF\lib\servlet-api-2.5.jar) - jar not loaded. See Servlet Spec 2.3, section
9.7.2. Offending class: javax/servlet/Servlet.class

Next the web.xml located in the /webapp/WEB-INF folder:

<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
 version="2.5">

    <display-name>Spring MVC Example</display-name>

    <listener>
        <listener-class>org.springframework.web.context.ContextLoaderListener</listener-class>
    </listener>

    <servlet>
        <servlet-name>springMVCExample</servlet-name>
        <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
        <load-on-startup>1</load-on-startup>
    </servlet>

    <servlet-mapping>
        <servlet-name>springMVCExample</servlet-name>
        <url-pattern>*.htm</url-pattern>
    </servlet-mapping>

    <welcome-file-list>
        <welcome-file>home.jsp</welcome-file>
    </welcome-file-list>

</web-app>

The context loader is a listener class called ContextLoaderListener. By default this will load the config in the /WEB-INF/applicationContext.xml but you can specify more files by adding a contextConfigLocation param and list one or more xml files. For example,


    contextConfigLocation    /WEB-INF/example-persistence.xml
        /WEB-INF/example-security.xml

If an applicationContext.xml file isn't present when not using a context param list, then the WAR won't deploy properly. An example empty applicationContext.xml is below:

<?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:aop="http://www.springframework.org/schema/aop"
 xsi:schemaLocation="http://www.springframework.org/schema/context 
    http://www.springframework.org/schema/context/spring-context.xsd
    http://www.springframework.org/schema/util 
    http://www.springframework.org/schema/util/spring-util.xsd
    http://www.springframework.org/schema/beans
    http://www.springframework.org/schema/beans/spring-beans.xsd
    http://www.springframework.org/schema/aop    
    http://www.springframework.org/schema/aop/spring-aop.xsd">

</beans>

The servlet's configuration does not need to be explicitly specified as it can be loaded by following the same naming convention of the servlet, in this case springMVCExample-servlet.xml. The servlet is the front controller which delegates requests to other parts of the system.

The servlet-mapping tags in the web.xml denote what URLs the DispatcherServlet will handle. In this example HTML.

Also included in the web.xml by way of the welcome-file, is a default home page. This doesn't have to be included but the page can be used to forward a request as can be seen later in the post.

As mentioned previously, the servlet's config is in it's own XML file. This describes the mapping between the a URL and the Controller which will handle the request. It also contains the a ViewResolver which maps the view name in the ModelAndView to an actual view. The springMVCExample-servlet.xml is shown below:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.springframework.org/schema/beans  
    http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean name="/example.htm" class="com.city81.spring.mvc.ExampleController">
    </bean>

    <bean id="viewResolver" class="org.springframework.web.servlet.view.InternalResourceViewResolver">
        <property name="prefix">
            <value>/WEB-INF/jsp/</value>
        </property>
        <property name="suffix">
            <value>.jsp</value>
        </property> 
    </bean>

</beans>

The ExampleController class is shown below. It extends AbstractController therefore must implement the method handleRequestInternal(HttpServletRequest request, HttpServletResponse response). The return value of this method is a ModelAndView object. This object is constructed by passing in the view name (example), the model name (message) and the model object (in this case a String)


package com.city81.spring.mvc;

import javax.servlet.http.HttpServletRequest;
import javax.servlet.http.HttpServletResponse;
import org.springframework.web.servlet.ModelAndView;
import org.springframework.web.servlet.mvc.AbstractController;

public class ExampleController extends AbstractController {
  
    protected ModelAndView handleRequestInternal(
        HttpServletRequest request, HttpServletResponse response) 
            throws Exception {
        ModelAndView modelAndView = new ModelAndView("example", "message", "Spring MVC Example");

        return modelAndView;
    }

}

The view jsp will then have the ${message} value populated by the model object from the ModelAndView. The example.jsp is below and resides in the /webapp/WEB-INF/jsp folder:


<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<html>
    <head>
        <title>Spring MVC Example</title>
    </head>
    <body>
        <h2>Welcome to the Example Spring MVC page</h2>
        <h3>The message text is:</h3>
        <p>${message}</p>
    </body>
</html>

As mentioned previously, a default home page can included in the web.xml and instead of displaying html etc., it can be used to redirect requests to another URL. The below home.jsp redirects requests to example.htm:


<%@ page contentType="text/html;charset=UTF-8" language="java" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<c:redirect url="/example.htm"/>

Deploying the above to a container like Tomcat should result in a page like the following:

This is just the very basics of Spring MVC but later posts, will expand on the framework and show how it can be used with, for example, web services like REST.

Spring, JMS, Listener Adapters and Containers

2011-10-13T08:14:00.000-07:00

In order to receive JMS messages, Spring provides the concept of message listener containers. These are beans that can be tied to receive messages that arrive at certain destinations. This post will examine the different ways in which containers can be configured.

A simple example is below where the DefaultMessageListenerContianer has been configured to watch one queue (the property jms.queue.name) and has a reference to a myMessageListener bean which implements the MessageListener interface (ie onMessage):

<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
    <property name="connectionFactory" ref="connectionFactory" /> 
    <property name="destinationName" value="${jms.queue.name}" /> 
    <property name="messageListener" ref="myMessageListener" />
</bean>

This is all very well but means that the myMessageListener bean will have to handle the JMS Message object and process accordingly depending upon the type of javax.jms.Message and its payload. For example:

if (message instanceof MapMessage) {
    // cast, get object, do something
}

An alternative is to use a MessageListenerAdapter. This class abstracts away the above processing and leaves your code to deal with just the message's payload. For example:

<bean id="jmsContainer" class="org.springframework.jms.listener.DefaultMessageListenerContainer">
    <property name="connectionFactory" ref="connectionFactory" />
    <property name="destinationName" value="${jms.queue.name}" />
    <property name="messageListener" ref="myMessageAdapter" />
</bean> 

<bean id="myMessageAdapter" class="org.springframework.jms.listener.adapter.MessageListenerAdapter">
    <property name="delegate" ref="myMessageReceiverDelegate" />
    <property name="defaultListenerMethod" value="processMessage" />
</bean>

The delegate is a reference to a myMessageReceiverDelegate bean which has one or more methods called processMessage. It does not need to implement the MessageListener interface. This method can be overload to handle different payload types. Spring behind the scenes will determine which gets called. For example:

public void processMessage(final HashMap message) {
    // do something
}

public void processMessage(final String message) {
    // do something
}

For the given approach though, only one queue can be tied to the container. Another approach is to tie many listeners (therefore many queues) to the one container, The below Spring XML, using the jms namespace, shows how two listeners for different queues can be tied to one container:

<jms:listener-container container-type="default" 
  connection-factory="connectionFactory" acknowledge="auto">  
    <jms:listener destination="${jms.queue.name1}" ref="myMessageReceiverDelegate" method="processMessage" />  
    <jms:listener destination="${jms.queue.name2}" ref="myMessageReceiverDelegate" method="processMessage" />  
</jms:listener-container>

The myMessageReceiverDelegate bean is treated as an adapter delegate, therefore does not need to implement the MessageListener interface. Each listener can have a different delegate but for the above example, all messages arriving at the two queues are processed by the one receiver bean ie myMessageReceiverDelegate.

If there is a need to check the message type and extract the payload, then the listener can use a class which implements the MessageListener interface (eg the myMessageListener bean used in the first example). The onMessage method will then be called when messages arrive at the specified destination:


<jms:listener-container container-type="default" 
  connection-factory="connectionFactory" acknowledge="auto">  
    <jms:listener destination="${jms.queue.name1}" ref="myMessageListener" />  
    <jms:listener destination="${jms.queue.name2}" ref="myMessageListener" />  
</jms:listener-container>

Spring JMS with ActiveMQ

2011-09-16T02:31:00.000-07:00

ActiveMq is a powerful open source messaging broker, and is very easy and straightforward to use with Spring as the below classes and XML will prove. The example below is the bar minimum needed to get up and running with transactions and message converters.

On the sending side, the ActiveMq connection factory needs to be created with the url of the broker. This in turn is used to create the Spring JMS connection factory and as no session cache property is supplied the default cache is one. The template is then used in turn to create the Message Sender class:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:amq="http://activemq.apache.org/schema/core" 
 xmlns:context="http://www.springframework.org/schema/context"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xmlns:tx="http://www.springframework.org/schema/tx"
 xsi:schemaLocation="http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd  
  http://activemq.apache.org/schema/core 
  http://activemq.apache.org/schema/core/activemq-core-5.5.0.xsd  
  http://www.springframework.org/schema/context 
  http://www.springframework.org/schema/context/spring-context.xsd  
  http://www.springframework.org/schema/jms 
  http://www.springframework.org/schema/jms/spring-jms.xsd
  http://www.springframework.org/schema/tx
  http://www.springframework.org/schema/tx/spring-tx.xsd">

    <!-- Activemq connection factory -->
    <bean id="amqConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <constructor-arg index="0" value="${jms.broker.url}"/>
    </bean>

    <!-- ConnectionFactory Definition -->
    <bean id="connectionFactory" class="org.springframework.jms.connection.CachingConnectionFactory">
        <constructor-arg ref="amqConnectionFactory" />
    </bean>

    <!--  Default Destination Queue Definition-->
    <bean id="defaultDestination" class="org.apache.activemq.command.ActiveMQQueue">
        <constructor-arg index="0" value="${jms.queue.name}"/>
    </bean>

    <!-- JmsTemplate Definition -->
    <bean id="jmsTemplate" class="org.springframework.jms.core.JmsTemplate">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="defaultDestination" ref="defaultDestination" /> 
    </bean>

    <!-- Message Sender Definition -->
    <bean id="messageSender" class="com.city81.jms.MessageSender">
        <constructor-arg index="0" ref="jmsTemplate" />
    </bean>

</beans>

An example sending class is below. It uses the convertandSend method of the JmsTemplate class. As there is no destination arg, the message will be sent to the default destination which was set up in the XML file:

import java.util.Map;
import org.springframework.jms.core.JmsTemplate;

public class MessageSender {

    private final JmsTemplate jmsTemplate;

    public MessageSender(final JmsTemplate jmsTemplate) {
        this.jmsTemplate = jmsTemplate;
    }

    public void send(final Map map) {
        jmsTemplate.convertAndSend(map);
    }

}

On the receiving side, there needs to be a listener container. The simplest example of this is the SimpleMessageListenerContainer. This requires a connection factory, a destination (or destination name) and a message listener.

An example of the Spring configuration for the receiving messages is below:

<?xml version="1.0" encoding="UTF-8"?>
<beans xmlns="http://www.springframework.org/schema/beans"
 xmlns:amq="http://activemq.apache.org/schema/core"

 xmlns:jms="http://www.springframework.org/schema/jms"
 xmlns:context="http://www.springframework.org/schema/context"
 xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
 xsi:schemaLocation="http://www.springframework.org/schema/beans
  http://www.springframework.org/schema/beans/spring-beans.xsd  
  http://activemq.apache.org/schema/core 
  http://activemq.apache.org/schema/core/activemq-core-5.5.0.xsd  
  http://www.springframework.org/schema/context 
  http://www.springframework.org/schema/context/spring-context.xsd  
  http://www.springframework.org/schema/jms 
  http://www.springframework.org/schema/jms/spring-jms.xsd">

    <!-- Activemq connection factory -->
    <bean id="amqConnectionFactory" class="org.apache.activemq.ActiveMQConnectionFactory">
        <constructor-arg index="0" value="${jms.broker.url}"/>
    </bean>

    <!-- ConnectionFactory Definition -->
    <bean id="connectionFactory" class="org.springframework.jms.connection.CachingConnectionFactory">
        <constructor-arg ref="amqConnectionFactory" />
    </bean>  

    <!-- Message Receiver Definition -->
    <bean id="messageReceiver" class="com.city81.jms.MessageReceiver">
    </bean>

    <bean class="org.springframework.jms.listener.SimpleMessageListenerContainer">
        <property name="connectionFactory" ref="connectionFactory" />
        <property name="destinationName" value="${jms.queue.name}" />
        <property name="messageListener" ref="messageReceiver" />
    </bean>

</beans>

The listening/receiving class needs to extend javax.jms.MessageListener and implement the onMessage method:

import javax.jms.MapMessage;
import javax.jms.Message;
import javax.jms.MessageListener;

public class MessageReceiver implements MessageListener {

    public void onMessage(final Message message) {
        if (message instanceof MapMessage) {
            final MapMessage mapMessage = (MapMessage) message;
            // do something
        }
    }

}

To then send a message would be as simple as getting the sending bean from the bean factory as shown in the below code:


    MessageSender sender = (MessageSender) factory.getBean("messageSender");
    Map map = new HashMap();
    map.put("Name", "MYNAME");
    sender.send(map);

Will try to expand and build up JMS and Spring articles with examples of using transactions and other brokers like MQSeries.

JUnit, DBUnit and Oracle

2011-06-06T02:26:00.000-07:00

As previously blogged, DBUnit is a powerful addition to your unit test armoury. Having used it with Oracle, there are a few nuances which are worth writing about and therefore remembering!

When creating a connection to an Oracle database, DBUnit will populate a Map of table names. By default these will not be prefixed with the schema name. As a result, you can get duplicate table names. An example of an exception raised for the duplicate table WWV_FLOW_DUAL100 is shown below:

org.dbunit.database.AmbiguousTableNameException: WWV_FLOW_DUAL100 at org.dbunit.dataset.OrderedTableNameMap.add(OrderedTableNameMap.java:198)
at org.dbunit.database.DatabaseDataSet.initialize(DatabaseDataSet.java:231)
at org.dbunit.database.DatabaseDataSet.getTableMetaData(DatabaseDataSet.java:281)
at org.dbunit.operation.AbstractOperation.getOperationMetaData(AbstractOperation.java:80)
at org.dbunit.operation.AbstractBatchOperation.execute(AbstractBatchOperation.java:140)

To resolve this, set the database config property FEATURE_QUALIFIED_TABLE_NAMES to be true. This will make sure all tables in the Map are unique. As a consequence of this, the table names in the XML data file will need to be prefixed with the schema name.

Another useful database config property is PROPERTY_DATATYPE_FACTORY. In the XML data file, if there are dates with the time element set then the time element will be ignored unless the database config property PROPERTY_DATATYPE_FACTORY is set to new Oracle10DataTypeFactory() (or the equivalent data factory for the version of Oracle being used.)

An example of setting these values in a @BeforeClass annotated JUnit method is shown below:


@BeforeClass
public static void loadDataset() throws Exception {

    // database connection
    ResourceCache resourceCache = ResourceCache.getInstance();
    String driverClassString = resourceCache.getProperty("datasource.driver.class.name");
    String databaseURL = resourceCache.getProperty("datasource.url");
    String username = resourceCache.getProperty("test.datasource.username");
    String password = resourceCache.getProperty("test.datasource.password");

    Class driverClass = Class.forName(driverClassString);
    Connection jdbcConnection = DriverManager.getConnection(databaseURL, username, password);              
    connection = new DatabaseConnection(jdbcConnection);
    DatabaseConfig config = connection.getConfig();
    config.setProperty(DatabaseConfig.FEATURE_QUALIFIED_TABLE_NAMES, true);
    config.setProperty(DatabaseConfig.PROPERTY_DATATYPE_FACTORY, new Oracle10DataTypeFactory());         
        
    FlatXmlDataSetBuilder flatXmlDataSetBuilder = new FlatXmlDataSetBuilder();
    flatXmlDataSetBuilder.setColumnSensing(true);
    dataset = flatXmlDataSetBuilder.build(Thread.currentThread()
        .getContextClassLoader()
        .getResourceAsStream("Test-dataset.xml"));
 }

Using Spring's StoredProcedure class with Oracle Spatial JGeometry

2011-05-04T05:42:00.000-07:00

The Spring framework provides a neat wrapper class you can extend when you want to call a stored procedure. Sometimes though you need to extend to use a native connection because, for example, you need to pass an ORACLE Geometry type to the stored procedure.

The below code wraps a Create_Geometry_Line stored procedure which takes a geometry object. The calling code will use the executeMap method to pass in a Map of in parameters. It converts the list of doubles (which represent the points of the line) to an object of type STRUCT.

package uk.co.city81.persistence.dao.geometry;

import java.sql.Connection;
import java.sql.SQLException;
import java.sql.Types;
import java.util.Map;

import oracle.jdbc.OracleTypes;
import oracle.spatial.geometry.JGeometry;
import oracle.sql.STRUCT;

import org.springframework.dao.DataAccessException;
import org.springframework.jdbc.core.JdbcTemplate;
import org.springframework.jdbc.core.SqlOutParameter;
import org.springframework.jdbc.core.SqlParameter;
import org.springframework.jdbc.object.StoredProcedure;


public class CreateGeometryLineDAO extends StoredProcedure {

    private Connection nativeConn = null;

    public static final String CREATE_GEOMETRY_LINE = "geometry_pkg.Create_Geometry_Line";

    // Constructor
    public CreateGeometryLineDAO(JdbcTemplate jdbcTemplate) {
        setJdbcTemplate(jdbcTemplate);
        setFunction(true);
        setSQL();
        declareParameter(new SqlOutParameter("l_Return", Types.INTEGER));
        declareInParameters();
        declareOutParameters();
        compile();
    }

    // Get the native connection
    protected Connection getNativeConn() throws SQLException {  
        if ((nativeConn == null) || nativeConn.isClosed()) {
            nativeConn = this.getJdbcTemplate().getNativeJdbcExtractor()
                .getNativeConnection(this.getJdbcTemplate()
                .getDataSource().getConnection());
        }
        return nativeConn;   
    }

    protected void declareInParameters() {
        declareParameter(new SqlParameter("p_geom_data",OracleTypes.STRUCT)); 
    }

    protected void declareOutParameters() {
        // declare out params
    }

    protected void setSQL() {
        setSql(CREATE_GEOMETRY_LINE);
    }

    /**
     * Execute the stored procedure
     * 
     * @param inParamMap a map of the stored procedure parameters
     */
    public Map executeMap(Map inParamMap) {
        Map outParamMap = null;
        try {  
            if (inParamMap.get("p_geom_data") != null) {
                java.util.List<Double> ordinates 
                    = (java.util.List<Double>) inParamMap.get("p_geom_data");
                double[] ordinateDoubles = new double[ordinates.size()];
                int count = 0;
                for (Double ordinate : ordinates) {
                    ordinateDoubles[count] = ordinate.doubleValue();
                    count++;
                }

                int[] elemInfo = new int[]{1,2,1};
                JGeometry j_geom = new JGeometry(
                    JGeometry.GTYPE_CURVE,8307, elemInfo,ordinateDoubles);        
                STRUCT obj = JGeometry.store(j_geom, getNativeConn());
                inParamMap.put("p_geom_data", obj);
            }

            outParamMap = super.execute(inParamMap);

        } catch (DataAccessException daex) {
            // throw exception
        } catch (SQLException e) {
            // throw exception
        }

        return outParamMap;
    }

}

The jdbcTemplate can be injected into the DAO's constructor. The extracts from the context xml are below:


    <bean id="datasource" class="org.springframework.jdbc.datasource.DriverManagerDataSource" 
        destroy-method="close">

        <property name="driverClassName">
            <value>oracle.jdbc.OracleDriver</value>
        </property>
        <property name="url">
            <value>jdbc:oracle:thin:@server:port:db</value>
        </property>
        <property name="username">
            <value>username</value>
        </property>
        <property name="password">
            <value>password</value>
        </property>
    </bean>

    <bean id="nativeJdbcExtractor" class="org.springframework.jdbc.support.nativejdbc.SimpleNativeJdbcExtractor" 
      lazy-init="true"/>

    <bean id="jdbcTemplate" class="org.springframework.jdbc.core.JdbcTemplate">
        <property name="dataSource">
            <ref bean="datasource" />
        </property>
        <property name="nativeJdbcExtractor">
            <ref bean="nativeJdbcExtractor" />
        </property>
    </bean>

    <bean id="createGeometryLineDAO" class="uk.co.city81.persistence.dao.geometry.CreateGeometryLineDAO">
        <constructor-arg ref="jdbcTemplate" />
    </bean>

JAAS, EJB Security and Glassfish

2011-04-15T02:31:00.000-07:00

With EJBs you can specify security by using annotations from the javax.annotation.security package. The below article describes how to setup security on a bean and access the methods of the bean via an annotation or via JAAS which has been setup on Glassfish.

The below bean class only allows the MANAGER role access to use the services exposed. In this case, findCustomerByAccountNumber. (The AccessRoles.MANAGER resolves to a string so if the string changes the CustomerServiceBean doesn't have to change.)

@RolesAllowed(AccessRoles.MANAGER)
@Stateless(mappedName = JndiResourceName.CUSTOMER_SERVICE)
@Remote(CustomerService.class)
public class CustomerServiceBean implements CustomerService {

    @Override
    public Customer findCustomerByAccountNumber(String accountNumber) {
        Customer customer = null;
        // do stuff to find customer
        return customer;
    } 

}

To call the findCustomerByAccountNumber, the code can use the @RunAs annotation as described below:

    @RunAs(AccessRoles.MANAGER)
    public void verifyCustomer(String accountNumber) {
        // do stuff 
        Customer customer = 
            customerService.findCustomerByAccountNumber(String accountNumber);
        // do more stuff 
    }

But what if the roles calling the verify method can vary ie MANAGERS, OPERATORS, ADMIN. In this scenario, we would want to authenticate the 'caller' before accessing the findCustomerByAccountNumber method. A solution to this would be to use JAAS (Java Authentication and Authorization Service.)

The principal of this is to create realms and have users and groups in the realm. There are a few steps involved which are described as follows:

Firstly, the app server (in this example Glassfish) needs to create a realm and the below describes how to do this using the command line. It assumes connection pools, user and group database tables have been created and populated, and that the flexiblejdbcrealm-0.4.jar is in the Glassfish lib dir:

asadmin --host  delete-auth-realm customer-realm

asadmin --host  create-auth-realm --classname=org.wamblee.glassfish.auth.FlexibleJdbcRealm --property="jaas.context=customerJdbcRealm:datasource.jndi=
jdbc/Customer:sql.password=select password from customeruser where username\=?:sql.groups=select g.groupname from customergroup g inner join user_group ug on g.id\=ug.group_id inner join customeruser u on ug.user_id\=u.id where u.username\=?:password.digest=MD5:password.encoding=BASE64" customer-realm

asadmin --host  --user admin set server-config.security-service.activate-default-principal-to-role-mapping=true

asadmin --host  set-log-level javax.enterprise.system.core.security=INFO

asadmin --host  set-log-level org.wamblee.glassfish.auth=INFO

The login.conf needs to have the below added to it:

customerJdbcRealm {com.mypackage.auth.CustomerLoginModule required;}

The CustomerLoginModule class extends FlexibleJdbcLoginModule and gives us the ability to intercept the login/authentication calls if we so wish. In this case, any login exceptions are being logged:

public class CustomerLoginModule extends FlexibleJdbcLoginModule implements LoginModule {

    private static final Logger SECURITY_LOGGER = Logger.getLogger("com.mypackage");

    @Override
    protected void authenticate() throws javax.security.auth.login.LoginException {

        try {
            super.authenticate();
        } catch(LoginException le){
            SECURITY_LOGGER.error("Authentication failed for " 
                + _username + ". " + le.getMessage());
            throw le;
        }

    }

}

We can now change the verify method to authenticate before calling the 'secure' findCustomerByAccountNumber method:


    private ProgrammaticLoginInterface programmaticLogin = 
        new ProgrammaticLogin();

    public void verifyCustomer(String accountNumber) {
        Customer customer = null;
        boolean loginSuccessful = programmaticLogin.login("manager", "password", "customer-realm", true);  

        if (loginSuccessful) { 
            customer = customerService.findCustomerByAccountNumber(String accountNumber);
        } else {
            // throw exception 
        }

    }

The call to the ProgrammaticLogin instance attempts to use the supplied name and password directly to login to the current realm. If successful, a security context is created for that user and is used by the EJB when checking what roles are allowed to call it.

For example purposes, the above verifyCustomer method has the name and password hard coded but in reality these values could be obtained from a login web page or other such authentication mechanisms.

Portable Global JNDI Names and Maven

2011-03-31T04:10:00.000-07:00

With the advent of the EJB 3.1 specification, the JNDI names for session beans have become portable via the java:global namespace.

As described on the Glassfish EJB FAQ page (http://glassfish.java.net/javaee5/ejb/EJB_FAQ.html#What_is_the_syntax_for_portable_global_) the syntax for the global namespace is:

java:global[/<app-name>]/<module-name>/<bean-name>

where the app-name is the ear name (if the app is deployed as an ear), the module-name the ejb jar or war name and the bean-name the session bean name. Note that names are unqualified and minus the extension.

Given the syntax an example of using the portable JNDI name using the @EJB annotation would be:

@EJB(lookup=
"java:global/customer-ear/customer-1-0-0/CustomerServiceBean")

The JNDI name may now be portable but the above code would not be reusable if the customer jar name changed. It is quite often the case that jars will have versions in their name eg customer-1-0-0.jar and you would not want to change your code everytime there was a new release of the customer jar so you need to change the module name in the lookup.

One option would be to rename the jar when building the ear file so the module name defaults to the jar name. To do this in Maven would be to explicitly add the ejbModule to the ear plugin as shown below. The name of the jar is what is specified in the bundleFileName tag.


    <plugin>
        <artifactId>maven-ear-plugin</artifactId>
        <version>2.4</version>
        <configuration>
            <generateApplicationXml>true</generateApplicationXml>
            <archive>
                <manifest>
                    <addClasspath>true</addClasspath>
                </manifest>
            </archive>
            <version>6</version>
            <defaultLibBundleDir>lib</defaultLibBundleDir>
            <earSourceDirectory>resources</earSourceDirectory>
            <modules>
                <ejbModule>
                    <groupId>com.mybank.customer</groupId>
                    <artifactId>customer-server</artifactId>
                    <bundleFileName>customer.jar</bundleFileName>
                </ejbModule>
            </modules>
        </configuration>
    </plugin>

The lookup would then be as below:

@EJB(lookup=
"java:global/customer-ear/customer/CustomerServiceBean")

This means the code containing the injection point doesn't have to change with the names of the jars.

Java Collections and Threading

2011-03-31T04:09:00.000-07:00

In the java.util.concurrent package, there exist several collection classes which aid the development of thread safe code. Below is a brief overview of the five most useful classes and a comparison of them with the some collection that exist in the java.util package.

ConcurrentHashMap<K,V>

java.util.HashMap is a collection which holds key value pairs but it is not synchronised. If multiple threads are accessing such a collection, the keys and values being put into the collection may not be visible to those threads calling get. A solution would be to create a synchronised version by calling the static method Collections.synchronizedMap() but this would 'lock' all operations on the Map.

Another solution would be to use ConcurrentHashMap<K,V>. The idea behind this class is that only the bucket that holds the data being accessed is 'locked'. This allows (more often than not) the get operation to work without blocking. Note that using an iterator obtained from the ConcurrentHashMap will not reflect map modifications since getting the iterator. Therefore the iterator will not throw ConcurrentModificationException.

ConcurrentSkipListMap<K,V>

java.util.concurrent.ConcurrentSkipListMap offers similar functionality to the above class but it maintains a sorted order (either the natural order or the order based on using a Comparator.) It also provides methods like ceilingKey, lowerEntry and tailMap. Because of the ordering, insertion can be slower than that of a ConcurrentHashMap but iterating over the collection would be faster.

ConcurrentSkipListSet<E>

Similar to the above but is a NavigableSet.

CopyOnWriteArrayList<E>

java.util.ArrayList is a collection which holds a resizable list of entries but it is not synchronised. As with ConcurrentHashMap, a solution would be to create a synchronised version by calling the static method Collections.synchronizedList() but this would 'lock' all operations on the List. Another solution would be to use CopyOnWriteArrayList<E> and this is best suited to lists where reads are frequent and writes are infrequent. It works by making a change to a copy of the list and then replacing the existing list with the modified copy..

CopyOnWriteArraySet<E>

Similar to the above but is a Set.

Thread-safe and lock free variables

2011-03-25T07:36:00.000-07:00

The java.util.concurrent.atomic package contains classes which aim to ease concurrency concerns in multithreaded applications. They offer better performance than using synchronisation because its operations on fields do not require locking.

The classes AtomicBoolean, AtomicInteger, AtomicLong and AtomicReference enable the primitives boolean, int, long and an object reference to be atomically updated. They all provide utility methods like compareAndSet which takes an expected value and the update value and returns false if the expected value doesn't equal (==) the current value. The AtomicInteger and AtomicLong classes also provide atomic pre and post decrement/increment methods like getAndIncrement or incrementAndGet.

An example use of one of the 'scalar' atomic classes is shown below:

public class IdentifierGenerator {

    private AtomicLong seed = new AtomicLong(0);

    public long getNextIdentifier() {
        return seed.getAndIncrement();
    }

}

The int and long primitives, and also object references can be held in arrays where the elements are atomically updated namely AtomicIntegerArray, AtomicLongArray and AtomicReferenceArray.

There also exists field updater classes namely AtomicIntegerFieldUpdater, AtomicLongFieldUpdater and AtomicReferenceFieldUpdater. With these classes you can still use the methods on the class but use the updater class to manage the field that requires atomic access via methods like compareAndSet. Note that because of this, atomcity isn't guaranteed.

These are abstract classes and the below (contrived!) example shows how an instance would be created:


    public void setBalance(Customer customer, int exisitngBalance, 
        int newBalance) {

        AtomicIntegerFieldUpdater<Customer> balanceAccessor 
            = AtomicIntegerFieldUpdater.newUpdater(
        Customer.class, "balance"); 
        balanceAccessor.compareAndSet(customer, exisitngBalance, newBalance);

    }

Weak and Soft References and the Garbage Collector

2011-03-24T04:57:00.000-07:00

Java uses the Garbage Collector to manage memory. It does this by freeing up memory no longer needed by the application ie memory used by objects that are not referenced anymore, in other words, objects that are ‘unreachable’.

Typically, objects are strongly referenced so they remain in memory until no longer reachable,

Customer customer = new Customer();

but there are certain scenarios where you’d want to keep references to objects and also allow them to be garbage collected if needs be eg when memory is at a premium. A solution to this problem is to use Reference Objects.

There are three concrete implementations of the java.lang.ref.Reference<T> class: WeakReference, SoftReference and PhantomReference.

Objects held only by a WeakReference are deemed to be weakly reachable and are therefore eligible for garbage collection. An example of creating a WeakReference is below:

WeakReference<Customer> weakCustomer = new

WeakReference<Customer>(customer);

To obtain the customer object held by the weak reference, you would call weakCustomer.get(). This will always return the customer object unless the garbage collecter has deemed the object to be weakly reachable and therefore has freed it from memory. In that case, calling the get method will return null;

If you want to hold a collection of the objects that can be garbage collected, then you can use a WeakHashMap. This collection uses weak references as keys, so when the key becomes garbage collected, the entry for that key in the WeakHashMap gets removed. This collection class isn’t synchronized so use Collections.synchronizedMap for a synchronized version, but be beware that whether synchronized or not, the size of the Map may decrease over time as the garbage collector removes entries, so an iterator may return ConcurrentModificationException.

A SoftReference holds onto the object more strongly than a WeakReference and if memory is not a problem the garbage collector will not free up the memory used by objects held by a soft reference.

You can also create another type of reference to an object, a PhantomReference. Calling the get method on such a reference will always return null though thereby preventing you from ‘resurrecting’ the object. It’s only real use is when you pass a ReferenceQueue into the PhantomReference constructor.

You can pass a ReferenceQueue into the constructor of all the Reference types. It enables you to keep track of objects which have been garbage collected. When the object’s finalize method is called, the object will be placed on the reference queue. This process is called ‘enqueuing’. You then know when it was removed from memory.

In the case of a PhantomReference, passing in a null ReferenceQueue would be a pointless exercise, rendering the creation of the PhantomReference useless.

Testing JPA Entities using DBUnit

2011-03-08T02:01:00.000-08:00

DBUnit is a powerful testing tool that allows you to put your database into a known state in between tests. A common problem (and one of poor test design) is where a test changes the state of an object and this state affects the testing of objects in later tests. Each test should be independent and tests within a suite should be able to run in any order. This post will aim to describe the code needed to setup a database before each run of a JUnit test method.

The below class has three key methods:

initEntityManager() - this method is annotated with @BeforeClass so will only be called once for this test and called before any tests are run. The method will create an entity manager, get a connection to an instance of the in memory Java database HSQL and then populate it by reading in the flat xml database record structure that is contained in the file test-dataset.xml. For alternative dataset formats please visit http://www.dbunit.org/apidocs/org/dbunit/dataset/IDataSet.html
closeEntityManager() - this method is annotated with @AfterClass so will only be called once for this test and called after all the tests have been run. The method will close down the entity manager and the entity manager connection factory.
cleanDB() - this method is annotated with @Before and will be called before every test method call. The call to DatabaseOperation.CLEAN_INSERT.execute will clean the database tables and insert the records from the dataset xml file. Database operations other than CLEAN_INSERT are described below:

            UPDATE    updates the database using the data in the dataset.
            INSERT         inserts the data in the dataset into the database.
            DELETE       deletes only the data in the dataset from the database.
            DELETE_ALL deletes all rows of tables present in the specified dataset.
            TRUNCATE   truncate tables listed in the dataset.
            REFRESH     refreshes the database using the data in the dataset.
            NONE           does what it says, nothing.

import org.dbunit.database.DatabaseConfig;
import org.dbunit.database.DatabaseConnection;
import org.dbunit.database.IDatabaseConnection;
import org.dbunit.dataset.IDataSet;
import org.dbunit.dataset.xml.FlatXmlDataSetBuilder;
import org.dbunit.ext.hsqldb.HsqldbDataTypeFactory;
import org.dbunit.operation.DatabaseOperation;
import org.hibernate.impl.SessionImpl;
import org.junit.AfterClass;
import org.junit.Before;
import org.junit.BeforeClass;
import javax.persistence.EntityManager;
import javax.persistence.EntityManagerFactory;
import javax.persistence.Persistence;
import org.junit.Test;

public class JPATest {

    protected static EntityManagerFactory entityManagerFactory;
    protected static EntityManager entityManager;
    protected static IDatabaseConnection connection;
    protected static IDataSet dataset;

    @BeforeClass
    public static void initEntityManager() throws Exception {
        entityManagerFactory = Persistence.createEntityManagerFactory("PersistenceUnit");
        entityManager = entityManagerFactory.createEntityManager();
        connection = new DatabaseConnection(((SessionImpl)(entityManager.getDelegate())).connection());
        connection.getConfig().setProperty(DatabaseConfig.PROPERTY_DATATYPE_FACTORY, new HsqldbDataTypeFactory());

        FlatXmlDataSetBuilder flatXmlDataSetBuilder = new FlatXmlDataSetBuilder();
        flatXmlDataSetBuilder.setColumnSensing(true);
        dataset = flatXmlDataSetBuilder.build(
        Thread.currentThread().getContextClassLoader().getResourceAsStream("test-dataset.xml"));
    }

    @AfterClass
    public static void closeEntityManager() {
        entityManager.close();
        entityManagerFactory.close();
    }

    @Before
    public void cleanDB() throws Exception {
        DatabaseOperation.CLEAN_INSERT.execute(connection, dataset);
    }

    @Test
    public void testAUsefulMethod() throws Exception {
        // .... test code
    }

}

An example structure of the dataset.xml is shown below:

<?xml version='1.0' encoding='UTF-8'?>
<dataset>
    <customer id="1" surname="SURNAME" firstName="FIRSTNAME" middleName="MIDDLENAME" personalAccount="true"/>
    <customer id="2" surname="SURNAME" firstName="FIRSTNAME" personalAccount="true" balance="100000.00/>
</dataset>

One point of note is that when deleting database records using DBUnit the same rules apply as if you were using SQL. You will not be able to delete a record if its primary key is a foreign key on another table. An example in Flat XML for a Customer class that has many Addresses would be:

<?xml version='1.0' encoding='UTF-8'?>
<dataset>
    <customer/>
    <address/>
    <customer_address/>
</dataset>

Finally, there are many useful methods on IDataSet and ITable interfaces. An example being to obtain the number of records of a particular table:

int customerRecordCount = dataset.getTable("Customer").getRowCount();

Useful JMS-related Glassfish and OpenMq commands

2011-03-07T08:38:00.000-08:00

Below are a few Glassfish JMS admin commands and some useful OpenMQ commands (to query, purge and list) which can be be used in scripts to perform tasks as opposed to performing the same procedures via the Glassfish or OpenMQ admin consoles:

Glassfish JMS Commands

To clear previous JMS setup

asadmin delete-jms-resource <JMS_TOPIC_RESOURCE_NAME>
asadmin delete-jms-resource <JMS_TOPIC_CONNECTION_FACTORY_NAME>

To create the JMS Topic Connection factory

asadmin create-jms-resource --restype=javax.jms.TopicConnectionFactory --property transaction-support=LocalTransaction --description="JMS Topic Connection Factory." <JMS_TOPIC_CONNECTION_FACTORY_NAME>

To create the JMS Topic resource

asadmin create-jms-resource --restype=javax.jms.Topic --description="JMS Topic" <JMS_TOPIC_RESOURCE_NAME>

To list JMS resources

asadmin list-jms-resources

OpenMQ Commands

Query the JMS resources

imqcmd query bkr -b <host>:<port> -passfile <password file> -u <user name>

Purge the Topic (or Queue)

imqcmd purge dst -f -passfile <password file> -n <topic name> -t t -b <host>:<port> -u <user name>

List the message rate and packet flow

imqcmd list dst -passfile <password file> -b <host>:<port> -u <user name>

An example output from the list command would be:

Listing all the destinations on the broker specified by:

-------------------------
Host         Primary Port
-------------------------
localhost    7676

-----------------------------------------------------------------------------------------------------------------
             Name                Type    State      Producers        Consumers                  Msgs
                                                 Total Wildcard Total Wildcard Count Remote UnAck Avg Size
-----------------------------------------------------------------------------------------------------------------
JMSTopic                         Topic RUNNING 0      0         1      0         0      0       0      0.0
mq.sys.dmq                       Queue RUNNING 0      -         0      -         171    0       0      5273.322

Pessimistic and Optimistic Locking in JPA 2.0

2011-03-03T22:51:00.000-08:00

A most welcome addition to JPA 2.0 was the introduction of pessimistic locking. This allows the entity manager (or query) to lock a database record thereby preventing other transactions from changing the same record. This will ensure data consistency but at a performance cost so for each entity you need to ask yourself what is the chance of contention?

Let's look at the two approaches in more detail:

Optimistic Locking

Optimistic locking is the preferred approach when modifying entities that are infrequently updated. Optimistic locking can be explicit as will be shown later or implicit by using a version attribute. A version attribute is an attribute which has been annotated with @Version. This attribute will then get incremented when the transaction commits. The below class shows an example of its usage:

import java.io.Serializable;
import javax.persistence.Column;
import javax.persistence.EntityManager;
import javax.persistence.Id;
import javax.persistence.MappedSuperclass;
import javax.persistence.PersistenceContext;
import javax.persistence.Version;

@MappedSuperclass
public abstract class BaseEntity implements Serializable {

    private static final long serialVersionUID = 1L;
    private static final int ID_LENGTH=36;

    @Id
    @Column(length = ID_LENGTH)
    private String id;
    @Version
    private int versionNumber;

    // etc ...

}

There are two optimistic lock modes:

OPTIMISTIC or READ - locks the entity when the transaction reads it for entities wit a version
OPTIMISTIC_FORCE_INCREMENT or WRITE - locks the entity when the transaction reads it for entities with a version and increments the version attribute

Pessimistic Locking

Pessimistic locking can be applied to all entities regardless of whether they have a version attribute or not.

There are three pessimistic lock modes:

PESSIMISTIC_READ - locks the entity when the transaction reads it and allows reads from other transactions
PESSIMISTIC_WRITE - locks the entity when the transaction updates it but does not allow reads, updates or deletes from other transactions
PESSIMISTIC_FORCE_INCREMENT - locks the entity when the transaction reads it and increments the version attribute (if present)

There are many different ways to implement a pessimistic or optimistic lock using the Entity Manager and Query interfaces as shown in the example classes below:

import java.io.Serializable;
import java.util.List;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Named;
import javax.persistence.EntityManager;
import javax.persistence.LockModeType;
import javax.persistence.PersistenceContext;
import javax.persistence.Query;

@Named("customerManager")
@ApplicationScoped
public class CustomerManager implements Serializable {

    private static final long serialVersionUID = 1L;

    @PersistenceContext
    private EntityManager entityManager;

    public void setName(String id, String name) {
        Customer customer =
            entityManager.find(Customer.class, id);
        entityManager.lock(customer,
            LockModeType.OPTIMISTIC_FORCE_INCREMENT);
        customer.setName(name);
    }

    public Customer findCustomer(String id) {
        return entityManager.find(Customer.class, id,
            LockModeType.OPTIMISTIC);
    }

    public Customer
        applyBankCharges(String id, Double charges) {

        Customer customer =
            entityManager.find(Customer.class, id);
        customer.setBalance(customer.getBalance() - charges);
        if (customer.getBalance() < 0.0) {
            // overwrite changes and return the refreshed
            // and locked object
            entityManager.refresh(customer,
                LockModeType.PESSIMISTIC_WRITE);
        }
        return customer;
    }

    public List<Customer>
        findCustomerByPartialName(String partialName) {

        Query query = entityManager.createQuery(
                "SELECT c FROM Customer c WHERE c.name" +
                " LIKE :partialName").
                setParameter("partialName", partialName);
        query.setLockMode(
            LockModeType.PESSIMISTIC_FORCE_INCREMENT);
        return query.getResultList();
    }
}

import javax.persistence.Entity;
import javax.persistence.LockModeType;
import javax.persistence.NamedQuery;

@Entity
@NamedQuery(name = "findByNameQuery",
    query = "SELECT c FROM Customer c WHERE c.name LIKE :name",
    lockMode = LockModeType.PESSIMISTIC_FORCE_INCREMENT)
public class Customer extends BaseEntity {

    private String name;
    private Double balance;

    public void setName(String name) {
        this.name = name;
    }
    public Double getBalance() {
        return this.balance;
    }
    public void setBalance(Double balance) {
        this.balance = balance;
    }
}

Finally, a word on exceptions. If a PessimisticLockException or an OptimisticLockException are thrown then the transaction is rolled back as they are both RuntimeExceptions.

Generating Web Services from WSDLs using Maven and deploying to Glassfish

2011-02-17T02:15:00.000-08:00

This blog post aims to cover generating Java classes from WSDLs using Maven and it also covers a problem with web annotations when deploying to an app server.

There are many different ways to generate Java classes for a given wsdl file (and associated xsds). One of those ways is to use the JAX-WS wsimport tool. Amongst the classes that the tool can generate are the service endpoint interface and the service class.

When using Maven, you can use the jaxws-maven-plugin and the wsimport goal. The plugin will read a WSDL file (from the /src/wsdl directory unless otherwise specified via the wsdlLocation tag) and generate the Java classes. The plugins sections from a pom.xml is shown below:

       <plugins>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>jaxws-maven-plugin</artifactId>
                <version>1.10</version>
                <executions>
                    <execution>
                        <goals>
                            <goal>wsimport</goal>
                        </goals>
                        <configuration>
                            <wsdlFiles>
                                <wsdlFile>Customer.wsdl</wsdlFile>
                            </wsdlFiles>
                            <staleFile>
             ${project.build.directory}/jaxws/stale/Customer.stale
                            </staleFile>
                        </configuration>
                        <id>wsimport-generate-Customer</id>
                        <phase>generate-sources</phase>
                    </execution>
                </executions>
                <dependencies>
                    <dependency>
                        <groupId>javax.xml</groupId>
                        <artifactId>webservices-api</artifactId>
                        <version>${javax.xml.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>com.sun.xml.bind</groupId>
                        <artifactId>jaxb-xjc</artifactId>
                        <version>${jaxb-xjc.version}</version>
                    </dependency>
                    <dependency>
                        <groupId>com.sun.xml.ws</groupId>
                        <artifactId>jaxws-rt</artifactId>
                        <version>${jaxws-rt.version}</version>
                    </dependency>
                </dependencies>
                <configuration>
                    <sourceDestDir>
       ${project.build.directory}/generated-sources/jaxws-wsimport
                    </sourceDestDir>
                    <xnocompile>true</xnocompile>
                    <verbose>true</verbose>
                    <extension>true</extension>
                    <catalog>
                        ${basedir}/src/jax-ws-catalog.xml
                    </catalog>
                </configuration>
            </plugin>
        </plugins>

The generated web service class will look like the class below:

@WebService(
    name = "Customer",
    targetNamespace = "http://<package>/Customer")
@SOAPBinding(
    parameterStyle = SOAPBinding.ParameterStyle.BARE)
public interface Customer {

    /**
     *
     * @param body
     */
    @WebMethod(
        operationName = "AddCustomer",
        action = "http://<package>/Customer/AddCustomer")
    public void addCustomer(
        @WebParam(name = "AddCustomer",
            targetNamespace = "http://<package>/Customer",
            partName = "body") AddCustomer body);
}

Given the above interface, a class can be written to implement the above generated interface as shown below:

@WebService(name = Customer.NAME,
            targetNamespace = Customer.TARGET_NAMESPACE,
            portName = Customer.PORT_NAME,
            serviceName = Customer.SERVICE_NAME,
            wsdlLocation = Customer.WSDL_LOCATION_URL)
@SOAPBinding(parameterStyle = SOAPBinding.ParameterStyle.BARE)
@BindingType(value = Customer.SOAP12_OVER_HTTP)
@SchemaValidation()
public class CustomerWebService implements Customer {

    static final String NAME = "Customer";
    static final String TARGET_NAMESPACE
        = TARGET_NAMESPACE_URL + NAME;
    static final String PORT_NAME = NAME + "SOAP";
    static final String SERVICE_NAME = NAME;
    static final String WSDL_LOCATION_URL
        = WSDL_LOCATION_PATH + NAME + ".wsdl";
    static final String SOAP12_OVER_HTTP
        = "http://java.sun.com/xml/ns/jaxws/2003/05/soap/bindings/HTTP/";

    @Override
    @WebMethod(operationName = "AddCustomer")
    public void addCustomer(
        @WebParam(name = "AddCustomer",
            targetNamespace = "http://<package>/Customer",
            partName = "body") AddCustomer body) {

        // do something
    }

}

Having built an ear file containing the web service, you can then deploy it. To deploy to eg Glassfish v3.0.1, you can use the following command:

asadmin --host <server> --port <port> --interactive=false --echo=true --terse=true deploy
--name customer-ear --force=false --precompilejsp=false --verify=false --enabled=true --generatermistubs=false --availabilityenabled=false
--keepreposdir=false --keepfailedstubs=false --logReportedErrors=true --help=false ./customer-ear.ear

One point to note is that the below implementation of the addCustomer method would compile...

    @Override
    public void addCustomer(AddCustomer body) {

        // do something
    }

... but it would not inherit the Web annotations and would result in the below error when deploying the ear:

com.sun.enterprise.admin.cli.CommandException: remote failure: Exception while loading the app : java.lang.Exception: java.lang.IllegalStateException: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: org.apache.catalina.LifecycleException: javax.servlet.ServletException
Exception while invoking class com.sun.enterprise.web.WebApplication start method : java.lang.Exception: java.lang.IllegalStateException: ContainerBase.addChild: start: org.apache.catalina.LifecycleException: org.apache.catalina.LifecycleException: javax.servlet.ServletException

The Web annotations need to be explicitly replicated in the concrete class.

Subversion Reminders - Branching, Merging and Rollbacks

2011-02-16T05:38:00.000-08:00

Below are a few Subversion reminders on how to branch, merge and rollback changes.

To create a branch from the HEAD of the trunk:

svn copy http://<server>/<svn repo>/<svn project>/branches/<branch name>

You can add a -m <comment> onto the operation to provide a reason for the branch.

To delete a branch:

svn delete http://<server>/<svn repo>/<svn project>/branches/<branch name>

If for some reason you want to include changes from the trunk post-branch, then you can use the merge command from the branch root directory. A useful precursor to this is to use the dry run argument as below:

svn merge --dry-run -r2602:HEAD http://<server>/<svn repo>/<svn project>/trunk

NOTE: 2602 is non-inclusive i.e. revisions merged will start from 2603 onwards.

Now do the actual merge:

svn merge -r2602:HEAD http://<server>/<svn repo>/<svn project>/trunk

No doubt there will be conflicts so once resolved in your favourite IDE, check the changes in.

The above commands assume you noted down the revision number (2602) when branching. If not known, then from the branch root directory, execute the below command:

svn log -v --stop-on-copy

To merge branch changes into the trunk, the merge command can be used in similar fashion from the trunk root directory:

svn merge -r2602:HEAD http://<server>/<svn repo>/<svn project>/branches/<branch name>

If you want to rollback commited changes, then you can use the merge command with the -r argument:

svn merge -r10:9 http://<server>/<svn repo>/<svn project>/trunk

To rollback a commit that took place a while ago and others that have been committed since, use the merge command again:

svn merge -r7:5 http://<server>/<svn repo>/<svn project>/trunk

NOTE: Note that this will revert revisions 7 and 6. Revision 5 is the target revision that we want to keep.

Many thanks to Rob Legg of Asset Source Ltd for the above summary.

Unit testing managed beans using Mockito

2011-02-14T07:17:00.000-08:00

Mockito is a powerful testing framework which is ideal for unit testing managed beans. It allows developers to mock existing classes thereby enabling the behaviour of those classes to be manipulated by the developer depending upon what the aim of the test is.

A simple managed bean which is to be tested is below:

import java.io.Serializable;
import java.math.BigDecimal;
import javax.annotation.Named;
import javax.enterprise.context.ApplicationScoped;
import javax.inject.Inject;

@Named("customerManager")
@ApplicationScoped
public class CustomerManager implements Serializable {
    private static final long serialVersionUID = 1L;
    private AccountManager accountManager;

    @Inject
    public void setAccountManager(
        final AccountManager accountManager) {
        this.accountManager = accountManager;
    }

    public boolean isInCredit() {
        boolean inCredit = false;
        BigDecimal currentAccountBalance =
            this.accountManager.getBalance(AccountType.CURRENT);
        BigDecimal depositAccountBalance =
            this.accountManager.getBalance(AccountType.DEPOSIT);
        BigDecimal accountBalance =
            new BigDecimal(currentAccountBalance.doubleValue())
                .add(depositAccountBalance);
        if (accountBalance.compareTo(BigDecimal.ZERO) > 0) {
            inCredit = true;
        }
        return inCredit;
    }

}

The test class for CustomerManager could include various scenarios depending on what is returned by the AccountManager class. An example test class is below:

import java.math.BigDecimal;
import org.junit.Before;
import org.junit.Test;

import static org.mockito.Mockito.mock;
import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
import static org.mockito.Mockito.any;
import static org.mockito.Mockito.times;
import static junit.framework.Assert.assertTrue;

public class CustomerManagerTest {

    private CustomerManager customerManager;
    private AccountManager mockAccountManager =
        mock(AccountManager.class);

    @Before
    public void setUp() throws Exception {
        customerManager = new CustomerManager();
        customerManager.setAccountManager(mockAccountManager);
    }

    @Test
    public void testPositiveBalance() {
        BigDecimal positiveAmount = new BigDecimal(1000.00);
        when(mockAccountManager.getBalance(((AccountType)any())))
            .thenReturn(positiveAmount);
        boolean inCredit = customerManager.isInCredit();
        assertTrue(inCredit);
        verify(mockAccountManager, times(2))
            .getBalance((AccountType)any());
    }

}

The when is mocking calls to the AccountManager getBalance method for any given parameter of type AccountType. As the method should have been called twice (once for CURRENT and once for DEPOSIT), the verify call can determine the number of getBalance method invocations. A more fine grained test equivalent of the above could be:

    @Test
    public void testPositiveBalance() {
        BigDecimal positiveAmount = new BigDecimal(1000.00);
        when(mockAccountManager.getBalance(AccountType.CURRENT))
            .thenReturn(positiveAmount);
        when(mockAccountManager.getBalance(AccountType.DEPOSIT))
            .thenReturn(positiveAmount);
        boolean inCredit = customerManager.isInCredit();
        assertTrue(inCredit);
        verify(mockAccountManager)
            .getBalance(AccountType.CURRENT);
        verify(mockAccountManager)
            .getBalance(AccountType.DEPOSIT);
    }

The argument matchers are more explicit in the above and could also return different results if needs be.

It is also possible to mock consecutive calls to a method so the same argument can generate a different return object. Using the getBalance example, the first call could return 1000.0 and the next 2000.0.

        BigDecimal positiveAmount1 = new BigDecimal(1000.00);
        BigDecimal positiveAmount2 = new BigDecimal(2000.00);
        when(mockAccountManager.getBalance(((AccountType)any())))
            .thenReturn(positiveAmount1)
            .thenReturn(positiveAmount2);

It is also possible to partially mock real objects using the spy method. If a real AccountManager object had been created and set, then the getBalance method could have be stubbed as shown below:

import java.math.BigDecimal;
import org.junit.Before;
import org.junit.Test;

import static org.mockito.Mockito.verify;
import static org.mockito.Mockito.when;
import static org.mockito.Mockito.any;
import static org.mockito.Mockito.spy;
import static org.mockito.Mockito.times;
import static junit.framework.Assert.assertTrue;

public class CustomerManagerTest {

    private CustomerManager customerManager;
    private AccountManager accountManager = new AccountManager();

    @Before
    public void setUp() throws Exception {
        customerManager = new CustomerManager();
    }

    @Test
    public void testPositiveBalance() {
        AccountManager spyAccountManager = spy(accountManager);
        customerManager.setAccountManager(spyAccountManager);
        BigDecimal postiveAmount = new BigDecimal(1000.00);
        when(spyAccountManager.getBalance(((AccountType)any())))
            .thenReturn(postiveAmount);
        boolean inCredit = customerManager.isInCredit();
        assertTrue(inCredit);
        verify(spyAccountManager, times(2))
            .getBalance((AccountType)any());
    }

}

There are many more features to the Mockito framework than described here (throwing exceptions, stubbing void methods, etc..) and http://mockito.org/ is a good starting point.

Finally, you can also use annotations to declare mock objects. An alternative to using

    private AccountManager mockAccountManager =
        mock(AccountManager.class);

would be to use the @Mock annotation as below:

    @Mock
    private AccountManager mockAccountManager;

and in the setup method initialise them by the following command:

    MockitoAnnotations.initMocks(this);

JPA Entity Lifecycle Callback and Listener Annotations

2011-02-08T03:47:00.000-08:00

Within the javax.persistence package there are annotations that may be applied to methods of an entity or a mapped superclass to specify that the annotated method must be called for a certain lifecycle event. A lifecycle event being either: Persist, Update, Remove or Load. and each event has a Pre or Post event.

Listeners can also have methods annotated with a lifecycle event. Listeners can be used to hold the business logic that would otherwise be in the entities (or another layer.) This enables the entities to be just POJOs. It also means that the testing of the business logic can be done in isolation.

Below is an example of using lifecycle events to populate an id var and also populate a lastUpdated var, in a mapped superclass:

@MappedSuperclass
public abstract class BaseEntity implements Serializable {

    private static final long serialVersionUID = 1L;
    private static final int ID_LENGTH=36;

    @Id
    @Column(length = ID_LENGTH)
    private String id;

    @Temporal(TemporalType.TIMESTAMP)
    @Column(updatable = false)
    private Date dateCreated;
    @Temporal(TemporalType.TIMESTAMP)
    private Date lastModified;

    // constructor(s)

    @PreUpdate
    public void updateLastModified () {
        lastModified = new Date();
    }

    @PrePersist
    protected void generateUUID() {
        id = java.util.UUID.randomUUID().toString();
        dateCreated = new Date();
        lastModified = new Date();
    }

    .....

}

An simple example of using a Listener could be where an entity has a transient var that needs to be populated after the entity has been persisted, updated or loaded.

public class AvailableCreditListener {

    @PostLoad
    @PostPersist
    @PostUpdate
    public void calculateAvailableCredit{Account account) {

        account.setAvailableCredit(
            account.getBalance().add(
                account.getOverdraftLimit()));
    }

}

The entity class would be annotated with @EntityListeners:

@EntityListeners({AvailableCreditListener.class})
public class AccountEntity extends BaseEntity {

    private BigDecimal balance;
    private BigDecimal overdraftLimit;
    @Transient
    private BigDecimal availableCredit;

    // getters and setters

}

Finally, instead of annotations, an XMl mapping file can be used and deployed with the application to specify default listeners. (This mapping file is referenced by the persistence.xml file.) But an entity can use the @ExcludeDefaultListeners annotation if it does not want to use the default listeners.

@ExcludeDefaultListeners

@Entity

public class AccountEntity extends BaseEntity {

    ....

}

Loose Coupling using CDI

2011-02-01T07:05:00.000-08:00

A key to n-tier architectures is notion of loose coupling and CDI enables this between classes in Java EE 6.

By using the @Inject annotation, you can specify an injection point in a class. The below example uses the annotation on a setter method.

    @Inject
    public void setCustomer(Customer customer) {
        this.customer = customer;
    }

It could equally be used on a field as below:

    @Inject
    Customer customer;

It is possible that more than one implementation of the Customer class exists so to resolve this problem at runtime, qualifiers are used. They provide the ability to 'qualify' what gets injected. an example qualifier is below:

import javax.inject.Qualifier;
import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

@Documented
@Qualifier
@Target({ElementType.TYPE, ElementType.FIELD, ElementType.METHOD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface TradeCustomerQualifier {
}

The TradeCustomer class would be enhanced to use the qualifier by way of an annotation.

@TradeCustomerQualifier
@Named("tradeCustomer")
@ApplicationScoped
public class TradeCustomer extends Customer {

    ......

}

An example of using the qualifier is below:

    @Inject
    public void setCustomer(@TradeCustomerQualifier Customer customer) {
        this.customer = customer;
    }

Finally, in order for CDI to bootstrap, there'll need to be a beans.xml file in the META-INF folder (for jars and in the WEB-INF for web applications.)

<beans xmlns="http://java.sun.com/xml/ns/javaee"
       xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
       xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/beans_1_0.xsd">
</beans>

Extending Bean Functionality using Interceptors

2011-01-27T05:30:00.000-08:00

A key part of the Java EE 6 platform is CDI (Context and Dependency Injection) and CDI supports two ways of extending bean functionality: interceptors and decorators.

For this post, we'll concentrate on interceptors and provide an example of implementing a cross-cutting concern across multiple beans ie logging.

An example of an interceptor which extracts the user value from the SessionContext for logging is shown below:

import org.apache.log4j.MDC;
import javax.interceptor.AroundInvoke;
import javax.interceptor.InvocationContext;
import java.io.Serializable;

public final class AuditLoggingInterceptor implements Serializable {

    protected static final String MDC_USER = "user";
    protected static final String UNAUTHENTICATED_USER =
        "Unauthenticated User";
    protected static final String NULL_USER =
        "Authenticated User Name is Null";
    private static final long serialVersionUID = 1L;
    private SessionContext sessionContext;

    @AroundInvoke
    public Object captureUser(InvocationContext context)
        throws Exception {

        MDC.put(MDC_USER, determineUsername());

        try {
            return context.proceed();
        }catch(Exception e){
            // handle exception
        }finally {
            MDC.remove(MDC_USER);
        }
    }

    /**
     * Inject the calling Session Context.
     * @param sessionContext context the current invocation
     */
    @Resource
    public void setSessionContext(SessionContext sessionContext) {
        this.sessionContext = sessionContext;
    }

    public SessionContext getSessionContext() {
        return sessionContext;
    }

    /**
     * Determine what the username should be based on the session context.
     *
     * @return the username
     */
    protected String determineUsername() {
        String username = NULL_USER;
        if (sessionContext != null) {
            try{
                if (sessionContext.getCallerPrincipal() == null) {
                    username = UNAUTHENTICATED_USER;
                } else {
                    username =
                    sessionContext.getCallerPrincipal().getName();
                }
            }catch(NullPointerException npe){
                // handle exception
            }
        }
        return username;
    }
}

The above interceptor implements a captureUser method which is marked with the @AroundInvoke annotation. This ensures that the method is invoked around the business methods for the classes that the interceptor is bound to.

import org.apache.log4j.Logger;
import javax.interceptor.Interceptors;
import javax.ejb.Remote;
import javax.ejb.Stateless;

@Interceptors({AuditLoggingInterceptor.class})
@Stateless(mappedName = JndiResourceName.BUSINESS_SERVICE)
@Remote(BusinessService.class)
public class BusinessServiceBean implements BusinessService {

    private static final Logger LOGGER =
        Logger.getLogger(BusinessServiceBean .class);

    @Override
    public void doSomething() {
        LOGGER.info("BusinessServiceBean.doSomething ()");
        // do something
    }
}

When the doSomething method is invoked on the business service, the method will be wrapped by captureUser method. The log4j class MDC (Mapped Diagnostic Context) will set the user key in the context map to be the caller principal name from the session context. This value will be used when the info message is logged. When the method completes, the user value is removed from the context.

The entry in the log4j.properties file so that the MDC value gets picked up is below:

log4j.appender.AUDITROLLINGFILE.layout.ConversionPattern = %d{yyyy-MM-dd HH:mm:ss} [%X{user}] %c{1} [%p] %m%n

To exclude a class's methods from being 'intercepted' then the business methods can be annotated with @ExcludeClassInterceptors.

Second Level Caching

2011-01-22T12:39:00.000-08:00

JPA has two levels of caching. The first level of caching is the persistence context (which can be either transaction scoped or extended.), and the second level of caching, introduced in JPA 2.0, sites in between the entity manager and the database.

With second level caching entities not found in the persistence context will be loaded from the second level cache, and if not found there, from the database. The ideal type of entity to live in the second level cache are those that are rarely updated, or those that are constantly read.

To mark an entity as requiring caching, you can use the @Cacheable annotation as below:

@Entity
@Cacheable(true)
public class Person {

    @Id @GeneratedValue
    private Long id;
    private String name;

    // etc ...
}

To override the provider-specific defaults for managing cached entities, you can set the shared-cache-mode value in the persistence.xml. The possible values are below:

ALL- all entities are cached
DISABLE_SELECTIVE - all entities cached apart from those with the annotation @Cacheable(false)
ENABLE_SELECTIVE - only entities with the annotation @Cacheable(true) are cached
NONE - no caching for the persistence unit
UNSPECIFIED - provider-specific default

JPA 2.0 also introdcued the Cache interface which can be used to evict or invalidate entities in the second level cache. It can claso be used to check whether ot not an entity exisits in the cache as well.

Finally, you cannot implement a caching strategy without also considering a locking strategy (but that's for another post!)

CriteriaBuilder and Dynamic Queries in JPA 2.0

2011-01-21T03:12:00.000-08:00

A major new feature of Java EE 6 is JPA 2.0 and in particular the addition of the Criteria API which provides the ability to dynamically construct object-based queries.

This resolves some of the problems which arise when building dynamic native queries. The below example shows how to find customer entities with two search parameters:

public List<CustomerEntity> findCustomers(
    final String firstName, final String surname) {

    StringBuilder queryBuilder = new StringBuilder(
        "select c from Customer where ");
    List<String> paramList = new ArrayList<String>();
    paramList.add(" upper(c.firstName) like '%?%'"
        .replace("?", firstName.toUpperCase()));
    paramList.add(" upper(c.surname) like '%?%'"
        .replace("?", surname.toUpperCase()));

    Iterator itr = paramList.iterator();
    while(itr.hasNext()) {
        queryBuilder.append(itr.next());
        if (itr.hasNext()) {
            queryBuilder.append(" and ");
        }
    }

    final Query query = entityManager.createNativeQuery(
        queryBuilder.toString());

    List<Object> resultList = (List<Object>)query.getResultList();

    // iterate, cast, populate and return a list
}

The problem with the above is that it is not type safe and involves iterating over a List of Object where those Objects are themselves Object arrays. Also should Customer contain any child elements, these would have to be retrieved in a separate call.

Using the CriteriaBuilder, the same results can be achieved as shown below:

public List<CustomerEntity> findCustomers(final String firstName, final String surname) {

    CriteriaBuilder builder = entityManager.getCriteriaBuilder();
    CriteriaQuery<CustomerEntity> query = builder.createQuery(CustomerEntity.class);
    Root<CustomerEntity> cust = query.from(CustomerEntity.class);
    query.select(cust);

    List<Predicate> predicateList = new ArrayList<Predicate>();

    Predicate firstNamePredicate, surnamePredicate;

    if ((firstName != null) && (!(firstName.isEmpty()))) {
        firstNamePredicate = builder.like(
            builder.upper(cust.<String>get("firstName")), "%"+firstName.toUpperCase()+"%");
        predicateList.add(firstNamePredicate);
    }

    if ((surname != null) && (!(surname.isEmpty()))) {
        surnamePredicate = builder.like(
            builder.upper(cust.<String>get("surname")), "%"+surname.toUpperCase()+"%");
        predicateList.add(surnamePredicate);
    }

    Predicate[] predicates = new Predicate[predicateList.size()];
    PredicateList.toArray(predicates);
    query.where(predicates);

    return entityManager.createQuery(query).getResultList();
}

There is some type safety in the above but it can be furthered tied down by using the metamodel class for the entity, by using the metamodel class's public static members instead of text strings for the entity's attributes. The code would now look like this:


    firstNamePredicate = builder.like(
        builder.upper(cust.get(CustomerEntity_.firstName)),
            "%"+firstName.toUpperCase()+"%");

    surnamePredicate = builder.like(
        builder.upper(cust.get(CustomerEntity_.surname)), 
            "%"+surname.toUpperCase()+"%");

Having built metamodel classes using Maven, it's questionable whether it's a worthwhile exercise as any mistakes in the text based approach to finding attribute names should be flagged up by comprehensive unit testing.

Java Blogging and Tweeting

2011-01-21T03:08:00.000-08:00

The idea behind this blog is to remind myself of all the useful bits of code I come across whilst working on projects and contracts. On numerous occasions, I've spent hours resolving problems on one contract only to hit the same problems on another so by putting nuggets of Java code up on the web, I should have no excuse in spending hours resolving the same problems I've encountered before. It'll also be retrospective and not just about problems I come across on current contracts, so if I can remember useful stuff from the past then I'll post about those too.

The posts may stray into the realms of build tools like Maven, test frameworks like Mockito, application servers like Glassfish and JBoss, and platforms like Android but in the main it'll be about Core and Enterprise Java.

As for the Twiiter account, there will be tweets about new blog posts plus me writing down all those daft thoughts that enter your head whilst staring out of the window at work. Also in amongst the tweets will the odd football rant about the ups and downs of Swansea City !