Thought Forge

jBPM Developer Guide

John Turner — Mon, 01 Mar 2010 19:26:23 +0000

Business Process Management (BPM) has been around in one guise or another for quite a while now and most people have had some exposure to its many facets. With so much promised, it is easy to see why it has generated so much interest.

jBPM is an open source BPM framework from JBoss that has matured into a real alternative to the many other BPM offerings. The ‘jBPM Developer Guide’ introduces to its readers the main artifacts of BPM and what is involved in implementing typical jBPM solution.

The book begins by providing a background to BPM and how it can be leveraged to deliver benefit to the business. This includes an introduction to processes, tasks and process management (Business Process Management or BAM). As any good book should, terminologies that are associated with BPM are introduced and defined. Thankfully, the definitions are void of the usual marketing hype.

With the help of an example, graph orientated programming (GOP) is then introduced and its relevance to jBPM discussed. Specifically the Node, Transition and Process Definition concepts are covered before the author works through sample implementations of each. Wait states (asynchronous system interactions and human tasks) and automatic nodes are compared before process execution is demonstrated through a sample process execution engine implementation.

The book goes on to give some background to the jBPM project and covers the setup of tools to be used throughout the remainder of the book (Maven, MySql, Eclipse etc.). It outlines how to install jBPM from a distribution and from source. I used the installer to install the version used for the examples (3.2.6.SP1).

Two example process projects are then created using the eclipse designer plugin and then the maven plugin to contrast both approaches. Use of the ‘Graphical Process Editor’ is also demonstrated.

The jPDL language is then explored in greater depth describing in detail the XML\Class definitions of the process, the various node types (Node, Start State, End State, State, Decision), transitions and the execution token. As an example (recruitment) process is automated with the jBPM framework. This is achieved iteratively adding more detail in each stage.

Process instance persistence is discussed in depth. This includes details on how and when process definition amd process instance persistence occurs. A brief review is given of the jBPM API to interact with the database and the jBPM\Hibernate persistence configuration.

Human Task’s are explained including details on input data, task action and output data. The distinction between a TaskNode and Task is also made. A brief introduction to the jBPM Identity module is provided during a discussion about task assignment before demonstrating an example process.

The transactional behaviour of jBPM is then discussed along with a more detailed discussion on variable mappings and task assignment. Process variables and the type’s of information stored in process variables are explained and the specific API for variable manipulation is covered in brief, along with the variable persistence and hierarchy. These concepts are demonstrated with a concrete example.

More advanced node types are covered in this chapter including Fork and Join nodes, Super state nodes, Process state nodes and the Email node. Variable mapping strategies as discussed in depth and related to the Process State node.

Further examples of using Super state nodes and Process state nodes are covered in addition to asynchronous execution and the JobExecutor. The examples focused on the asynchronous execution are thorough and provide a good understanding of this process.

The book finished by discussing the use of jBPM within a JEE environment. In particular, JTA, Data Source’s, the CommandServiceBean, the JobExecutor and JMS and finally Timers and reminders.

My overall impression of the book was that it relayed the key information required to get up and running with jBPM. The author was clearly knowledgeable in the subject and provided useful examples to complement the concept’s being discussed. I liked the fact that the author gives details on installing the developer tools as it allows the reader to follow along with the examples.

The only negative comment I can make was that I found the poor construction of sentences and awkward use of English a little distracting. It reads as a book that was translated into English from another language.

Note: There is a rating embedded within this post, please visit this post to rate it.

Creating a Logging Aspect with Spring AOP and AspectJ

John Turner — Tue, 16 Feb 2010 22:56:17 +0000

After working in software development for a number of years, one tends to build up a repository of useful code examples and utilities. I’m certainly no different in this regard and go one step further by maintaining a hosted Subversion repository to keep such code examples safe and sound (and readily accessible).

One such code example that I often turn to is a logging aspect implemented using Spring AOP and AspectJ. This logging aspect traces method entry and exit which proves very useful if you need to perform root cause analysis in pre-production environments.

In what follows, I’m going to share this code example. I have also made the logging aspect source code available for download.

I have assumed you have a reasonable grasp of Aspect Orientated Programming concepts and terminologies.

The Logger

There are a few options to choose from when considering a logging framework and these have evolved over the years so it is probably best to abstract the logging framework from the aspect. For this purpose, I have implemented a simple logging interface and log level enum.

package net.thoughtforge.logger;

public interface Logger {

    boolean isLogLevel(LogLevel logLevel, Class clazz);

    void log(LogLevel logLevel, Class clazz, Throwable throwable,
        String pattern, Object... arguments);
}

Listing 1 : Logger.java

package net.thoughtforge.logger;

public enum LogLevel {
  DEBUG,
  ERROR,
  FATAL,
  INFO,
  TRACE,
  WARN
}

Listing 2 : LogLevel.java

In the majority of cases, I end up using the Commons Logging framework and so have included this implementation of the Logger in the source download.

You may decide that this level of abstraction is overkill and that you are willing to commit to using a specific logging framework. When making this decision, keep in mind that you will be specifying the log level throughout your code base.

The Logging Aspect

I am going to use the @Aspect approach to implement the logging aspect which is to say I will use annotations to specify the advice. I want the logging aspect to log the method name, argument values, return value and any exception thrown so I will use the @Before, @AfterThrowing and @AfterReturning annotations.

  @Before(value = "@annotation(trace)", argNames = "joinPoint, trace")
  public void before(JoinPoint joinPoint, Loggable loggable) {

    Class clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();
    
    if (ArrayUtils.isEmpty(joinPoint.getArgs())) {
      logger.log(loggable.value(), clazz, null, BEFORE_STRING, name,
        constructArgumentsString(clazz, joinPoint.getArgs()));
    } else {
      logger.log(loggable.value(), clazz, null, BEFORE_WITH_PARAMS_STRING, name,
          constructArgumentsString(clazz, joinPoint.getArgs()));      
    }
  }

Listing 3 : @Before Code Snippet

The ‘Before’ advice simply logs (at the appropriate log level) the method name and the toString value of all arguments (if any). ‘Before’ advice executes when a join point is reached.

  @AfterThrowing(value = "@annotation(net.thoughtforge.aspect.Loggable)",
      throwing = "throwable", argNames = "joinPoint, throwable")
  public void afterThrowing(JoinPoint joinPoint, Throwable throwable) {

    Class clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();
    logger.log(LogLevel.ERROR, clazz, throwable, AFTER_THROWING, name,
        throwable.getMessage(), constructArgumentsString(clazz,
            joinPoint.getArgs()));
  }

Listing 4 : @AfterThrowing Code Snippet

The ‘AfterThrowing’ advice logs the method name, exception message and the toString value of all arguments (if any). ‘AfterThrowing’ advice executes after a method exits by throwing an exception.

  @AfterReturning(value = "@annotation(trace)", returning = "returnValue",
      argNames = "joinPoint, trace, returnValue")
  public void afterReturning(JoinPoint joinPoint, Loggable loggable,
      Object returnValue) {

    Class clazz = joinPoint.getTarget().getClass();
    String name = joinPoint.getSignature().getName();

    if (joinPoint.getSignature() instanceof MethodSignature) {
      MethodSignature signature = (MethodSignature) joinPoint
          .getSignature();
      Class returnType = signature.getReturnType();
      if (returnType.getName().compareTo("void") == 0) {
        logger.log(loggable.value(), clazz, null, AFTER_RETURNING_VOID,
            name, constructArgumentsString(clazz, returnValue));

        return;
      }
    }

    logger.log(loggable.value(), clazz, null, AFTER_RETURNING, name,
        constructArgumentsString(clazz, returnValue));
  }

Listing 5 : @AfterReturning Code Snippet

