Visualizing package dependencies can be useful for a number of reasons:

• Reverse engineering the architecture of an application when documentation is limited, out-of-date, or non-existent.
• Automatically generating diagrams, saving the time required to draw them manually.
• To understand impacts when doing large-scale refactorings or changing implementations of components.
• To determine how to extract functionality for reuse.
• To support good architecture / design as espoused by Robert C. Martin in his book Agile Software Development, Principles, Patterns, and Practices, such as by eliminating cyclical dependencies or unwanted dependencies.

Here is an example package dependency diagram generated by Graphviz:

The source code provided below that was used to generate this example diagram is available from my Java Examples project on GitHub or as a packaged bundle on my Software page. The code can easily be reused: change the directory of compiled code scanned by JDepend ("dist/classes"), and change the root package used to limit the scope of the diagram ("com.basilv.examples.packagediagram").

package com.basilv.examples.packagediagram;
import java.io.*;
import java.util.*;
import jdepend.framework.*;

public class PackageDiagramCreatorApp {

  public static void main(String[] args) {
    createPackageDependencyDiagram();
    System.exit(0);
  }

  public static void createPackageDependencyDiagram() {
    Collection packages = analyzePackages();
    StringBuilder builder = generateGraph(packages);
    generateImage("packages", builder.toString());
  }

  @SuppressWarnings("unchecked")
  private static Collection analyzePackages() {
    JDepend jdepend = new JDepend();
    try {
      jdepend.addDirectory("dist/classes");
    } catch (IOException e) {
      throw new RuntimeException("Error adding directory for JDepend to analyze.", e);
    }
    Collection packages = jdepend.analyze();
    return packages;
  }

  private static StringBuilder generateGraph(
    Collection packages) {
    StringBuilder builder = new StringBuilder();
    builder.append("digraph packages {").append("\n");
    builder.append("node [shape=box];").append("\n");
    builder.append("rankdir=BT;").append("\n");
    Set drawnDependencies = new HashSet();
    for (JavaPackage javaPackage : packages) {
      String packageNodeName = getGraphVizNodeForPackage(javaPackage);
      if (packageNodeName == null) {
        continue;
      }
      builder.append(packageNodeName).append("\n");

      @SuppressWarnings("unchecked")
      Collection dependencies = javaPackage.getEfferents();

      for (JavaPackage dependency : dependencies) {
        String dependencyNodeName = getGraphVizNodeForPackage(dependency);
        if (dependencyNodeName == null
          || packageNodeName.equals(dependencyNodeName)) {
          continue;
        }
        String dependencyKey = packageNodeName + "->"
          + dependencyNodeName;
        if (drawnDependencies.contains(dependencyKey)) {
          continue;
        }
        builder.append(packageNodeName).append(" -> ").append(
          dependencyNodeName).append(" [weight=4]").append("\n");
        drawnDependencies.add(dependencyKey);
      }
    }
    builder.append("}\n");
    return builder;
  }

  private static String getGraphVizNodeForPackage(
    JavaPackage javaPackage) {

    String rootPackage = "com.basilv.examples.packagediagram";
    String packageName = javaPackage.getName();
    if (!packageName.startsWith(rootPackage)) {
      return null;
    }

    return packageName.replace(".", "_");
  }

  private static void generateImage(String fileName,
    String graphVizDotFormattedGraph) {
    try {
      File graphFile = createFileWithContents(fileName
        + ".txt", graphVizDotFormattedGraph);

      // This requires the Graphviz software to be installed -
      // see http://graphviz.org/
      String imageFileLocation = fileName + ".png";
      Runtime.getRuntime().exec(
        "dot -v -Tpng " + graphFile.getName() + " -o "
          + imageFileLocation);

      System.out.println("Image file available at "
        + new File(imageFileLocation).getAbsolutePath());
    } catch (IOException e) {
      throw new RuntimeException("Error generating image " + fileName, e);
    }
  }

  private static File createFileWithContents(
    String fileName, String graphVizDotFormattedGraph)
    throws IOException {
    File graphFile = new File(fileName);
    FileWriter writer = new FileWriter(graphFile, false);
    try {
      writer.append(graphVizDotFormattedGraph);
    } finally {
      writer.close();
    }
    return graphFile;
  }

}

I was tuning a batch processing application that received XML input data sets, each consisting of thousands of separate input records. The processing logic converted each input record into multiple Hibernate entities – as many as several hundred. This logic required a number of queries to implement - some to load related, preexisting entities, and others to verify consistency with existing data. This queried data would often be needed for multiple input records in the same data set. Based on this, I decided to use a single Hibernate session to process the entire data set, committing after each input record but keeping the session open to be able to make use of cached entities for subsequent processing.

When initial performance tests were carried out, they showed a disturbing trend: the processing time required per input record in the data set increased linearly. This meant that the total time required to process a data set increased exponentially with the size of the set! This is illustrated by the diagrams below.

An analysis of where the time was being spent showed that the majority of the processing logic required only constant time per record. Where was the extra time going? The culprit seemed to be the call to commit the transaction to the database. I knew that even a few hundred database insert/update statements would execute quickly in nearly constant time (databases are built to scale, after all). The actual database commit was equally speedy. Normally by default I assume that network calls will be the source of performance delays. But in this case this assumption appeared to be incorrect.

So what exactly was happening when I committed the Hibernate transaction, before the calls to the database? Hibernate's first step is to perform a flush to write all entities with changes (called dirty entities) to the database via insert/update/delete calls. How exactly does Hibernate determine which entities are dirty? For loaded entities Hibernate uses byte-code instrumentation to add logic to track when entities become dirty. But my scenario involved new entities, for which Hibernate could not work its magic. So on each flush Hibernate scanned the fields of each entity to see if there were changes. A linearly-increasing number of entities naturally led to a linearly-increasing time per flush. To make matters worse, Hibernate's flush algorithm apparently has a performance problem when dealing with cascaded collections, which I was using in my scenario.

