Invariant Properties

Creating Sonarqube Projects

Bear Giles | January 27, 2014

Sonarqube (nee Sonar) is da bomb. It’s not something you have to check daily but if you’re serious about quality you’ll check it during sprint planning if not weekly.

Check out a sample project at nemo.sonarqube.com, e.g., OpenJPA, to get an idea of what information is available. You might want to focus on a specific component at first, e.g., OpenJPA JDBC.

As a developer I’m mostly interested in the “issues” (mostly FindBugs and Squid) and “unit test coverage.” As an architect I’m mostly interested in the “package tangle index” and “complexity” – the former is a measure of proper encapsulation and decoupling and the latter is a measure of maintainability.

It’s important to view these numbers with an appropriate amount of salt. They give valuable insights but it takes a bit of experience to make the best use of them. That’s why it’s important to keep this information away from the bean counters who will set unreasonable standards like 90% code coverage in all unit tests. (This can be impossible to achieve if you have rich exception handling but no way to mock the classes that will throw those exceptions. Only a fool would trade code robustness for a higher score.)

Installing Sonarqube

It’s straightforward to install sonarqube. It comes bundled with its own webapp server and embedded database so you can check it out by just unpacking it and running the startup script. A production system should use a real database. Multiple databases are supported.

Check the sonarqube site for details.

Creating Our Project

I’ll admit it – creating a project is very counter-intuitive. In a nutshell everything is handled by pushing data to the server without creating anything on the sonarqube server first. (You’ll still want to create admin users on the sonarqube server.)

In practice this means that we add a maven plugin. This is an expensive plugin so it’s common to use a custom profile, e.g., “sonar” (for the legacy name).

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<profiles>
<profile>
<id>sonar</id>
<properties>
<sonar.language>java</sonar.language>
<sonar.host.url>http://chaos:9000</sonar.host.url>
<sonar.jdbc.url>jdbc:postgresql://chaos/sonar</sonar.jdbc.url>
<sonar.jdbc.username>sonar</sonar.jdbc.username>
<sonar.jdbc.password>sonar</sonar.jdbc.password>
</properties>
<build>
<plugins>
<plugin>
<groupId>org.jacoco</groupId>
<artifactId>jacoco-maven-plugin</artifactId>
<version>0.6.4.201312101107</version>
<executions>
<execution>
<id>default-prepare-agent</id>
<goals>
<goal>prepare-agent</goal>
</goals>
</execution>
<execution>
<id>default-prepare-agent-integration</id>
<goals>
<goal>prepare-agent-integration</goal>
</goals>
</execution>
<execution>
<id>default-report</id>
<goals>
<goal>report</goal>
</goals>
</execution>
<execution>
<id>default-report-integration</id>
<goals>
<goal>report-integration</goal>
</goals>
</execution>
<execution>
<id>default-check</id>
<goals>
<goal>check</goal>
</goals>
<configuration>
<rules>
<rule implementation="org.jacoco.maven.RuleConfiguration">
<element>BUNDLE</element>
<limits>
<limit implementation="org.jacoco.report.check.Limit">
<counter>COMPLEXITY</counter>
<value>COVEREDRATIO</value>
<minimum>0.60</minimum>
</limit>
</limits>
</rule>
</rules>
</configuration>
</execution>
</executions>
</plugin>
</plugins>
</build>
</profile>
</profiles>
</project>

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

    <profiles>
        <profile>
            <id>sonar</id>
            <properties>
                <sonar.language>java</sonar.language>
                <sonar.host.url>http://chaos:9000</sonar.host.url>
                <sonar.jdbc.url>jdbc:postgresql://chaos/sonar</sonar.jdbc.url>
                <sonar.jdbc.username>sonar</sonar.jdbc.username>
                <sonar.jdbc.password>sonar</sonar.jdbc.password>
            </properties>
            <build>
                <plugins>
                    <plugin>
                        <groupId>org.jacoco</groupId>
                        <artifactId>jacoco-maven-plugin</artifactId>
                        <version>0.6.4.201312101107</version>
                        <executions>
                            <execution>
                                <id>default-prepare-agent</id>
                                <goals>
                                    <goal>prepare-agent</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>default-prepare-agent-integration</id>
                                <goals>
                                    <goal>prepare-agent-integration</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>default-report</id>
                                <goals>
                                    <goal>report</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>default-report-integration</id>
                                <goals>
                                    <goal>report-integration</goal>
                                </goals>
                            </execution>
                            <execution>
                                <id>default-check</id>
                                <goals>
                                    <goal>check</goal>
                                </goals>
                                <configuration>
                                    <rules>
                                        <!-- implmentation is needed only for Maven 2 -->
                                        <rule implementation="org.jacoco.maven.RuleConfiguration">
                                            <element>BUNDLE</element>
                                            <limits>
                                                <!-- implmentation is needed only for Maven 2 -->
                                                <limit implementation="org.jacoco.report.check.Limit">
                                                    <counter>COMPLEXITY</counter>
                                                    <value>COVEREDRATIO</value>
                                                    <minimum>0.60</minimum>
                                                </limit>
                                            </limits>
                                        </rule>
                                    </rules>
                                </configuration>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>
        </profile>
    </profiles>
</project>

Updating Our Project

The sonar plugin is expensive so it should not be run as part of a routine build. A common practice is to schedule a nightly build on the CI server (Hudson, Continuum, etc.) Developers may also want to perform off-schedule builds while working on the issue backlog – it’s not uncommon for one fix to introduce other lower-priority issues.

Source Code

A sample project using this plugin is at https://github.com/beargiles/project-student [github] and http://beargiles.github.io/project-student/ [github pages].

This project illustrates the need to be intelligent about how we interpret the results. I use two common practices – throwing an internal exception instead of returning a null value and using a custom ‘UnitTestException’ to test failure code without cluttering the logs with extraneous information. The code looks the same as questionable code so it’s properly flagged but there doesn’t seem to be a way to silence squid warnings. (Findbugs has its own SuppressWarnings annotation.)

Overall it’s still a huge win.

(Update: it’s possible to control the squid warnings via the sonarqube ‘Quality Profiles’ tab. This can be used to reduce the severity level to ‘info’ but I’m hesitant to disable these tests outright since they are sometimes legitimate warnings. That’s why I strongly prefer to use per-instance FindBugs SuppressWarnings annotations instead of changing those warning levels.)

Comments: No Comments »
Categories: java
Comments rss
Trackback

Creating Maven Source and Javadoc Artifacts

Bear Giles | January 27, 2014

Many people are aware of maven source and javadoc artifacts but don’t know why they would want to create them. I was definitely in this camp – I can see why people want this information but it seemed like a relatively inefficient way to get it since it requires manual navigation of the maven repository.

Then I got hit by a clue stick.

These artifacts are used by IDEs, not people. If you’re using maven dependencies the IDE is smart enough to know how to find these artifacts. The source artifact is used when you’re single-stepping through code in the debugger – you no longer have to explicitly bind source code to libraries in the IDE. The javadoc artifact is used for auto-completion and context-sensitive help in the editor.

Neither of these is required – I was happy using ‘vi’ for many years – but it definitely improves your productivity when you mostly know what you need but aren’t quite sure of the details.

Source Artifacts

The source artifacts are the easiest to create. Add a plugin that will be run automatically as part of a standard build and you’re done. Builds take slightly longer but it’s probably not enough to worry about since you’re just creating an archive of a few directories.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-source-plugin</artifactId>
<version>2.1.1</version>
<executions>
<execution>
<id>attach-sources</id>
<phase>verify</phase>
<goals>
<goal>jar-no-fork</goal>
<goal>test-jar-no-fork</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
</project>

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
    <build>
        <plugins>
            <!-- create source jar -->
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-source-plugin</artifactId>
                <version>2.1.1</version>
                <executions>
                    <execution>
                        <id>attach-sources</id>
                        <phase>verify</phase>
                        <goals>
                            <!-- produce source artifact for project main sources -->
                            <goal>jar-no-fork</goal>
                            <!-- produce test source artifact for project test sources -->
                            <goal>test-jar-no-fork</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
    </build>
</project>

Javadoc Artifacts

Javadoc artifacts are a little more complex since you’ll probably want to create a human-friendly site at the same time. The biggest issue there, in my experience, is that external classes were opaque since it took so much effort to create the necessary links. The maven plugin now takes care of that for us!

This artifact takes a significant amount of time to build so you probably don’t want to do it every time. There are two approaches – either specify the maven target explicitly or tie it to a custom profile, e.g., ‘javadoc’. The configuration below uses a custom profile.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<profiles>
<profile>
<id>javadoc</id>
<build>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
<detectLinks />
<includeDependencySources>true</includeDependencySources>
<dependencySourceIncludes>
<dependencySourceInclude>com.invariantproperties.project.student:*</dependencySourceInclude>
</dependencySourceIncludes>
<links>
<link>http://docs.oracle.com/javase/7/docs/api/</link>
<link>http://docs.oracle.com/javaee/6/api</link>
<link>http://docs.spring.io/spring/docs/current/javadoc-api/</link>
<link>http://docs.spring.io/spring-data/commons/docs/1.6.2.RELEASE/api/</link>
<link>http://docs.spring.io/spring-data/jpa/docs/1.4.3.RELEASE/api/</link>
<link>http://docs.spring.io/spring-data/data-jpa/docs/1.4.3.RELEASE/api/</link>
<link>https://jersey.java.net/apidocs/1.17/jersey/</link>
<link>http://hamcrest.org/JavaHamcrest/javadoc/1.3/</link>
<link>http://eclipse.org/aspectj/doc/released/runtime-api/</link>
<link>http://eclipse.org/aspectj/doc/released/weaver-api</link>
<link>http://tapestry.apache.org/5.3.7/apidocs/</link>
</links>
</configuration>
<executions>
<execution>
<id>aggregate</id>
<phase>package</phase>
<goals>
<goal>aggregate</goal>
<goal>jar</goal>
</goals>
</execution>
</executions>
</plugin>
</plugins>
</build>
<reporting>
<plugins>
<plugin>
<groupId>org.apache.maven.plugins</groupId>
<artifactId>maven-javadoc-plugin</artifactId>
<version>2.9.1</version>
<configuration>
</configuration>
<reportSets>
<reportSet>
<id>non-aggregate</id>
<configuration>
</configuration>
<reports>
<report>javadoc</report>
</reports>
</reportSet>
<reportSet>
<id>aggregate</id>
<configuration>
</configuration>
<reports>
<report>aggregate</report>
</reports>
</reportSet>
</reportSets>
</plugin>
</plugins>
</reporting>
</profile>
</profiles>
</project>

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

        <profiles>
            <!-- create javadoc -->
            <profile>
                <id>javadoc</id>
                <build>
                    <plugins>
                        <plugin>
                            <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-javadoc-plugin</artifactId>
                        <version>2.9.1</version>
                        <configuration>
                            <detectLinks />
                            <includeDependencySources>true</includeDependencySources>
                            <dependencySourceIncludes>
                                <dependencySourceInclude>com.invariantproperties.project.student:*</dependencySourceInclude>
                            </dependencySourceIncludes>
                            <!-- heavily used dependencies -->
                            <links>
                                <link>http://docs.oracle.com/javase/7/docs/api/</link>
                                <link>http://docs.oracle.com/javaee/6/api</link>
                                <link>http://docs.spring.io/spring/docs/current/javadoc-api/</link>
                                <link>http://docs.spring.io/spring-data/commons/docs/1.6.2.RELEASE/api/</link>
                                <link>http://docs.spring.io/spring-data/jpa/docs/1.4.3.RELEASE/api/</link>
                                <link>http://docs.spring.io/spring-data/data-jpa/docs/1.4.3.RELEASE/api/</link>
                                <link>https://jersey.java.net/apidocs/1.17/jersey/</link>
                                <link>http://hamcrest.org/JavaHamcrest/javadoc/1.3/</link>
                                <link>http://eclipse.org/aspectj/doc/released/runtime-api/</link>
                                <link>http://eclipse.org/aspectj/doc/released/weaver-api</link>
                                <link>http://tapestry.apache.org/5.3.7/apidocs/</link>
                            </links>
                        </configuration>
                        <executions>
                            <execution>
                                <id>aggregate</id>
                                <!-- <phase>site</phase> -->
                                <phase>package</phase>
                                <goals>
                                    <goal>aggregate</goal>
                                    <goal>jar</goal>
                                </goals>
                            </execution>
                        </executions>
                    </plugin>
                </plugins>
            </build>

            <reporting>
                <plugins>
                    <plugin>
                        <groupId>org.apache.maven.plugins</groupId>
                        <artifactId>maven-javadoc-plugin</artifactId>
                        <version>2.9.1</version>
                        <configuration>
                            <!-- Default configuration for all reports -->
                        </configuration>
                        <reportSets>
                            <reportSet>
                                <id>non-aggregate</id>
                                <configuration>
                                    <!-- Specific configuration for the non aggregate report -->
                                </configuration>
                                <reports>
                                    <report>javadoc</report>
                                </reports>
                            </reportSet>
                            <reportSet>
                                <id>aggregate</id>
                                <configuration>
                                    <!-- Specific configuration for the aggregate report -->
                                </configuration>
                                <reports>
                                    <report>aggregate</report>
                                </reports>
                            </reportSet>
                        </reportSets>
                    </plugin>
                </plugins>
            </reporting>
        </profile>
    </profiles>
