“Everyone has different learning styles” says my wife the teacher.  I think this also applies to how we look at code.  I tend to be a big picture person and need to understand the lay of the land before I can dive into the details.  What are the architectural layers? How is the code structured? What are the main components of the application?  One would think this would be obvious across similar domains, but it’s suprisingly not.  When diving into a new codebase it’s often very handy to be able to get a big picture view quickly.  One easy way to do so is with a sequence diagraming tool that can generate a sequence diagram for you.  One such tool is Object Aid.

Object Aid provides two plug-ins for Eclipse: a class diagramming tool and a sequence diagramming tool.  Both can reverse engineer from your code.  The class diagramming tool is free, the sequence diagramming tool is an inexpensive $19 at the time of this writing.  This is the best bang for your UML buck I’ve found.  Register on their site to get a free trial.

Installation is easy, so we’ll skip that and dive right in.

Class Diagrams

Class diagrams are saved as files within any of your Eclipse projects.  They can sit right alongside the code  in your source tree, in a seperate folder in your project or in a separate project on it’s own.  I generally use one of the latter two approaches.  If one keeps a class diagram within a package in the source tree that would indicate to the poor sap maintaining your code that the diagram contains only classes from the package it’s saved in.  That’s not likely to be a very useful or interesting diagram.

Creating a class diagram is a simple matter of creating a new file in Eclipse.  Once done, you can drag any class visible in Eclipse to the diagram.  Associations will automatically displayed between classes that have them.  Tip: in the project explorer or navigator view keep the “sync with editor option” unselected. Otherwise when you start to drag a class that class will become visible in the editor if it happens to be open.

There are lots of visibility options you can explore.  Here’s a sample class diagram:

Sequence diagrams

The fun really starts with sequence diagrams.  This is my secret weapon when I’m looking at a new code base.

Sequence diagrams can be generated from many different sources:

• manually in the diagram by dragging a message from a lifeline, by selecting a method, or dragging a method from the project explorer or navigator views.
• java stack trace console
• debugger stack frames
• dragging methods from the call hierarchy view

The most useful to me is from the debugger.  Quite often one know the entry point to a server call.  From there stepping through the code dives deeper into the code.  Once in the target class it can be tought to see the forest from the trees.  Here’s where the sequence diagram shines.

In a new sequence diagram right-click the debugger stack and select “add to sequence diagram”.  The entire stack frame will be put on the diagram.

On very complex apps, especially those using JEE or Spring there are often quite a lot of layers and proxy classes.  These are not very useful in a sequence diagram.  In the preference one specify filters and filter the unwanted classes from the diagram.

In this post we’ll create a second module for deploying to a servlet container. We’ll call this module example-web and it will produce a WAR artifact for deployment in Tomcat, Jetty, or any other suitable application server.

So lets roll…

Lets review, currently we have our project structured as shown below:

	trunk
		example-core
		example-parent

Now we’ll add one more directory for our web module and our new structure will be so:

	trunk
		example-core
		example-parent
		example-web

Now we’ll need to crack open the settings.Gradle file located in trunk and change it to add the new module.

At this point we can start creating the web module, we’ll start with a simple build file (build.Gradle in the example-web directory) to get it going.

At the top of the file you notice the apply plugin: ‘war’ line. The war plugin is a standard Gradle plugin that is used to create compliant war archives. The war plugin also includes the java plugin so all of those conventions will also be present. The default layout for the source, test and web files is as follows.

	example-web
		src
			main
				java
				resources
				webapp
			test
				java
				resources

All source files are found in the main directory while tests are in tests. Within the main directory the java, resources, and webapp directories hold java source files, non-java resource files and the webapp files (css, html, css, web.xml etc.) respectively.

I’ve built a simple web app that greets the guest when the root of the application is accessed, this builds on the previous post. To do this I needed to add a dependency on the javax servlet API. But, since the official API jar dependency isn’t found in maven central I used the one from the geronimo project. I’ve also added a dependency to the example-core project.

In order to include the project as a dependency I used two lines:

	dependsOn(':example-core')

And

	compile project(':example-core')

The first line is used by Gradle internally to order how projects are built. Without the dependsOn clause Gradle would build them in the order found, usually alphabetical. The second line adds the example-core project to the compile dependencies for example-web. You should always include both of these lines when adding a project as a dependency.

Finally we’ll add the jetty plugin to the example-web build file so we can run the app. The final build file will appear as below.

Now we can start the webapp by issuing the Gradle task

jettyRun

. Here’s the output:

At this point a jetty instance should be running on port 8080 with our application. This link should get you to the front page http://localhost:8080/example-web/. To kill the server issue a Ctrl-C at the command line.

Well that wraps up setting up the web module and if you’d like you can still go back and run example-core. The implementation is still there and works exactly the same as the web version. As usual you can find the project at https://github.com/jhollandus/opiblog, for this post look at the p2 tag. You’ll also note that I’ve added eclipse files to the projects. In the next post I’ll go through how to set that up so you can keep it up to date with the Gradle build files as they change.

Why choose gradle