The solution to my performance problem was to evict all the entities from the session after committing, thus making all entities detached, and then reattaching to the session the few entities I reused in subsequent processing.

This article is one of a series on Hibernate Tips & Tricks.

• Working with Java 5 Annotations
• Parsing and Generating XML with Java
• Advanced Uses of Java 5 Enums
• A Tale of Bad Exception Handling in Finally Blocks in Java
• Automatically Populating Audit Columns in Hibernate
• Simple XML Parsing using JAXB
• Tips for Using Log4j
• Exposing Mutable Objects as Public Properties
• Understanding Java RMI: A Simple Tutorial
• Java-Based Configuration of Spring Dependency Injection

Code is formatted using a non-standard coding convention to display better on the website. Code is generally written with minimal comments or error-handling: it is intended for educational purposes and not necessarily for production use.

This state of affairs with Spring configuration changed with the introduction of the Spring Java Configuration project, commonly called JavaConfig. JavaConfig provides roughly the same capabilities as Spring's XML-based configuration but uses Java code that is quite compact and readable. I have tried out JavaConfig and I really like it – my unease over XML configuration has been finally laid to rest. Using JavaConfig is fairly simple: you create one or more configuration classes using the conventions expected by JavaConfig, then create an instance of JavaConfigApplicationContext or JavaConfigWebApplicationContext and use it like a regular Spring AppplicationContext.

The most significant decision I think you need to make when using JavaConfig is what approach to use to define dependencies. The approach you choose determines how you go about writing your configuration class. While this decision is not specific to JavaConfig - Spring's standard XML configuration allows for the same set of approaches to be used – the application of each approach using JavaConfig is different. These three approaches to defining dependencies are:

1. Explicit declaration of beans and dependencies.
2. Automatic dependencies via autowiring.
3. Automatic beans via component scanning.

In the remainder of this article I am going to provide examples using JavaConfig for these three approaches and discuss the pros and cons of each. While the examples focus exclusively on one of the approaches at a time you can easily combine all three approaches within a single configuration class. For the sake of clarity, however, I recommend on real projects to choose one approach as the primary method of configuration. The source code listed in this article is provided in the Java Examples project which can be downloaded from the Software page.

All three approaches use the same configuration example. There are two beans to configure, each with an interface and an underlying implementation class. The first bean is ResumeRepository which is a Repository class (aka Data Access Object) that provides CRUD-type operations for the domain object Resume. For this example this repository interface only contains a single method Set<Resume> findAll(). The second bean is CalculatorService, which is a Service class that provides functionality relating to resumes: for this example a single method void validate(Resume). The Java code for these two interfaces and the domain object is provided below:

package com.basilv.examples.spring;
import java.util.Set;

public interface CalculatorService
{
  boolean validate(Resume resume);
}

public interface ResumeRepository
{
  Set<Resume> findAll();
}

public class Resume
{
  public String getName() {
    return name;
  }
  public void setName(String name) {
    this.name = name;
  }

  private String name;
}

The implementation class of CalculatorService is CalculatorServiceImpl which requires (has a dependency on) ResumeRepository. The implementation class of ResumeRepository is HardcodedResumeRepository, which is used for this example rather than a more typical repository implementation to avoid further dependencies on e.g. a DataSource. These implementation classes are the same in terms of logic across the three approaches, but there are configuration differences so the code for these classes will be shown for each approach below.

Explicit Declaration of Beans and Dependencies

The explicit approach requires that all beans and their dependencies be explicitly coded within the configuration class as shown below:

package com.basilv.examples.spring.explicit;

import org.springframework.config.java.annotation.*;
import com.basilv.examples.spring.*;

@Configuration
public class ExplicitConfig
{
  @Bean
  public ResumeRepository resumeRepository() {
    return new HardcodedResumeRepository();
  }

  @Bean
  public CalculatorService calculatorService() {
    return new CalculatorServiceImpl(
      resumeRepository()); // Inject dependency
  }
}

The @Configuration annotation is needed on the class, and each bean definition method must be annotated with @Bean. By default bean names are based on the method names.

The implementation classes HardcodedResumeRepository and CalculatorServiceImpl do not require any special configuration code. Constructor injection was used in CalculatorServiceImpl as it is safer and results in more compact code within the configuration class. The code for these implementation classes is shown below:

package com.basilv.examples.spring.explicit;

import java.util.*;
import com.basilv.examples.spring.*;

public class HardcodedResumeRepository implements ResumeRepository
{
  public Set<Resume> findAll() {
    HashSet<Resume> set = new HashSet<Resume>();
    Resume resume = new Resume();
    resume.setName("Coded, Hard");
    set.add(resume);

    return set;
  }
}

public class CalculatorServiceImpl implements CalculatorService
{
  private ResumeRepository resumeRepository;

  public CalculatorServiceImpl(ResumeRepository resumeRepository) {
    this.resumeRepository = resumeRepository;
  }

  public boolean validate(Resume resume) {
      for (Resume repoResume : resumeRepository.findAll()) {
        if (repoResume.getName().equals(resume.getName())) {
          return true;
        }
      }

      return false;
  }
}

As explained above, using the ExplicitConfig configuration class is quite simple. The unit test shown below demonstrates how it is done.

package com.basilv.examples.spring.explicit;

import static org.junit.Assert.assertFalse;
import static org.junit.Assert.assertNotNull;
import static org.junit.Assert.assertTrue;

import java.util.Set;

import org.junit.*;
import org.springframework.config.java.context.JavaConfigApplicationContext;

import com.basilv.examples.spring.*;

public class ExplicitConfigTest
{
  private JavaConfigApplicationContext context;

  @Before
  public void setUp() {
    context = new JavaConfigApplicationContext(ExplicitConfig.class);
  }

  @Test
  public void repositoryConfig() {

    ResumeRepository resumeRepository = context.getBean(ResumeRepository.class);
    Set<Resume> resumes = resumeRepository.findAll();
    assertNotNull(resumes);
    assertTrue(!resumes.isEmpty());
  }