</project>

package-info.java

Finally each package should have a package-info.java file. This replaces the old package-info.html file but is an improvement since it allows the use of class annotations. (It will not be compiled since it’s an invalid class name.)

I’ve found it extremely helpful to include links to resources that help me understand why the classes look the way they do. For instance the metadata package in my ‘student’ project contains links to my blog posts, other blog posts that I’ve found useful, and even the appropriate Oracle tutorial. At a company these could be links to wiki pages.

/**
* Classes that support JPA Criteria Queries for persistent entities.
*
* @see <a href="http://invariantproperties.com/2013/12/19/project-student-persistence-with-spring-data/">Project Student: Persistence with Spring Data</a>
* @see <a href="http://invariantproperties.com/2013/12/29/project-student-jpa-criteria-queries/">Project Student: JPA Criteria Queries</a>
* @see <a href="http://www.petrikainulainen.net/programming/spring-framework/spring-data-jpa-tutorial-part-four-jpa-criteria-queries/">Spring Data JPA Tutorial Part Four: JPA Criteria Queries</a> [www.petrikainulainen.net]
* @see <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjitv.html">JEE Tutorial</a>
*
* @author Bear Giles <bgiles@coyotesong.com>
*/
package com.invariantproperties.project.student.metamodel;

/**                     
 * Classes that support JPA Criteria Queries for persistent entities.
 *                          
 * @see <a href="http://invariantproperties.com/2013/12/19/project-student-persistence-with-spring-data/">Project Student: Persistence with Spring Data</a>
 * @see <a href="http://invariantproperties.com/2013/12/29/project-student-jpa-criteria-queries/">Project Student: JPA Criteria Queries</a>
 * @see <a href="http://www.petrikainulainen.net/programming/spring-framework/spring-data-jpa-tutorial-part-four-jpa-criteria-queries/">Spring Data JPA Tutorial Part Four: JPA Criteria Queries</a> [www.petrikainulainen.net]
 * @see <a href="http://docs.oracle.com/javaee/6/tutorial/doc/gjitv.html">JEE Tutorial</a>      
 *  
 * @author Bear Giles <bgiles@coyotesong.com>
 */             
package com.invariantproperties.project.student.metamodel;

Source Code

The source code is at https://github.com/beargiles/project-student [github] and http://beargiles.github.io/project-student/ [github pages].

Comments: No Comments »
Categories: java
Comments rss
Trackback

Project Student Moved To Github

Bear Giles | January 27, 2014

A quick note – Project Student has moved to Git Hub. I’ll be updating the blog posts here (but not at Java Code Geeks) to point to it soon. The package names have also been refactored so it’s in ‘project’ instead of ‘sandbox’.

Github

Github Project Pages.

Comments: No Comments »
Categories: java
Comments rss
Trackback

Project Student: Simplifying Code With AOP

Bear Giles | January 9, 2014

This is part of Project Student.

Many people strongly believe that methods should fit within your editor window (say, 20 lines), and some people believe that methods should be even smaller than that. The idea is that a method should do one thing and only one thing. If it does more than that it should be broken apart into multiple methods and the old method’s “one thing” is to coordinate the new methods.

This does not mean breaking apart a method after an arbitrary number of lines. Sometimes methods are naturally larger. It’s still always a good question to ask.

So how do you recognize code that does more than one thing? A good touchstone is if the code is duplicated in multiple methods. The canonical example is transaction management in persistence classes. Every persistence class needs it and the code always looks the same.

Another example is the unhandled exception handler in my Resource classes. Every REST-facing method needs to deal with this and the code always looks the same.

That’s the theory. In practice the code can be ugly and with modest gains. Fortunately there’s a solution: Aspect-Oriented Programming (AOP). This allows us to transparently weave code before or after our method calls. This often lets us simplify our methods dramatically.

Design Decisions

AspectJ – I’m using AspectJ via Spring injection.

Limitations

The AspectJ pointcut expressions are relatively simple with the CRUD methods. That might not be true as more complex functionality is added.

Unhandled Exceptions in Resource Methods

Our first concern is unhandled exceptions in resource methods. Jersey will return a SERVER INTERNAL ERROR (500) message anyway but it will probably include a stack trace and other content that we don’t want an attacker to know. We can control what it includes if we send it ourselves. We could add a ‘catch’ block in all of our methods but it’s boilerplate that we can move into an AOP method. That will leave all of our Resource methods a lot slimmer and easier to read.

This class also checks for “Object Not Found” exceptions. It would be easy to handle in the individual Resource classes but it muddies the code. Putting the exception handler here allows our methods to focus on the happy path and guarantees consistency in the response.

This class has two optimizations. First, it explicitly checks for a UnitTestException and skips detailed logging in that case. One of my biggest pet peeve is tests that that flood the logs with stack traces when everything is working like expected. That makes it impossible to skim the logs for obvious problems. This single change can make problems much easier to find.

Second, it uses the logger associated with the targeted class, e.g., CourseResource, instead of with the AOP class. Besides being clearer this allows us to selectively change the logging level for a single Resource instead of all of them.

Another trick is to call an ExceptionService in our handler. This is a service that can do something useful with exceptions, e.g., it might create or update a Jira ticket. This hasn’t been implemented so I just put in a comment to show where it goes.

@Aspect
@Component
public class UnexpectedResourceExceptionHandler {
@Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource)")
public Object checkForUnhandledException(ProceedingJoinPoint pjp) throws Throwable {
Object results = null;
Logger log = Logger.getLogger(pjp.getSignature().getClass());
try {
results = pjp.proceed(pjp.getArgs());
} catch (ObjectNotFoundException e) {
// this is safe to log since we know that we've passed filtering.
String args = Arrays.toString(pjp.getArgs());
results = Response.status(Status.NOT_FOUND).entity("object not found: " + args).build();
if (log.isDebugEnabled()) {
log.debug("object not found: " + args);
}
} catch (Exception e) {
// find the method we called. We can't cache this since the method
// may be overloaded
Method method = findMethod(pjp);
if ((method != null) && Response.class.isAssignableFrom(method.getReturnType())) {
// if the method returns a response we can return a 500 message.
if (!(e instanceof UnitTestException)) {
if (log.isInfoEnabled()) {
log.info(
String.format("%s(): unhandled exception: %s", pjp.getSignature().getName(),
e.getMessage()), e);
}
} else if (log.isTraceEnabled()) {
log.info("unit test exception: " + e.getMessage());
}
results = Response.status(Status.INTERNAL_SERVER_ERROR).build();
} else {
// DO NOT LOG THE EXCEPTION. That just clutters the log - let
// the final handler log it.
throw e;
}
}
return results;
}
/**
* Find method called via reflection.
*/
Method findMethod(ProceedingJoinPoint pjp) {
Class[] argtypes = new Class[pjp.getArgs().length];
for (int i = 0; i < argtypes.length; i++) {
argtypes[i] = pjp.getArgs()[i].getClass();
}
Method method = null;
try {
// @SuppressWarnings("unchecked")
method = pjp.getSignature().getDeclaringType().getMethod(pjp.getSignature().getName(), argtypes);
} catch (Exception e) {
Logger.getLogger(UnexpectedResourceExceptionHandler.class).info(
String.format("could not find method for %s.%s", pjp.getSignature().getDeclaringType().getName(),
pjp.getSignature().getName()));
}
return method;
}
}

@Aspect
@Component
public class UnexpectedResourceExceptionHandler {
    @Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource)")
    public Object checkForUnhandledException(ProceedingJoinPoint pjp) throws Throwable {
        Object results = null;
        Logger log = Logger.getLogger(pjp.getSignature().getClass());

        try {
            results = pjp.proceed(pjp.getArgs());
        } catch (ObjectNotFoundException e) {
            // this is safe to log since we know that we've passed filtering.
            String args = Arrays.toString(pjp.getArgs());
            results = Response.status(Status.NOT_FOUND).entity("object not found: " + args).build();
            if (log.isDebugEnabled()) {
                log.debug("object not found: " + args);
            }
        } catch (Exception e) {
            // find the method we called. We can't cache this since the method
            // may be overloaded
            Method method = findMethod(pjp); 
            if ((method != null) && Response.class.isAssignableFrom(method.getReturnType())) {
                // if the method returns a response we can return a 500 message.
                if (!(e instanceof UnitTestException)) {
                    if (log.isInfoEnabled()) {
                        log.info(
                                String.format("%s(): unhandled exception: %s", pjp.getSignature().getName(),
                                        e.getMessage()), e);
                    }
                } else if (log.isTraceEnabled()) {
                    log.info("unit test exception: " + e.getMessage());
                }
                results = Response.status(Status.INTERNAL_SERVER_ERROR).build();
            } else {
                // DO NOT LOG THE EXCEPTION. That just clutters the log - let
                // the final handler log it.
                throw e;
            }
        }

        return results;
    }

    /**
     * Find method called via reflection.
     */
    Method findMethod(ProceedingJoinPoint pjp) {
        Class[] argtypes = new Class[pjp.getArgs().length];
        for (int i = 0; i < argtypes.length; i++) {
            argtypes[i] = pjp.getArgs()[i].getClass();
        }

        Method method = null;

        try {
            // @SuppressWarnings("unchecked")
            method = pjp.getSignature().getDeclaringType().getMethod(pjp.getSignature().getName(), argtypes);
        } catch (Exception e) {
            Logger.getLogger(UnexpectedResourceExceptionHandler.class).info(
                    String.format("could not find method for %s.%s", pjp.getSignature().getDeclaringType().getName(),
                            pjp.getSignature().getName()));
        }

        return method;
    }
}

REST Post Values Checking

Our Resource methods also have a lot of boilerplate code to check the REST parameters. Are they non-null, are email addresses well-formed, etc. Again it’s easy to move much of this code into an AOP method and simplify the Resource method.

We start by defining an interface that indicates a REST transfer object can be validated. This first version gives us a simple thumbs-up or thumbs-down, an improved version will give us a way to tell the client what the specific problems are.

public interface Validatable {
boolean validate();
}

public interface Validatable {

    boolean validate();
}

We now extend our earlier REST transfer objects to add a validation method.

Two notes. First, the name and email address accept Unicode letters, not just the standard ASCII letters. This is important as our world becomes internationalized.

Second, I’ve added a toString() method but it’s unsafe since it uses unsanitized values. I’ll address sanitization later.

@XmlRootElement
public class NameAndEmailAddressRTO implements Validatable {
// names must be alphabetic, an apostrophe, a dash or a space. (Anne-Marie,
// O'Brien). This pattern should accept non-Latin characters.
// digits and colon are added to aid testing. Unlikely but possible in real
// names.
private static final Pattern NAME_PATTERN = Pattern.compile("^[\\p{L}\\p{Digit}' :-]+$");
// email address must be well-formed. This pattern should accept non-Latin
// characters.
private static final Pattern EMAIL_PATTERN = Pattern.compile("^[^@]+@([\\p{L}\\p{Digit}-]+\\.)?[\\p{L}]+");
private String name;
private String emailAddress;
private String testUuid;
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
public String getEmailAddress() {
return emailAddress;
}
public void setEmailAddress(String emailAddress) {
this.emailAddress = emailAddress;
}
public String getTestUuid() {
return testUuid;
}
public void setTestUuid(String testUuid) {
this.testUuid = testUuid;
}
/**
* Validate values.
*/
@Override
public boolean validate() {
if ((name == null) || !NAME_PATTERN.matcher(name).matches()) {
return false;
}
if ((emailAddress == null) || !EMAIL_PATTERN.matcher(emailAddress).matches()) {
return false;
}
if ((testUuid != null) && !StudentUtil.isPossibleUuid(testUuid)) {
return false;
}
return true;
}
@Override
public String toString() {
// FIXME: this is unsafe!
return String.format("NameAndEmailAddress('%s', '%s', %s)", name, emailAddress, testUuid);
}
}

@XmlRootElement
public class NameAndEmailAddressRTO implements Validatable {