I’ll assume since you’re here that you have an interest in gradle and may have already scoured the internet for comparisons of it with other popular build tools (Ant and Maven).  Below are some of the reasons why I chose Gradle for my project and not the others.

1. Gradle is built on top of a full fledged programming language (groovy) and has direct access to all of it’s goodies.  No reliance on plugins for custom scripting (Maven, Ant plugin), no overhead of creating custom Java classes or plugins, and finally no angle bracket soup (ant scripting).

2. Gradle out of the box has support for dependency management via Ivy and is compatible with all Maven repositories including enterprise ones (Artifactory, Nexus, etc.).

3. Gradle supports multi-module projects without having to reinvent the wheel (ant).

4. Finally, Gradle is extremely flexible allowing for just about any build configuration you could imagine unlike other build tools (I’m looking at you Maven).

First thing first, install gradle.  There is good online documentation on how this is done here http://gradle.org/installation.

Project Layout

So lets get started with our first project.  For this post lets keep it simple with a single module.  We’ll set it up though with the forethought that we may be adding more modules in the future.

I’ll use a flat layout since this is most compatible with the Eclipse IDE. The project layout will look thusly:

• trunk
  • example-core
  • example-parent

Gradle also allows for a hierarchical layout but I’ve found that Eclipse does not do well with projects that include sub-projects.

The modules are intended to be used in the following manner:

example-core

Contains domain classes, services, and any data access objects.  Really the essence of the whole system.

example-parent

Contains common configuration information for the entire projects (all modules).  This is where our main build.gradle script will be found.

Most of our build configuration will be done  in example-parent with details specific to modules found in the module directories.  The module build files usually contain information on dependencies and artifacts.  They’ll also have custom tasks that are specific to that module. But before we start our build file we need to setup one other piece of information, the settings.gradle file.

settings.gradle

The settings.gradle file is responsible for letting gradle know what modules are part of the project and where they are.  By default Gradle assumes that settings.gradle will be found in the directory in which the build is executed but if it’s not then gradle will look in the parent directory. If still not found in the parent it will continue going up the directory hierarchy until it’s found.  There is one exception though, if there happens to be a directory named ‘master’ then it will look in there also.  This facilitates flat layouts.

Here’s our settings.gradle file found in the trunk directory:

Now with that there we are ready to create our first build script in example-parent.

build.gradle

All default gradle build scripts should be named build.gradle, it’s the name that the gradle command will look for by default when run. Let’s look at our simple build script, I’ll go through the sections afterwards.

Now let’s walk through it.  Remember that this script is really a groovy script with a very detailed and structured DSL, you can do anything in this DSL that you could do in groovy.  An example is the SLF4J_VERSION variable set at the top.  This is a regular old groovy variable and is used later in constructing the dependency strings (using GString replacement).

The group and version propeties set at the top are part of the Project object which is the groovy object that the DSL is delegating to by default.  By setting these properties you tell gradle what group and version this project is and can be used for dependency management.  If this project is pushed into a maven repository it will use these properties as part of the pom.xml.

Next is the allprojects block which is part of the DSL. This block will apply all configurations found in the block to each module in the project. For this example that would be example-parent and example-core. You are free to do any configuration you care to here as if this was a single module project.

Inside the allprojects block is the repositories block.  This block is used to configure what repositories will be used to locate dependencies. Here I have used a convenient method to include the maven central repository.  Gradle supports all kinds of different repositories from maven and ivy to even a  file system. It is extremely flexible. In a previous project I was on we stored all of our dependenies in source control inside a subdirectory found in our project and Gradle used that as it’s repository.

The subprojects block is used to configure all projects except for the root project. Generally the root project does not produce any artifacts therefore won’t have a need for many configuration parts. Here we set up a couple of configurations.

Configurations are used to store sets of dependencies and files.  In this example I’ve created two common configurations for common test dependencies and common compile dependencies later on we’ll use these in our other modules.

The dependencies block is where all dependencies for this project are declared.  A dependency needs to be added to a configuration, here I’ve added JUnit to the commonTest configuration and slf4j with log4j to the common configuration. You’ll notice that the dependencies are declared using a string.  Gradle supports a few different ways of doing this along with methods for excluding transitive dependencies but I didn’t do that here. The pattern I’m following is ‘group:name:version’.

example-core build.gradle

The example-core project is going to be a simple java project with one main file that prints out “Hello World” (I know, I know). We’ll set this up so it can be run from the command line using gradle. We’ll also make it so we can create an archive for deployment, therefore everyone can enjoy our genius easily.

Here’s the build.gradle file found in example-core:

Besides the code for the HelloWorld class this is all you need to set it up.  If you look at the top of the script you may notice the ‘apply plugin:’ stanza.  This imports a plugin into this script and applies its conventions to the build.  In this case it also imports the java plugin as part of it.  You can apply as many plugins as you like and you can also use plugins that are imported from any URL (file, http, etc.), the application plugin is built into gradle by default.

I then set the version of this module. The group is inherited from the root project so we don’t need to set it here also, in fact the version was too but I overrode it.