  @Test
  public void serviceConfig() {

    CalculatorService service = context.getBean(CalculatorService.class);
    assertNotNull(service);

    assertFalse(service.validate(new Resume()));
  }

}

One nice feature of the JavaConfigApplicationContext class is that beans can be retrieved via the getBean method in a type-safe manner with no casting required. The only piece of this code that is specific to this approach is the configuration class used – the other approaches to defining dependencies do not need to change anything else in this test case.

At first glance it may appear that the configuration class with its explicit definitions could be used directly without Spring. That would be correct for this simplistic example. In real-life usage, however, the Spring Framework provides many additional features via its container including bean life-cycle events, bean scope (singleton versus prototype), and aspects such as transactional behavior.

Automatic Dependencies via Autowiring

While the explicit declaration approach described above may look quite reasonable for this simplistic example, in real-life usage the number of dependencies per class can really add up, particularly for Service classes that may require five or more Repository or other Service classes. Instead of manually defining all of these dependencies, Spring allows such dependencies to be inferred using a feature called Autowiring.

Here is how Autowiring works. Dependencies within an implementation class must be flagged with the @Autowired annotation. At bean construction time the Spring container will automatically populate these dependencies by finding a matching bean based on the Java type. (Multiple beans of the same type can be handled through the use of qualifiers or through the @Resource annotation. See the Spring documentation for further details.)

While the Spring XML-based configuration can autowire both constructor and setter injection, Java-based configuration cannot autowire dependencies in constructors when beans are explicitly defined. So for the example the CalculatorServiceImpl class had to be changed to use setter injection. Below is the code for the configuration class and CalculatorServiceImpl - the HardcodedResumeRepository class is unchanged from the explicit declaration approach.

package com.basilv.examples.spring.autowire;

import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.config.java.annotation.*;
import org.springframework.config.java.plugin.context.AnnotationDrivenConfig;
import com.basilv.examples.spring.*;

@Configuration
@AnnotationDrivenConfig // Needed for @Autowire to work
public class AutowireConfig
{

  @Bean
  public ResumeRepository resumeRepository() {
    return new HardcodedResumeRepository();
  }

  @Bean
  public CalculatorService calculatorService() {
    return new CalculatorServiceImpl(); // Do not need to specify dependency.
  }
}

public class CalculatorServiceImpl implements CalculatorService
{
  @Autowired
  private ResumeRepository resumeRepository;

  public boolean validate(Resume resume) {
      for (Resume repoResume : resumeRepository.findAll()) {
        if (repoResume.getName().equals(resume.getName())) {
          return true;
        }
      }

      return false;
  }

  public void setResumeRepository(ResumeRepository resumeRepository) {
    this.resumeRepository = resumeRepository;
  }
}

Automatic Beans via Component Scanning

While the previous approach did reduce the amount of configuration required, each bean still needed to be explicitly defined within the configuration class. This approach eliminates this requirement by enabling Spring to scan for component classes that are automatically configured as beans with dependencies autowired as per the previous approach. Bean implementation classes must be annotated with the annotation @Component or a specialization of this annotation such as @Service or @Repository. The configuration class is then configured to scan one or more packages for these classes. The code below shows the configuration class and the two implementation classes which were revised to add these annotations.

package com.basilv.examples.spring.componentscan;

import java.util.*;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.config.java.annotation.Configuration;
import org.springframework.config.java.plugin.context.*;
import org.springframework.stereotype.*;
import com.basilv.examples.spring.*;

@Configuration
@AnnotationDrivenConfig // Needed for @Autowire to work
@ComponentScan("com.basilv.examples.spring.componentscan")
public class ComponentScanConfig
{
  // No explicit configuration needed
}

@Repository
public class HardcodedResumeRepository implements ResumeRepository
{
  public Set<Resume> findAll() {
    HashSet<Resume> set = new HashSet<Resume>();
    Resume resume = new Resume();
    resume.setName("Coded, Hard");
    set.add(resume);

    return set;
  }
}

@Service
public class CalculatorServiceImpl implements CalculatorService
{
  private ResumeRepository resumeRepository;

  @Autowired
  public CalculatorServiceImpl(ResumeRepository resumeRepository) {
    super();
    this.resumeRepository = resumeRepository;
  }

  public boolean validate(Resume resume) {
      for (Resume repoResume : resumeRepository.findAll()) {
        if (repoResume.getName().equals(resume.getName())) {
          return true;
        }
      }

      return false;
  }
}

The most notable thing about this example is that the configuration class is empty – all bean definitions and dependencies have been inferred via annotations. The CalculatorServiceImpl class is also able to use autowired constructor injection, unlike the previous approach, because the class itself is being instantiated by the Spring container rather than explicitly in our configuration class.

Pros and Cons

There are advantages and disadvantages to each configuration approach. The explicit declaration approach is the easiest to understand, especially for developers unfamiliar with Spring. But this approach is the most work to set up. The approach of autowiring dependencies while explicitly defining beans strikes I believe a nice balance between these two factors. Implementation classes are still explicitly referenced, which I think is important for developers unfamiliar with Spring as otherwise IDEs will report no uses of such classes within the production code base. But all dependency information can be left out. A significant disadvantage with this approach, however, is that constructor injection cannot be autowired. In general I tend to prefer constructor injection, which makes this approach pointless (as constructor dependencies still need to be explicitly defined). The third approach of using component scanning is the most aggressive in minimizing configuration needed – virtually no setup work is required. But I am concerned that this will be much harder to understand for those developers unfamiliar with Spring as a lot of magic is being performed behind the scenes.

Is there a clear winner? I would say no, which is one reason Spring provides for these various configuration options. While I value the ease-of-understanding provided by the first approach, I strongly dislike writing "boilerplate" code, which much of the dependency configuration is, and this pushes me towards the third approach. As per the comment below from Chris Beams, Lead for the Spring JavaConfig project, his recommendation is to use component scanning and not use the hybrid explicit beans + autowiring approach. He also points out that 'external' dependencies, such as data sources, still require explicit configuration.