The ‘AfterReturning’ advice logs the method name and the toString value of the returned value (if any). ‘AfterReturning’ advice executes after a method exits normally.

You will notice that I log the toString value to identify objects. I routinely use the Apache Commons ToStringBuilder to create the toString value. I find this particularly useful when working with persistent entities as it allows me to clearly identify the entity.

Another possible implementation that avoids using the toString method is to use the Apache Commons ReflectionToStringBuilder within the logging aspect to create a string representation of the object being logged.

If you are writing your own toString implementations (the Commons implementation is perfectly adequate) and are implementing an object with complex properties be aware of recursive invocations that may result in a stack overflow exception.

Specifying the Pointcut

A pointcut expression is an expression that specifies where in the code the advice will be applied. With AspectJ, you can create a pointcut by specifying package, class and method attributes among other things. I find the easiest way to specify a pointcut for the logging aspect is by matching methods that have a specific annotation.

package net.thoughtforge.aspect;

import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

import net.thoughtforge.logger.LogLevel;

@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.METHOD)
public @interface Loggable {

    LogLevel value();
}

Listing 6 : Loggable.java

As you can see, the Loggable annotation has one property that specifies the log level at which the log statement should be output. Using the annotation means that developers never need to alter the pointcut expression to add or remove methods to the pointcut. A developer only has to add the annotation to a method to have the logging aspect applied.

package net.thoughtforge.bean;

import java.util.Date;

import net.thoughtforge.aspect.Loggable;
import net.thoughtforge.logger.LogLevel;

import org.apache.commons.lang.builder.ToStringBuilder;
import org.springframework.stereotype.Component;

@Component(value = "simpleBean")
public class SimpleBean {

  private Date dateProperty;

  private Integer integerProperty;

  private String stringProperty;

  @Loggable(value = LogLevel.TRACE)
  public Date getDateProperty() {
    return dateProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setDateProperty(final Date dateProperty) {
    this.dateProperty = dateProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public Integer getIntegerProperty() {
    return integerProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setIntegerProperty(final Integer integerProperty) {
    this.integerProperty = integerProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public String getStringProperty() {
    return stringProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setStringProperty(final String stringProperty) {
    this.stringProperty = stringProperty;
  }

  @Override
  public String toString() {
    return new ToStringBuilder(this).append("dateProperty", dateProperty)
        .append("integerProperty", integerProperty).append(
            "stringProperty", stringProperty).toString();
  }
}

Listing 7 : SimpleBean.java

The SimpleBean and SimpleBeanSubclass are for demonstration purposes. You can see that each method is annotated with the @Loggable annotation and the log level is set to TRACE. You can obviously use different log levels for different methods as required.

package net.thoughtforge.bean;

import java.math.BigDecimal;

import net.thoughtforge.aspect.Loggable;
import net.thoughtforge.logger.LogLevel;

import org.apache.commons.lang.builder.ToStringBuilder;
import org.springframework.stereotype.Component;

@Component(value = "simpleBeanSubclass")
public class SimpleBeanSubclass extends SimpleBean {

  private BigDecimal decimalProperty;

  @Loggable(value = LogLevel.TRACE)
  public BigDecimal getDecimalProperty() {
    return decimalProperty;
  }

  @Loggable(value = LogLevel.TRACE)
  public void setDecimalProperty(final BigDecimal decimalProperty) {
    this.decimalProperty = decimalProperty;
  }

  @Override
  public String toString() {
    return new ToStringBuilder(this).append("decimalProperty",
        decimalProperty).appendSuper(super.toString()).toString();
  }
}

Listing 8 : SimpleBeanSubclass.java

Also note the use of the ToStringBuilder to create the toString value. You may choose to use the ReflectionToStringBuilder or some other mechanism.

Testing the Logging Aspect

One way to test the logging aspect is to simply have a test invoke instrumented methods and observe the log statements produced. This is a useful exercise but requires manual intervention to determine if the test was successful.

In order to create an automated test for the logging aspect, I needed to create a mock logger that simulates the actions of a logger and allows me to interrogate the log statements produced.

package net.thoughtforge.mock.logger;

import java.text.MessageFormat;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

import net.thoughtforge.logger.LogLevel;
import net.thoughtforge.logger.Logger;

import org.springframework.stereotype.Component;

@Component
public class MockLogger implements Logger {

  private Map, LogLevel> logLevelMap =
    new HashMap, LogLevel>();
  
  private Map, List> messages = new HashMap, List>();
  
  public boolean isLogLevel(LogLevel logLevel,  Class clazz) {
    boolean result = false;

    switch (logLevel) {
      case DEBUG:
        result = isLogLevelEnabled(clazz, LogLevel.DEBUG);
  
      case ERROR:
        result = isLogLevelEnabled(clazz, LogLevel.ERROR);
  
      case FATAL:
        result = isLogLevelEnabled(clazz, LogLevel.FATAL);
  
      case INFO:
        result = isLogLevelEnabled(clazz, LogLevel.INFO);
  
      case TRACE:
        result = isLogLevelEnabled(clazz, LogLevel.TRACE);
  
      case WARN:
        result = isLogLevelEnabled(clazz, LogLevel.WARN);
  
      default:
        result = false;
    }
    
    return result;
  }

  public void log(LogLevel logLevel,  Class clazz,
       Throwable throwable,  String pattern,
       Object... arguments) {

    switch (logLevel) {
      case DEBUG:
        debug(clazz, throwable, pattern, arguments);
        break;
  
      case ERROR:
        error(clazz, throwable, pattern, arguments);
        break;
  
      case FATAL:
        fatal(clazz, throwable, pattern, arguments);
        break;
  
      case INFO:
        info(clazz, throwable, pattern, arguments);
        break;
  
      case TRACE:
        trace(clazz, throwable, pattern, arguments);
        break;
  
      case WARN:
        warn(clazz, throwable, pattern, arguments);
        break;
    }
  }

  private void debug(Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.DEBUG, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.DEBUG, format(pattern, arguments)));
    }
  }

  private void error(Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.ERROR, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.ERROR, format(pattern, arguments)));
    }
  }

  private void fatal(Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.FATAL, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.FATAL, format(pattern, arguments)));
    }
  }

  private void info(Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.INFO, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.INFO, format(pattern, arguments)));
    }
  }

  private void trace( Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.TRACE, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.TRACE, format(pattern, arguments)));
    }
  }

  private void warn( Class clazz,  Throwable throwable,
       String pattern,  Object... arguments) {

    if (throwable != null) {
      getMessages(clazz).add(new LogMessage(LogLevel.WARN, format(pattern, arguments), throwable));
    } else {
      getMessages(clazz).add(new LogMessage(LogLevel.WARN, format(pattern, arguments)));
    }
  }

  private String format( String pattern,  Object... arguments) {

    return MessageFormat.format(pattern, arguments);
  }

  public void resetLoggers() {
    messages = new HashMap, List>();
  }
  
  public List getMessages(Class clazz) {
    if (messages.get(clazz) == null) {
      messages.put(clazz, new ArrayList());
    }
    
    return messages.get(clazz);
  }

  private boolean isLogLevelEnabled(Class clazz, LogLevel logLevel) {
    return logLevelMap.get(clazz) != null && logLevelMap.get(clazz).equals(logLevel);
  }
  
  public void setLogLevel(Class clazz, LogLevel logLevel) {
    logLevelMap.put(clazz, logLevel);
  }
  
  public class LogMessage {
    private LogLevel logLevel;
    
    private String message;
    
    private Throwable throwable;

    public LogMessage(LogLevel logLevel, String message, Throwable throwable) {
      this(logLevel, message);
      this.throwable = throwable;
    }
    
    public LogMessage(LogLevel logLevel, String message) {
      this.logLevel = logLevel;
      this.message = message;
    }
    
    public LogLevel getLogLevel() {
      return logLevel;
    }
    
    public String getMessage() {
      return message;
    }
    
    public Throwable getThrowable() {
      return throwable;
    }
  }
}