    // names must be alphabetic, an apostrophe, a dash or a space. (Anne-Marie,
    // O'Brien). This pattern should accept non-Latin characters.
    // digits and colon are added to aid testing. Unlikely but possible in real
    // names.
    private static final Pattern NAME_PATTERN = Pattern.compile("^[\\p{L}\\p{Digit}' :-]+$");

    // email address must be well-formed. This pattern should accept non-Latin
    // characters.
    private static final Pattern EMAIL_PATTERN = Pattern.compile("^[^@]+@([\\p{L}\\p{Digit}-]+\\.)?[\\p{L}]+");

    private String name;
    private String emailAddress;
    private String testUuid;

    public String getName() {
        return name;
    }

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

    public String getEmailAddress() {
        return emailAddress;
    }

    public void setEmailAddress(String emailAddress) {
        this.emailAddress = emailAddress;
    }

    public String getTestUuid() {
        return testUuid;
    }

    public void setTestUuid(String testUuid) {
        this.testUuid = testUuid;
    }

    /**
     * Validate values.
     */
    @Override
    public boolean validate() {
        if ((name == null) || !NAME_PATTERN.matcher(name).matches()) {
            return false;
        }

        if ((emailAddress == null) || !EMAIL_PATTERN.matcher(emailAddress).matches()) {
            return false;
        }

        if ((testUuid != null) && !StudentUtil.isPossibleUuid(testUuid)) {
            return false;
        }

        return true;
    }

    @Override
    public String toString() {
        // FIXME: this is unsafe!
        return String.format("NameAndEmailAddress('%s', '%s', %s)", name, emailAddress, testUuid);
    }
}

We make similar changes to the other REST transfer objects.

We can now write our AOP methods to check the parameters to our CRUD operations. As before the logs are written using the logger associated with the Resource instead of the AOP class.

These methods also log the entry of the Resource methods. Again it’s boilerplate and doing it here simplifies the Resource methods. It would be trivial to also log the method’s exit and elapsed time but we should use a stock logger AOP class in that case.

@Aspect
@Component
public class CheckPostValues {
/**
* Check post values on create method.
*
* @param pjp
* @return
* @throws Throwable
*/
@Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(validatable,..)")
public Object checkParametersCreate(ProceedingJoinPoint pjp, Validatable rto) throws Throwable {
final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
final String name = pjp.getSignature().getName();
Object results = null;
if (rto.validate()) {
// this should be safe since parameters have been validated.
if (log.isDebugEnabled()) {
log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
}
results = pjp.proceed(pjp.getArgs());
} else {
// FIXME: this is unsafe
if (log.isInfoEnabled()) {
log.info(String.format("%s(%s): bad arguments", name, Arrays.toString(pjp.getArgs())));
}
// TODO: tell caller what the problems were
results = Response.status(Status.BAD_REQUEST).build();
}
return results;
}
/**
* Check post values on update method.
*
* @param pjp
* @return
* @throws Throwable
*/
@Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(uuid,validatable,..)")
public Object checkParametersUpdate(ProceedingJoinPoint pjp, String uuid, Validatable rto) throws Throwable {
final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
final String name = pjp.getSignature().getName();
Object results = null;
if (!StudentUtil.isPossibleUuid(uuid)) {
// this is a possible attack.
if (log.isInfoEnabled()) {
log.info(String.format("%s(): uuid", name));
}
results = Response.status(Status.BAD_REQUEST).build();
} else if (rto.validate()) {
// this should be safe since parameters have been validated.
if (log.isDebugEnabled()) {
log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
}
results = pjp.proceed(pjp.getArgs());
} else {
// FIXME: this is unsafe
if (log.isInfoEnabled()) {
log.info(String.format("%s(%s): bad arguments", name, Arrays.toString(pjp.getArgs())));
}
// TODO: tell caller what the problems were
results = Response.status(Status.BAD_REQUEST).build();
}
return results;
}
/**
* Check post values on delete method. This is actually a no-op but it
* allows us to log method entry.
*
* @param pjp
* @return
* @throws Throwable
*/
@Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(uuid,version) && execution(* *.delete*(..))")
public Object checkParametersDelete(ProceedingJoinPoint pjp, String uuid, Integer version) throws Throwable {
final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
final String name = pjp.getSignature().getName();
Object results = null;
if (!StudentUtil.isPossibleUuid(uuid)) {
// this is a possible attack.
if (log.isInfoEnabled()) {
log.info(String.format("%s(): uuid", name));
}
results = Response.status(Status.BAD_REQUEST).build();
} else {
// this should be safe since parameters have been validated.
if (log.isDebugEnabled()) {
log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
}
results = pjp.proceed(pjp.getArgs());
}
return results;
}
/**
* Check post values on find methods. This is actually a no-op but it allows
* us to log method entry.
*
* @param pjp
* @return
* @throws Throwable
*/
@Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && execution(* *.find*(..))")
public Object checkParametersFind(ProceedingJoinPoint pjp) throws Throwable {
final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
if (log.isDebugEnabled()) {
log.debug(String.format("%s(%s): entry", pjp.getSignature().getName(), Arrays.toString(pjp.getArgs())));
}
final Object results = pjp.proceed(pjp.getArgs());
return results;
}
}

@Aspect
@Component
public class CheckPostValues {

    /**
     * Check post values on create method.
     * 
     * @param pjp
     * @return
     * @throws Throwable
     */
    @Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(validatable,..)")
    public Object checkParametersCreate(ProceedingJoinPoint pjp, Validatable rto) throws Throwable {
        final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
        final String name = pjp.getSignature().getName();
        Object results = null;

        if (rto.validate()) {
            // this should be safe since parameters have been validated.
            if (log.isDebugEnabled()) {
                log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
            }
            results = pjp.proceed(pjp.getArgs());
        } else {
            // FIXME: this is unsafe
            if (log.isInfoEnabled()) {
                log.info(String.format("%s(%s): bad arguments", name, Arrays.toString(pjp.getArgs())));
            }
            // TODO: tell caller what the problems were
            results = Response.status(Status.BAD_REQUEST).build();
        }

        return results;
    }

    /**
     * Check post values on update method.
     * 
     * @param pjp
     * @return
     * @throws Throwable
     */
    @Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(uuid,validatable,..)")
    public Object checkParametersUpdate(ProceedingJoinPoint pjp, String uuid, Validatable rto) throws Throwable {
        final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
        final String name = pjp.getSignature().getName();
        Object results = null;

        if (!StudentUtil.isPossibleUuid(uuid)) {
            // this is a possible attack.
            if (log.isInfoEnabled()) {
                log.info(String.format("%s(): uuid", name));
            }
            results = Response.status(Status.BAD_REQUEST).build();
        } else if (rto.validate()) {
            // this should be safe since parameters have been validated.
            if (log.isDebugEnabled()) {
                log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
            }
            results = pjp.proceed(pjp.getArgs());
        } else {
            // FIXME: this is unsafe
            if (log.isInfoEnabled()) {
                log.info(String.format("%s(%s): bad arguments", name, Arrays.toString(pjp.getArgs())));
            }
            // TODO: tell caller what the problems were
            results = Response.status(Status.BAD_REQUEST).build();
        }

        return results;
    }

    /**
     * Check post values on delete method. This is actually a no-op but it
     * allows us to log method entry.
     * 
     * @param pjp
     * @return
     * @throws Throwable
     */
    @Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && args(uuid,version) && execution(* *.delete*(..))")
    public Object checkParametersDelete(ProceedingJoinPoint pjp, String uuid, Integer version) throws Throwable {
        final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());
        final String name = pjp.getSignature().getName();
        Object results = null;

        if (!StudentUtil.isPossibleUuid(uuid)) {
            // this is a possible attack.
            if (log.isInfoEnabled()) {
                log.info(String.format("%s(): uuid", name));
            }
            results = Response.status(Status.BAD_REQUEST).build();
        } else {
            // this should be safe since parameters have been validated.
            if (log.isDebugEnabled()) {
                log.debug(String.format("%s(%s): entry", name, Arrays.toString(pjp.getArgs())));
            }
            results = pjp.proceed(pjp.getArgs());
        }

        return results;
    }

    /**
     * Check post values on find methods. This is actually a no-op but it allows
     * us to log method entry.
     * 
     * @param pjp
     * @return
     * @throws Throwable
     */
    @Around("target(com.invariantproperties.sandbox.student.webservice.server.rest.AbstractResource) && execution(* *.find*(..))")
    public Object checkParametersFind(ProceedingJoinPoint pjp) throws Throwable {
        final Logger log = Logger.getLogger(pjp.getSignature().getDeclaringType());

        if (log.isDebugEnabled()) {
            log.debug(String.format("%s(%s): entry", pjp.getSignature().getName(), Arrays.toString(pjp.getArgs())));
        }
        final Object results = pjp.proceed(pjp.getArgs());

        return results;
    }
}

Updated Spring Configuration

We must tell Spring to search for AOP classes. This is a one-line change to our configuration file.

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

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

    <aop:aspectj-autoproxy/>
</beans>

Updated Resource

We can now simplify our Resource classes. Several methods have been reduced to the happy path alone.

@Service
@Path("/course")
public class CourseResource extends AbstractResource {
private static final Logger LOG = Logger.getLogger(CourseResource.class);
private static final Course[] EMPTY_COURSE_ARRAY = new Course[0];
@Resource
private CourseFinderService finder;
@Resource
private CourseManagerService manager;
@Resource
private TestRunService testRunService;
/**
* Default constructor.
*/
public CourseResource() {
}
/**
* Set values used in unit tests. (Required due to AOP)
*
* @param finder
* @param manager
* @param testService
*/
void setServices(CourseFinderService finder, CourseManagerService manager, TestRunService testRunService) {
this.finder = finder;
this.manager = manager;
this.testRunService = testRunService;
}
/**
* Get all Courses.
*
* @return
*/
@GET
@Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
public Response findAllCourses() {
final List courses = finder.findAllCourses();
final List results = new ArrayList(courses.size());
for (Course course : courses) {
results.add(scrubCourse(course));
}
final Response response = Response.ok(results.toArray(EMPTY_COURSE_ARRAY)).build();
return response;
}
/**
* Create a Course.
*
* FIXME: what about uniqueness violations?
*
* @param req
* @return
*/
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
public Response createCourse(CourseInfo req) {
final String code = req.getCode();
final String name = req.getName();
Response response = null;
Course course = null;
if (req.getTestUuid() != null) {
TestRun testRun = testRunService.findTestRunByUuid(req.getTestUuid());
if (testRun != null) {
course = manager.createCourseForTesting(code, name, req.getSummary(), req.getDescription(),
req.getCreditHours(), testRun);
} else {
response = Response.status(Status.BAD_REQUEST).entity("unknown test UUID").build();
}
} else {
course = manager.createCourse(code, name, req.getSummary(), req.getDescription(), req.getCreditHours());
}
if (course == null) {
response = Response.status(Status.INTERNAL_SERVER_ERROR).build();
} else {
response = Response.created(URI.create(course.getUuid())).entity(scrubCourse(course)).build();
}
return response;
}
/**
* Get a specific Course.
*
* @param uuid
* @return
*/
@Path("/{courseId}")
@GET
@Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
public Response getCourse(@PathParam("courseId") String id) {
// 'object not found' handled by AOP
Course course = finder.findCourseByUuid(id);
final Response response = Response.ok(scrubCourse(course)).build();
return response;
}
/**
* Update a Course.
*
* FIXME: what about uniqueness violations?
*
* @param id
* @param req
* @return
*/
@Path("/{courseId}")
@POST
@Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
@Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
public Response updateCourse(@PathParam("courseId") String id, CourseInfo req) {
final String name = req.getName();
// 'object not found' handled by AOP
final Course course = finder.findCourseByUuid(id);
final Course updatedCourse = manager.updateCourse(course, name, req.getSummary(), req.getDescription(),
req.getCreditHours());
final Response response = Response.ok(scrubCourse(updatedCourse)).build();
return response;
}
/**
* Delete a Course.
*
* @param id
* @return
*/
@Path("/{courseId}")
@DELETE
public Response deleteCourse(@PathParam("courseId") String id, @PathParam("version") Integer version) {
// we don't use AOP handler since it's okay for there to be no match
try {
manager.deleteCourse(id, version);
} catch (ObjectNotFoundException exception) {
LOG.debug("course not found: " + id);
}
final Response response = Response.noContent().build();
return response;
}
}

@Service
@Path("/course")
public class CourseResource extends AbstractResource {
    private static final Logger LOG = Logger.getLogger(CourseResource.class);
    private static final Course[] EMPTY_COURSE_ARRAY = new Course[0];

    @Resource
    private CourseFinderService finder;

    @Resource
    private CourseManagerService manager;

    @Resource
    private TestRunService testRunService;

    /**
     * Default constructor.
     */
    public CourseResource() {

    }