Despite the questions over the approach to defining dependencies, I am happy with the use of Spring JavaConfig overall. One issue I encountered using Spring JavaConfig is that it is still in beta – it has not had a final 1.0 release yet. I used JavaConfig 1.0.0.M4, which worked fine with Spring 2.5.6 but does not work with Spring 3.0.M2 due to classpath issues. I discovered on the Spring forums that some portion of the JavaConfig functionality with be included in the Spring 3.0 release due out this summer, but it is unclear what is planned for the remaining functionality. See Chris Beam's comment below for more details.

FindBugs is a Java static analysis tool that scans compiled java code for potential defects and bad programming practices. Think of it as the Java compiler on steroids: it operates in roughly the same fashion but reports on a much larger set of errors and warnings. Static analysis makes a great complement to automated unit tests. Unit tests require effort to write, targets a specific piece of code, but can verify application-specific functionality. Static analysis requires no effort to write (beyond initial setup), targets the entire code base, but can only verify general code constructs. At least, that's the theory. How does it work in practice?

FindBugs supports a number of different ways of being used: command line, Swing GUI, integration into automated builds (i.e. via an Ant task and Hudson plugin), and Eclipse plugin. I decided to go with the plugin, and installation was as easy as adding the update site http://findbugs.cs.umd.edu/eclipse and installing it. Well, actually there were two gotchas. First, you need to be running Eclipse version 3.3 or greater for the plugin to work – RAD version 7 will not work. Second, you need to fully restart Eclipse after installing the plugin. I made the mistake of choosing the option to activate the plugin without doing a restart, which left portions of the plugin not working. It also seemed like you must bring up the Bug Explorer and Bug Details views, then restart Eclipse, in order to get those views working properly.

I used the FindBugs manual to get started. I selected my Time Reporter project to be the first guinea pig and ran FindBugs on it. I keep my code well-polished and well-tested with most Eclipse warnings turned on so I was not expecting FindBugs to turn up anything major. As I scanned the relatively small list of issues (under 30), I was surprised to see an actual defect! It actually took me a few moments of staring at it to find the problem. See the screen shot below.

It turned out this same defect occurred elsewhere in the code. FindBugs also identified cases of bad error handling that I would classify as defects: I was improperly ignoring return values from method calls like File.delete() or File.mkdir(). Most of these serious issues were in test code rather than application code, which made me feel a little better (but not much).

I fixed all the issues reported by FindBugs that I agreed with, turned off one FindBugs warning I did not agree with at all, and was then left with a small number of false positives – incorrect warnings about code that was actually correct. My preferred approach to compiler warnings is to have none in the code base. This is based on the fact that if your code base has existing warnings that should be ignored then it becomes very difficult to tell when you write some code that produces a warning that should instead be fixed. People become blind to all warnings if there are always some present. Warnings should be produced as part of the developer's regular process (i.e. writing code) rather than requiring an extra step. It was trivial to configure FindBugs to run automatically, but how to get rid of the unwanted warnings?

Eclipse warnings can be eliminated by using the Java 5 annotation @SuppressWarning, but FindBugs does not appear to support this annotation (or if it does I could not successfully determine what text must be supplied to the annotation to ignore the warning). I found some hints on the web that FindBugs does have the ability to ignore specific warnings, but it appears this feature has only been implemented in the Swing GUI and not in the Eclipse plugin. After further investigation I found a solution. I exported the current set of project warnings to an XML file, and then configured FindBugs to use that XML file as a baseline of warnings to ignore. This causes FindBugs to only report issues not in the baseline, leaving me with an empty list of FindBugs warnings – for now at least.

One annoying limitation of the FindBugs Eclipse plugin is that all configuration can only be done on a per-project basis. Unlike most other Eclipse functionality with global configuration that can be overridden on a per-project basis, FindBugs must be enabled and configured individually for each project. There were a few other wrinkles with the FindBugs Eclipse plugin. My general impression is that the plugin is still in a beta state, lagging behind the functionality offered by the FindBug Swing GUI.

Next I tried including FindBug as part of a continuous integration build running in Hudson. It was fairly easy to configure the Ant build to execute FindBugs on the project: the only snag was needing to allocate more memory for the JVM. Installing and configuring the FindBugs plugin for Hudson was likewise straight-forward, and resulted in a nice set of pages for viewing the trends and details regarding the FindBugs warnings. The big issue came when I wanted to filter out (exclude) all the warnings I did not want to fix. After much investigation and trial and error, I discovered that if I used the FindBug Swing GUI to create an exclude list, I could then configure the ant build to use that list as an exclude filter. Using the filter created by the Eclipse plugin did not seem to work. The FindBugs documentation concerning this was rather poor, but I did see a statement admitting that filter support was a bit messed up across the various FindBugs tools, and it sounds like this area will be targeted for improvement in the next year.