For configurations I merely extended the compile and compileTest configurations to include the ones we set up in example-parent.  You may be asking yourself where compileTest and compile came from.  Well, those were brought in via the apply plugin statement. They are standard configurations used by the java plugin.

For this example I don’t require any additional dependencies so I left it empty for display purposes. In real use you would omit it all together.

Finally, I set the mainClassName property to the fully qualified name of the class that I want to be executed when this application is run. This property was added by the application plugin.

Performing a Build

Now we are ready to perform a build.  I’ve skipped the part were we actually write the code but you can get it at github (https://github.com/jhollandus/opiblog), look at the p1 tag for this post.

First, open a command shell (cmd, bash, etc.) and change to the example-core directory.  From there execute this command:

gradle build

You should see gradle startup and then echo out the different parts of the build lifecycle it’s going through.  In this case we don’t have any unit tests so that’ll go quickly but the java plugin brings in an entire build cycle that includes a test phase. The output should resemble this:

jholland-mac:example-core jholland$ gradle build
:example-core:compileJava
Download http://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.6.4/slf4j-api-1.6.4.pom
Download http://repo1.maven.org/maven2/org/slf4j/slf4j-parent/1.6.4/slf4j-parent-1.6.4.pom
Download http://repo1.maven.org/maven2/org/slf4j/slf4j-log4j12/1.6.4/slf4j-log4j12-1.6.4.pom
Download http://repo1.maven.org/maven2/log4j/log4j/1.2.14/log4j-1.2.14.pom
Download http://repo1.maven.org/maven2/log4j/log4j/1.2.16/log4j-1.2.16.pom
Download http://repo1.maven.org/maven2/org/slf4j/slf4j-api/1.6.4/slf4j-api-1.6.4.jar
Download http://repo1.maven.org/maven2/org/slf4j/slf4j-log4j12/1.6.4/slf4j-log4j12-1.6.4.jar
Download http://repo1.maven.org/maven2/log4j/log4j/1.2.16/log4j-1.2.16.jar
:example-core:processResources
:example-core:classes
:example-core:jar
:example-core:assemble
:example-core:compileTestJava UP-TO-DATE
:example-core:processTestResources UP-TO-DATE
:example-core:testClasses UP-TO-DATE
:example-core:test
Download http://repo1.maven.org/maven2/junit/junit/4.8.2/junit-4.8.2.pom
Download http://repo1.maven.org/maven2/junit/junit/4.8.2/junit-4.8.2.jar
:example-core:check
:example-core:build

BUILD SUCCESSFUL

Total time: 5.031 secs
jholland-mac:example-core jholland$

As you can see Gradle downloaded the necessary dependencies and then compiled the code. If you build again you’ll find that it won’t download the dependencies again and it won’t recompile your code. Gradle fully supports incremental builds and will only process files that have changed.

Now if you run ‘gradle run’ it will execute our main class. You should see the following output, note that the logging is currently also going to stdout.

jholland-mac:example-core jholland$ gradle run
:example-core:compileJava UP-TO-DATE
:example-core:processResources UP-TO-DATE
:example-core:classes UP-TO-DATE
:example-core:run
21:54:47,089        DEBUG HelloWorld:10 - Executing...
Hello World

BUILD SUCCESSFUL

Total time: 2.736 secs
jholland-mac:example-core jholland$

Finally if you run ‘gradle distZip’ Gradle will produce a deployable zip file that you can use to execute the program. You can find the zip archive example-core-1.0-SNAPSHOT.zip in the build/distributions directory. The distZip and run tasks are a part of the application plugin.

And that about all for now.  In the next post I’ll create an additional module to show how multi module builds work. In the meantime check out the Gradle documentation online at http://gradle.org/documentation

A little background: Spring 3.0 brought the Converter and Formatter framework with a concise @DateTimeFormat annotation, simplifying the Date to Object conversion that previously took custom binders or other wiring code. With @DateTimeFormat you can easily supply a String pattern used to parse and print a Date (or joda DateTime) object. However, the annotation does not strictly validate the String before converting to a Date. For instance, supplying a MM/dd/yyyy pattern does NOT enforce a 4 digit year. Instead a 2 digit year will be accepted and parsed using the SimpleDateFormat rules. Similar loose checking goes for 1 digit days and months, and also the slash character used as a separator. It would be easy to just throw the @Pattern tag onto your Date field except that @Pattern is only allowed on String fields. Combining @Pattern and @DateTimeFormat is what drove the creation of @StrictDateTimeFormat:

//sample usage using defaults for regex and pattern
@StrictDateTimeFormat
private DateTime birthday;

Read more below for a discussion and snippets of code, and the entire codeset with comments is available on github.

The RegexParserDecorator: The first step is to create a Regex Parser class that will apply a regex pattern to validate a String for us. Creating this as a Decorator gives the added benefit that you can easily wrap any Spring Formatter to apply Regex patterns. The constructor takes a Parser to wrap and a regex to apply; and the parse method first validates against the regex before passing onto the decorated Parser:

public RegexParserDecorator(Parser parser, String regex) {
	this.parser = parser;
	this.regexPattern = Pattern.compile(regex);
}
public T parse(String text, Locale locale) throws ParseException {
	if (!regexPattern.matcher(text).matches()) {
		throw new IllegalArgumentException("Text does not match regex: " + text);
	}
	return parser.parse(text, locale);
}

The @StrictDateTimeFormat Annotation: Next step is to setup the annotation interface class. It is very similar to DateTimeFormat but adds the field to hold a regex. The default regex allows 1 or 2 digit days and months, requires a forward slash as the separator, and enforces a 4 digit year. This can be easily overriden when applying the annotation to a field by supplying your own (regex=”", pattern=”") extension. A pattern is still required so make sure your pattern and regex are paired appropriately.

@Target({ElementType.METHOD, ElementType.FIELD, ElementType.PARAMETER})
@Retention(RetentionPolicy.RUNTIME)
public @interface StrictDateTimeFormat {
    public static final String REGEX_DEFAULT = "^(0?[1-9]|1[012])/(0?[1-9]|[12][0-9]|3[01])/\\d\\d\\d\\d$";
    public static final String PATTERN_DEFAULT = "MM/dd/yyyy";
    String regex() default REGEX_DEFAULT;
    String pattern() default PATTERN_DEFAULT;
}

Spring then requires a StrictDateTimeFormatAnnotationFormatterFactory to wire the annotation with the parser. Nothing fancy here as it borrows heavily upon Spring’s own JodaDateTimeFormatAnnotationFormatterFactory. The getParser method applies our regex to the DateTimeFormat functionality:

public class StrictDateTimeFormatAnnotationFormatterFactory implements
		AnnotationFormatterFactory {
...
	public Parser getParser(StrictDateTimeFormat annotation, Class fieldType) {
		DateTimeParser parser = new DateTimeParser(forPattern(annotation.pattern()));
		return new RegexParserDecorator(parser, annotation.regex());
	}
	private DateTimeFormatter forPattern(String pattern) {
		return org.joda.time.format.DateTimeFormat.forPattern(pattern);
	}
...

Hooking it all together: Here is the snippet from my applicationConfig.xml showing how the annotation is registered into Spring:

<mvc:annotation-driven conversion-service="myConversionService" />
<bean id="myConversionService" class="org.springframework.format.support.FormattingConversionServiceFactoryBean">
	<property name="formatters">
		<list>
			<bean class="jeffsheets.util.format.StrictDateTimeFormatAnnotationFormatterFactory" />
		</list>
	</property>
</bean>

Hopefully this information is helpful in creating a reusable regex validating DateTime formatter for use in your own web application.

Preview

Annotations

One very nice thing Servlet 3.0 brings us is a set of annotations to declare Filters and Servlets and Listeners. With these annotations, the configuration of applications is removed from the web.xml file and put into the application’s JARs and WEB-INF/classes.  This is an exciting feature because it also allows you to package your Servlets,  Filters, and Listeners into JAR files and include them in your web application simply by including the JAR file in the WEB-INF/lib folder of the application. Packaging and fragmenting an application is a topic for another day; let’s just focus on the annotations for the moment.

For those familiar with annotated frameworks such as Spring, it shouldn’t be too difficult to see the benefit of annotating code instead of adding configuration to the web.xml file. There’s the easy spot of “ease,” as it simply doesn’t need to be done. There’s a simple case for “error-proofing” as the annotation should be close enough to the code that it alleviates some of those errors.

Filters

Typically Filters are declared in the web.xml file in the following fashion:

<filter>
  <filter-name>site-filter</filter-name>
  <filter-class>foo.SiteFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>site-filter</filter-name>
  <url-pattern>/*</url-pattern>
</filter-mapping>

It’s a bit of XML just to relate a URL pattern (or few) to a class. Of course, additional information can be provided, including initialization parameters for the filter class. The filter class needs to then implement the javax.servlet.Filter interface, and contain a few methods to satisfy the Filter interface. This doesn’t change much in the Servlet 3.0 annotation scheme.

To use a Servlet 3.0 annotated filter, the class must still implement the Filter interface and contain the methods to satisfy the interface, but rather than all of that XML configuration, the annotation @WebFilter() can be added to the class definition, and its parameters added as attributes to the Filter. Here’s what it takes to replace that block of XML:

@WebFilter( "/*" )
public class SiteFilter implements Filter {
  @Override
  public void destroy() {
  }
  @Override
  public void doFilter(final ServletRequest servletRequest,
                       final ServletResponse servletResponse,
                       final FilterChain filterChain)
         throws IOException, ServletException {
    // Whatever you need to do
    filterChain.doFilter(servletRequest, servletResponse);
  }
  @Override
  public void init(final FilterConfig filterConfig)
         throws ServletException {
  }
}

Of course, as with the XML, additional values can be applied.

@WebFilter(urlPatterns = { "/specific","/url","/patterns.ext" },
           initParams={@WebInitParam(name="something",value="cool")})

The sample above allows our Filter only to match three specific URL patterns (since there’s no wildcard), and adds a cool value to the initialization values.

Including Other Filters

This can also be applied to older Filters that are not annotated. For example, I frequently use the Tuckey UrlRewriteFilter to ensure my application doesn’t throw itself for a loop by adding the session ID to the returned URL. It’s a simple Filter, expressed in some XML included with the application (taken from their examples):

<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE urlrewrite>
<!-- PUBLIC "-//tuckey.org//DTD UrlRewrite 3.2//EN"
"http://tuckey.org/res/dtds/urlrewrite3.2.dtd"-->
<urlrewrite>
  <outbound-rule encodefirst="true">
    <name>Strip URL Session ID's</name>
    <from>^(.*?)(?:\;jsessionid=[^\?#]*)?(\?[^#]*)?(#.*)?$</from>
    <to>$1$2$3</to>
  </outbound-rule>
</urlrewrite>

This strips the jsessionid parameter from any outbound data returned to the browser; this stops the URL from changing to /somepath.ext?jsessionid=breakmenow which can cause relative URLs in the application to end up wrong, like /somepath.ext?jsessionid=breakmenow/images/reallywanted.jpg. To implement this the old way, you’d specify the Filter in the web.xml, as the following (from their documentation) demonstrates:

<filter>
<filter-name>UrlRewriteFilter</filter-name>
  <filter-class>org.tuckey.web.filters.urlrewrite.UrlRewriteFilter</filter-class>
</filter>
<filter-mapping>
  <filter-name>UrlRewriteFilter</filter-name>
  <url-pattern>/*</url-pattern>
  <dispatcher>REQUEST</dispatcher>
  <dispatcher>FORWARD</dispatcher>
</filter-mapping>

To implement this annotation-unaware Filter into your annotated application, though, simply make a Filter that overrides the UrlRewriteFilter, and pass it the URLs to filter:

@WebFilter(urlPatterns = { "/*" },
           dispatcherTypes = { DispatcherType.REQUEST, DispatcherType.FORWARD })
public class RewriteFilter extends UrlRewriteFilter {
}

No other content in the class is required, and the now annotated Filter is added without any inclusion in the web.xml file.

Listener

Listeners are defined much the same way. As before, the old way of defining a Listener was to declare it in the web.xml file

<listener>
  <listener-class>foo.SiteListener</listener-class>
</listener>

The listeners define classes that the web app container will find and start. As before, the class must implement an appropriate interface; one of the javax.servlet.Servlet*Listeners. And, of course, it must implement the methods to satisfy the interface.

To use an annotated Listener, implement the desired Listener, satisfy it with the required methods, and annotate it with the @WebListener annotation.

@WebListener()
public class SiteListener implements ServletRequestListener {
  @Override
  public void requestDestroyed(ServletRequestEvent servletRequestEvent) {
  }
  @Override
  public void requestInitialized(ServletRequestEvent servletRequestEvent) {
  }
}

The annotation doesn’t require any parameters. The only parameter it allows is an optional description of the Listener.

Including Other Listeners

As with Filters, it’s easy to include Listeners that aren’t annotated. For example, to include Apache Tiles in your web.xml, you can define the Listener using the XML (from their documentation):

<listener>
  <listener-class>org.apache.tiles.web.startup.simple.SimpleTilesListener</listener-class>
</listener>

Or using annotations, simply extend the Tiles Listener you want to use, and annotate it appropriately.

@WebListener
public class TilesListener extends SimpleTilesListener {
}

This way you can contain the configuration entirely in software.

Servlet

Servlets are mapped much the same way Filters are mapped. Traditionally, the web.xml will define a Servlet and Servlet mappings to tie URLs to the correct Servlet.

<servlet>
  <servlet-name>SiteServlet</servlet-name>
  <servlet-class>foo.SiteServlet</servlet-class>
</servlet>
<servlet-mapping>
  <servlet-name>SiteServlet</servlet-name>
  <url-pattern>/mapping</url-pattern>
</servlet-mapping>

The Servlet then needs to extend the class javax.servlet.http.HttpServlet. No methods are required, but generally either or both of the doGet() or doPost() methods are implemented to handle the request action.

To use the Servlet 3.0 annotation for a Servlet, the HttpServlet class must still be implemented, and the annotation @WebServlet needs to be applied. The @WebServlet annotation requires only one attribute as it needs to know at least one URL to which the Servlet will be mapped.

@WebServlet("/mapping")
public class SiteServlet extends HttpServlet {
  @Override
  protected void doPost(final HttpServletRequest httpServletRequest,
                        final HttpServletResponse httpServletResponse)
             throws ServletException, IOException {
  // Do your stuff
  }
}

Of course, mutliple URLs can be added, as with the Filter, by specifying the urlPatterns parameter.

Using Other Servlets

With many frameworks, like Spring MVC or Apache Struts, there’s only one Servlet. That Servlet handles all of the processing of requests, routing them to the appropriate Action or Controller as necessary. As with the Filter and Listener annotations, a simple annotation can bring that third-party Servlet into the application with @WebServlet annotations. From the Spring documentation, here’s how to set up a basic DispatcherServlet in the web.xml file.

<servlet>
  <servlet-name>example</servlet-name>
  <servlet-class>org.springframework.web.servlet.DispatcherServlet</servlet-class>
  <load-on-startup>1</load-on-startup>
</servlet>
<servlet-mapping>
  <servlet-name>example</servlet-name>
  <url-pattern>*.form</url-pattern>
</servlet-mapping>

Here’s how to do the same using Servlet 3.0 annotations.

@WebServlet(urlPatterns={"/*.form"}, loadOnStartup=1)
public class SpringDispatcherServlet extends DispatcherServlet {
}

With this, the Spring DispatcherServlet is mapped to accept all URLs ending in .form, and it will be loaded when the application starts (instead of waiting for the first request). As with @WebFilter annotations, the @WebServlet also accepts init parameters, so those can also be added to help configure the application.

Some Limitations

One thing that some of the other frameworks like Spring bring is an ability to map the URL to methods with their annotations. While Servlet 3.0 annotations allow mapping more than one URL to a Servlet class, it is still up to the developer to decipher the URL in the Servlet, as necessary. This is no different than “usual” Servlet development where more than one URL is mapped to a Servlet; inside the Servlet the request path or URI or other mechanism can be used to determine by which the visitor arrived to the Servlet.

Additionally, Servlet 3.0 doesn’t bring any tools to map elements such as GET or POST parameters to method parameters. The same Servlet digestion of parameters occurs, and they’re all Strings until converted. It’s up to the developer to handle all of the parameter transformation.

There are two main libraries for creating Excel documents from Java/Groovy; POI and JXL.  After some research, I came to the conclusion that JXL is more up-to-date and powerful.  It is a Java library though.  As such, it is strongly typed with a lot of extra syntax that those of us developing in Groovy like to avoid.  To get around this, I created the Grails JXL plugin.

The plugin is a wrapper for the library, but it also adds some nice builder-like syntax to create Excel documents.  For example, to create a workbook with a single worksheet and a few cells you can write:

workbook('/path/to/test.xls') {
    sheet('SheetName') {
        cell(0,0,'Column 1').bold().center()
        cell(1,0,'Column 2').bold().center()
        cell(0,1,'Value 1').left()
        cell(1,1,'Value 2').left()
    }
}

Or if you prefer, you can add the data as a map

workbook('/path/to/test.xls') {
    sheet('SheetName') {
        addData([
            ['Column 1','Column 2'],
            ['Value 1','Value 2']
       ])
    }
    (0..1).each { cell(it,0).bold().center() } 
    (0..1).each { cell(it,1).left() }
}

To get this builder syntax, you simply have to use the Mixin grails.plugin.jxl.ExcelBuilder.

    @Mixin(ExcelBuilder)
    class MyBuilder {

Notice that columns and rows are 0 indexed, and that the cell method can be used to set the cell value when one is provided, or get the current cell when no value is provided.  In either case you can use provided methods to do formatting.

The plugin provides many built in methods for formatting, such as bold(), italic(), thinBorder(), dottedBorder() etc.  It also give access to all of the JXL functionality, by allowing you to set properties of WritableFont and WritableFormat directly on the cell, such as

    cell(0,0,"foo").pointSize = 16

The plugin also allows you to create Excel formulas, as in

    cell(3,6, formula.sum(formula.range(3,0,3,5)))

which generates a cell with the formula =SUM(A4:F4). The formula object supplies a range function to create the Excel formatted range. All other functions dynamically create the Excel function with the same name; in this case sum.

The Grails JXL plugin takes advantage of a great library and Groovy’s dynamic nature to give a more convenient way to generate formatted Excel documents.  Feedback is very welcome, as this plugin is still in it’s early stages. For more detailed information, check out the wiki on github.

[Dec-15 21:26:10.777][DEBUG][http-8080-2] [org.springframework.security.web.
authentication.preauth.AbstractPreAuthenticatedProcessingFilter
:doAuthenticate] No pre-authenticated principal found in request

Pretty innocuous, but it turns out that this particular Spring Security filter spits out a lot of messages at the DEBUG level – so many, in fact, that it made it difficult to find debugging messages that I was actually interested in. I had configured Log4J to record org.springframework.security log events at the WARN level or higher, and had spent a couple of hours scratching my head, trying to figure out why these messages were still being logged.

I recently revisited the logging infrastructure in this project, switching out Log4J in favor of SLF4J and Logback.  I eliminated all references to commons-logging using the SLF4J JCL bridge and migrated my log4j.xml config to a logback.xml config, yet the debug messages from Spring Security still continued to be emitted. After a few hours of debugging my way through the depths of the logging systems and this stackoverflow.com post, I figured out what the problem was: the name of the logger used did not match the classname being emitted by the log message.

Consider this code:

public abstract class A {
    private static final Logger LOG = LoggerFactory.getLogger(getClass());
    public void performAbstractOperation()
        { LOG.debug("Performing abstract operation"); }
}

public class B extends A {
    private static final Logger LOG = LoggerFactory.getLogger(B.class);
    public void performConcreteOperation()
        { LOG.debug("Performing concrete operation"); }
}

If the logging facility is set up to report the class name that issues the logging event and is configured to emit logging events from class A at WARN level or higher and from class B at DEBUG level or higher, the LOG.debug message from class A (“Performing abstract operation”) will still show up in the logs when your code runs (and will show up as being emitted by class A!), even though it appears that the logging facility is configured to filter out that logging event.

This happens because of how Log4J and Logback implement their loggers. Each logger has a name associated with it. This name is technically any arbitrary string, but is usually a fully-qualified Java package or class – for example, org.springframework.security or com.mycompany.MyClass. (Using fully-qualified Java package names or class names allows logging configurations to manage entire hierarchies of classes with a single logger entry.) These loggers are fetched by name using the LoggerFactory.getLogger() facility (for SLF4J/Logback – Log4J uses LogFactory.getLog()), passing the object’s Class object as an argument. The named logger that gets fetched is named identically to the fully-qualified class name. In the example above, class B gets the logger named “B” – but class A also gets the logger named “B”, by virtue of using getClass in the call to getLogger (because class “A” is abstract, any instantiated class would have to be of type “B”, which is what getClass() returns).  Because they both get the logger named “B” and “B” is configured to emit DEBUG messages or higher, the logging events from both “A” and “B” are recorded.

By default, the logger name is not emitted into the log files, but the class name is, so it appears that unwanted logging messages aren’t being properly filtered by the logging facility. However, both Log4J and Logback can use “%c” as a pattern in their logging configurations to emit the logger name used by a logging event. This makes it very easy to track down and eliminate any pesky debugging messages from abstract classes (like in the example above.)

Because both “A” and “B” use the same name, it is impossible to filter the DEBUG event from “A” while still seeing the DEBUG event from “B”. In order to fix this, pass a unique name (as a String) to LoggerFactory.getLogger() in either the abstract class or the derived class. This name will become the name of the logger for that class, while the other class will retain the fully-qualified name of the derived class for the name of its logger. The logging facility can then be configured to allow logging events at one level for the logger with the unique name and to allow logging events at a different level for the logger with the name of the derived class.

In our case, the tag was being used to set an attribute to the value of another attribute’s inner property, as the following shows:

<c:set var="something"
    value="${somethingElse.property}"/>

Even more, the same attribute ame was being used in different JSPs, connected by including one in another, although storing the attribute in different scopes, as the following shows:

<c:set var="something"
    value="${somethingElse.property}" scope="request" />
<c:set var="something"
    value="${anotherElse.property}" />

In this case, the including page contained the first line, the request-scope set value. The included file contained the second, implicit scope value. The page was included with the request-time <c:import url=”included.jsp”/>, which “calls” the included page. The included page gets its own page context, but shares the request and session. When things worked well, the request value was unmodified, and “returning” from the included page left the page attribute behind. The discovered problem occurred when the value of the property resolved to NULL. In this case, not only was the page attribute “unset,” but it happened that the request attribute was also lost.

It was unsettling to find that what seemed to be a default page context action would affect the other scopes, but it turns out to be the case!

The following JSP shows this with a simple example. A few values are set, just to show what’s happening, and then the attributes are modified to show the results.

<%@taglib uri="http://java.sun.com/jsp/jstl/core" prefix="c"%>
<c:set var="something"
    value="Saved in Session" scope="session" />
<c:set var="something"
     value="Saved in Request" scope="request" />
<c:set var="something"
     value="Saved in Page" scope="page" />
<html>
<head>
<style type="text/css">
.value {
color: green;
}
</style>
<title>Test</title>
</head>
<body>
<p>
Session:
<span class="value"><%=session.getAttribute("something")%></span>
<br />Request:
<span class="value"><%=request.getAttribute("something")%></span>
<br />Page:
<span class="value"><%=pageContext.getAttribute("something")%></span>
<br />EL: <span class="value">${something}</span>
</p>
<c:set var="something" value="${nothing}" scope="page" />
<p>
Session:
<span class="value"><%=session.getAttribute("something")%></span>
<br />Request:
<span class="value"><%=request.getAttribute("something")%></span>
<br />Page:
<span class="value"><%=pageContext.getAttribute("something")%></span>
<br />EL: <span class="value">${something}</span>
</p>
<c:set var="something" value="${nothing}" />
<p>
Session:
<span class="value"><%=session.getAttribute("something")%></span>
<br />Request:
<span class="value"><%=request.getAttribute("something")%></span>
<br />Page:
<span class="value"><%=pageContext.getAttribute("something")%></span>
<br />EL: <span class="value">${something}</span>
</p>
</body>
</html>

The actions are pretty simple.

• The first block shows all of the values as initially set. Since the page attribute is set, the EL resolves to the page-scoped value.
• The page-scope value is set to something that resolves to NULL (note this doesn’t set the value to NULL, but removes the value from the attributes Map, which will resolve to NULL in future uses) with an explicit scope definition. This correctly clears the page attribute, but leaves the other alone, as is demonstrated by the EL evaluating to the request-scoped value.
• The final block sets the attribute with an implicit scope definition; the documentation says this will default to the page scope (which it does), but what the documentation fails to note is that the other scopes are also removed! This is demonstrated by all of the “null” entries, and the empty EL (EL doesn’t show NULL values).

Here’s what the output looks like:

Session: Saved in Session
Request: Saved in Request
Page: Saved in Page
EL: Saved in Page

Session: Saved in Session
Request: Saved in Request
Page: null
EL: Saved in Request

Session: null
Request: null
Page: null
EL:

This “undocumented feature” is found in the implementation of the org.apache.taglibs.standard.tag.common.core.SetSupport.doEndTag() which has the following bit of close in it:

if (scopeSpecified)
    pageContext.removeAttribute(var, scope);
else
    pageContext.removeAttribute(var);

It would seem that it should be the case that if the scope isn’t specified that the page scope would be used, as that is the default according to the documentation. It isn’t the case, though, so when not specified the attribute looks to be entirely removed. Checking deeper, at least in the Tomcat source, the pageContext.removeAttribute(var) ends up in the JSTL org.apache.jasper.runtime.PageContextImpl which finally results in executing the following:

private void doRemoveAttribute(String name) {
    removeAttribute(name, PAGE_SCOPE);
    removeAttribute(name, REQUEST_SCOPE);
    if( session != null ) {
        try {
            removeAttribute(name, SESSION_SCOPE);
        } catch(IllegalStateException ise) {
            // Session has been invalidated.
            // Ignore and fall throw to application scope.
        }
    }
    removeAttribute(name, APPLICATION_SCOPE);
}

As we can see, it removes the attributes from all of the scopes, even the application (the Servlet’s Context) scope, which we didn’t test! As disconcerting as this is, the solution is trivial to implement: explicitly name the page scope where the attribute may collide and where the value may evaluate to NULL. As long as both of those don’t happen, the problem doesn’t occur. If they do both happen, though, no matter where the <c:set> is encountered, the request and session attributes are lost.

This has been tested on Tomcat v6, v7, and Weblogic v11.

I found a bug in an application I was working on that I narrowed down to a concurrency issue. Threads were deadlocked somewhere. I couldn’t figure it out in the application so I wrote the most minimal app I could that reproduced the problem. Here’s that code (I removed various System.out… calls for brevity):

public class Foo {

	private int counter;

	public static void main(String[] args) throws Exception {
		 new Foo().run();
	}

	public void run() throws Exception {

		Thread[] threads = new Thread[2];

		for (int i = 0; i < threads.length; i++) {
			threads[i] = new Thread() {
				public void run() {
					for (int i = 0; i < 1000000000; i++) {
						increment();
					}
				}
			};
		}

		for (Thread t : threads) {
			t.start();
		}

		for (Thread t : threads) {
			t.join();
		}
	}

	private synchronized void increment() {
		counter++;
	}
}

The code above deadlocks both created threads in the counting loop; zero CPU usage. I didn't see any reason that should happen so I sent the code sample to some coworkers. They didn't see a problem either. At this point I started trying to isolate environmental issues. I was running this hardware, OS, and JVM:

        MacBook Pro
        2.3GHz Intel Core i7
        8GB 1333MHz DDR3

        OS X 10.6.8 with 64 bit enabled

        Java version 1.6.0_29
        Java(TM) SE Runtime Environment (build 1.6.0_29-b11-402-10M3527)
        Java HotSpot(TM) 64-Bit Server VM (build 20.4-b02-402, mixed mode)

The deadlock didn't happen if I used a Lock instead of a synchronized method. It also didn't happen if I ran the JVM in 32 bit mode, only in 64 bit mode.

I started considering the possibility of a JVM issue. That's not a conclusion to jump to lightly so I sent the problem to a prominent Java expert who in turn involved two others. I haven't their permission to give their names. One of them was able to reproduce the issue running similar hardware.

Next we tried running on 2 other JVMs: openjdk version 1.7.0-ea and soylatte java version 1.6.0_03-p3. There was no deadlock on either of these JVMs. It was starting to look a lot like a JVM problem.

Once we determined it wasn't a problem with the application code we ran the app until it deadlocked then forced a core dump. To force a core dump from the command line:

1. ulimit -c unlimited - set this to allow core dumps
2. kill -SIGSEGV pid - send a segmentation fault signal to force the app to crash

The core file is saved in /cores/core.pid. There is also a *.crash file saved in [user home]/Library/Logs/DiagnosticReports.

The crash file analysis showed this info for the 2 threads:

Thread 24:  Java: Thread-1
0   libSystem.B.dylib             0x00007fff89f88d7a mach_msg_trap + 10
1   libSystem.B.dylib             0x00007fff89f893ed mach_msg + 59
2   libclient64.dylib             0x000000010100d903 jio_snprintf + 37641
...

Thread 25:  Java: Thread-2
0   libSystem.B.dylib             0x00007fff89f88d7a mach_msg_trap + 10
1   libSystem.B.dylib             0x00007fff89f893ed mach_msg + 59
2   libclient64.dylib             0x000000010100db03 jio_snprintf + 38153
...

They are both waiting on a message from the kernel. It appears to be an issue with the kernel not delivering the message instead of a JVM problem but we aren't ready to declare any definite answer yet. The next step is the core dump analysis. Wherever this leads or whether we definitively identify the problem, its been an interesting experience.