    /**
     * Set values used in unit tests. (Required due to AOP)
     * 
     * @param finder
     * @param manager
     * @param testService
     */
    void setServices(CourseFinderService finder, CourseManagerService manager, TestRunService testRunService) {
        this.finder = finder;
        this.manager = manager;
        this.testRunService = testRunService;
    }

    /**
     * Get all Courses.
     * 
     * @return
     */
    @GET
    @Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    public Response findAllCourses() {
        final List courses = finder.findAllCourses();

        final List results = new ArrayList(courses.size());
        for (Course course : courses) {
            results.add(scrubCourse(course));
        }

        final Response response = Response.ok(results.toArray(EMPTY_COURSE_ARRAY)).build();

        return response;
    }

    /**
     * Create a Course.
     * 
     * FIXME: what about uniqueness violations?
     * 
     * @param req
     * @return
     */
    @POST
    @Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    @Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    public Response createCourse(CourseInfo req) {
        final String code = req.getCode();
        final String name = req.getName();

        Response response = null;
        Course course = null;

        if (req.getTestUuid() != null) {
            TestRun testRun = testRunService.findTestRunByUuid(req.getTestUuid());
            if (testRun != null) {
                course = manager.createCourseForTesting(code, name, req.getSummary(), req.getDescription(),
                        req.getCreditHours(), testRun);
            } else {
                response = Response.status(Status.BAD_REQUEST).entity("unknown test UUID").build();
            }
        } else {
            course = manager.createCourse(code, name, req.getSummary(), req.getDescription(), req.getCreditHours());
        }
        if (course == null) {
            response = Response.status(Status.INTERNAL_SERVER_ERROR).build();
        } else {
            response = Response.created(URI.create(course.getUuid())).entity(scrubCourse(course)).build();
        }

        return response;
    }

    /**
     * Get a specific Course.
     * 
     * @param uuid
     * @return
     */
    @Path("/{courseId}")
    @GET
    @Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    public Response getCourse(@PathParam("courseId") String id) {

        // 'object not found' handled by AOP
        Course course = finder.findCourseByUuid(id);
        final Response response = Response.ok(scrubCourse(course)).build();

        return response;
    }