Despite these tooling problems, the ease with which FindBugs finds defects makes it definitely worthwhile to use on all Java projects. When I turned FindBugs loose against the code base of a reasonably-sized production application, it found 5 definite defects, 14 cases that were either potential defects or extremely bad coding style, and many other warnings (I didn't bother to count, but probably over 100) that were worth investigating and often worth fixing.

My conclusion from this is that using FindBugs is definitely worthwhile. I plan to roll it out to all my Java projects and integrate it into the automated builds so that the FindBugs results are also available from the continuous integration server. If you plan to adopt FindBugs then I recommend checking out some FindBugs tutorials. If you want to promote the use of FindBugs to your coworkers or management then I'll point out that FindBugs is a corporate standard at both Google and eBay and eBay reports that "using 2 developers to audit/review FindBugs warnings was 10 times more effective at finding P1 bugs than using two testers" (http://findbugs-tutorials.googlecode.com/files/UFIA-intro.pdf).

What are automated unit tests? They are a type of testing performed by developers to ensure that the code they write works as intended. They are automated: tests are expressed as test code that automatically invokes the code to be tested and verifies that the results of execution match the developer's expectations. The scope of testing is individual units of functionality within the code base, such as a single class or method.

This tutorial is oriented towards beginners and therefore is prescriptive. It provides a single step-by-step method for setting up and writing unit tests, usually without explaining the reasons behind why a particular method was used or what some alternative options may be.

This tutorial assumes you already have a Java project with some code (maybe only a single class) set up in the Eclipse IDE. As you go through the tutorial, you should apply the instructions to your project. The tutorial uses a sample project called UnitTestingTutorial to provide concrete examples when appropriate. Use the link below to download this project.

Download the Unit Testing Tutorial Example Project v1.0

This tutorial is divided into a number of sections, each of which is presented as a separate page:

• Section 1: Initial Setup: How to install JUnit and configure your Java project to use it.
• Section 2: Write Your First Unit Test: Create your first automated unit test by writing test code using JUnit and watch the test pass.

I plan to add additional sections to this tutorial over time. If there is particular content you are interested in let me know in the comments below.

Next: Section 1: Initial Setup

Using Resume Calculator

Resume Calculator is a Java program that is executed on the command-line. A sample resume file is listed below:

<?xml version="1.0" encoding="UTF-8"?>
<resume name="Foo Bar">
  <entries>
    <entry id="1" summary="Zoo Project" interval="2006-2007"/>
    <entry id="2" summary="Team Yak" interval="May, 2007 - Present"/>
    <entry id="Baz Project" summary="Team Lead for Baz" interval="Jan, 2008 - Mar, 2008"/>
  </entries>
</resume>

Executing Resume Calculator against this file to calculate the duration of entries "1" and "Baz Project" produces the following output:

Resume Calculator
Copyright 2008 by Basil Vandegriend.  All rights reserved.

Executed on: 8-Dec-2008 6:29:45 AM
Working directory: C:\Dev\Java\ResumeCalculator\dist\release\example

Using resume "C:\Dev\Java\ResumeCalculator\dist\release\example\sampleResume.xml".
Calculating for "Foo Bar" the duration of the resume entries:
1: Zoo Project
Baz Project: Team Lead for Baz
Duration is 14.0 months or 1.2 years.

Finished execution successfully.

More details on how to use Resume Calculator and the full format of the XML file are specified in the user manual included with the distribution.

Technical Details

Resume Calculator uses JAXB for parsing XML (which I just wrote about). I used the Joda Time library for manipulating dates – it is far superior to the standard Java classes. The Joda library, however, does not include logic for calculating the duration of multiple intervals of time so I had to code that functionality myself. This proved to be an interesting algorithm to write – thank goodness for unit tests. The source code for Resume Calculator is included in the distribution if you want to learn more.

I had already looked at JAXB, but was turned off by the apparent requirement to generate the Java classes from a XML Schema definition of the XML format - I already had my Java POJOs and did not want to be bothered to write a schema definition. It turns out that JAXB does support my use case. The online documentation, unfortunately, seems strongly biased towards web services developers who more than likely do start with a schema definition, and possibly even have tooling that hides the use of JAXB entirely. I was also misled by older documentation referring to JAXB version 1, which does not support annotations and generates (from the schema) very ugly code that is difficult to maintain. This was fixed in JAXB version 2, which does support the use of annotations (and incidentally generates much cleaner code).

Using that article as inspiration, I wrote a helper class for parsing XML into objects and vice-versa. The code for this helper class is shown below:

// Copyright 2008 by Basil Vandegriend.  All rights reserved.

package com.basilv.examples.jaxb;

import java.io.Reader;
import java.io.Writer;
import java.net.URL;
import java.util.ArrayList;
import java.util.List;

import javax.xml.bind.*;

import org.w3c.dom.Node;

/**
 * Tools for working with the JAXB (XML Binding) library.
 */
public class XmlBindingTools
{
  /**
   * Parse the XML supplied by the reader into the
   * corresponding tree of Java objects.
   *
   * @param reader Cannot be null. The source of the XML.
   * @param rootElementClass Cannot be null. The type of the
   *        root element.
   * @return the Java object that is the root of the tree,
   *         of type rootElement.
   * @throws JAXBException if an error occurs parsing the
   *         XML.
   */
  @SuppressWarnings("unchecked")
  public static <E extends Object> E parseXML(
    Reader reader, Class<E> rootElementClass)
    throws JAXBException {

    if (rootElementClass == null)
      throw new IllegalArgumentException("rootElementClass is null");
    if (reader == null)
      throw new IllegalArgumentException("reader is null");

    JAXBContext context = JAXBContext.newInstance(rootElementClass);
    Unmarshaller unmarshaller = context.createUnmarshaller();

    CollectingValidationEventHandler handler =
      new CollectingValidationEventHandler();
    unmarshaller.setEventHandler(handler);

    E object = (E) unmarshaller.unmarshal(reader);
    if (!handler.getMessages().isEmpty()) {
      String errorMessage = "XML parse errors:";
      for (String message : handler.getMessages()) {
        errorMessage += "\n" + message;
      }
      throw new JAXBException(errorMessage);
    }

    return object;
  }

  /**
   * Generate XML using the supplied root element as the
   * root of the object tree and write the resulting XML to
   * the specified writer
   *
   * @param rootElement Cannot be null.
   * @param writer Cannot be null.
   * @throws JAXBException
   */
  public static void generateXML(Object rootElement,
    Writer writer) throws JAXBException {

    if (rootElement == null)
      throw new IllegalArgumentException("rootElement is null");
    if (writer == null)
      throw new IllegalArgumentException("writer is null");

    JAXBContext context = JAXBContext.newInstance(rootElement.getClass());
    Marshaller marshaller = context.createMarshaller();
    marshaller.setProperty(
      Marshaller.JAXB_FORMATTED_OUTPUT, Boolean.TRUE);
    marshaller.marshal(rootElement, writer);
  }

  private static class CollectingValidationEventHandler
    implements ValidationEventHandler
  {
    private List<String> messages = new ArrayList<String>();

    public List<String> getMessages() {
      return messages;
    }

    public boolean handleEvent(ValidationEvent event) {
      if (event == null)
        throw new IllegalArgumentException("event is null");

      // calculate the severity prefix and return value
      String severity = null;
      boolean continueParsing = false;
      switch (event.getSeverity()) {
        case ValidationEvent.WARNING:
          severity = "Warning";
          continueParsing = true; // continue after warnings
          break;
        case ValidationEvent.ERROR:
          severity = "Error";
          continueParsing = true; // terminate after errors
          break;
        case ValidationEvent.FATAL_ERROR:
          severity = "Fatal error";
          continueParsing = false; // terminate after fatal errors
          break;
        default:
          assert false : "Unknown severity.";
      }

      String location = getLocationDescription(event);
      String message = severity + " parsing " + location
        + " due to " + event.getMessage();
      messages.add(message);

      return continueParsing;
    }

    private String getLocationDescription(ValidationEvent event) {
      ValidationEventLocator locator = event.getLocator();
      if (locator == null) {
        return "XML with location unavailable";
      }

      StringBuffer msg = new StringBuffer();
      URL url = locator.getURL();
      Object obj = locator.getObject();
      Node node = locator.getNode();
      int line = locator.getLineNumber();

      if (url != null || line != -1) {
        msg.append("line " + line);
        if (url != null) msg.append(" of " + url);
      } else if (obj != null) {
        msg.append(" obj: " + obj.toString());
      } else if (node != null) {
        msg.append(" node: " + node.toString());
      }

      return msg.toString();
    }
  }
}

One important refinement I made to the code was to add better error handling. Parser warnings and errors are collected along with location information (such as line numbers) and the caller notified via an exception. This was necessary because the JAXB default error handling simply wrote messages to the console and reported nothing back to the caller. Due to my basic needs, I simply collected these errors and warnings into string messages. If your error-handling requirements are more sophisticated then you can collect the errors and warnings into proper objects that are returned back to the caller, who can then traverse the information and decide how to report it.

The unit test for this helper class is shown below. It includes a utility class with JAXB annotations to map it to XML that the tests use to exercise the functionality of the helper class. The last test exercises (in a trivial way) the additional error-handling functionality.

// Copyright 2008 by Basil Vandegriend.  All rights reserved.

package com.basilv.examples.jaxb;

import static org.junit.Assert.*;

import java.io.StringReader;
import java.io.StringWriter;

import javax.xml.bind.JAXBException;
import javax.xml.bind.annotation.XmlAttribute;
import javax.xml.bind.annotation.XmlRootElement;

import org.junit.Test;

public class XmlBindingToolsTest
{
  @XmlRootElement(name = "xmltest")
  static class XmlTest
  {
    private String id;

    @XmlAttribute
    public String getId() {
      return id;
    }

    public void setId(String id) {
      this.id = id;
    }

  }

  @Test
  public void parseXml() throws Exception {

    String xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
      + "<xmltest id=\"test\"/>";

    StringReader reader = new StringReader(xml);
    XmlTest xmlTest = XmlBindingTools.parseXML(reader,
      XmlTest.class);
    assertNotNull(xmlTest);
    assertEquals("test", xmlTest.getId());
  }

  @Test
  public void generateXml() throws Exception {
    XmlTest xmlTest = new XmlTest();
    xmlTest.setId("test");
    StringWriter writer = new StringWriter();
    XmlBindingTools.generateXML(xmlTest, writer);
    assertEquals(
      "<?xml version=\"1.0\" encoding=\"UTF-8\" "
        + "standalone=\"yes\"?>\n<xmltest id=\"test\"/>\n",
      writer.getBuffer().toString());
  }

  @Test
  public void parseInvalidXml() throws Exception {

    String xml = "<?xml version=\"1.0\" encoding=\"UTF-8\"?>\n"
      + "<xmltest id=\"test\"><fake/></xmltest>";

    StringReader reader = new StringReader(xml);
    try {
      XmlBindingTools.parseXML(reader, XmlTest.class);
      fail("Expected Exception");
    } catch (JAXBException e) {
      // Expected case.
    }
  }

}

I did encounter some surprises when using JAXB. JAXB imposes a number of coding limitations on the mapped POJOs which are actually quite similar to Hibernate, but not documented as well. So as a general guideline, use Hibernate's restrictions and you will probably do okay. One limitation I encountered involved handling a parent-child relationship between two mapped entities. The parent class will need to have a collection of child entities. The getter method to return the collection must return the actual collection used by the class and not a copy or wrapper: JAXB appears to add children to the parent by calling the add() method on the collection returned by the getter. (See this article for why you might want to return a copy of the underlying collection.)

JAXB shares more than just limitations with Hibernate. Many of the mapping capabilities offered by Hibernate have analogues in JAXB. JAXB can map both fields and methods, either of which may be private. JAXB also supports mapping to custom types using the @XmlJavaTypeAdapter annotation.

Despite the limitations and surprises I ran into, I was generally pleased with JAXB. It met my original goal of providing simple parsing of XML into Java POJOs using annotations to specify the mapping. My biggest disappointment with JAXB was the poor documentation. In fact, for all but trivial parsing tasks, I would recommend writing a XML Schema definition and generating the POJOs instead of doing what I did - the documentation just does not support the approach I took.

The source code listed in this article is provided in the Java Examples project which can be downloaded from the Software page.

An immutable class (or object) is one whose state cannot be changed once the instance is constructed. Mutable objects do allow state changes, typically via setter methods.

Below is an example of such a mutable class:

import java.util.Calendar;

public class Order
{
  private Calendar date = Calendar.getInstance();

  public Calendar getDate() {
    return date;
  }

  public void setDate(Calendar calendar) {
    this.date = calendar;
  }
}

The public property date uses Calendar as its type. Calendar is itself a mutable class – it has methods such as setters that modify the state of the class. So what is the issue? Consider the following code:

  public static void exampleOne(Order order) {
    Calendar cal = order.getDate();
    // Is order past due?
    cal.add(Calendar.DAY_OF_YEAR, -10);
    if (cal.before(Calendar.getInstance())) {
      // Order past due logic...
    }
  }

Can you spot the problem? I must admit that I failed to notice anything wrong at first glance. Here is the same example instrumented with print statements. Can you predict what will happen when you run it?

import java.text.DateFormat;
import java.util.*;

public class ExampleTwo
{
  public static void exampleTwo(Order order) {
    print("Original order date = "
      + convertToText(order.getDate()));
    Calendar cal = order.getDate();

    // Is order past due?
    cal.add(Calendar.DAY_OF_YEAR, -10);
    if (cal.before(Calendar.getInstance())) {
      // Order past due logic...
    }
    print("Ending order date = "
      + convertToText(order.getDate()));
  }

  private static void print(String message) {
    System.out.println(message);
  }

  private static String convertToText(Calendar calendar) {
    return DateFormat.getDateInstance().format(
      new Date(calendar.getTimeInMillis()));
  }

  public static void main(String[] args) {
    Order order = new Order();
    exampleTwo(order);
  }
}

Below is the console output from executing this code:

Original order date = 8-Aug-2008
Ending order date = 29-Jul-2008

This clearly shows the problem: the date contained in the Order instance is changed within the exampleTwo method, which is likely incorrect behavior. The trap for a developer using the Order class (i.e. to write exampleTwo()) is that they would not necessarily consider or realize that changing the Calendar object returned by order.getDate() would change the value within the instance. The Order class is correct (no defects) but the implementation is unsafe because a mutable object is returned from the getter. How can this be addressed?

One solution for this particular example is to take the order-past-due check and turn it into a method on the Order class that does not change the date. While I would likely employ this solution, it unfortunately does not address the underlying issue. Even if the getDate() method is removed, the underlying problem can occur with the setDate() method. The following example demonstrates this:

import java.text.DateFormat;
import java.util.*;

public class ExampleThree
{
  public static void exampleThree() {
    Calendar calendar = Calendar.getInstance();
    Order firstOrder = new Order();
    Order secondOrder = new Order();
    firstOrder.setDate(calendar);

    calendar.add(Calendar.DAY_OF_YEAR, 10);
    secondOrder.setDate(calendar);

    print("First date = "
      + convertToText(firstOrder.getDate()));
    print("Second date = "
      + convertToText(secondOrder.getDate()));
  }

  private static void print(String message) {
    System.out.println(message);
  }

  private static String convertToText(Calendar calendar) {
    return DateFormat.getDateInstance().format(
      new Date(calendar.getTimeInMillis()));
  }

  public static void main(String[] args) {
    exampleThree();
  }
}

The console output is:

First date = 19-Aug-2008
Second date = 19-Aug-2008

The same instance of Calendar is added to both Order instances, so when the calendar's date value is changed for assignment to the secondOrder instance, it also changes within the firstOrder instance. This is likely incorrect behavior which occurs because the setter directly stores the provided mutable object. So we end up with two references to Calendar in each of the Order instances that point to the same instance. This is called aliasing.

By now you are perhaps convinced that getters and setters should never deal with mutable objects. It is unfortunately not that simple. Consider the following example:

public class Order
{
  private Customer customer;

  public Customer getCustomer() {
    return customer;
  }

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

public class Customer
{
  private String name;

  public String getName() {
    return name;
  }

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

public class ExampleFour
{
  public static void exampleFour(Order order) {

    print("Original order customer name = "
      + order.getCustomer().getName());

    String newName = "New name";
    Customer customer = order.getCustomer();
    customer.setName(newName);

    print("Final order customer name = "
      + order.getCustomer().getName());
  }

  private static void print(String message) {
    System.out.println(message);
  }

  public static void main(String[] args) {
    Customer customer = new Customer();
    customer.setName("Starting name");
    Order order = new Order();
    order.setCustomer(customer);
    exampleFour(order);
  }
}

The console output is:

Original order customer name = Starting name
Final order customer name = New name

In this case it seems perfectly reasonable to update the customer's name and have this change remembered within the Order instance. Before I explain the difference between these scenarios, I will show one more example involving a collection property:

import java.util.*;

public class Order
{
  private Customer customer;

  public Customer getCustomer() {
    return customer;
  }

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

public class Customer
{
  private List orders = new ArrayList();

  public List getOrders() {
    return orders;
  }

  public void addOrder(Order order) {
    if (order == null) {
      return;
    }
    orders.add(order);
    order.setCustomer(this);
  }
}

In this case, calling customer.getOrders().add(order) might seem reasonable but is not correct as this will not invoke the extra logic in customer.addOrder(order) to call order.setCustomer().

The following table summarizes the above discussion.

Given that the code for the Calendar property compared to the Customer property is basically identical, why should we have different expectations of their behavior? The reason has to do with the nature of the two types. Calendar is a Value Object - a simple object whose equality is based on its value rather than its identity. Changing a calendar means ending up with a new date that is not equal to the original. Customer is a Reference Object – an object with business meaning whose identity is the basis for equality. Two customers can have the same values but be distinct. Changing a customer is just that – a change to that customer that should propagate throughout the system. For a fuller discussion of value objects see page 486 of the book Patterns of Enterprise Application Architecture by Martin Fowler. This discussion includes a short section on the risk of encountering aliasing defects if a value object is mutable and recommends that they be immutable.

I agree with this recommendation and I think it should be a design principle for classes: class properties that are value objects should be immutable. Many typical value object types in Java such as String and Long are already immutable, but we have already seen that others such as Calendar and List are not. What are the options in such circumstances? I will address this question in a future article.

The source code listed in this article is provided in the Java Examples project which can be downloaded from the Software page.

Using existing annotations is fairly easy - an annotation is prefixed with '@' and optionally suffixed with one or more arguments of the form (<single-arg-value>) or (<arg1=value1>, <arg2=value2>, ...). The annotation is added immediately before the Java code element being annotated. Below is an example using two of the standard annotations defined in Java 5 (@Override and @SuppressWarnings):

package com.basilv.examples.annotations;

import java.util.ArrayList;

@SuppressWarnings("unchecked")
public class AnnotationUsage
{
  public void doStuff() {
    ArrayList list = new ArrayList();
    list.add("");
  }

  @Override
  public String toString() {
    return "AnnotationUsage";
  }
}

Defining a new annotation is a little more complicated. While an annotation is conceptually fairly similar to a Java interface - it has a name and a set of properties - the syntax for defining an annotation is, unfortunately, somewhat different from the syntax used to define an interface. This is best explained with an example:

package com.basilv.examples.annotations;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)
@Target( {ElementType.TYPE, ElementType.METHOD })
public @interface MyAnnotation {
  int myProperty();
  String myPropertyWithDefault() default "";
}

The @interface syntax is bizarre - I mentally convert it to annotation - i.e. public annotation MyAnnotation. (I am not sure why Sun did not go with this more intuitive syntax, but I assume they did not want to create another reserved keyword for compatibility reasons - a weak reason considering that they added the assert keyword in v1.4 and the enum keyword in v5.) The declaration of individual properties is similar to the declaration of methods in interfaces except for the optional default clause that can be supplied. If no default is supplied then a value for the property must be supplied when using the annotation.

Annotations with no properties are allowed and are called marker annotations. Annotations with a single property by convention name the property value(), which allows the annotation property value to be declared without the name of the property: i.e. @Annotation("value").

The other interesting quirk is that Java annotations (@Retention and @Target) are used when declaring an annotation. The @Retention annotation defines how the metadata for uses of this annotation is retained via the RetentionPolicy enum. The default is RetentionPolicy.CLASS, which stores the metadata in the compiled class file but does not necessarily load it at runtime. I think the default should have been RetentionPolicy.RUNTIME, which ensures that the Java VM will load the metadata and make it available at runtime. When coding my first annotation I forgot to specify the runtime retention policy. This leads to the puzzling error of not being able to retrieve at runtime the metadata on the classes using the annotation, with no indication of what was wrong. The @Target annotation specifies the Java code elements that this annotation can be applied to.

Annotation metadata is only useful if we can retrieve and act on it. The Reflections API in Java 5 was augmented with methods to retrieve annotation metadata for java code elements such as classes and methods. These annotation related methods are defined by a common interface java.lang.reflect.AnnotatedElement. Examples include boolean isAnnotationPresent(Class) and T getAnnotation(Class).

The following example shows a somewhat-realistic example of an annotation being used. I define an annotation to map URLs to methods on a class, and then implement a servlet to delegate requests to the appropriate method using this metadata. First the definition of the annotation:

package com.basilv.examples.annotations;

import java.lang.annotation.*;

@Retention(RetentionPolicy.RUNTIME)// or source or compile
@Target( { ElementType.TYPE, ElementType.METHOD })
public @interface WebAction {
  String url();
}

Now the class which uses this annotation to map URLs to particular methods:

package com.basilv.examples.annotations;

import javax.servlet.http.*;

public class ActionExecutor
{
  private HttpServletRequest request;
  private HttpServletResponse response;

  public ActionExecutor(HttpServletRequest request,
    HttpServletResponse response) {
    this.request = request;
    this.response = response;
  }

  private void setMessage(String message) {
    request.setAttribute("message", message);
  }

  @WebAction(url = "/test")
  public void doTest() {
    // Set a message for demo purposes. Normally execute some logic.
    setMessage("test");
  }

  @WebAction(url = "/submit")
  public void submitWork() {
    // Set a message for demo purposes. Normally execute some logic.
    setMessage("submit");
  }
}

Now the servlet to handle requests by executing the appropriate method on ActionExecutor:

package com.basilv.examples.annotations;

import java.io.IOException;
import java.lang.reflect.Method;
import javax.servlet.*;
import javax.servlet.http.*;

public class DispatchingServlet extends HttpServlet
{
  @Override
  protected void doGet(HttpServletRequest request,
    HttpServletResponse response) throws ServletException,
    IOException {
    response.setContentType("text/html;charset=UTF-8");

    String url = request.getPathInfo();
    ActionExecutor executor = new ActionExecutor(request,
      response);

    boolean actionFound = false;
    for (Method method : ActionExecutor.class.getMethods()) {
      if (method.isAnnotationPresent(WebAction.class)) {
        WebAction action = method.getAnnotation(
          WebAction.class);
        if (url.equals(action.url())) {
          actionFound = true;
          try {
            method.invoke(executor, (Object[]) null);
          } catch (Exception e) {
            throw new RuntimeException(
              "Error invoking method " + method.getName()
                + ".", e);
          }
        }
      }
    }
    if (!actionFound) {
      request.setAttribute("message", "No action found");
    }
    RequestDispatcher rd = request
      .getRequestDispatcher("/view.jsp");
    rd.forward(request, response);
  }

  @Override
  protected void doPost(HttpServletRequest request,
    HttpServletResponse response) throws ServletException,
    IOException {
    doGet(request, response);
  }
}

There are a number of scenarios for which it would be useful to iterate over all classes with a particular annotation. The above example of the dispatching servlet would be more useful if it could dispatch to methods on any number of classes based on a class-level annotation. The Reflections API, however, does not provide a mechanism for obtaining all classes with a particular annotation. This is difficult functionality to provide for a number of reasons explained by Bill Burke, but since it is so valuable various open source projects such as Spring and JBoss have implemented solutions to this.

The source code listed in this article is provided in the Java Examples project which can be downloaded from the Software page.