Listing 9 : MockLogger.java

The logging aspect test utilises the MockLogger and makes assertions about the log statements produced.

package net.thoughtforge.aspect;

import java.math.BigDecimal;

import junit.framework.Assert;
import net.thoughtforge.bean.SimpleBean;
import net.thoughtforge.bean.SimpleBeanSubclass;
import net.thoughtforge.logger.LogLevel;
import net.thoughtforge.mock.logger.MockLogger;
import net.thoughtforge.mock.logger.MockLogger.LogMessage;

import org.apache.commons.lang.time.DateUtils;
import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "/applicationContext/applicationContext-aspect.xml",
    "/applicationContext/applicationContext-logger.xml",
    "/applicationContext/applicationContext.xml" })
public class LoggingAspectTest {

  @Autowired
  private MockLogger logger;
  
  @Autowired
  @Qualifier(value = "simpleBean")
  public SimpleBean simpleBean;

  @Autowired
  public SimpleBeanSubclass simpleBeanSubclass;

  @Before
  public void before() {
    logger.setLogLevel(SimpleBean.class, LogLevel.TRACE);
    logger.setLogLevel(SimpleBeanSubclass.class, LogLevel.TRACE);
    logger.resetLoggers();
  }
  
  @Test
  public void testSimpleBean_SetDateProperty() throws Exception {
    simpleBean.setDateProperty(
        DateUtils.parseDate("01/01/2010", new String[] {"dd/MM/yyyy"}));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDateProperty > with params Fri Jan 01 00:00:00 GMT 2010 ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDateProperty > ]");
  }
  
  @Test
  public void testSimpleBean_SetIntegerProperty() {
    simpleBean.setIntegerProperty(100);
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setIntegerProperty > with params 100 ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setIntegerProperty > ]");
  }
  
  @Test
  public void testSimpleBean_SetStringProperty() {
    simpleBean.setStringProperty("stringProperty");
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < setStringProperty > with params stringProperty ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setStringProperty > ]");
  }
  
  @Test
  public void testSimpleBean_GetDateProperty() {
    simpleBean.getDateProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDateProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDateProperty > returning Fri Jan 01 00:00:00 GMT 2010 ]");
  }
  
  @Test
  public void testSimpleBean_GetIntegerProperty() {
    simpleBean.getIntegerProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getIntegerProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getIntegerProperty > returning 100 ]");
  }
  
  @Test
  public void testSimpleBean_GetStringProperty() {
    simpleBean.getStringProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBean.class).size());
    assertEquals(logger.getMessages(SimpleBean.class).get(0),
        LogLevel.TRACE,
        "[ entering < getStringProperty > ]");
    assertEquals(logger.getMessages(SimpleBean.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getStringProperty > returning stringProperty ]");
  }

  @Test
  public void testSimpleBeanSubclass_SetDateProperty() throws Exception {
    simpleBeanSubclass.setDateProperty(
        DateUtils.parseDate("01/01/2010", new String[] {"dd/MM/yyyy"}));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDateProperty > with params Fri Jan 01 00:00:00 GMT 2010 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDateProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetDecimalProperty() {
    simpleBeanSubclass.setDecimalProperty(new BigDecimal("0.25"));
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setDecimalProperty > with params 0.25 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setDecimalProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetIntegerProperty() {
    simpleBeanSubclass.setIntegerProperty(100);
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setIntegerProperty > with params 100 ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setIntegerProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_SetStringProperty() {
    simpleBeanSubclass.setStringProperty("stringProperty");
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < setStringProperty > with params stringProperty ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < setStringProperty > ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetDateProperty() {
    simpleBeanSubclass.getDateProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDateProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDateProperty > returning Fri Jan 01 00:00:00 GMT 2010 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetDecimalProperty() {
    simpleBeanSubclass.getDecimalProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getDecimalProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getDecimalProperty > returning 0.25 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetIntegerProperty() {
    simpleBeanSubclass.getIntegerProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getIntegerProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getIntegerProperty > returning 100 ]");
  }
  
  @Test
  public void testSimpleBeanSubclass_GetStringProperty() {
    simpleBeanSubclass.getStringProperty();
    
    Assert.assertEquals(2, logger.getMessages(SimpleBeanSubclass.class).size());
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(0),
        LogLevel.TRACE,
        "[ entering < getStringProperty > ]");
    assertEquals(logger.getMessages(SimpleBeanSubclass.class).get(1),
        LogLevel.TRACE,
        "[ leaving < getStringProperty > returning stringProperty ]");
  }
  
  private void assertEquals(LogMessage logMessage, LogLevel logLevel, String message) {
    Assert.assertEquals(logLevel, logMessage.getLogLevel());
    
    Assert.assertEquals(message, logMessage.getMessage());    
  }
}

Listing 10 : LoggingAspectTest.java

The test is not exhaustive but suffices to test the general operation of the logging aspect.

Final Word

Hopefully you found my example useful but I will finish by saying that there are many choices that I made in deciding on this approach.

A strong argument could be made for the use of XML configuration as opposed to the @Aspect approach which allows you greater control over the execution of the advice without modifying code. This would be particularly relevant in an environment where performance was a major focus. I personally have found that the control provided by logging frameworks to enable and disable particular loggers is sufficient in most environments.

Note: There is a rating embedded within this post, please visit this post to rate it.

Web Form Validation with JBoss RichFaces and Hibernate Validator

John Turner — Tue, 09 Feb 2010 21:02:09 +0000

Last month I posted about Building a Dynamic Tree with JBoss RichFaces and Spring Web Flow. Since then, I have received a few requests to demonstrate how to implement validation within the modal dialog. There are several internet resources that already deal with this but none that provide a complete working example so I decided I would do just that.

You can download the source code in the form of a Maven project and follow along.

Hibernate Validator Dependencies

First step is to add the Hibernate Validator dependency to the project pom. I have used Hibernate Validator 4.0.0.GA because it is a JSR 303 compliant implementation.


  org.hibernate
  hibernate-validator
  4.0.0.GA
  compile

Listing 1 : Hibernate Validator Dependency

Annotating the Model Class

JSR 303 allows for the specification of validation constraints via Annotations and\or XML. The Hibernate Validator documentation has recently been updated to include details on specifying the validation.xml if you prefer to use XML.

For this example I am going to use Annotations to specify a ‘Size’ constraint on the name and description properties of the Organisation class. These are basic constraints but they will suffice for demonstration purposes.

package net.thoughtforge.model;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import javax.validation.constraints.Size;

import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;

@Component
@Scope("prototype")
public class Organisation implements Serializable {

  private static final long serialVersionUID = -2023156931701914562L;

  private List children;
  
  @Size(min=3, max=200, message="Description must be between 3 and 200 characters in length.")
  private String description;
  
  @Size(min=3, max=50, message="Name must be between 3 and 50 characters in length.")
  private String name;

  private Organisation parent;
  
  public void addChild(Organisation child) {
        if (child.getParent() == null || !child.getParent().equals(this)) {
            child.setParent(this);
        }
        
        if (children == null) {
            children = new ArrayList();
        }
        
        if (!children.contains(child)) {
          children.add(child);
        }
  }
  
  public void removeChild(Organisation child) {
        if (child.getParent() != null && child.getParent().equals(this)) {
            child.setParent(null);
        }
        
        if (children != null) {
            children.remove(child);
        }
  }

  public List getChildren() {
    if (children == null) {
      children = new ArrayList();
    }
    
    return Collections.unmodifiableList(children);
  }
  
  public String getDescription() {
    return description;
  }

  public void setDescription(String description) {
    this.description = description;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Organisation getParent() {
    return parent;
  }

  public void setParent(Organisation parent) {
    this.parent = parent;
  }
}

Listing 2 : Organisation.java

Applying the Constraints

Of course, as annotations do nothing in and of themselves, I need to invoke the validator to apply the constraints. RichFaces provides 3 components that invoke either the Hibernate or JSR 303 bean validator during the JSF ‘Process Validations’ phase.

I wanted to validate the Organisation name and description properties. These are set within the ‘addChildModalPanel’ and updated within the ‘editChildModalPanel’. The validations are applied to each in exactly the same way.

To apply validations to the name and description ‘inputText’ fields I added a child field. Adding this child component results in the validator being invoked during the ‘Process Validations’ phase.

Listing 3 : rich:beanValidator

If the validation fails, messages are added to the FacesContext and will be displayed using the component.

Listing 4 : rich:messages

Displaying Validation Messages within the Modal Dialog

Finally, I needed to keep the Modal Dialog from closing when validation failures occured. This is achieved by modifying the a4j:commandButton as shown below. It is worth highlighting that each has its own and this is very important (as highlighted in the JBoss RichFaces documentation).

Listing 5 : a4j:commandButton

What I ended up with was a really intuitive and responsive UI with appropriate validations. It was an interesting exercise especially due to the intricacies of the component.

Note: There is a rating embedded within this post, please visit this post to rate it.

Marshalling XML with Spring WS and JAXB

John Turner — Thu, 04 Feb 2010 22:21:09 +0000

The ‘object-relational impedance mismatch’ is a well documented set of conceptual and technical difficulties that are often encountered when a relational database management system is being used by a program written in an object-oriented programming language. A similar impedance mismatch exists when XML is used by a program written in an object-oriented programming language.

Many popular ‘Object-Relational Mapping’ (ORM) frameworks exist that address the object-relational impedance mismatch and no doubt helped to inspire the evolution of ‘Object-XML Mapping’ (OXM) frameworks to address the object-xml impedance mismatch.

For the Java community, there are a number of OXM frameworks from which to choose (Castor, XStream, JiBX, JAXB) with each having particular strengths and weaknesses. The standard OXM framework for Java is JAXB.

In the following I work through a simple example that demonstrates object to XML marshalling (and demarshalling) using Spring, Spring WS and JAXB (and later JAXB Introductions!)

I have provided Maven projects for download so you can follow along:

Spring OXM and JAXB Source Download
Spring OXM, JAXB and JAXB Introductions Download

The Model

The model object that I have used for this example is a simple object representing a ‘Person’. The class contains only simple attributes.

package net.thoughtforge.model;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Calendar;

import javax.xml.bind.annotation.XmlAccessType;
import javax.xml.bind.annotation.XmlAccessorType;
import javax.xml.bind.annotation.XmlElement;
import javax.xml.bind.annotation.XmlRootElement;
import javax.xml.bind.annotation.XmlType;

@XmlRootElement(
    name="Person",
    namespace="http://thoughtforge.net/model")
@XmlAccessorType(XmlAccessType.FIELD)
@XmlType
public class Person implements Serializable {

  private static final long serialVersionUID = 8465162879793776395L;

  @XmlElement(namespace="http://thoughtforge.net/model")
  private Calendar dateOfBirth;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private String firstName;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private BigDecimal height;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private String lastName;
  
  @XmlElement(namespace="http://thoughtforge.net/model")
  private BigDecimal weight;

  public Calendar getDateOfBirth() {
    return dateOfBirth;
  }

  public void setDateOfBirth(Calendar dateOfBirth) {
    this.dateOfBirth = dateOfBirth;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public BigDecimal getHeight() {
    return height;
  }

  public void setHeight(BigDecimal height) {
    this.height = height;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public BigDecimal getWeight() {
    return weight;
  }

  public void setWeight(BigDecimal weight) {
    this.weight = weight;
  }
}

Listing 1 : Person.java

As you can see from the listing, the class is annotated with JAXB annotations that are fairly self explanatory. I will leave it to you to look up the precise definition and consequence of these annotations (which can be found on the JAXB Reference Implementation website).

The XML Schema (XSD)

JAXB does not require an XML schema (a default schema can be generated), but for this example (and always on commercial projects) I have explicitly specified a schema in order to include type restrictions. It is important to remember that the XSD forms the contract between XML producers and consumers (marshaller and unmarshaller) and should be as detailed as possible.

Listing 2 : person.xsd

The Marshaller Abstraction

Rather than use the Spring Marshaller/Unmarshaller interface directly, I often use an abstraction for the Marshaller. The abstraction I used here is very simple and of course would not be practical for use with large XML files as it does not support streaming etc.

package net.thoughtforge.marshaller;

public interface Marshaller {

  String marshal(Object object);

  Object unmarshal(String string);
}

Listing 3 : Marshaller.java

The implementation of the marshaller delegates to a Spring JAXB marshaller.

package net.thoughtforge.marshaller;

import java.io.StringWriter;

import javax.xml.transform.stream.StreamResult;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.stereotype.Component;
import org.springframework.xml.transform.StringSource;

@Component(value="marshaller")
public class Jaxb2Marshaller implements Marshaller {

  @Autowired
  @Qualifier(value="jaxb2Marshaller")
  private org.springframework.oxm.jaxb.Jaxb2Marshaller marshaller;
  
  public String marshal(Object object) {
    final StringWriter out = new StringWriter();
    marshaller.marshal(object, new StreamResult(out));
    return out.toString();
  }

  public Object unmarshal(String string) {
    return marshaller.unmarshal(new StringSource(string));
  }
}

Listing 4 : Jaxb2Marshaller.java

The Configuration

Using Spring to define a JAXB marshaller is relatively straight forward as the listing shows. I have specified the classes to be bound and the XML schema. If the XML schema is specified, the marshaller will instruct the XML parser to validate XML against the schema.





  
  
  
    
      
        net.thoughtforge.model.Person

Listing 5 : applicationContext-marshaller.xml

The Test

The following test is not exhaustive but demonstrates the marshalling and unmarshalling of a Person object. It also demonstrates XML schema validation occurring during the marshalling and unmarshalling process.

package net.thoughtforge.marshaller;

import java.math.BigDecimal;
import java.util.Calendar;

import net.thoughtforge.model.Person;

import org.apache.commons.lang.text.StrBuilder;
import org.junit.Assert;
import org.junit.BeforeClass;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.beans.factory.annotation.Qualifier;
import org.springframework.oxm.MarshallingFailureException;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "classpath:applicationContext/applicationContext-*.xml"})
public class Jaxb2MarshallerTest {

  private static final String MARSHALLED_PERSON =
    "1965-01-01T00:00:00ZJoe1.85Bloggs12.2";
  
  private static Calendar dateOfBirth;
  
  private static String firstName;
  
  private static BigDecimal height;
  
  private static String lastName;
  
  private static BigDecimal weight;
  
  @Autowired
  @Qualifier(value="marshaller")
  private Jaxb2Marshaller marshaller;

  @BeforeClass
  public static void beforeClass() {
    dateOfBirth = Calendar.getInstance();
    dateOfBirth.clear();
    dateOfBirth.set(Calendar.DATE, 1);
    dateOfBirth.set(Calendar.MONTH, Calendar.JANUARY);
    dateOfBirth.set(Calendar.YEAR, 1965);
    
    firstName = "Joe";
    height = new BigDecimal("1.85");
    lastName = "Bloggs";
    weight = new BigDecimal("12.2");
  }
  
  @Test
  public void marshallPerson() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight);
    
    String xml = marshaller.marshal(person);
    
    Assert.assertNotNull(xml);
    Assert.assertEquals(MARSHALLED_PERSON, xml);
  }

  @Test
  public void marshallPersonInvalidFirstName() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(new StrBuilder(firstName).appendPadding(50, '0').toString());
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("First name length restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("is not facet-valid with respect to maxLength '50'") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidHeight() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height.add(new BigDecimal("0.1111")));
    person.setLastName(lastName);
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("Height precision restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("the number of fraction digits has been limited to 2") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidLastName() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(new StrBuilder(lastName).appendPadding(50, '0').toString());
    person.setWeight(weight);
    
    try {
      marshaller.marshal(person);
      Assert.fail("First name length restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("is not facet-valid with respect to maxLength '50'") == -1);
    }
  }
  
  @Test
  public void marshallPersonInvalidWeight() {
    Person person = new Person();
    person.setDateOfBirth(dateOfBirth);
    person.setFirstName(firstName);
    person.setHeight(height);
    person.setLastName(lastName);
    person.setWeight(weight.add(new BigDecimal("0.1111")));
    
    try {
      marshaller.marshal(person);
      Assert.fail("Weight precision restriction not applied.");
    } catch (MarshallingFailureException marshallingFailureException) {
      Throwable rootCause = marshallingFailureException.getRootCause();
      Assert.assertFalse(rootCause.getMessage().indexOf("the number of fraction digits has been limited to 2") == -1);
    }
  }
  @Test
  public void unmarshallPerson() {
    Person person = (Person) marshaller.unmarshal(MARSHALLED_PERSON);
    
    Assert.assertNotNull(person);
    Assert.assertTrue(dateOfBirth.compareTo(person.getDateOfBirth()) == 0);
    Assert.assertEquals(firstName, person.getFirstName());
    Assert.assertEquals(height, person.getHeight());
    Assert.assertEquals(lastName, person.getLastName());
    Assert.assertEquals(weight, person.getWeight());
  }
}

Listing 6 : Jaxb2MarshallerTest.java

Removing JAXB Annotations

If you are using the reference implementation of JAXB you are required to use annotations to map objects to XML. As I mentioned in a previous post, I’m not a fan of using annotations for the purpose of mapping objects to some other format (relational database or XML or A.N. Other). I find it creates code clutter especially in instances were entity model classes are mapped to both a relational database and XML (using JAXB). In modular projects, it also creates unnecessary dependencies on the model module.

Luckily, some bright spark came along and created JAXB Introductions which allows you to define the mapping of objects to XML in an XML file. I’m not going to regurgitate the information on the JAXB Introductions website but I will outline the modifications I had to make to allow me to use JAXB Introductions with the example above.

First, I added the maven dependency to the project.

    
        jboss.jaxbintros
        jboss-jaxb-intros
        1.0.1.GA

Listing 7 : JAXB Introductions Maven Dependency

Second, I created a JAXB Introductions mapping file.

Listing 8 : marshaller-mapping.xml

Thirdly, I modified the Spring configuration to inject the JAXB Introductions annotation reader into the JAXB marshaller.





  
  
  
    
      
        net.thoughtforge.model.Person
      
    
    
            
                
                    
                        
                    
                  
                    
                        
                    
                
            
    
    
  

    
        classpath:marshaller-mapping.xml

Listing 9 : applicationContext-marshaller.xml

Finally, I removed the JAXB annotations from the model class (Person.java).

package net.thoughtforge.model;

import java.io.Serializable;
import java.math.BigDecimal;
import java.util.Calendar;

public class Person implements Serializable {

  private static final long serialVersionUID = 8465162879793776395L;

  private Calendar dateOfBirth;
  
  private String firstName;
  
  private BigDecimal height;
  
  private String lastName;
  
  private BigDecimal weight;

  public Calendar getDateOfBirth() {
    return dateOfBirth;
  }

  public void setDateOfBirth(Calendar dateOfBirth) {
    this.dateOfBirth = dateOfBirth;
  }

  public String getFirstName() {
    return firstName;
  }

  public void setFirstName(String firstName) {
    this.firstName = firstName;
  }

  public BigDecimal getHeight() {
    return height;
  }

  public void setHeight(BigDecimal height) {
    this.height = height;
  }

  public String getLastName() {
    return lastName;
  }

  public void setLastName(String lastName) {
    this.lastName = lastName;
  }

  public BigDecimal getWeight() {
    return weight;
  }

  public void setWeight(BigDecimal weight) {
    this.weight = weight;
  }
}

Listing 10 : Person.java

Hopefully, this short example will prove useful for those starting out with JAXB and OXM. For those already familiar with JAXB and OXM, perhaps it has shown you how you can use JAXB without annotations.

Note: There is a rating embedded within this post, please visit this post to rate it.

Ron Jefferies – Annals of Kate Oneal

John Turner — Wed, 27 Jan 2010 19:56:52 +0000

While I was re-reading JUnit Recipes recently I followed one of the suggested links to Ron Jefferies website on Extreme Programming. Ron provides some really interesting material on his website but one of the things that I really liked was the ‘Annals of Kate Oneal‘.

Anyone who has read one of the Head First series of books will be familiar with a conversational style of writing that introduces concepts progressively through fictitious scenarios. Ron uses a similar approach with the ‘Annals of Kate Oneal’ through which he presents Agile ideas and concepts.

The ‘Annals of Kate Oneal’ are presented in a series of bite size stories centered on Kate Oneal, who is advocating Agile methods to a company that has had difficulty using traditional approaches to software development. As an advocate, Kate is often explaining the advantages of Agile from different perspectives and to different audiences. She also has to deal with the practical aspects of introducing Agile to a company that has no previous exposure, so is often found in the role of a mentor.

I am not going to describe her tales any further but, if you haven’t done so already, I do recommend you visit Ron Jefferies website and read the ‘Annals of Kate Oneal’.

Note: There is a rating embedded within this post, please visit this post to rate it.

Starting out with Spring and Hibernate JPA

John Turner — Thu, 21 Jan 2010 17:06:50 +0000

More often than not, I am brought onto a project after the project initiation phase has been completed. By this stage major decisions regarding the development environment and code organisation have already been made. It would be fairly common that I would refactor and re-organise some of the code and in particular the Hibernate JPA code.

In this post I am going to outline how I prefer to implement and organise the Hibernate JPA code on projects I am involved with (where that option exists). I will also demonstrate how I implement the persistent entity classes, data access objects, associated configuration and unit tests. A fairly typical project would utilise Maven, Spring and Hibernate JPA.

Creating the Maven Project

My preferred project structure consists of a root project containing a model module and persistence module with the persistence module having a dependency on the model module. While this would seem pretty straight forward, one now has to decide if one is going to use annotations or XML configuration for the ORM mapping. The reason I prefer to make this decision now is that it affects the dependencies of the model module.

There are arguments for and against using annotations or XML for ORM (any XRM really) but if no precedent has been set I normally try to avoid using annotations in model classes. This way model classes are very clean and the model module does not have any dependencies on javax.persistence. I was involved in a project using JPA and JAXB annotations in model classes and they became difficult to work with very quickly.

The persistence module really does encapsulate all the information relating to the persistence mechanism with the exception of (some) transactional characteristics which would ordinarily be defined in service classes within a service module. Of course the price you pay for this is having some quite large XML files.

Creating the Persistent Entity Classes

For this example, I am going to use a fairly typical security domain model. A UserToken represents an authorisation token that can be associated to a User or a UserGroup. A UserGroup is a hierarchical data structure and so can be associated with one parent and\or many child UserGroup’s. A UserGroup can be associated with many Users and a User can be associated with many UserGroup’s. A UserGroup inherits UserToken’s from child UserGroup’s and a User inherits UserTokens from associated UserGroup’s.

I hope the explanation along with the entity model diagram has given you a good understanding of the entity classes.

Figure 1 : Entity Model

The entity classes are added to the model module. I am not going to post code listings for the persistent entity classes as I have made all the code available for download.

It is worth highlighting though that all model classes extend a common super class (PersistentEntity) that typically defines identifier and version properties. Depending on the requirements, it may also define properties such as dateCreated, dateLastUpdated, tenancy (for multi-tenanted domains) etc.

Creating the JPA Mapping Configuration

For the sake of clarity, I generally separate the JPA mapping configuration into persistence.xml and persistence-mapping.xml (and persistence-query.xml which we will discuss later) files. I try to use the same persistence.xml configuration in all environments so I move anything that varies into the Spring configuration. This includes the definition of the data source, dialect etc.



    
        META-INF/persistence-mapping.xml
        META-INF/persistence-query.xml

        net.thoughtforge.model.User
        net.thoughtforge.model.UserGroup
        net.thoughtforge.model.UserToken
        net.thoughtforge.model.UserTokenHolder
        net.thoughtforge.model.PersistentEntity

Listing 1 : persistence.xml

The option exists to further seperate the persistence-mapping.xml file into a file for each class as is normal practice for hibernate .hbm files.

As you can see from the applicationContext-persistence.xml file below, the ‘jpaProperties’ property of the entityManagerFactory bean contains all the connection information. If you are not using a JNDI data source in any of your environments it will be sufficient to use a properties file to contain the connection information for each environment. If however some of your environments use a JNDI data source and some do not you will obviously have to use seperate Spring configuration files to specify the connection information.





    
        
            
        
        
            
        
        
        
            
        
        
            
                org.hibernate.dialect.HSQLDialect

              org.hsqldb.jdbcDriver
              
              jdbc:hsqldb:file:target/hsqldb/data
              sa

Listing 2 : applicationContext-persistence.xml

Creating the Data Access Objects

The data access objects (obviously) reside in the persistence module. I have a fairly standard PersistentEntityDao interface from which all data access object interfaces extend.

package net.thoughtforge.dao;

import java.util.List;

import net.thoughtforge.model.PersistentEntity;

public interface PersistentEntityDao {

    Entity findByIndexId(Integer indexId);
    
    List findByNamedQuery(String queryName);
    
    List findByNamedQueryAndParams(String queryName, Object ...params);
    
    Entity findUniqueByNamedQuery(String queryName);
    
    Entity findUniqueByNamedQueryAndParams(String queryName, Object ...params);
    
    Entity merge(Entity persistentEntity);
    
    void refresh(Entity persistentEntity);
    
    void remove(Entity persistentEntity);
    
    void save(Entity persistentEntity);
}

Listing 3 : PersistentEntityDao.java

Specific data access object interfaces would typically then only contain specific finder methods (See UserDao) below:

package net.thoughtforge.dao;

import net.thoughtforge.model.User;

public interface UserDao extends PersistentEntityDao {

    User findByUsername(String username);
}

Listing 4 : UserDao.java

The implementation classes reside in a specific sub-package that is named after the data access mechanism. For example, a JPA implementation has a ‘jpa’ sub-package, a Hibernate implementation has a ‘hibernate’ sub-package and a JDBC implementation has a ‘jdbc’ sub-package. I hate seeing sub-packages named impl; generally I feel that the only time this should happen is if there could only be one implementation of an interface which is clearly not the case for data access objects.

Similar to the data access object interfaces, ORM data access objects extend a common super class that exposes common CRUD functionality.

package net.thoughtforge.dao.jpa;

import java.lang.reflect.ParameterizedType;
import java.util.List;

import net.thoughtforge.dao.PersistentEntityDao;
import net.thoughtforge.model.PersistentEntity;

import org.springframework.orm.jpa.JpaTemplate;

public abstract class PersistentEntityDaoImpl
        implements PersistentEntityDao {

    private Class entityClass;
    
    private JpaTemplate jpaTemplate;
    
    @SuppressWarnings(value="unchecked")
    public PersistentEntityDaoImpl(JpaTemplate jpaTemplate) {
        this.jpaTemplate = jpaTemplate;
        
        ParameterizedType genericSuperclass = (ParameterizedType) getClass().getGenericSuperclass();
        this.entityClass = (Class) genericSuperclass.getActualTypeArguments()[0];
    }

    public final Entity findByIndexId(Integer indexId) {
        return (Entity) jpaTemplate.find(entityClass, indexId);
    }
    
    @SuppressWarnings("unchecked")
    public final List findByNamedQuery(String queryName) {
        return (List) jpaTemplate.findByNamedQuery(queryName);
    }
    
    @SuppressWarnings("unchecked")
    public final List findByNamedQueryAndParams(String queryName, Object ...params) {
        return (List) jpaTemplate.findByNamedQuery(queryName, params);
    }
    
    public final Entity findUniqueByNamedQuery(String queryName) {
        List results = findByNamedQuery(queryName);
        
        if (results.isEmpty()) {
            return null;
        } else {
            return results.get(0);
        }
    }
    
    public final Entity findUniqueByNamedQueryAndParams(String queryName, Object ...params) {
        List results = findByNamedQueryAndParams(queryName, params);
        
        if (results.isEmpty()) {
            return null;
        } else {
            return results.get(0);
        }
    }
    
    public final Entity merge(Entity persistentEntity) {
        return (Entity) jpaTemplate.merge(persistentEntity);
    }

    public final void refresh(Entity persistentEntity) {
        jpaTemplate.refresh(persistentEntity);
    }
    
    public final void remove(Entity persistentEntity) {
        jpaTemplate.remove(persistentEntity);
    }
    
    public final void save(Entity persistentEntity) {
        jpaTemplate.persist(persistentEntity);
    }
}

Listing 5 : PersistentEntityDaoImpl.java

Specific data access object interfaces would typically then only contain specific finder methods (See UserDaoImpl) below:

package net.thoughtforge.dao.jpa;

import net.thoughtforge.dao.UserDao;
import net.thoughtforge.model.User;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.orm.jpa.JpaTemplate;
import org.springframework.stereotype.Repository;
import org.springframework.transaction.annotation.Transactional;

@Repository
public class UserDaoImpl extends PersistentEntityDaoImpl implements UserDao {

    @Autowired
    public UserDaoImpl(JpaTemplate jpaTemplate) {
        super(jpaTemplate);
    }
    
    public User findByUsername(String username) {
        return findUniqueByNamedQueryAndParams("user.findByUsername", username);
    }
}

Listing 6 : UserDaoImpl.java

As you can see, I always use named queries and NEVER hard code SQL into data access objects. The main reasons are that it reduces clutter in the code and maintains all SQL in a single place (persistence-query.xml). While I have not defined any query hints it is worth pointing out that they are almost always present in any meaningful implementation.

It is also good practice to use namespaces for naming queries.





    
        
            from UserGroup
            where name = ?
        
    

        
        
            from UserToken
            where name = ?
        
    
    
        
        
            from User
            where username = ?

Listing 7 : persistence-query.xml

The above code examples should suffice to demonstrate the implementation and organisation of the data access objects. The complete code is available for download.

Testing the Data Access Objects

Spring provides support for writing transactional data access object tests that I always utilise when testing data access objects. Where possible, I use an embedded database to ‘exercise’ my data access objects during testing. By this I mean that at a minimum I test create, update and delete for every type of persistent entity and invoke every find method (and named query). I have only included a sample test which should be enough for the purpose of demonstration.

package net.thoughtforge.dao.jpa;

import junit.framework.Assert;
import net.thoughtforge.dao.UserDao;
import net.thoughtforge.model.User;

import org.junit.Before;
import org.junit.Test;
import org.junit.runner.RunWith;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.test.context.ContextConfiguration;
import org.springframework.test.context.junit4.SpringJUnit4ClassRunner;
import org.springframework.test.context.transaction.TransactionConfiguration;
import org.springframework.transaction.annotation.Transactional;

@RunWith(SpringJUnit4ClassRunner.class)
@ContextConfiguration(locations = {
    "classpath:applicationContext/applicationContext-*.xml"})
@TransactionConfiguration(transactionManager="transactionManager", defaultRollback=true)
@Transactional
public class UserDaoImplTest {

  private static final String FIRST_NAME = "joe";
  
  private static final String LAST_NAME = "bloggs";
  
  private static final String PASSWORD = "password";
  
  private static final String USERNAME = "joe.bloggs";
  
  @Autowired
  private UserDao userDao;
  
  @Before
  public void before() {
    User user = new User();
    user.setFirstName(FIRST_NAME);
    user.setLastName(LAST_NAME);
    user.setPassword(PASSWORD);
    user.setUsername(USERNAME);
    
    userDao.save(user);
  }
  
  @Test
  public void findByUserName() {
    User user = userDao.findByUsername(USERNAME);
    
    Assert.assertNotNull(user);
    Assert.assertEquals(USERNAME, user.getUsername());
  }
}

Listing 8 : UserDaoImplTest.java

I hope that I have given you a good overview of how I implement and organise Hibernate JPA code. There are lots of variations on this approach and none are perfect but I always find this approach a good place to start.

Note: There is a rating embedded within this post, please visit this post to rate it.

Building a Dynamic Tree with JBoss RichFaces and Spring Web Flow

John Turner — Tue, 19 Jan 2010 15:51:54 +0000

Recently I was involved in a project that required a user interface that would facilitate the manipulation of a hierarchical data structure. I was already using JBoss RichFaces so it made perfect sense to utilise the tree and associated components (i.e. recursiveTreeNodesAdaptor and treeNode). The project was also utilising the Spring Framework and Spring Web Flow and these were also incorporated into the eventual solution.

To start with, as any good developer does, I searched for existing solutions to the problem and while I found some useful information I did not find exactly what I was looking for. With this in mind, when I eventually finished the development of the user interface I decided I would share my implementation and hopefully you will find what follows useful.

To allow you to follow along, I have made the source (maven project) available as a download. This way, I do not have to worry about explaining everything in minute detail.

For a preview, you can always build the source, deploy to a server and navigate to http://[server]:[port]/dynamic-tree/spring/flow-main replacing the [server] and [port] with appropriate values.

The Data Structure

For the purpose of demonstrating my implementation, I am going to use a simple organisational hierarchy (as discussed in Martin Fowlers book ‘Analysis Patterns’) as illustrated below:

Figure 1 : Data Structure

This is a very basic hierarchical data structure but it suffices for my purpose. The implementation of this class is also very basic and requires little explanation. To keep things simple, I have not considered the persistence mechanism that was employed.

package prototype.dynamictree.model;

import java.io.Serializable;
import java.util.ArrayList;
import java.util.Collections;
import java.util.List;

import org.springframework.context.annotation.Scope;
import org.springframework.stereotype.Component;

@Component
@Scope("prototype")
public class Organisation implements Serializable {

  private static final long serialVersionUID = -2023156931701914562L;

  private List<Organisation> children;

  private String description;

  private String name;

  private Organisation parent;

  public void addChild(Organisation child) {
    if (child.getParent() == null || !child.getParent().equals(this)) {
      child.setParent(this);
    }

    if (children == null) {
      children = new ArrayList<Organisation>();
    }

    if (!children.contains(child)) {
      children.add(child);
    }
  }

  public void removeChild(Organisation child) {
    if (child.getParent() != null && child.getParent().equals(this)) {
      child.setParent(null);
    }

    if (children != null) {
      children.remove(child);
    }
  }

  public List<Organisation> getChildren() {
    if (children == null) {
      children = new ArrayList<Organisation>();
    }

    return Collections.unmodifiableList(children);
  }

  public String getDescription() {
    return description;
  }

  public void setDescription(String description) {
    this.description = description;
  }

  public String getName() {
    return name;
  }

  public void setName(String name) {
    this.name = name;
  }

  public Organisation getParent() {
    return parent;
  }

  public void setParent(Organisation parent) {
    this.parent = parent;
  }
}

Listing 1 : Organisation.java

Strictly speaking, a Set would have been a more appropriate data structure for the Organisation’s children but I encountered strange behaviour by the tree component if Set was used as opposed to List.

Displaying the Hierarchical Data

As already mentioned, I used Spring Web Flow to manage the UI conversations and binding with the entity model. The first step in the flow creates the root Organisation and sets a default name (Joe Bloggs Inc). The second step is a view step that renders the hierarchical data using the tree component.

Listing 2 : dynamicTree.xhtml

The reason I have used a nested recursiveTreeNodesAdaptor component is that later in the process, I will be associating a different contextMenu component with the root node than other nodes.

Upon executing the flow the following is rendered.

Figure 2 : Rendered View

Creating the Node Selection Listener

In order to manipulate the tree structure, we will need to be able to determine the currently selected node. This is achieved by creating a class to listen for the node selection event and configuring this class to receive the event.

The code for the class is straight forward and the listing is as follows:

package prototype.dynamictree.bean;

import java.io.Serializable;

import org.richfaces.component.html.HtmlTree;
import org.richfaces.event.NodeSelectedEvent;

public class DynamicTree implements Serializable {

  private static final long serialVersionUID = 4935795680279034480L;

  private Object selectedNodeData;

  public void processNodeSelection(NodeSelectedEvent event) {
    HtmlTree tree = ((HtmlTree) event.getComponent());

    selectedNodeData = tree.getRowData();
  }

  public Object getSelectedNodeData() {
    return selectedNodeData;
  }
}

Listing 3 : DynamicTree.java

The method getSelectedNodeData will return the Organisation associated with the selected node.

To configure the class to receive the node selection event (via ajax) the tree component attributes need to be amended as follows:

Listing 4 : dynamicTree.xhtml

Adding Support for Creating Child Nodes

Now that we are being notified of the node selection event we will be able to add child nodes to the tree component. This will achieved by adding 2 context menu components (one for the root node and one for all others) and a modal dialog.

Listing 5 : dynamicTree.xhtml

Figure3 : Context Menu

As you can see, when the user right clicks on a tree node, the appropriate context menu will be displayed. If the user then clicks on ‘Add Child’ the addChild flow transition is invoked (via ajax) which creates a child Organisation object. On return from this ajax call the dynamicTreePanel and addChildModalPanel will be re-rendered before displaying the modal panel.

Figure 4 : Modal Panel

When the user clicks on the Ok button, the modal dialog is hidden and the addChildModalPanelConfirm flow transition is invoked. This transition adds the child Organisation to its parent and again on return from this ajax call the dynamicTreePanel and addChildModalPanel will be re-rendered.

When the user clicks on the Cancel button, the modal dialog is hidden and the addChildModalPanelCancel flow transition is invoked. On return from this ajax call the dynamicTreePanel and addChildModalPanel will be re-rendered.

Figure 5 : Tree with child nodes.

I’m sure the wide awake among you have also noticed the addChildModalPanelRendered property. This property is used to make sure the components that refer to a child Organisation are not rendered if no child organisation exists in the current conversation (i.e. when we are not actually adding a child organisation).

Adding Support for Editing Node Data

Now that we are able to add a child node, it is relatively straight forward to add support for editing a node. To achieve this, we will have to add 2 menu items to the already existing context menus and add another modal dialog.

Listing 6 : dynamicTree.xhtml

As you can see, the context menu’s operate in the same way as before as does the flow transitions and modal dialogs. The main difference here is in the flow transition because rather that create a new child Organisation we are editing an existing one.

It is also worth pointing out the use of the ajaxSingle=”true” attribute on the Cancel commandButton component. The reason this is used is so that the model is not updated during the ajax request.

Adding Support for Removing Child Nodes

Similarly, it is relatively straight forward to add support for removing a child node. To achieve this, we will have to add 2 menu items to the already existing context menus and a transition to the flow step.

What’s Outstanding?

I did notice during this process is that there are some strange happenings that need to be investigated further.

When I use a Set as opposed to a List for the child variable in Organisation.java the tree does not bahave as expected.
When I try to remove the last child node from the root node the tree does not behave as expected

I realise there is some duplication in the above that should be removed but I do hope you have found this useful and look forward to your comments.

Note: There is a rating embedded within this post, please visit this post to rate it.

Practical RichFaces

John Turner — Fri, 08 Jan 2010 17:09:16 +0000

As I had mentioned in a previous post, I recently invested in a couple of books on JBoss RichFaces. Having read and reviewed JBoss RichFaces 3.3 I set about doing the same for the other book, Practical RichFaces.

The book started out giving the same background information on JSF, RichFaces and Ajax4Jsf but in contrast to JBoss RichFaces 3.3 stated that it will not be using JBoss Seam in the example’s which I was happy about. That is of course not a reflection on JBoss Seam but more my desire to read about RichFaces and not the many technologies that might complement it.

In the second chapter, the book suggests installing JBoss Tools and as I have not used this Eclipse plug-in before I decided I would do just that. It then proceeds to work through a small example to verify the Eclipse\JBoss Tools installation. This is done in some detail and would be quite useful if looking at RichFaces for the first time.

Some time is then spent introducing the main RichFaces components that support Ajax functionality, namely , , and . These concepts were covered clearly and concisely with good use of appropriate examples. The remaining a4j components are covered in the chapter that follows.

Having covered the a4j components the book then proceeds to cover the majority of rich components dividing the coverage into input components, output components, data iteration components, selection components and menu components. The coverage of the input components is brief which is to be expected as it would be difficult to add anything to the JBoss RichFaces reference documentation. The coverage of the output components is a little more in-depth than the reference documentation and demonstrates, by example, some nice tips and tricks. The data iteration components, selection components and menu components are covered in roughly the same level of detail as that provided by the reference documentation.

The Scrollable Data Table and Tree are given a chapter of their own which covers the main functionality and usage of these components. As with JBoss RichFaces 3.3 I was disappointed with the level of coverage the Tree component received. This is one of the more complicated components and I would like to have seen more examples of its usage.

The last chapter on skinning is on a par with JBoss RichFaces 3.3 and covers the subject well.

My overall impression was again that I’m not really sure that this book adds anything to the freely available reference documentation but the tutorial style is certainly easier to read. I would recommend this book for someone starting out with RichFaces or for someone wanting to read a book end-to-end to get up to speed quickly. What is really needed for RichFaces is a RichFaces Recipe’s Book which is packed full of real world examples of using rich faces beyond the simple examples available on the RichFaces demo website.

One last comment that I would make on the book is that it got me wondering about the level of proof reading of these books. There are a number of glaring errors that would have been noticed if reviewed by anyone with RichFaces knowledge who reads this book. I think these types of mistakes should not make their way to print.

Note: There is a rating embedded within this post, please visit this post to rate it.

JBoss Rich Faces 3.3

John Turner — Wed, 16 Dec 2009 11:30:54 +0000

I have been developing with JBoss Rich Faces for a couple of years now and recently I decided to invest in a couple of books on the subject to try and obtain a better (more rounded) understanding of the framework. When purchasing books related to frameworks that already have good reference documentation I’m always sceptical that the book will provide additional insight above and beyond the freely available references.

One of the books I purchased was ‘JBoss Rich Faces 3.3′ which I set about reading from cover to cover. As with many of these books, it builds a sample application to demonstrate the use of the framework in a ‘real world’ application. In this instance, an advanced contact manager is developed.

The development of the application is demonstrated using Seam, Facelets, Hibernate JPA and Hibernate Validator which may or may not be desirable for the reader. I personally have no immediate interest in Seam and I found the level of content dedicated to Seam to be excessive. There are a number of books available on Seam and I would have purchased one of those had I wanted to read about Seam. I have used Hibernate JPA extensively and given that JPA is a standardised API it’s inclusion in the examples is welcome (it makes for more realistic examples).

The demonstration application used the AJAX components of Rich Faces extensively and this was one of the areas I wanted to focus on. Each of the AJAX components is discussed in the context of the contact manager application as well as smaller examples. This does a good job of relaying the key characteristics of the component and its attributes. In particular, the book does a reasonably good job of describing how the AJAX support components interact with the JSF lifecycle.

One thing that I would have liked to have seen was a significant working example of using the RichFaces tree components in conjunction with JPA entities. I have been toiling over this myself for some time now.

I’m not really sure that this book add’s anything to the freely available reference documentation but the tutorial style is certainly easier to read, particularly if you want to get up to speed quickly. Reading the reference documentation end-to-end would be as tedious as watching channel 4’s Big Brother dominated summer programming.

Note: There is a rating embedded within this post, please visit this post to rate it.

Building Twitter with Grails

John Turner — Tue, 08 Dec 2009 18:24:19 +0000

I have been hearing good things about Groovy and Grails for quite a while now without really knowing much about either. The aquisition of the company that developed Grails (G2One) by Spring Source in late 2008 has naturally added some weight to the Grails movement. Having grown tired of standing, eyes glazed over, as others discuss the advantages delivered by Grails I decided I would learn more.

One of the more popular demonstrations of Grails is that delivered by Graeme Rocher in which he demonstrates building an application similar to Twitter using Grails. A webinar of this demonstration is available for download from the Spring Source website.

The webinar runs for just over an hour and begins by giving an introduction to Grails, what it is, what it hopes to deliver and how it delivers it. This includes how Grails leverages existing technologies such as Spring, Hibernate, Sitemesh and Groovy. Graeme then gives a brief history of Grails explaining its inception in 2005 through to acquisition by Spring in 2008 before using download metrics to give an indication of the current adoption of Grails (70,000 downloads per month at the end of 2008).

The core of the webinar is focused on the demonstration of building Twitter with Grails. Graeme starts by introducing the Grails command line interface and uses it to build the initial project directory and file structure. He gives an tour of the directory structure explaining what goes where before proceeding to install the Spring Security (acegi) plugin for Grails. The functionality provided by this plugin includes the generation of the authentication domain model, authentication manager and login\registration process (user interface and controllers).

Graeme then demonstrates the creation of additional domain model objects to which he adds associations and constraints. In order to manipulate the additional domain objects, Graeme creates a controller and associated view (.gsp file). This controller and view facilitates posting a tweet and displaying a history of tweets.

Graeme then proceeds to install and demonstrate the use of the Searchable plugin which facilitates searching for domain objects using criteria queries. This also requires overriding the default view of the searchable plugin. The Searchable plugin and associated view modifications allow the user to add people who they are interested in hearing tweets from.

If someone who the current user is interested in adds a tweet, a JMS message is sent to notify them (update their tweet history) that a new tweet has been added. The JMS functionality is delivered via an activemq plugin which is installed through the Grails command line interface.

Graeme then demonstrates exposing the same tweets via RSS and XML using the same controller that handles web requests.

The key features of Grails are specified as:

Plugins to let you rapidly compose an application
Plugins that use convention over configuration
Not only a web framework but an entire platform (JMS support etc.)
Plugins to enable testing (Selenium, Fitness, Code Coverage etc.)
Rich Grails (Flex, GWT, Grails UI\Yahoo UI etc.)
Secure Grails (Spring Security, JSecurity OpenID)
Integrate Grails (Search, Jasper Reports, JMS)

This was a good introduction to Grails, the command line interface, project conventions and the plugin system. It has piqued my interest sufficiently that I will spend a bit more time (when I have it!) progressing through some of the many Grails tutorials.

Note: There is a rating embedded within this post, please visit this post to rate it.