    /**
     * Update a Course.
     * 
     * FIXME: what about uniqueness violations?
     * 
     * @param id
     * @param req
     * @return
     */
    @Path("/{courseId}")
    @POST
    @Consumes({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    @Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    public Response updateCourse(@PathParam("courseId") String id, CourseInfo req) {

        final String name = req.getName();

        // 'object not found' handled by AOP
        final Course course = finder.findCourseByUuid(id);
        final Course updatedCourse = manager.updateCourse(course, name, req.getSummary(), req.getDescription(),
                req.getCreditHours());
        final Response response = Response.ok(scrubCourse(updatedCourse)).build();

        return response;
    }

    /**
     * Delete a Course.
     * 
     * @param id
     * @return
     */
    @Path("/{courseId}")
    @DELETE
    public Response deleteCourse(@PathParam("courseId") String id, @PathParam("version") Integer version) {

        // we don't use AOP handler since it's okay for there to be no match
        try {
            manager.deleteCourse(id, version);
        } catch (ObjectNotFoundException exception) {
            LOG.debug("course not found: " + id);
        }

        final Response response = Response.noContent().build();

        return response;
    }
}

Unit Tests

The unit tests require a change to every test since we can’t simply instantiate the objects being tested – we must use Spring so the AOP classes are properly weaved. Fortunately that’s essentially the only change – we retrieve the Resource and set the services via a package-private method instead of via package-private constructors.

We also need to create Spring values for our service beans. A Configurer class takes care of this.

@Configuration
@ComponentScan(basePackages = { "com.invariantproperties.sandbox.student.webservice.server.rest" })
@ImportResource({ "classpath:applicationContext-rest.xml" })
// @PropertySource("classpath:application.properties")
public class TestRestApplicationContext1 {
@Bean
public CourseFinderService courseFinderService() {
return null;
}
@Bean
public CourseManagerService courseManagerService() {
return null;
}
....

@Configuration
@ComponentScan(basePackages = { "com.invariantproperties.sandbox.student.webservice.server.rest" })
@ImportResource({ "classpath:applicationContext-rest.xml" })
// @PropertySource("classpath:application.properties")
public class TestRestApplicationContext1 {

    @Bean
    public CourseFinderService courseFinderService() {
        return null;
    }

    @Bean
    public CourseManagerService courseManagerService() {
        return null;
    }

    ....

Integration Tests

The integration tests do not require any changes.

Source Code

The source code is at https://github.com/beargiles/project-student [github] and http://beargiles.github.io/project-student/ [github pages].

Comments: No Comments »
Categories: java
Comments rss
Trackback

Check your REST parameters!

Bear Giles | January 6, 2014

I was doing research related to my ongoing “project student” series and realized that I had made one of the most common – and most easily remedied – mistakes. I wasn’t using everything I know about the webapp to push my security perimeter outwards.

I am thinking specifically about the UUID parameters. I know that every valid externally visible ID will be a UUID. I know the form of the UUIDs. So why don’t I verify that my “uuid” parameters are potentially valid UUIDs before going any further?

It’s true that the database layer won’t recognize a bad “uuid” value – but that may not be the intent of the attacker. Perhaps it’s part of a SQL injection attack. Perhaps it’s part of an XSS attack. Perhaps it’s part of an attack on my logs (e.g., by including a really long value that might cause a buffer overflow). Perhaps it’s part of something I’ve never heard of. It doesn’t matter – I will always be stronger by eliminating known-invalid data as quickly as possible.

Utility Method

The utility method to determine whether a value is a possible UUID uses a simple regex pattern.

public final class StudentUtil {
private static final Pattern UUID_PATTERN = Pattern
.compile("^\\p{XDigit}{8}+-\\p{XDigit}{4}+-\\p{XDigit}{4}-\\p{XDigit}{4}+-\\p{XDigit}{12}$");
/**
* Private constructor to prevent instantiation.
*/
private StudentUtil() {
}
public static boolean isPossibleUuid(String value) {
return value != null && UUID_PATTERN.matcher(value).matches();
}
}

public final class StudentUtil {
    private static final Pattern UUID_PATTERN = Pattern
            .compile("^\\p{XDigit}{8}+-\\p{XDigit}{4}+-\\p{XDigit}{4}-\\p{XDigit}{4}+-\\p{XDigit}{12}$");

    /**
     * Private constructor to prevent instantiation.
     */
    private StudentUtil() {

    }

    public static boolean isPossibleUuid(String value) {
        return value != null && UUID_PATTERN.matcher(value).matches();
    }
}

If we want to be aggressive we could carefully select our UUIDs so they have additional properties that we can check. For instance the corresponding BigInteger could always have a remainder of 3 mod 17. It’s unlikely an attack would know this and we would have warning when somebody is probing our system. An even more sophisticated approach would use a different property for each class of UUID, e.g., a ‘course’ UUID might be 3 mod 17 while a ‘student’ UUID is 5 mod 17.

Unit Test

It’s easy to go overboard on our tests but a minimal set would be checking for non-hex digits,
too many or too few values, an empty string, and a null value.

public class StudentUtilTest {
@Test
public void testValidUuid() {
assertTrue(StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e1"));
}
@Test
public void testInvalidUuid() {
assertTrue(!StudentUtil.isPossibleUuid("63c7d68x-705c-4374-937c-6628952b41e1"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d68-8705c-4374-937c-6628952b41e1"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c4-374-937c-6628952b41e1"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-43749-37c-6628952b41e1"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c6-628952b41e1"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e1a"));
assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e"));
assertTrue(!StudentUtil.isPossibleUuid(""));
assertTrue(!StudentUtil.isPossibleUuid(null));
}
}

public class StudentUtilTest {

    @Test
    public void testValidUuid() {
        assertTrue(StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e1"));
    }

    @Test
    public void testInvalidUuid() {
        assertTrue(!StudentUtil.isPossibleUuid("63c7d68x-705c-4374-937c-6628952b41e1"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d68-8705c-4374-937c-6628952b41e1"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c4-374-937c-6628952b41e1"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-43749-37c-6628952b41e1"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c6-628952b41e1"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e1a"));
        assertTrue(!StudentUtil.isPossibleUuid("63c7d688-705c-4374-937c-6628952b41e"));
        assertTrue(!StudentUtil.isPossibleUuid(""));
        assertTrue(!StudentUtil.isPossibleUuid(null));
    }
}

REST Server

The REST server should check the UUID value for all methods that require one. It’s safe to log the request parameter after we’ve verified it’s a well-formed UUID but still need to be careful about logging unsanitized values in the request.

@Path("/{courseId}")
@GET
@Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
public Response getCourse(@PathParam("courseId") String id) {
Response response = null;
if (!StudentUtil.isPossibleUuid(id)) {
response = Response.status(Status.BAD_REQUEST).build();
LOG.info("attempt to use malformed UUID");
} else {
LOG.debug("CourseResource: getCourse(" + id + ")");
try {
Course course = finder.findCourseByUuid(id);
response = Response.ok(scrubCourse(course)).build();
} catch (ObjectNotFoundException e) {
response = Response.status(Status.NOT_FOUND).build();
LOG.debug("course not found: " + id);
} catch (Exception e) {
if (!(e instanceof UnitTestException)) {
LOG.info("unhandled exception", e);
}
response = Response.status(Status.INTERNAL_SERVER_ERROR).build();
}
}
return response;
}

    @Path("/{courseId}")
    @GET
    @Produces({ MediaType.APPLICATION_JSON, MediaType.TEXT_XML })
    public Response getCourse(@PathParam("courseId") String id) {

        Response response = null;
        if (!StudentUtil.isPossibleUuid(id)) {
            response = Response.status(Status.BAD_REQUEST).build();
            LOG.info("attempt to use malformed UUID");
        } else {
            LOG.debug("CourseResource: getCourse(" + id + ")");
            try {
                Course course = finder.findCourseByUuid(id);
                response = Response.ok(scrubCourse(course)).build();
            } catch (ObjectNotFoundException e) {
                response = Response.status(Status.NOT_FOUND).build();
                LOG.debug("course not found: " + id);
            } catch (Exception e) {
                if (!(e instanceof UnitTestException)) {
                    LOG.info("unhandled exception", e);
                }
                response = Response.status(Status.INTERNAL_SERVER_ERROR).build();
            }
        }

        return response;
    }

An obvious improvement is to move this check (and the exception catchall) into an AOP wrapper to all service methods. This will simplify the code and go a long way towards guaranteeing that the checks are always performed. (I’m not using it in Project Student at the moment since the webservice server layer doesn’t currently have Spring dependencies.)

You can make a strong opsec argument that the REST methods should return a NOT_FOUND response instead of a BAD_REQUEST response in order to reduce information leakage.

Webapps

The details differ but we should do the same thing with webapps even if they’re just shallow front-ends to REST services. Whenever there’s a UUID, no matter it’s source, it should be checked before it is used.

Filters

There is a school of thought that security should be handled separately from the application – that the best security is knit in at deployment (via filters and AOP) instead of being baked into the application. Nobody is suggesting that app developers should ignore security considerations, just that checks like I discussed above are clutter that distract the developer and aren’t reliable since it’s easy for a developer to overlook. They would recommend using AOP or a filter instead.

It’s straightforward to write a filter that does the same work as the code above:

public class RestParameterFilter implements Filter {
private static final Logger LOG = Logger.getLogger(RestParameterFilter.class);
private static final Set<String> validNouns = new HashSet<>();
/**
* @see javax.servlet.Filter#init(javax.servlet.FilterConfig)
*/
@Override
public void init(FilterConfig cfg) throws ServletException {
// learn valid nouns
final String nouns = cfg.getInitParameter("valid-nouns");
if (nouns != null) {
for (String noun : nouns.split(",")) {
validNouns.add(noun.trim());
}
}
}
/**
* @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
* javax.servlet.ServletResponse, javax.servlet.FilterChain)
*/
@Override
public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException,
ServletException {
HttpServletRequest hreq = (HttpServletRequest) req;
HttpServletResponse hresp = (HttpServletResponse) resp;
// verify the noun + uuid
if (!checkPathInfo(hreq, hresp)) {
return;
}
// do additional tests, e.g., inspect payload
chain.doFilter(req, resp);
}
/**
* @see javax.servlet.Filter#destroy()
*/
@Override
public void destroy() {
}
/**
* Check the pathInfo. We know that all paths should have the form
* /{noun}/{uuid}/...
*
* @param req
* @return
*/
public boolean checkPathInfo(HttpServletRequest req, HttpServletResponse resp) {
// this pattern only handles noun and UUID, no additional parameters.
Pattern pattern = Pattern.compile("^/([\\p{Alpha}]+)(/?([\\p{XDigit}-]+)?)?");
Matcher matcher = pattern.matcher(req.getPathInfo());
matcher.find();
// verify this is a valid noun.
if ((matcher.groupCount() >= 1) && !validNouns.contains(matcher.group(1))) {
// LOG.info("unrecognized noun");
LOG.info("unrecognized noun: '" + matcher.group(1) + "'");
resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
return false;
}
// verify this is a valid verb.
if ((matcher.groupCount() >= 4) && !StudentUtil.isPossibleUuid(matcher.group(4))) {
LOG.info("invalid UUID");
resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
return false;
}
return true;
}
}

public class RestParameterFilter implements Filter {
    private static final Logger LOG = Logger.getLogger(RestParameterFilter.class);
    private static final Set<String> validNouns = new HashSet<>();

    /**
     * @see javax.servlet.Filter#init(javax.servlet.FilterConfig)
     */
    @Override
    public void init(FilterConfig cfg) throws ServletException {

        // learn valid nouns
        final String nouns = cfg.getInitParameter("valid-nouns");
        if (nouns != null) {
            for (String noun : nouns.split(",")) {
                validNouns.add(noun.trim());
            }
        }
    }

    /**
     * @see javax.servlet.Filter#doFilter(javax.servlet.ServletRequest,
     *      javax.servlet.ServletResponse, javax.servlet.FilterChain)
     */
    @Override
    public void doFilter(ServletRequest req, ServletResponse resp, FilterChain chain) throws IOException,
            ServletException {

        HttpServletRequest hreq = (HttpServletRequest) req;
        HttpServletResponse hresp = (HttpServletResponse) resp;

        // verify the noun + uuid
        if (!checkPathInfo(hreq, hresp)) {
            return;
        }

        // do additional tests, e.g., inspect payload

        chain.doFilter(req, resp);
    }

    /**
     * @see javax.servlet.Filter#destroy()
     */
    @Override
    public void destroy() {
    }

    /**
     * Check the pathInfo. We know that all paths should have the form
     * /{noun}/{uuid}/...
     * 
     * @param req
     * @return
     */
    public boolean checkPathInfo(HttpServletRequest req, HttpServletResponse resp) {
        // this pattern only handles noun and UUID, no additional parameters.
        Pattern pattern = Pattern.compile("^/([\\p{Alpha}]+)(/?([\\p{XDigit}-]+)?)?");
        Matcher matcher = pattern.matcher(req.getPathInfo());
        matcher.find();

        // verify this is a valid noun.
        if ((matcher.groupCount() >= 1) && !validNouns.contains(matcher.group(1))) {
            // LOG.info("unrecognized noun");
            LOG.info("unrecognized noun: '" + matcher.group(1) + "'");
            resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
            return false;
        }

        // verify this is a valid verb.
        if ((matcher.groupCount() >= 4) && !StudentUtil.isPossibleUuid(matcher.group(4))) {
            LOG.info("invalid UUID");
            resp.setStatus(HttpServletResponse.SC_BAD_REQUEST);
            return false;
        }

        return true;
    }
}

There’s no reason why we can’t also inspect the payload. For instance we can verify that dates, phone numbers and credit card numbers are properly formed; or that names only include letters (including non-Latin characters like ñ), spaces and apostrophes. (Think “Anne-Marie Peña O’Brien”.) It’s important to remember that these checks are not for ‘valid’ data – it’s to eliminate clearly ‘invalid’ data.

We must add the filter to our web.xml file.

web.xml

<filter>
<filter-name>REST parameter filter</filter-name>
<filter-class>com.invariantproperties.sandbox.student.webservice.security.RestParameterFilter</filter-class>
<init-param>
<param-name>valid-nouns</param-name>
<param-value>classroom,course,instructor,section,student,term,testRun</param-value>
</init-param>
</filter>
<filter-mapping>
<filter-name>REST parameter filter</filter-name>
<servlet-name>REST dispatcher</servlet-name>
</filter-mapping>

<filter>
    <filter-name>REST parameter filter</filter-name>
    <filter-class>com.invariantproperties.sandbox.student.webservice.security.RestParameterFilter</filter-class>
     <init-param>
        <param-name>valid-nouns</param-name>
        <param-value>classroom,course,instructor,section,student,term,testRun</param-value>
    </init-param>
</filter>

<filter-mapping>
    <filter-name>REST parameter filter</filter-name>
    <servlet-name>REST dispatcher</servlet-name>
</filter-mapping>

ModSecurity

It’s easy to write a filter for simple elements like phone numbers and names but plaintext fields are another matter. These fields need the maximum flexibility while at the same time we want to minimize the risk of XSS and other attacks.

A good resource along these lines is ModSecurity. This was originally an Apache module but it has been adopted by Trustwave Spider Labs. It sits on the web server – not the webapp – and inspects the data crossing it. A recent port (in summer 2013) allows it to be set up using a servlet filter instead of an external reverse proxy. (It uses JNI to instrument the containing appserver.)

For more information see ModSecurity for Java.

Comments: No Comments »
Categories: java, security
Comments rss
Trackback

Project Student: Maintenance Webapp (editable)

Bear Giles | January 4, 2014

This is part of Project Student. Other posts are Webservice Client With Jersey, Webservice Server with Jersey, Business Layer, Persistence with Spring Data, Sharding Integration Test Data, Webservice Integration, JPA Criteria Queries and Maintenance Webapp (read-only).

Last time we created a simple webapp that allows us to take a quick peek into the database. It had very limited functionality – the primary goal was to knit together a system that exercised the entire stack from web browser to database. This time we add actual CRUD support.

This post is borrows heavily from the jumpstart site but there are significant differences. There’s a lot of code but it’s boilerplate that can be easily reused.

Limitations

User authentication – no effort has been made to authenticate users.

Encryption – no effort has been made to encrypt communications.

Pagination – no effort has been made to support pagination. The Tapestry 5 component will give the appearance of pagination but it will always contain the same first page of data.

Error Messages – error messages will be shown but server-side errors will be uninformative for now.

Cross-Site Scripting (XSS) – no effort has been made to prevent XSS attacks.

Internationalization – no effort has been made to support internationalization.

Goal

We want the standard CRUD pages.

First, we need to be able to create a new course. Our list of courses should include a link as a default message when we don’t have any data. (The first “create…” is a separate element.)

Now a creation page with several fields. A code uniquely identifies a course, e.g., CSCI 101, and name, summary and description should be self-explanatory.

After successful creation we’re taken to a review page.

And then back to an update page if we need to make a change.

At any point we can go back to the list page.

We’re prompted for confirmation before deleting a record.

And finally we’re able to show server-side errors, e.g., for duplicate values in unique fields, even if the messages are pretty useless at the moment.

We also have client-side error checking although I don’t show it here.

Index.tml

We start with the index page. It’s similar to what we saw in the last post.

Tapestry 5 has three major types of links. A pagelink is mapped to a standard HTML link. An actionlink is directly handled by the corresponding class, e.g., Index.java for the Index.tml template. Finally an eventlink injects an event into the normal event flow within the tapestry engine. All of my links go to a closely related page so I use an actionlink.

<html t:type="layout" title="Course List"
t:sidebarTitle="Framework Version"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd"
xmlns:p="tapestry:parameter">
<t:zone t:id="zone">
<p>
"Course" page
</p>
<t:actionlink t:id="create">Create...</t:actionlink><br/>
<t:grid source="courses" row="course" include="code, name,creationdate" add="edit,delete">
<p:codecell>
<t:actionlink t:id="view" context="course.uuid">${course.code}</t:actionlink>
</p:codecell>
<p:editcell>
<t:actionlink t:id="update" context="course.uuid">Edit</t:actionlink>
</p:editcell>
<p:deletecell>
<t:actionlink t:id="delete" context="course.uuid" t:mixins="Confirm" t:message="Delete ${course.name}?">Delete</t:actionlink>
</p:deletecell>
<p:empty>
<p>There are no courses to display; you can <t:actionlink t:id="create1">create</t:actionlink> one.</p>
</p:empty>
</t:grid>
</t:zone>
<p:sidebar>
<p>
[
<t:pagelink page="Index">Index</t:pagelink>
]<br/>
[
<t:pagelink page="Course/Index">Courses</t:pagelink>
]
</p>
</p:sidebar>
</html>

<html t:type="layout" title="Course List"
      t:sidebarTitle="Framework Version"
      xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd"
      xmlns:p="tapestry:parameter">

    <t:zone t:id="zone">   
        <p>
            "Course" page
        </p>

        <t:actionlink t:id="create">Create...</t:actionlink><br/>
 
        <t:grid source="courses" row="course" include="code, name,creationdate" add="edit,delete">
            <p:codecell>
                <t:actionlink t:id="view" context="course.uuid">${course.code}</t:actionlink>
            </p:codecell>
            <p:editcell>
                <t:actionlink t:id="update" context="course.uuid">Edit</t:actionlink>
            </p:editcell>
            <p:deletecell>
                <t:actionlink t:id="delete" context="course.uuid" t:mixins="Confirm" t:message="Delete ${course.name}?">Delete</t:actionlink>
            </p:deletecell>
            <p:empty>
              <p>There are no courses to display; you can <t:actionlink t:id="create1">create</t:actionlink> one.</p>
            </p:empty>
        </t:grid>
    </t:zone>

    <p:sidebar>
        <p>
            [
            <t:pagelink page="Index">Index</t:pagelink>
            ]<br/>
            [
            <t:pagelink page="Course/Index">Courses</t:pagelink>
            ]
        </p>
    </p:sidebar>

</html>

Confirm mixin

The Index.tml template included a ‘mixin’ on the delete actionlink. It uses a mixture of javascript and java to display a popup message to ask the user to verify that he wants to delete the course.

This code is straight from the jumpstart and Tapestry sites.

// from http://jumpstart.doublenegative.com.au/
Confirm = Class.create({
initialize: function(elementId, message) {
this.message = message;
Event.observe($(elementId), 'click', this.doConfirm.bindAsEventListener(this));
},
doConfirm: function(e) {
// Pop up a javascript Confirm Box (see http://www.w3schools.com/js/js_popup.asp)
if (!confirm(this.message)) {
e.stop();
}
}
})
// Extend the Tapestry.Initializer with a static method that instantiates a Confirm.
Tapestry.Initializer.confirm = function(spec) {
new Confirm(spec.elementId, spec.message);
}

// from http://jumpstart.doublenegative.com.au/
Confirm = Class.create({
        
    initialize: function(elementId, message) {
        this.message = message;
        Event.observe($(elementId), 'click', this.doConfirm.bindAsEventListener(this));
    },
    
    doConfirm: function(e) {
        
        // Pop up a javascript Confirm Box (see http://www.w3schools.com/js/js_popup.asp)
        
        if (!confirm(this.message)) {
                e.stop();
        }
    }
})

// Extend the Tapestry.Initializer with a static method that instantiates a Confirm.

Tapestry.Initializer.confirm = function(spec) {
    new Confirm(spec.elementId, spec.message);
}

The corresponding java code is

// from http://jumpstart.doublenegative.com.au/
@Import(library = "confirm.js")
public class Confirm {
@Parameter(name = "message", value = "Are you sure?", defaultPrefix = BindingConstants.LITERAL)
private String message;
@Inject
private JavaScriptSupport javaScriptSupport;
@InjectContainer
private ClientElement clientElement;
@AfterRender
public void afterRender() {
// Tell the Tapestry.Initializer to do the initializing of a Confirm,
// which it will do when the DOM has been
// fully loaded.
JSONObject spec = new JSONObject();
spec.put("elementId", clientElement.getClientId());
spec.put("message", message);
javaScriptSupport.addInitializerCall("confirm", spec);
}
}

// from http://jumpstart.doublenegative.com.au/
@Import(library = "confirm.js")
public class Confirm {

    @Parameter(name = "message", value = "Are you sure?", defaultPrefix = BindingConstants.LITERAL)
    private String message;

    @Inject
    private JavaScriptSupport javaScriptSupport;

    @InjectContainer
    private ClientElement clientElement;

    @AfterRender
    public void afterRender() {

        // Tell the Tapestry.Initializer to do the initializing of a Confirm,
        // which it will do when the DOM has been
        // fully loaded.

        JSONObject spec = new JSONObject();
        spec.put("elementId", clientElement.getClientId());
        spec.put("message", message);
        javaScriptSupport.addInitializerCall("confirm", spec);
    }
}

Index.java

The java that supports the index template is straightforward since we only need to define a data source and provide a few action handlers.

package com.invariantproperties.sandbox.student.maintenance.web.pages.course;
public class Index {
@Property
@Inject
@Symbol(SymbolConstants.TAPESTRY_VERSION)
private String tapestryVersion;
@InjectComponent
private Zone zone;
@Inject
private CourseFinderService courseFinderService;
@Inject
private CourseManagerService courseManagerService;
@Property
private Course course;
// our sibling page
@InjectPage
private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Editor editorPage;
/**
* Get the datasource containing our data.
*
* @return
*/
public GridDataSource getCourses() {
return new CoursePagedDataSource(courseFinderService);
}
/**
* Handle a delete request. This could fail, e.g., if the course has already
* been deleted.
*
* @param courseUuid
*/
void onActionFromDelete(String courseUuid) {
courseManagerService.deleteCourse(courseUuid, 0);
}
/**
* Bring up editor page in create mode.
*
* @param courseUuid
* @return
*/
Object onActionFromCreate() {
editorPage.setup(Mode.CREATE, null);
return editorPage;
}
/**
* Bring up editor page in create mode.
*
* @param courseUuid
* @return
*/
Object onActionFromCreate1() {
return onActionFromCreate();
}
/**
* Bring up editor page in review mode.
*
* @param courseUuid
* @return
*/
Object onActionFromView(String courseUuid) {
editorPage.setup(Mode.REVIEW, courseUuid);
return editorPage;
}
/**
* Bring up editor page in update mode.
*
* @param courseUuid
* @return
*/
Object onActionFromUpdate(String courseUuid) {
editorPage.setup(Mode.UPDATE, courseUuid);
return editorPage;
}
}

package com.invariantproperties.sandbox.student.maintenance.web.pages.course;

public class Index {
    @Property
    @Inject
    @Symbol(SymbolConstants.TAPESTRY_VERSION)
    private String tapestryVersion;

    @InjectComponent
    private Zone zone;

    @Inject
    private CourseFinderService courseFinderService;

    @Inject
    private CourseManagerService courseManagerService;

    @Property
    private Course course;

    // our sibling page
    @InjectPage
    private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Editor editorPage;

    /**
     * Get the datasource containing our data.
     * 
     * @return
     */
    public GridDataSource getCourses() {
        return new CoursePagedDataSource(courseFinderService);
    }

    /**
     * Handle a delete request. This could fail, e.g., if the course has already
     * been deleted.
     * 
     * @param courseUuid
     */
    void onActionFromDelete(String courseUuid) {
        courseManagerService.deleteCourse(courseUuid, 0);
    }

    /**
     * Bring up editor page in create mode.
     * 
     * @param courseUuid
     * @return
     */
    Object onActionFromCreate() {
        editorPage.setup(Mode.CREATE, null);
        return editorPage;
    }

    /**
     * Bring up editor page in create mode.
     * 
     * @param courseUuid
     * @return
     */
    Object onActionFromCreate1() {
        return onActionFromCreate();
    }

    /**
     * Bring up editor page in review mode.
     * 
     * @param courseUuid
     * @return
     */
    Object onActionFromView(String courseUuid) {
        editorPage.setup(Mode.REVIEW, courseUuid);
        return editorPage;
    }

    /**
     * Bring up editor page in update mode.
     * 
     * @param courseUuid
     * @return
     */
    Object onActionFromUpdate(String courseUuid) {
        editorPage.setup(Mode.UPDATE, courseUuid);
        return editorPage;
    }
}

Editor.tml

The CRUD pages could be three separate pages (for create, review and update) or a single page. I’m following the pattern used by the jumpstart site – a single page. I’ll be honest – I’m not sure why he made this decision – perhaps it is because the pages are closely related and he uses event processing? In any case I’ll discuss the elements separately.

CREATE template

The “create” template is a simple form. You can see that HTML <input> elements are enhanced with some tapestry-specific attributes, plus a few additional tags like <t:errors/> and <t:submit>.

The CustomForm and CustomError are local extensions to the standard Tapestry Form and Error classes. They’re currently empty but allow us to easily add local extensions.

<html t:type="layout" title="Course Editor"
t:sidebarTitle="Framework Version"
xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd" xmlns:p="tapestry:parameter">
<t:zone t:id="zone">
<t:if test="modeCreate">
<h1>Create</h1>
<form t:type="form" t:id="createForm" >
<t:errors/>
<table>
<tr>
<th><t:label for="code"/>:</th>
<td><input t:type="TextField" t:id="code" value="course.code" t:validate="required, maxlength=12" size="12"/></td>
<td>(required)</td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="code"/></td>
</tr>
<tr>
<th><t:label for="name"/>:</th>
<td><input t:type="TextField" t:id="name" value="course.name" t:validate="required, maxlength=80" size="45"/></td>
<td>(required)</td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="name"/></td>
</tr>
<tr>
<th><t:label for="summary"/>:</th>
<td><input cols="50" rows="4" t:type="TextArea" t:id="summary" value="course.summary" t:validate="maxlength=400"/></td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="summary"/></td>
</tr>
<tr>
<th><t:label for="description"/>:</th>
<td><input cols="50" rows="12" t:type="TextArea" t:id="description" value="course.description" t:validate="maxlength=2000"/></td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="description"/></td>
</tr>
</table>
<div class="buttons">
<t:submit t:event="cancelCreate" t:context="course.uuid" value="Cancel"/>
<input type="submit" value="Save"/>
</div>
</form>
</t:if>
...
</html>

<html t:type="layout" title="Course Editor"
      t:sidebarTitle="Framework Version"
      xmlns:t="http://tapestry.apache.org/schema/tapestry_5_3.xsd" xmlns:p="tapestry:parameter">

    <t:zone t:id="zone">   

    <t:if test="modeCreate">
        <h1>Create</h1>
        
        <form t:type="form" t:id="createForm" >
            <t:errors/>
    
            <table>
                <tr>
                    <th><t:label for="code"/>:</th>
                    <td><input t:type="TextField" t:id="code" value="course.code" t:validate="required, maxlength=12" size="12"/></td>
                    <td>(required)</td>
                </tr>
                <tr class="err">
                    <th></th>
                    <td colspan="2"><t:CustomError for="code"/></td>
                </tr>
                <tr>
                    <th><t:label for="name"/>:</th>
                    <td><input t:type="TextField" t:id="name" value="course.name" t:validate="required, maxlength=80" size="45"/></td>
                    <td>(required)</td>
                </tr>
                <tr class="err">
                    <th></th>
                    <td colspan="2"><t:CustomError for="name"/></td>
                </tr>
                <tr>
                    <th><t:label for="summary"/>:</th>
                    <td><input cols="50" rows="4" t:type="TextArea" t:id="summary" value="course.summary" t:validate="maxlength=400"/></td>
                </tr>
                <tr class="err">
                    <th></th>
                    <td colspan="2"><t:CustomError for="summary"/></td>
                </tr>
                <tr>
                    <th><t:label for="description"/>:</th>
                    <td><input cols="50" rows="12" t:type="TextArea" t:id="description" value="course.description" t:validate="maxlength=2000"/></td>
                </tr>
                <tr class="err">
                    <th></th>
                    <td colspan="2"><t:CustomError for="description"/></td>
                </tr>
            </table>

            <div class="buttons">
                <t:submit t:event="cancelCreate" t:context="course.uuid" value="Cancel"/>
                <input type="submit" value="Save"/>
            </div>
        </form>
    </t:if>

    ...
</html>

CREATE java

The corresponding java class is straightforward. We must define a few custom events.

The ActivationRequestParameter values are pulled from the URL query string.

The course field contains the values to be used when creating a new object.

The courseForm field contains the corresponding <form> on the template.

The indexPage contains a reference to the index page.

There are four event handlers named onEventFromCreateForm, where event
can be prepare, validate, success or failure. Each event handler has very specific roles.

There is one additional event handler, onCancelCreate(). You can see the name of that event in the <t:submit> tag in the template.

/**
* This component will trigger the following events on its container (which in
* this example is the page):
* {@link Editor.web.components.examples.component.crud.Editor#CANCEL_CREATE} ,
* {@link Editor.web.components.examples.component.crud.Editor#SUCCESSFUL_CREATE}
* (Long courseUuid),
* {@link Editor.web.components.examples.component.crud.Editor#FAILED_CREATE} ,
*/
// @Events is applied to a component solely to document what events it may
// trigger. It is not checked at runtime.
@Events({ Editor.CANCEL_CREATE, Editor.SUCCESSFUL_CREATE, Editor.FAILED_CREATE })
public class Editor {
public static final String CANCEL_CREATE = "cancelCreate";
public static final String SUCCESSFUL_CREATE = "successfulCreate";
public static final String FAILED_CREATE = "failedCreate";
public enum Mode {
CREATE, REVIEW, UPDATE;
}
// Parameters
@ActivationRequestParameter
@Property
private Mode mode;
@ActivationRequestParameter
@Property
private String courseUuid;
// Screen fields
@Property
private Course course;
// Work fields
// This carries version through the redirect that follows a server-side
// validation failure.
@Persist(PersistenceConstants.FLASH)
private Integer versionFlash;
// Generally useful bits and pieces
@Inject
private CourseFinderService courseFinderService;
@Inject
private CourseManagerService courseManagerService;
@Component
private CustomForm createForm;
@Inject
private ComponentResources componentResources;
@InjectPage
private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;
// The code
public void setup(Mode mode, String courseUuid) {
this.mode = mode;
this.courseUuid = courseUuid;
}
// setupRender() is called by Tapestry right before it starts rendering the
// component.
void setupRender() {
if (mode == Mode.REVIEW) {
if (courseUuid == null) {
course = null;
// Handle null course in the template.
} else {
if (course == null) {
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
// Handle null course in the template.
}
}
}
}
}
// /////////////////////////////////////////////////////////////////////
// CREATE
// /////////////////////////////////////////////////////////////////////
// Handle event "cancelCreate"
Object onCancelCreate() {
return indexPage;
}
// Component "createForm" bubbles up the PREPARE event when it is rendered
// or submitted
void onPrepareFromCreateForm() throws Exception {
// Instantiate a Course for the form data to overlay.
course = new Course();
}
// Component "createForm" bubbles up the VALIDATE event when it is submitted
void onValidateFromCreateForm() {
if (createForm.getHasErrors()) {
// We get here only if a server-side validator detected an error.
return;
}
try {
course = courseManagerService.createCourse(course.getCode(), course.getName(), course.getSummary(),
course.getDescription(), 1);
} catch (RestClientFailureException e) {
createForm.recordError("Internal error on server.");
createForm.recordError(e.getMessage());
} catch (Exception e) {
createForm.recordError(ExceptionUtil.getRootCauseMessage(e));
}
}
// Component "createForm" bubbles up SUCCESS or FAILURE when it is
// submitted, depending on whether VALIDATE
// records an error
boolean onSuccessFromCreateForm() {
componentResources.triggerEvent(SUCCESSFUL_CREATE, new Object[] { course.getUuid() }, null);
// We don't want "success" to bubble up, so we return true to say we've
// handled it.
mode = Mode.REVIEW;
courseUuid = course.getUuid();
return true;
}
boolean onFailureFromCreateForm() {
// Rather than letting "failure" bubble up which doesn't say what you
// were trying to do, we trigger new event
// "failedCreate". It will bubble up because we don't have a handler
// method for it.
componentResources.triggerEvent(FAILED_CREATE, null, null);
// We don't want "failure" to bubble up, so we return true to say we've
// handled it.
return true;
}
....
}

/**
 * This component will trigger the following events on its container (which in
 * this example is the page):
 * {@link Editor.web.components.examples.component.crud.Editor#CANCEL_CREATE} ,
 * {@link Editor.web.components.examples.component.crud.Editor#SUCCESSFUL_CREATE}
 * (Long courseUuid),
 * {@link Editor.web.components.examples.component.crud.Editor#FAILED_CREATE} ,
 */
// @Events is applied to a component solely to document what events it may
// trigger. It is not checked at runtime.
@Events({ Editor.CANCEL_CREATE, Editor.SUCCESSFUL_CREATE, Editor.FAILED_CREATE })
public class Editor {
    public static final String CANCEL_CREATE = "cancelCreate";
    public static final String SUCCESSFUL_CREATE = "successfulCreate";
    public static final String FAILED_CREATE = "failedCreate";

    public enum Mode {
        CREATE, REVIEW, UPDATE;
    }

    // Parameters

    @ActivationRequestParameter
    @Property
    private Mode mode;

    @ActivationRequestParameter
    @Property
    private String courseUuid;

    // Screen fields

    @Property
    private Course course;

    // Work fields

    // This carries version through the redirect that follows a server-side
    // validation failure.
    @Persist(PersistenceConstants.FLASH)
    private Integer versionFlash;

    // Generally useful bits and pieces

    @Inject
    private CourseFinderService courseFinderService;

    @Inject
    private CourseManagerService courseManagerService;

    @Component
    private CustomForm createForm;

    @Inject
    private ComponentResources componentResources;

    @InjectPage
    private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;

    // The code

    public void setup(Mode mode, String courseUuid) {
        this.mode = mode;
        this.courseUuid = courseUuid;
    }

    // setupRender() is called by Tapestry right before it starts rendering the
    // component.

    void setupRender() {

        if (mode == Mode.REVIEW) {
            if (courseUuid == null) {
                course = null;
                // Handle null course in the template.
            } else {
                if (course == null) {
                    try {
                        course = courseFinderService.findCourseByUuid(courseUuid);
                    } catch (ObjectNotFoundException e) {
                        // Handle null course in the template.
                    }
                }
            }
        }
    }

    // /////////////////////////////////////////////////////////////////////
    // CREATE
    // /////////////////////////////////////////////////////////////////////

    // Handle event "cancelCreate"

    Object onCancelCreate() {
        return indexPage;
    }

    // Component "createForm" bubbles up the PREPARE event when it is rendered
    // or submitted

    void onPrepareFromCreateForm() throws Exception {
        // Instantiate a Course for the form data to overlay.
        course = new Course();
    }

    // Component "createForm" bubbles up the VALIDATE event when it is submitted

    void onValidateFromCreateForm() {

        if (createForm.getHasErrors()) {
            // We get here only if a server-side validator detected an error.
            return;
        }

        try {
            course = courseManagerService.createCourse(course.getCode(), course.getName(), course.getSummary(),
                    course.getDescription(), 1);
        } catch (RestClientFailureException e) {
            createForm.recordError("Internal error on server.");
            createForm.recordError(e.getMessage());
        } catch (Exception e) {
            createForm.recordError(ExceptionUtil.getRootCauseMessage(e));
        }
    }

    // Component "createForm" bubbles up SUCCESS or FAILURE when it is
    // submitted, depending on whether VALIDATE
    // records an error

    boolean onSuccessFromCreateForm() {
        componentResources.triggerEvent(SUCCESSFUL_CREATE, new Object[] { course.getUuid() }, null);

        // We don't want "success" to bubble up, so we return true to say we've
        // handled it.
        mode = Mode.REVIEW;
        courseUuid = course.getUuid();
        return true;
    }

    boolean onFailureFromCreateForm() {
        // Rather than letting "failure" bubble up which doesn't say what you
        // were trying to do, we trigger new event
        // "failedCreate". It will bubble up because we don't have a handler
        // method for it.
        componentResources.triggerEvent(FAILED_CREATE, null, null);

        // We don't want "failure" to bubble up, so we return true to say we've
        // handled it.
        return true;
    }

    ....
}

REVIEW template

The “review” template is a simple table. It is wrapped in a form but that’s solely for the navigation buttons at the bottom of the page.

<t:if test="modeReview">
<h1>Review</h1>
<strong>Warning: no attempt is made to block XSS</strong>
<form t:type="form" t:id="reviewForm">
<t:errors/>
<t:if test="course">
<div t:type="if" t:test="deleteMessage" class="error">
${deleteMessage}
</div>
<table>
<tr>
<th>Uuid:</th>
<td>${course.uuid}</td>
</tr>
<tr>
<th>Code:</th>
<td>${course.code}</td>
</tr>
<tr>
<th>Name:</th>
<td>${course.name}</td>
</tr>
<tr>
<th>Summary:</th>
<td>${course.summary}</td>
</tr>
<tr>
<th>Description:</th>
<td>${course.description}</td>
</tr>
</table>
<div class="buttons">
<t:submit t:event="toIndex" t:context="course.uuid" value="List"/>
<t:submit t:event="toUpdate" t:context="course.uuid" value="Update"/>
<t:submit t:event="delete" t:context="course.uuid" t:mixins="Confirm" t:message="Delete ${course.name}?" value="Delete"/>
</div>
</t:if>
<t:if negate="true" test="course">
Course ${courseUuid} does not exist.<br/><br/>
</t:if>
</form>
</t:if>

    <t:if test="modeReview">
        <h1>Review</h1>
        
        <strong>Warning: no attempt is made to block XSS</strong>

        <form t:type="form" t:id="reviewForm">
            <t:errors/>
        
        <t:if test="course">
            <div t:type="if" t:test="deleteMessage" class="error">
                ${deleteMessage}
            </div>

            <table>
                <tr>
                    <th>Uuid:</th>
                    <td>${course.uuid}</td>
                </tr>
                <tr>
                    <th>Code:</th>
                    <td>${course.code}</td>
                </tr>
                <tr>
                    <th>Name:</th>
                    <td>${course.name}</td>
                </tr>
                <tr>
                    <th>Summary:</th>
                    <td>${course.summary}</td>
                </tr>
                <tr>
                    <th>Description:</th>
                    <td>${course.description}</td>
                </tr>
            </table>

            <div class="buttons">
                <t:submit t:event="toIndex" t:context="course.uuid" value="List"/>
                <t:submit t:event="toUpdate" t:context="course.uuid" value="Update"/>
                <t:submit t:event="delete" t:context="course.uuid" t:mixins="Confirm" t:message="Delete ${course.name}?" value="Delete"/>
            </div>

        </t:if>
        <t:if negate="true" test="course">
            Course ${courseUuid} does not exist.<br/><br/>
        </t:if>
        </form>
    </t:if>

REVIEW java

The java required for the review form is trivial – we just need to load the data. I would have expected the setupRender() to be enough but in practice I needed the onPrepareFromReviewForm() method.

public class Editor {
public enum Mode {
CREATE, REVIEW, UPDATE;
}
// Parameters
@ActivationRequestParameter
@Property
private Mode mode;
@ActivationRequestParameter
@Property
private String courseUuid;
// Screen fields
@Property
private Course course;
// Generally useful bits and pieces
@Inject
private CourseFinderService courseFinderService;
@Component
private CustomForm reviewForm;
@Inject
private ComponentResources componentResources;
@InjectPage
private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;
// The code
public void setup(Mode mode, String courseUuid) {
this.mode = mode;
this.courseUuid = courseUuid;
}
// setupRender() is called by Tapestry right before it starts rendering the
// component.
void setupRender() {
if (mode == Mode.REVIEW) {
if (courseUuid == null) {
course = null;
// Handle null course in the template.
} else {
if (course == null) {
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
// Handle null course in the template.
}
}
}
}
}
// /////////////////////////////////////////////////////////////////////
// REVIEW
// /////////////////////////////////////////////////////////////////////
void onPrepareFromReviewForm() {
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
// Handle null course in the template.
}
}
// /////////////////////////////////////////////////////////////////////
// PAGE NAVIGATION
// /////////////////////////////////////////////////////////////////////
// Handle event "toUpdate"
boolean onToUpdate(String courseUuid) {
mode = Mode.UPDATE;
return false;
}
// Handle event "toIndex"
Object onToIndex() {
return indexPage;
}
....
}

public class Editor {

    public enum Mode {
        CREATE, REVIEW, UPDATE;
    }

    // Parameters

    @ActivationRequestParameter
    @Property
    private Mode mode;

    @ActivationRequestParameter
    @Property
    private String courseUuid;

    // Screen fields

    @Property
    private Course course;

    // Generally useful bits and pieces

    @Inject
    private CourseFinderService courseFinderService;

    @Component
    private CustomForm reviewForm;

    @Inject
    private ComponentResources componentResources;

    @InjectPage
    private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;

    // The code

    public void setup(Mode mode, String courseUuid) {
        this.mode = mode;
        this.courseUuid = courseUuid;
    }

    // setupRender() is called by Tapestry right before it starts rendering the
    // component.

    void setupRender() {

        if (mode == Mode.REVIEW) {
            if (courseUuid == null) {
                course = null;
                // Handle null course in the template.
            } else {
                if (course == null) {
                    try {
                        course = courseFinderService.findCourseByUuid(courseUuid);
                    } catch (ObjectNotFoundException e) {
                        // Handle null course in the template.
                    }
                }
            }
        }
    }

    // /////////////////////////////////////////////////////////////////////
    // REVIEW
    // /////////////////////////////////////////////////////////////////////

    void onPrepareFromReviewForm() {
        try {
            course = courseFinderService.findCourseByUuid(courseUuid);
        } catch (ObjectNotFoundException e) {
            // Handle null course in the template.
        }
    }

    // /////////////////////////////////////////////////////////////////////
    // PAGE NAVIGATION
    // /////////////////////////////////////////////////////////////////////

    // Handle event "toUpdate"

    boolean onToUpdate(String courseUuid) {
        mode = Mode.UPDATE;
        return false;
    }

    // Handle event "toIndex"

    Object onToIndex() {
        return indexPage;
    }

    ....
}

UPDATE template

Finally, the “update” template looks similar to the “create” template.

<t:if test="modeUpdate">
<h1>Update</h1>
<strong>Warning: no attempt is made to block XSS</strong>
<form t:type="form" t:id="updateForm">
<t:errors/>
<t:if test="course">
<table>
<tr>
<th><t:label for="updCode"/>:</th>
<td><input t:type="TextField" t:id="updCode" value="course.code" t:disabled="true" size="12"/></td>
<td>(read-only)</td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="updName"/></td>
</tr>
<tr>
<th><t:label for="updName"/>:</th>
<td><input t:type="TextField" t:id="updName" value="course.name" t:validate="required, maxlength=80" size="45"/></td>
<td>(required)</td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="updSummary"/></td>
</tr>
<tr>
<th><t:label for="updSummary"/>:</th>
<td><input cols="50" rows="4" t:type="TextArea" t:id="updSummary" value="course.summary" t:validate="maxlength=400"/></td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="updSummary"/></td>
</tr>
<tr>
<th><t:label for="updDescription"/>:</th>
<td><input cols="50" rows="12" t:type="TextArea" t:id="updDescription" value="course.description" t:validate="maxlength=50"/></td>
</tr>
<tr class="err">
<th></th>
<td colspan="2"><t:CustomError for="updDescription"/></td>
</tr>
</table>
<div class="buttons">
<t:submit t:event="toIndex" t:context="course.uuid" value="List"/>
<t:submit t:event="cancelUpdate" t:context="course.uuid" value="Cancel"/>
<input t:type="submit" value="Save"/>
</div>
</t:if>
<t:if negate="true" test="course">
Course ${courseUuid} does not exist.<br/><br/>
</t:if>
</form>
</t:if>

    <t:if test="modeUpdate">
        <h1>Update</h1>

        <strong>Warning: no attempt is made to block XSS</strong>
        
        <form t:type="form" t:id="updateForm">
            <t:errors/>
        
            <t:if test="course">
                <!-- If optimistic locking is not needed then comment out this next line. It works because Hidden fields are part of the submit. -->
                <!-- <t:hidden value="course.version"/> -->
        
                <table>
                    <tr>
                        <th><t:label for="updCode"/>:</th>
                        <td><input t:type="TextField" t:id="updCode" value="course.code" t:disabled="true" size="12"/></td>
                        <td>(read-only)</td>
                    </tr>
                    <tr class="err">
                        <th></th>
                        <td colspan="2"><t:CustomError for="updName"/></td>
                    </tr>
                    <tr>
                        <th><t:label for="updName"/>:</th>
                        <td><input t:type="TextField" t:id="updName" value="course.name" t:validate="required, maxlength=80" size="45"/></td>
                        <td>(required)</td>
                    </tr>
                    <tr class="err">
                        <th></th>
                        <td colspan="2"><t:CustomError for="updSummary"/></td>
                    </tr>
                    <tr>
                        <th><t:label for="updSummary"/>:</th>
                        <td><input cols="50" rows="4" t:type="TextArea" t:id="updSummary" value="course.summary" t:validate="maxlength=400"/></td>
                    </tr>
                    <tr class="err">
                        <th></th>
                        <td colspan="2"><t:CustomError for="updSummary"/></td>
                    </tr>
                    <tr>
                        <th><t:label for="updDescription"/>:</th>
                        <td><input cols="50" rows="12" t:type="TextArea" t:id="updDescription" value="course.description" t:validate="maxlength=50"/></td>
                    </tr>
                    <tr class="err">
                        <th></th>
                        <td colspan="2"><t:CustomError for="updDescription"/></td>
                    </tr>
                </table>

                <div class="buttons">
                    <t:submit t:event="toIndex" t:context="course.uuid" value="List"/>
                    <t:submit t:event="cancelUpdate" t:context="course.uuid" value="Cancel"/>
                    <input t:type="submit" value="Save"/>
                </div>
            </t:if>
            <t:if negate="true" test="course">
                Course ${courseUuid} does not exist.<br/><br/>
            </t:if>
        </form>    
    </t:if>

UPDATE java

Likewise the “update” java code looks a lot like the “create” java code. The biggest difference is that we have to be able to handle a race condition where a course has been deleted before we attempt to update the database.

@Events({ Editor.TO_UPDATE, Editor.CANCEL_UPDATE,
Editor.SUCCESSFUL_UPDATE, Editor.FAILED_UPDATE })
public class Editor {
public static final String TO_UPDATE = "toUpdate";
public static final String CANCEL_UPDATE = "cancelUpdate";
public static final String SUCCESSFUL_UPDATE = "successfulUpdate";
public static final String FAILED_UPDATE = "failedUpdate";
public enum Mode {
CREATE, REVIEW, UPDATE;
}
// Parameters
@ActivationRequestParameter
@Property
private Mode mode;
@ActivationRequestParameter
@Property
private String courseUuid;
// Screen fields
@Property
private Course course;
@Property
@Persist(PersistenceConstants.FLASH)
private String deleteMessage;
// Work fields
// This carries version through the redirect that follows a server-side
// validation failure.
@Persist(PersistenceConstants.FLASH)
private Integer versionFlash;
// Generally useful bits and pieces
@Inject
private CourseFinderService courseFinderService;
@Inject
private CourseManagerService courseManagerService;
@Component
private CustomForm updateForm;
@Inject
private ComponentResources componentResources;
@InjectPage
private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;
// The code
public void setup(Mode mode, String courseUuid) {
this.mode = mode;
this.courseUuid = courseUuid;
}
// setupRender() is called by Tapestry right before it starts rendering the
// component.
void setupRender() {
if (mode == Mode.REVIEW) {
if (courseUuid == null) {
course = null;
// Handle null course in the template.
} else {
if (course == null) {
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
// Handle null course in the template.
}
}
}
}
}
// /////////////////////////////////////////////////////////////////////
// UPDATE
// /////////////////////////////////////////////////////////////////////
// Handle event "cancelUpdate"
Object onCancelUpdate(String courseUuid) {
return indexPage;
}
// Component "updateForm" bubbles up the PREPARE_FOR_RENDER event during
// form render
void onPrepareForRenderFromUpdateForm() {
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
// Handle null course in the template.
}
// If the form has errors then we're redisplaying after a redirect.
// Form will restore your input values but it's up to us to restore
// Hidden values.
if (updateForm.getHasErrors()) {
if (course != null) {
course.setVersion(versionFlash);
}
}
}
// Component "updateForm" bubbles up the PREPARE_FOR_SUBMIT event during for
// submission
void onPrepareForSubmitFromUpdateForm() {
// Get objects for the form fields to overlay.
try {
course = courseFinderService.findCourseByUuid(courseUuid);
} catch (ObjectNotFoundException e) {
course = new Course();
updateForm.recordError("Course has been deleted by another process.");
}
}
// Component "updateForm" bubbles up the VALIDATE event when it is submitted
void onValidateFromUpdateForm() {
if (updateForm.getHasErrors()) {
// We get here only if a server-side validator detected an error.
return;
}
try {
courseManagerService
.updateCourse(course, course.getName(), course.getSummary(), course.getDescription(), 1);
} catch (RestClientFailureException e) {
updateForm.recordError("Internal error on server.");
updateForm.recordError(e.getMessage());
} catch (Exception e) {
// Display the cause. In a real system we would try harder to get a
// user-friendly message.
updateForm.recordError(ExceptionUtil.getRootCauseMessage(e));
}
}
// Component "updateForm" bubbles up SUCCESS or FAILURE when it is
// submitted, depending on whether VALIDATE
// records an error
boolean onSuccessFromUpdateForm() {
// We want to tell our containing page explicitly what course we've
// updated, so we trigger new event
// "successfulUpdate" with a parameter. It will bubble up because we
// don't have a handler method for it.
componentResources.triggerEvent(SUCCESSFUL_UPDATE, new Object[] { courseUuid }, null);
// We don't want "success" to bubble up, so we return true to say we've
// handled it.
mode = Mode.REVIEW;
return true;
}
boolean onFailureFromUpdateForm() {
versionFlash = course.getVersion();
// Rather than letting "failure" bubble up which doesn't say what you
// were trying to do, we trigger new event
// "failedUpdate". It will bubble up because we don't have a handler
// method for it.
componentResources.triggerEvent(FAILED_UPDATE, new Object[] { courseUuid }, null);
// We don't want "failure" to bubble up, so we return true to say we've
// handled it.
return true;
}
}

@Events({ Editor.TO_UPDATE, Editor.CANCEL_UPDATE,
        Editor.SUCCESSFUL_UPDATE, Editor.FAILED_UPDATE })
public class Editor {
    public static final String TO_UPDATE = "toUpdate";
    public static final String CANCEL_UPDATE = "cancelUpdate";
    public static final String SUCCESSFUL_UPDATE = "successfulUpdate";
    public static final String FAILED_UPDATE = "failedUpdate";
 
    public enum Mode {
        CREATE, REVIEW, UPDATE;
    }

    // Parameters

    @ActivationRequestParameter
    @Property
    private Mode mode;

    @ActivationRequestParameter
    @Property
    private String courseUuid;

    // Screen fields

    @Property
    private Course course;

    @Property
    @Persist(PersistenceConstants.FLASH)
    private String deleteMessage;

    // Work fields

    // This carries version through the redirect that follows a server-side
    // validation failure.
    @Persist(PersistenceConstants.FLASH)
    private Integer versionFlash;

    // Generally useful bits and pieces

    @Inject
    private CourseFinderService courseFinderService;

    @Inject
    private CourseManagerService courseManagerService;

    @Component
    private CustomForm updateForm;

    @Inject
    private ComponentResources componentResources;

    @InjectPage
    private com.invariantproperties.sandbox.student.maintenance.web.pages.course.Index indexPage;

    // The code

    public void setup(Mode mode, String courseUuid) {
        this.mode = mode;
        this.courseUuid = courseUuid;
    }

    // setupRender() is called by Tapestry right before it starts rendering the
    // component.

    void setupRender() {

        if (mode == Mode.REVIEW) {
            if (courseUuid == null) {
                course = null;
                // Handle null course in the template.
            } else {
                if (course == null) {
                    try {
                        course = courseFinderService.findCourseByUuid(courseUuid);
                    } catch (ObjectNotFoundException e) {
                        // Handle null course in the template.
                    }
                }
            }
        }
    }

    // /////////////////////////////////////////////////////////////////////
    // UPDATE
    // /////////////////////////////////////////////////////////////////////

    // Handle event "cancelUpdate"

    Object onCancelUpdate(String courseUuid) {
        return indexPage;
    }

    // Component "updateForm" bubbles up the PREPARE_FOR_RENDER event during
    // form render

    void onPrepareForRenderFromUpdateForm() {
        try {
            course = courseFinderService.findCourseByUuid(courseUuid);
        } catch (ObjectNotFoundException e) {
            // Handle null course in the template.
        }

        // If the form has errors then we're redisplaying after a redirect.
        // Form will restore your input values but it's up to us to restore
        // Hidden values.

        if (updateForm.getHasErrors()) {
            if (course != null) {
                course.setVersion(versionFlash);
            }
        }
    }

    // Component "updateForm" bubbles up the PREPARE_FOR_SUBMIT event during for
    // submission

    void onPrepareForSubmitFromUpdateForm() {
        // Get objects for the form fields to overlay.
        try {
            course = courseFinderService.findCourseByUuid(courseUuid);
        } catch (ObjectNotFoundException e) {
            course = new Course();
            updateForm.recordError("Course has been deleted by another process.");
        }
    }

    // Component "updateForm" bubbles up the VALIDATE event when it is submitted

    void onValidateFromUpdateForm() {

        if (updateForm.getHasErrors()) {
            // We get here only if a server-side validator detected an error.
            return;
        }

        try {
            courseManagerService
                    .updateCourse(course, course.getName(), course.getSummary(), course.getDescription(), 1);
        } catch (RestClientFailureException e) {
            updateForm.recordError("Internal error on server.");
            updateForm.recordError(e.getMessage());
        } catch (Exception e) {
            // Display the cause. In a real system we would try harder to get a
            // user-friendly message.
            updateForm.recordError(ExceptionUtil.getRootCauseMessage(e));
        }
    }

    // Component "updateForm" bubbles up SUCCESS or FAILURE when it is
    // submitted, depending on whether VALIDATE
    // records an error

    boolean onSuccessFromUpdateForm() {
        // We want to tell our containing page explicitly what course we've
        // updated, so we trigger new event
        // "successfulUpdate" with a parameter. It will bubble up because we
        // don't have a handler method for it.
        componentResources.triggerEvent(SUCCESSFUL_UPDATE, new Object[] { courseUuid }, null);

        // We don't want "success" to bubble up, so we return true to say we've
        // handled it.
        mode = Mode.REVIEW;
        return true;
    }

    boolean onFailureFromUpdateForm() {
        versionFlash = course.getVersion();

        // Rather than letting "failure" bubble up which doesn't say what you
        // were trying to do, we trigger new event
        // "failedUpdate". It will bubble up because we don't have a handler
        // method for it.
        componentResources.triggerEvent(FAILED_UPDATE, new Object[] { courseUuid }, null);
        // We don't want "failure" to bubble up, so we return true to say we've
        // handled it.
        return true;
    }
}

DELETE template and java

The editor doesn’t have an explicit “delete” mode but it does support deleting the current object on the review and update pages.

// /////////////////////////////////////////////////////////////////////
// DELETE
// /////////////////////////////////////////////////////////////////////
// Handle event "delete"
Object onDelete(String courseUuid) {
this.courseUuid = courseUuid;
int courseVersion = 0;
try {
courseManagerService.deleteCourse(courseUuid, courseVersion);
} catch (ObjectNotFoundException e) {
// the object's already deleted
} catch (RestClientFailureException e) {
createForm.recordError("Internal error on server.");
createForm.recordError(e.getMessage());
// Display the cause. In a real system we would try harder to get a
// user-friendly message.
deleteMessage = ExceptionUtil.getRootCauseMessage(e);
// Trigger new event "failedDelete" which will bubble up.
componentResources.triggerEvent(FAILED_DELETE, new Object[] { courseUuid }, null);
// We don't want "delete" to bubble up, so we return true to say
// we've handled it.
return true;
} catch (Exception e) {
// Display the cause. In a real system we would try harder to get a
// user-friendly message.
deleteMessage = ExceptionUtil.getRootCauseMessage(e);
// Trigger new event "failedDelete" which will bubble up.
componentResources.triggerEvent(FAILED_DELETE, new Object[] { courseUuid }, null);
// We don't want "delete" to bubble up, so we return true to say
// we've handled it.
return true;
}
// Trigger new event "successfulDelete" which will bubble up.
componentResources.triggerEvent(SUCCESFUL_DELETE, new Object[] { courseUuid }, null);
// We don't want "delete" to bubble up, so we return true to say we've
// handled it.
return indexPage;
}

    // /////////////////////////////////////////////////////////////////////
    // DELETE
    // /////////////////////////////////////////////////////////////////////

    // Handle event "delete"

    Object onDelete(String courseUuid) {
        this.courseUuid = courseUuid;
        int courseVersion = 0;

        try {
            courseManagerService.deleteCourse(courseUuid, courseVersion);
        } catch (ObjectNotFoundException e) {
            // the object's already deleted
        } catch (RestClientFailureException e) {
            createForm.recordError("Internal error on server.");
            createForm.recordError(e.getMessage());

            // Display the cause. In a real system we would try harder to get a
            // user-friendly message.
            deleteMessage = ExceptionUtil.getRootCauseMessage(e);

            // Trigger new event "failedDelete" which will bubble up.
            componentResources.triggerEvent(FAILED_DELETE, new Object[] { courseUuid }, null);
            // We don't want "delete" to bubble up, so we return true to say
            // we've handled it.
            return true;
        } catch (Exception e) {
            // Display the cause. In a real system we would try harder to get a
            // user-friendly message.
            deleteMessage = ExceptionUtil.getRootCauseMessage(e);

            // Trigger new event "failedDelete" which will bubble up.
            componentResources.triggerEvent(FAILED_DELETE, new Object[] { courseUuid }, null);
            // We don't want "delete" to bubble up, so we return true to say
            // we've handled it.
            return true;
        }

        // Trigger new event "successfulDelete" which will bubble up.
        componentResources.triggerEvent(SUCCESFUL_DELETE, new Object[] { courseUuid }, null);
        // We don't want "delete" to bubble up, so we return true to say we've
        // handled it.
        return indexPage;
    }

Next Steps

The obvious next steps are improving the error messages, adding support for pagination, support, and one-to-many and many-to-many relationships. All will require revising the REST payloads. I have a few additional items in the pipeline, e.g., an ExceptionService, to say nothing of the security issues.