Musings of a Programming Addict

Using Pax Runner with Eclipse 3.6

noreply@blogger.com (Gunnar Morling) — Sun, 09 Oct 2011 17:36:00 +0000

While working on a little pet project based on OSGi I wanted to use the Pax Runner Eclipse plug-in to launch my OSGi application on the Apache Felix OSGi framework.

Unfortunately this attempt resulted in the following error:

java.lang.NoClassDefFoundError: org/eclipse/pde/internal/ui/launcher/LaunchArgumentsHelper
at org.ops4j.pax.cursor.Utils.getVMArgsOptions(Utils.java:216)
at org.ops4j.pax.cursor.LaunchConfiguration.getProgramArguments(LaunchConfiguration.java:156)
at org.eclipse.pde.launching.AbstractPDELaunchConfiguration.launch(AbstractPDELaunchConfiguration.java:72)
at org.eclipse.pde.launching.OSGiLaunchConfigurationDelegate.launch(OSGiLaunchConfigurationDelegate.java:47)
at org.eclipse.debug.internal.core.LaunchConfiguration.launch(LaunchConfiguration.java:853)
at org.eclipse.debug.internal.core.LaunchConfiguration.launch(LaunchConfiguration.java:702)
at org.eclipse.debug.internal.ui.DebugUIPlugin.buildAndLaunch(DebugUIPlugin.java:923)
at org.eclipse.debug.internal.ui.DebugUIPlugin$8.run(DebugUIPlugin.java:1126)
at org.eclipse.core.internal.jobs.Worker.run(Worker.java:54)

This looked pretty much like an incompatability between the Pax Runner plug-in and the Eclipse platform. And indeed the plug-in unfortunately doesn't seem to keep up with PDE-internal changes in recent Eclipse versions due to limited developer resources.

Further googling then led me to PAXRUNNER-353 at Pax Runner's issue tracker.

The ticket itself is not yet resolved, but the good news is that Christian Baranowski (whom I had the pleasure to meet during the OSGi code camp last week) created a fork on GitHub fixing the issue for now. So let's hope that this fix gets quickly merged into the main branch.

Until then Christian even has established a temporary Eclipse update site which makes upgrading the plug-in to the forked version a breeze.

So my kudos go to Christian (for fixing the plug-in) and to GitHub (for making forking easy) :-)

What would YOU like to see included in Bean Validation 1.1?

noreply@blogger.com (Gunnar Morling) — Mon, 01 Aug 2011 20:36:00 +0000

Maybe you know it already: last week JSR 349 successfully passed the review ballot, meaning that the work on a new release of the Bean Validation API has officially started.

I'm really excited about this, because I've got the pleasure to be part of the JSR 349 expert group. I haven't been member of such a comitee before, so I guess this will be exciting times and I'll surely learn a whole lot of new things during the work on the specification.

What's most important right now is your feedback: what new features would you like to see included in Bean Validation 1.1, what problems did you face when working with BV 1.0 which you think should be addressed in the next release?

Your input and feedback is highly welcome at several places:

The Bean Validation feedback forum is a good platform for discussing ideas, requests for clarifications etc.
For concrete feature requests or bug reports you can open an issue at the Bean Validation issue tracker

As a starting point you might want to check out these two blog posts by Emmanuel Bernard (the Bean Validation spec. lead), where a lot of possible features are discussed.

Finally I'd like to point your attention to http://beanvalidation.org/, the JSR's official web site. There you'll find everything related, e.g. a news section, the road map and also the Bean Validation 1.0 spec. document for reference.

Now it's up to you – tell us what would YOU like to see included in Bean Validation 1.1.

Introducing Seam Validation

noreply@blogger.com (Gunnar Morling) — Sun, 08 May 2011 11:10:00 +0000

Note: This article originally appeared on in.relation.to as part of the Seam Module Spotlight series. In order to spread the word on Seam Validation I thought it might be a good idea to post it in this blog, too.

Seam Validation is a relatively new Seam module which provides an integration between Hibernate Validator which is the reference implementation of the Bean Validation standard (JSR 303) and CDI. The module's functionality falls into two areas:

Enhanced dependency injection services for validators, validator factories and constraint validators
Automatic validation of method parameters and return values based on Hibernate Validator's method validation API

Let's take a closer look at these features in the following.

Dependency injection services

The Bean Validation API is an integral part of the Java EE platform. So when running on a Java EE 6 compatible application server such as JBoss AS 6 you can easily retrieve Validator and ValidatorFactory instances via dependency injection.

Unfortunately this is not working out of the box when running in non-EE environments such as plain servlet containers. But don't worry, Seam Validation comes to the rescue. By adding the module as dependency to your project, validators and validator factories can be obtained using @Inject:

public class Foo {

    @Inject
    private Validator validator;

    public void doSomething() {

        Bar bar = new Bar();

        Set<ConstraintViolation<Bar>> constraintViolations = validator.validate(bar);
        //examine the violations ...
    }
}

But Seam Validation goes one step further and enables dependency injection also within constraint validator implementations. For instance we might have a custom constraint @ValidLicensePlate which is used to ensure that a car has a license plate which is properly registered, still valid etc.:

public class Car {

    @ValidLicensePlate
    private String licensePlate;

    //constructor, getter, setter etc.
}

In order to perform the required checks the constraint's validator invokes some sort of registration service (note: accessing external services can potentially be an expensive operation, so it may be a good idea to put the constraint into a separate validation group, but that's out of scope for this article). The Seam Validation module allows to inject this service into the validator as into any other CDI bean:

public class ValidLicensePlateValidator implements ConstraintValidator<ValidLicensePlate, String> {

    @Inject
    private RegistrationService registrationService;

    @Override
    public void initialize(ValidLicensePlate constraintAnnotation) {
    }

    @Override
    public boolean isValid(String value, ConstraintValidatorContext context) {

        if (value == null) {
            return true;
        }

        //delegate to registration service
        return registrationService.isValid(value);
    }
}

There is just on more step required before the @ValidLicensePlate constraint can be used: We have to register Seam Validation's constraint validator factory with the Bean Validation provider. This happens by putting a file named validation.xml with the following content into the META-INF folder of the application:

<?xml version="1.0" encoding="UTF-8"?>
<validation-config 
    xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration validation-configuration-1.0.xsd">

    <constraint-validator-factory>
        org.jboss.seam.validation.InjectingConstraintValidatorFactory
    </constraint-validator-factory>
</validation-config>

Method validation

The other main feature of Seam Validation besides dependency injection is the automatic validation of method parameters and return values based on the API for method validation introduced with Hibernate Validator 4.2 (note: at the time of writing Hibernate Validator 4.2 is released as Beta version, but no major changes are expected until the final release).

This API provides an easy-to-use facility for the "Programming by Contract" approach to program design based on the concepts defined by the Bean Validation API. That means that any Bean Validation constraint can be used to describe

the preconditions that must be met before a method may be invoked (by annotating method parameters with constraints) and
the postconditions that are guaranteed after a method invocation returns (by annotating methods).

Things should become clearer with an example:

@AutoValidating
public class RentalStation {

    @Valid
    public Car rentCar(@NotNull CustomerPK customerPK, @NotNull @Future Date startDate, @Min(1) int durationInDays) {

        //highly complex car rental business logic ...
    }
}

Here the following pre- and postconditions are applied onto the rentCar() method:

The customer's primary key may not be null
The rental start date must not be null and must be in the future
The rental duration must be at least one day
The returned object must be valid with respect to all constraints of the Car class

By annotating the class RentalStation with @AutoValidating, all these constraints are automatically validated by a method interceptor whenever the rentCar() method is invoked. If any of the constraints can't be validated successfully, a runtime exception describing the occurred constraint violation(s) is thrown.

This approach has several advantages over traditional parameter and return value checking:

The checks don't have to be performed by hand. This results in less boiler-plate code to write (and to read).
A method's pre- and postconditions are part of its API and generated documentation. It's not necessary to add comments such as "returns never null", as this information will automatically be put into the generated JavaDoc. This results in less redundancies and hence in less potential inconsistencies between implementation and documentation.

Future steps

This concludes our short tour through the Seam Validation module. If you feel like trying out the module yourself, the module home page is the right starting point. You might also be interested in the module's reference guide, and in case you found a bug or want to create a feature request the module's JIRA instance is the place to go.

Possible future developments of Seam Validation include a closer integration with other Seam 3 modules, the possibility to chose the validation groups to be used for method validation and the evaluation of standard bean constraints upon method validation.

2011 JBoss Community Awards: I need your vote!

noreply@blogger.com (Gunnar Morling) — Sat, 05 Mar 2011 16:39:00 +0000

I need your help.

To be more concise, I need your vote for the 2011 JBoss Community Recognition Awards.

These awards are an effort of JBoss/Red Hat to honor significant contributions to the JBoss community over the last year and I'm more than proud to say that I've been nominated in the "New Features" category for my contributions to Hibernate Validator.

So if you appreciate my work on Hibernate Validator – e.g. the HV annotation processor or the method validation feature I've built for HV 4.2 – or the Validation module for Seam 3 (I'll blog on this in a separate post) I've recently started, just head over to the poll and give me your vote. The voting is open until April, 2nd.

And if you really like my work, go and tell your friends that they should vote for me, too.

Just in case you feel like you need some more information to make a profound vote you might also check out my nominee description.

Another nomination I'd like to mention is the one of my fellow developer Kevin Pollet in the "Bug Fixes" category. He has done some really awesome work for HV 4.2. Besides fixing many bugs he implemented several new features like the integration with the Joda time API or the support for dynamic default group sequence definitions.

So when you (and your friends) have voted for me, don't forget to vote for Kevin, too :)

Method Validation with Hibernate Validator 4.2

noreply@blogger.com (Gunnar Morling) — Sun, 16 Jan 2011 21:32:00 +0000

Earlier this week the first beta version of Hibernate Validator 4.2 was released. Hardy's announcement on in.relation.to describes in detail what's new in this release, so be sure to check it out.

One of the new features I'm really excited about is method validation, which I therefore would like to discuss in more detail in the following.

What's it about?

Up to now constraint annotations were only supported at fields or at getter methods for property constraints and at type declarations for class-level constraints.

With HV 4.2 it is now also possible to use constraint annotations for a programming style known as "Programming by Contract". More specifically this means that any Bean Validation constraints (built-in as well as custom constraints) can be used to specify

any preconditions that must be met before a method invocation (by annotating method parameters with constraints) and
any postconditions that are guaranteed after a method invocation (by annotating methods)

As example let's consider the following class from a fictitious video rental application:

public class MovieRepository {

    public @NotNull Set<Movie> findMoviesByTitle( 
        @NotNull @Size(min = 3) String title) {

        //search movie in database ...
    }   

}

The following pre- and postconditions will hold here (provided the method validation is triggered automatically by some integration layer, see below):

The title parameter is guaranteed to be not null and at least 3 characters long
The return set of movies is guaranteed to be not null

Compared to traditional ways of parameter or result value checking this approach has two big advantages:

These checks don't have to be performed manually, which results in less code to write and maintain. You'll never again have to throw IllegalArgumentExceptions or similar by hand.
The pre- and postconditions of a method don't have to be expressed again in the method's JavaDoc, since any of it's annotations will automatically be included in the generated JavaDoc. This means less redundancy which reduces the chance of inconsistencies between implementation and comments.

Method validation is not restricted to constraints related to parameters or to return values themselves. Using the @Valid annotation it is also possible to recursively validate parameters or return values:

public class UserRepository {

    public void persistUser(@NotNull @Valid User user) {

        //persist user in database ...
    }   

}

In this example not only the @NotNull constraint at the user parameter would be checked, but also any constraints defined at the User type. As known from standard Bean Validation the @Valid annotation could also be applied to array-, Iterable- and Map-typed parameters or return values.

The MethodValidator interface

For the purposes of method validation Hibernate Validator defines the new interface MethodValidator (any type or method names are working titles and might change until HV 4.2 is final), which provides methods for parameter and return value validation:

public interface MethodValidator {

    public <T> Set<MethodConstraintViolation<T>> validateParameter(
        T object, Method method, Object parameterValue, 
        int parameterIndex, Class<?>... groups);

    public <T> Set<MethodConstraintViolation<T>> validateParameters(
        T object, Method method, Object[] parameterValues, Class<?>... groups);

    public <T> Set<MethodConstraintViolation<T>> validateReturnValue(
        T object, Method method, Object returnValue, Class<?>... groups);

}

To get hold of a method validator, unwrap an instance of HV's Validator implementation as follows:

MethodValidator validator = Validation.byProvider( HibernateValidator.class )
    .configure()
    .buildValidatorFactory()
    .getValidator()
    .unwrap( MethodValidator.class );

All of MethodValidator's methods return a set of MethodConstraintValidations which describe in detail any constraint violations that occurred during validation. MethodConstraintValidation extends the standard ConstraintViolation and provides additional information such as method and parameter causing a constraint violation:

public interface MethodConstraintViolation<T> extends ConstraintViolation<T> {

    public static enum Kind {

        PARAMETER,

        RETURN_VALUE
    }

    Method getMethod();

    Integer getParameterIndex();

    String getParameterName();

    Kind getKind();
}

Unfortunately the byte code of a Java program normally doesn't contain any information on parameter names, therefore getParameterName() for now returns synthetic names such as arg0 etc. For a future release we are investigating approaches for parameter naming, e.g. by leveraging JSR 330's @Named annotation. I created a JIRA issue for this, so if you have any feedback on this just add a comment to the ticket.

Triggering method validation

Hibernate Validator itself only provides the engine for method validation but it does not deal with triggering such a validation.

Instead this is typically done using frameworks/APIs which provide AOP or method interception services such as AspectJ or CDI. But also plain Java dynamic proxies can basically do the trick.

Typically such a validation interceptor does the following:

intercept each method call to be validated,
validate the invocation's parameter values,
proceed with the method invocation and
finally validate the invocation's return value.

If any of the two validation steps yields one ore more constraint violations the interceptor typically throws a MethodConstraintViolationException containing the constraint violations that have occurred.

Trying it out yourself

To see whether method validation works out as intended I started a project at GitHub called methodvalidation-integration which provides validation handlers for some interception technologies popular these days.

Currently there are implementations for CDI as well as Google Guice and an InvocationHandler which can be used with JDK dynamic proxies. I also plan to add support for Spring AOP/AspectJ when time permits.

To try method validation out yourself just get the bits from GitHub and have a look at the test in each of the sub-projects. Just give it a try and let me know how everything works.

Future steps

This post introduced the new method validation feature which will be part of Hibernate Validator 4.2. The first beta release contains the basic implementations of this, so we are more than interested in you feedback on this. Please report any bugs in HV's JIRA instance, any questions or ideas for improvement are also highly welcome in HV's forum.

For HV 4.2 Beta2 we plan to add documentation on the method validation feature to HV's reference guide which will also describe some advanced topics such as using method validation with group sequences etc. We will also add support for method level constraints to the constraint meta-data API.

Two further ideas scheduled for after 4.2 are providing the ability to specify method level constraints using XML and using the programmatic constraint configuration API.

Setting the active Maven profile in IntelliJ IDEA

noreply@blogger.com (Gunnar Morling) — Mon, 27 Dec 2010 17:38:00 +0000

This is more a note to myself, but in case someone else wonders how to specify the active Maven profile in IntelliJ IDEA for projects containing several profiles, that's the way to go:

Open the "Maven Projects" window by selecting "Window" - "Tool Windows" - "Maven Projects"
Expand the "Profiles" node and select the profile you want to use

Putting a SpEL(l) on the Bean Validation API

noreply@blogger.com (Gunnar Morling) — Mon, 27 Dec 2010 13:58:00 +0000

One of the new features introduced with version 3.0 of the Spring framework is the Spring Expression Language or short "SpEL". This language is tailored for the needs when working with Spring and can be used when creating XML/annotation based Spring bean definitions for instance.

So I thought it would be nice if it was possible to use SpEL together with Hibernate Validator's @ScriptAssert constraint which allows to express validation routines using script or expression languages.

Unfortunately this does not work since currently no SpEL language binding for JSR 223 ("Scripting for the Java^TM Platform") exists. As @ScriptAssert's validator uses JSR 223 for expression evaluation at least for now SpEL can't be used along with @ScriptAssert (there is an issue in Spring's JIRA addressing this problem).

But as shown in previous posts it is very simple to create new constraint annotations for the Bean Validation API. So the idea is to build a new constraint @SpelAssert which resembles HV's @ScriptAssert but works with SpEL instead of the JSR 223 API.

Defining the annotation type is straight-forward:

@Target({ TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = SpelAssertValidator.class)
@Documented
public @interface SpelAssert {


    String message() default "{de.gmorling.moapa.bvspel.SpelAssert.message}";

    Class<?>[] groups() default {};


    Class<? extends Payload>[] payload() default {};

    String value();


}

Besides the standard attributes message(), groups() and payload() mandated by the BV specification we define one more attribute value(), which takes the SpEL expression to evaluate.

Now let's come to the validator:

public class SpelAssertValidator implements

ConstraintValidator<SpelAssert, Object> {

    @Inject
    private ExpressionParser parser;

    private Expression expression;


    @Override
    public void initialize(SpelAssert constraintAnnotation) {

    String rawExpression = constraintAnnotation.value();


        if (rawExpression == null) {
            throw new IllegalArgumentException("The expression specified in @"

                + SpelAssert.class.getSimpleName() + " must not be null.");
        }

        expression = parser.parseExpression(rawExpression);
    }


    @Override
    public boolean isValid(Object value, ConstraintValidatorContext context) {

        if (value == null) {

            return true;
        }

        return Boolean.TRUE.equals(expression.getValue(value, Boolean.class));

    }
}

In initialize() we use an ExpressionParser to parse the specified SpEL expression (so this happens only once) and evaluate the given object against it in isValid().

But wait a minute, where does the ExpressionParser come from, it is not instantiated here?

Right, the cool thing is Spring comes with it's own ConstraintValidatorFactory which performs dependency injection on constraint validators. A validator relying on that feature of course is not portable, but as this validator is based on SpEL and Spring anyways this is not an issue here.

In order to have this working a parser bean must be part of the Spring application context. We just register a SpelExpressionParser:

<beans 
    xmlns="http://www.springframework.org/schema/beans"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"

    xsi:schemaLocation="http://www.springframework.org/schema/beans
        http://www.springframework.org/schema/beans/spring-beans-3.0.xsd">

    <bean id="parser"
        class="org.springframework.expression.spel.standard.SpelExpressionParser"/>


    <bean id="validator"
        class="org.springframework.validation.beanvalidation.LocalValidatorFactoryBean"/>
</beans>

This context also shows how to provide a BV Validator for dependency injection leveraging Spring's LocalValidatorFactoryBean.

Now let's have a look at the @SpelAssert constraint in action. The following shows the canonical example of a class CalendarEvent where the start date shall always be earlier than the end date:

@SpelAssert("startDate < endDate")
public class CalendarEvent {


    private Date startDate;

    private Date endDate;


    // getters, setters etc.

}

Note how SpEL allows dates to be compared using the "<" operator and that no alias for the evaluated bean is required, as all unqualified attribute/method names are resolved against the annotated object.

Finally we should have a test showing that the validator works as expected by validating a valid and an invalid CalendarEvent instance:

@RunWith(SpringJUnit4ClassRunner.class)

@ContextConfiguration
public class SpelAssertTest {

    @Inject
    private Validator validator;


    private Date startDate;
    private Date endDate;

    @Before

    public void setUpDates() {

        Calendar start = Calendar.getInstance();
        start.set(2010, 13, 24);

        startDate = start.getTime();

        Calendar end = Calendar.getInstance();
        end.set(2010, 13, 26);

        endDate = end.getTime();
    }

    @Test
    public void validEvent() {


        CalendarEvent event = new CalendarEvent();
        event.setStartDate(startDate);
        event.setEndDate(endDate);

        assertTrue(validator.validate(event).isEmpty());

    }

    @Test
    public void invalidEventYieldsConstraintViolation() {

        CalendarEvent event = new CalendarEvent();

        event.setStartDate(endDate);
        event.setEndDate(startDate);

        Set<ConstraintViolation<CalendarEvent>> violations = 
            validator.validate(event);

        assertEquals(1, violations.size());

        ConstraintViolation<CalendarEvent> violation = 
            violations.iterator().next();
        assertEquals(

            "SpEL expression \"startDate < endDate\" didn't evaluate to true.",
            violation.getMessage());
    }

}

The complete sources for this post can be found at GitHub, so don't hesistate to give it a try or use it in your projects if you like. Any feedback or ideas for improvement are warmly welcome.

Identifying files with missing SVN properties

noreply@blogger.com (Gunnar Morling) — Wed, 17 Nov 2010 16:40:00 +0000

At my day job we are using the SVN property "svn:keywords" to let SVN replace the string "$Id$" with author name, revision number etc. within each Java source file.

One can add this property automatically when creating new files with the help of SVN's auto props feature. But from time to time someone, e.g. a new developer not knowing about auto props, checks in files without having the "svn:keywords" property set.

So I wondered how to identify such files in the repository. SVN doesn't provide a command answering that question, you only can retrieve all files having a certain property set.

But no problem, some shell magic to the rescue:

1	comm -23 <(sort <(sed 's/\.\///g' <(find . -name ".java"))) <(sort <(sed 's/ - Id//g' <(svn propget svn:keywords -R)))

So what's happening here? The basic idea is to list those files with the svn:keywords property set (svn propget) and compare this to a list with all files (find).

The outputs of both commands are brought into the same format using sed, sorted and then passed as parameters to the comm command, which compares two input files to each other. The -23 parameter causes only those lines to be put out which are only contained in file1 but not in file2, which are exactly the names of those files lacking the "svn:keywords" property.

I tested the command successfully on Mac OS X, but I think it should work pretty much the same way on other Unix systems, too.

Retrieving JDT sources with Eclipse 3.6

noreply@blogger.com (Gunnar Morling) — Sun, 15 Aug 2010 18:44:00 +0000

While developing an Eclipse plug-in for a small spare-time project of mine I wondered where to find the sources of the Java Development Tools (JDT). They used to be part of the Eclipse RCP/plug-in developers package in previous releases, but this isn't the case anymore with Eclipse 3.6 (Helios).

After some googling I found the reason: as of release 3.6 the RCP distribution (now named "Eclipse for RCP and RAP Developers") no longer contains any sources (except those for the actual platform plug-ins) in order to reduce the size of the download package.

If you want to get the sources for plug-ins such as JDT which are not part of the core platform you have to retrieve them separately. To do so you can use the new plug-in import wizard which allows to fetch source projects corresponding to plug-ins of the target platform directly from the Eclipse CVS.

Just open the "Plug-ins" view, right-click on the plug-in you want to retrieve (e.g. org.eclipse.jdt.ui) and select "Import as" > "Project from a Repository ...". Confirm the next dialog by clicking "Finish", and the check-out starts. Afterwards the new project will automatically replace the plug-in JAR as dependency in any dependent projects within your workspace.

A CDI portable extension for JSR 223 scripting engines

noreply@blogger.com (Gunnar Morling) — Sat, 24 Jul 2010 12:41:00 +0000

In the last couple of days I spent some time experimenting a little bit with CDI, the standard of the Java EE 6 platform for dependency injection services.

I must say that I really like that spec, as it hits the sweet spot between specifying features that provide a value out of the box (type-safe DI, eventing, interceptor services etc.) and being open enough to allow people to build totally new stuff based on it (using portable extensions).

I've got the feeling we're going to see a lot of exciting things based on CDI within the near future. Actually this reminds me a bit of Java annotations. Having been introduced with Java 5, just over time people started using them for more and more use cases that had not been foreseen in the first place.

Anyway, to do something practical with CDI I built a small portable extension which allows to retrieve JSR 223 scripting engines using dependency injection.

Just annotate any injection points of type javax.script.ScriptEngine with one of the qualifier annotations @Language, @Extension or @MimeType. The following code extract shows an example of a JavaScript engine (for example the Rhino engine shipping with Java 6) being injected into some managed bean, where it can be used for arbitrary script evaluations:

@RequestScoped
public class MyBean {

    @Inject 
    @Language("javascript") 
    private ScriptEngine jsEngine;

    // ...

    public void foo() throws ScriptException {

        assert 42.0d == (Double)jsEngine.eval("2 * 21");
        // ...
    }
}

The extension can be found in my Maven repository. Just add the following dependency to your POM in order to use it:

<dependency>
    <groupId>de.gmorling.cdi.extensions</groupId>
    <artifactId>scripting-extension</artifactId>
    <version>0.1</version>
</dependency>

In case you want to take a look at the source code (which is just a few lines), you can check it out from GitHub. As always, any ideas for improvement or other feedback are highly appreciated.

What's new in Hibernate Validator 4.1?

noreply@blogger.com (Gunnar Morling) — Mon, 28 Jun 2010 21:33:00 +0000

I'm very proud to report that today Hibernate Validator 4.1.0 Final has been released. Besides many bug fixes this release adds also a lot of new features to the code base.

The changes fall into four areas, which I'm going to discuss in detail in the following:

New constraint annotations
ResourceBundleLocator API
API for programmatic constraint creation
Constraint annotation processor

New constraint annotations

In addition to the constraints defined in the Bean Validation spec and those custom constraints already part of HV 4.0, the new release ships with the following new constraint annotations:

@CreditCardNumber: Validates that a given String represents a valid credit card number using the Luhn algorithm. Useful to detect mis-entered numbers for instance.
@NotBlank: Validates that a given String is neither null nor empty nor contains only whitespaces.
@URL: Validates that a given String is a valid URL. Can be restricted to certain protocols if required: @URL(protocol = "http") private String url;
@ScriptAssert: Allows to use scripting or expression languages for the definition of class-level validation routines.

Let's have a closer look at the @ScriptAssert constraint, which I'm particularly excited about as I have implemented it :-).

The intention behind it is to provide a simplified way for expressing validation logic that is based on multiple attributes of a given type. Instead of having to implement dedicated class-level constraints the @ScriptAssert constraint allows to express such validation routines in an ad hoc manner using a wide range of scripting and expression languages.

In order to use this constraint an implementation of the Java Scripting API as defined by JSR 223 ("Scripting for the Java^TM Platform") must be part of the class path. This is automatically the case when running on Java 6. For older Java versions, the JSR 223 RI can be added manually to the class path.

As example let's consider a class representing calendar events. The start date of such an event shall always be earlier than the end date. Using JavaScript (for which an engine comes with Java 6) this requirement could be expressed as follows:

@ScriptAssert(lang = "javascript", script = "_this.startDate.before(_this.endDate)")
public class CalendarEvent {

    private Date startDate;

    private Date endDate;

    //...
}

So all you have to do is to specify a scripting expression returning true or false within the script attribute. The expression must be implemented in the language given within the language attribute. The language name must be the language's name as registered with the JSR 223 ScriptEngineManager. Within the expression the annotated element can be accessed using the alias _this by default.

The cool thing is that the @ScriptConsert constraint can be used with any other scripting language for which a JSR 223 binding exists. Let's take JEXL from the Apache Commons project for instance. Using Maven you only have to add the following dependency:

<dependency>
    <groupId>org.apache.commons</groupId>
    <artifactId>commons-jexl</artifactId>
    <version>2.0.1</version>
</dependency>

With JEXL dates can be compared using the "<" operator. Using a shorter alias for the evaluated object the constraint from above therefore can be rewritten as follows:

@ScriptAssert(lang = "jexl", script = "_.startDate < _.endDate", alias = "_")
public class CalendarEvent {

    private Date startDate;

    private Date endDate;

    //...
}

Very likely one will work with only one scripting language throughout all @ScriptAssert constraints of an application. So let's leverage the power of constraint composition to create a custom constraint which allows for an even more compact notation by setting the attributes lang and alias to fixed values:

@Target({ TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = {})
@Documented
@ScriptAssert(lang = "jexl", script = "", alias = "_")
public @interface JexlAssert {

    String message() default "{org.hibernate.validator.constraints.ScriptAssert.message}";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

    @OverridesAttribute(constraint = ScriptAssert.class, name = "script")
    String value();
}

Note how the script attribute of the composing @ScriptAssert constraint is overridden using the @OverridesAttribute meta-annotation. Using this custom constraint the example finally reads as follows:

@JexlAssert("_.startDate < _.endDate")
public class CalendarEvent {

    private Date startDate;

    private Date endDate;

    //...
}

As shown the @ScriptAssert constraint allows to define class-level constraints in a very compact way.

But there is also a price to pay. As scripting languages are used, compile-time type-safety is lost. When for instance the startDate attribute is renamed the script expression would have to be adapted by hand. Also evaluation performance should be considered when validation logic is getting more complex.

So I recommend to try it out and choose what ever fits your needs best.

The ResourceBundleLocator API

The Bean Validation API defines the MessageInterpolator interface which allows to plug in custom strategies for message interpolation and resource bundle loading.

As it turned out, most users only want to customize the latter aspect (e.g. in order to load message bundles from a database) but would like to re-use the interpolation algorithm provided by Hibernate Validator.

Therefore Hibernate Validator 4.1 introduces the interface ResourceBundleLocator which is used by HV's default MessageInterpolator implementation ResourceBundleMessageInterpolator to do the actual resource bundle loading.

The interface defines only one method, in which implementations have to return the bundle for a given locale:

public interface ResourceBundleLocator {

    ResourceBundle getResourceBundle(Locale locale);

}

The ResourceBundleLocator to be used can be set when creating a ValidatorFactory:

ValidatorFactory validatorFactory = Validation
    .byProvider(HibernateValidator.class)
    .configure()
    .messageInterpolator(
        new ResourceBundleMessageInterpolator(
            new MyCustomResourceBundleLocator()))
    .buildValidatorFactory();

The default ResourceBundleLocator implementation used by Hibernate Validator is PlatformResourceBundleLocator which simply loads bundles using ResourceBundle.loadBundle(). Another implementation provided out of the box is AggregateResourceBundleLocator, which allows to retrieve message texts from multiple bundles by merging them into a single aggregate bundle. Let's look at an example:

HibernateValidatorConfiguration configuration = Validation
    .byProvider(HibernateValidator.class)
    .configure();

ValidatorFactory validatorFactory = configuration
    .messageInterpolator(
        new ResourceBundleMessageInterpolator(
            new AggregateResourceBundleLocator(
                Arrays.asList("foo", "bar"), 
                configuration.getDefaultResourceBundleLocator())))
    .buildValidatorFactory();

Here messages from bundles "foo" and "bar" could be used in constraints. In case the same key was contained in both bundles, the value from bundle "foo" would have precedence, as it comes first in the list. If a given key can't be found in any of the two bundles as fallback the default locator (which provides access to the ValidationMessages bundle as demanded by the JSR 303 spec) will be tried.

API for programmatic constraint creation

Using the Bean Validation API constraints can be declared using either annotations and/or XML descriptor files. Hibernate Validator 4.1 introduces a third approach by providing an API for programmatic constraint declaration.

This API can come in handy for instance in dynamic scenarios where constraints change upon runtime or for testing scenarios.

As example let's consider two classes, Customer and Order, from a web shop application for which the following constraints shall apply:

each customer must have a name
each order must have a customer
each order must comprise at least one order line

With help of the programmatic constraint API these constraints can be declared as follows:

ConstraintMapping mapping = new ConstraintMapping();

mapping
    .type(Order.class)
        .property("customer", ElementType.FIELD)
            .constraint(NotNullDef.class)
        .property("orderLines", ElementType.FIELD)
            .constraint(SizeDef.class)
                .min(1)
                .message("An order must contain at least one order line")
    .type(Customer.class)
        .property("name", ElementType.FIELD)
            .constraint(NotNullDef.class);

As the listing shows the API is designed in a fluent style with the class ConstraintMapping as entry point. Constraints are declared by chaining method calls which specify to which property of which type which constraints should be added.

The API provides constraint definition classes such as NotNullDef etc. for all built-in constraints, which allow to access their properties (min(), message() etc.) in a type-safe way. For custom constraints you could either provide your own constraint definition class or you could make use of GenericConstraintDef which allows to identify properties by name.

Having created a constraint mapping it has to be registered with the constraint validator factory. As the programmatic API is not part of the Bean Validation spec, we must explicitely specify Hibernate Validator as the BV provider to be used:

Validator validator = Validation
    .byProvider(HibernateValidator.class)
    .configure()
    .addMapping(mapping)
    .buildValidatorFactory()
    .getValidator();

If you now use this validator to validate an Order object which has no customer set a constraint violation will occur, just as if the "customer" property was annotated with @NotNull.

Constraint annotation processor

The Hibernate Validator annotation processor might become your new favourite tool if you find yourself accidentally doing things like

annotating Strings with @Min to specify a minimum length (instead of using @Size)
annotating the setter of a JavaBean property (instead of the getter method)
annotating static fields/methods with constraint annotations (which is not supported)

Normally you would notice such mistakes only during run-time. The annotation processor helps in saving your valuable time by detecting these and similar errors already upon compile-time by plugging into the build process and raising compilation errors whenever constraint annotations are incorrectly used.

The processor can be used in basically every build environment (plain javac, Apache Ant, Apache Maven) as well as within all common IDEs. Just be sure to use JDK 6 or later, as the processor is based on the "Pluggable Annotation Processing API" defined by JSR 269 which was introduced with Java 6.

The HV reference guide describes in detail how to integrate the processor into the different environments, so I'll spare you the details here. As example the following screenshot shows some compilation errors raised by the processor within the Eclipse IDE (click to enlarge):

Just for the record it should be noted that the annotation processor already works pretty well but is currently still under development and is considered as an experimental feature as of HV 4.1. If you are facing any problems please report them in JIRA. Some known issues are also discussed in the reference guide.

Summary

The focus for Hibernate Validator 4.0 was to provide a feature-complete, production-ready reference implementation of the Bean Validation spec.

While strictly staying spec-compliant, HV 4.1 goes beyond what is defined in JSR 303 and aims at generating even more user value by providing new constraints, new API functionality as well as an annotation processor for compile-time annotation checking.

In order to try out the new features yourself just download the release from SourceForge. Of course HV 4.1 can also be retrieved from the JBoss Maven repository.

If you are already using HV 4.0.x, the new release generally should work as drop-in replacement. The only exception is that we had to move the class ResourceBundleMessageInterpolator to the new package messageinterpolation. So if you're directly referencing this class, you'll have to update your imports here.

The rationale behind this relocation was to clearly separate those packages which can safely be accessed by HV users from packages intended for internal use only. The public packages are:

org.hibernate.validator
org.hibernate.validator.cfg
org.hibernate.validator.constraints
org.hibernate.validator.messageinterpolation
org.hibernate.validator.resourceloading

Of course we'd be very happy on any feedback. Questions and comments can be posted in the HV forum, while any issues or feature requests should be reported in JIRA.

Oracle's extractValue() Function and XML Namespaces

noreply@blogger.com (Gunnar Morling) — Sat, 12 Jun 2010 21:42:00 +0000

With the help of Oracle's extractValue() function one can retrieve values from XML documents stored in a database using XPath expressions.

Generally this function works as expected but it gave me a hard time when XML namespaces came into play. As I didn't find much related information on the web I thought a short example might be helpful for others facing the same problem.

Let's take the web service from the video rental shop from my recent post Integrating JAX-WS with XmlBeans as example.

For auditing purposes all requests and responses of the web service might be logged in a database table REQUESTS created as follows:

CREATE TABLE REQUESTS (
    ID NUMBER(10,0) PRIMARY KEY,
    REQUEST XMLTYPE,
    RESPONSE XMLTYPE
);

In reality, logging would probably be implemented using a message handler, but for demonstration purposes let's simply insert a sample request of the FindMoviesByDirector() operation using SQL:

INSERT INTO REQUESTS (ID, REQUEST, RESPONSE)
VALUES (
    1,
    '<soapenv:Envelope 
        xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" 
        xmlns:typ="http://www.gunnarmorling.de/moapa/videorental/types">

        <soapenv:Header/>
        <soapenv:Body>
            <typ:FindMoviesByDirectorRequest>
                <Director>Bryan Singer</Director>
            </typ:FindMoviesByDirectorRequest>
        </soapenv:Body>
     </soapenv:Envelope>',
    '...';

Here we have two namespace aliases declared, soapenv for the SOAP message and typ for the actual message content.

The key for accessing values from this document using extractValue() is the pretty poorly documented optional parameter namespace_string, which can be used to declare any namespaces. This has to happen in the form xmlns:alias="URI", multiple namespaces must be separated by a space character.

Knowing that, it's easy to issue a SQL query which retrieves the director name from the request above. Just make sure to qualify the element names with their namespace alias in the XPath expression:

SELECT
    req.id,
    extractValue(
        req.request,
        '/soapenv:Envelope/soapenv:Body/typ:FindMoviesByDirectorRequest/Director',
        'xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/" xmlns:typ="http://www.gunnarmorling.de/moapa/videorental/types"') Title
FROM 
    requests req
WHERE
    id = 1
;

ID   TITLE 
-----------------
1    Bryan Singer

Providing Bean Validation Support for the Joda Time API

noreply@blogger.com (Gunnar Morling) — Fri, 14 May 2010 21:10:00 +0000

Amongst others the Bean Validation API defines two constraint annotations related to time: @Past and @Future. With the help of these constraints one can validate that a given element is a date either in the past or in the future.

As per the BV specification these constraints are allowed for the types java.util.Date and java.util.Calendar. But what if you are working with an alternative date/time library such as the Joda Time API? Does that mean you can't use the @Past/@Future constraints?

Luckily not, as the Bean Validation API defines a mechanism for adding new validators to existing constraints. Basically all you have to do is to implement a validator for each type to be supported and register it within a constraint mapping file.

Note that for the remainder of this post I'll focus on the @Past constraint. Doing the same for @Future is left as an exercise for the reader.

Providing a Validator

So let's start with implementing a validator. The Joda Time API provides a whole bunch of types replacing the JDK date and time types. A good introduction to these types can be found in Joda's quickstart guide.

All Joda types representing exact points on the time-line implement the interface ReadableInstant. Providing an @Past validator for that interface will allow the @Past constraint to be used for widely used ReadableInstant implementations such as DateTime or DateMidnight.

Implementing the validator is straight-forward. Obeying the contract defined by @Past the given date is simply compared to a new DateTime instance which represents the current instant in the default time zone:

public class PastValidatorForReadableInstant implements
        ConstraintValidator<Past, ReadableInstant> {

    public void initialize(Past constraintAnnotation) {}

    public boolean isValid(ReadableInstant value,
            ConstraintValidatorContext constraintValidatorContext) {

        if(value == null) {
            return true;
        }

        return value.isBefore(new DateTime());
    }
}

Similar validators could also be written for other Joda types which don't implement ReadableInstant (such as LocalDate) but as this is basically the same, it is out of the scope of this post.

Registering the Validator

Having implemented the validator we need to register it within a constraint mapping file:

<constraint-mappings
    xmlns="http://jboss.org/xml/ns/javax/validation/mapping"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation=
        "http://jboss.org/xml/ns/javax/validation/mapping validation-mapping-1.0.xsd">

    <constraint-definition annotation="javax.validation.constraints.Past">
        <validated-by include-existing-validators="true">
             <value>de.gmorling.moapa.joda_bv_integration.PastValidatorForReadableInstant</value>
        </validated-by>
    </constraint-definition>

</constraint-mappings>

Using the validated-by element we add our new validator to the validators for the @Past constraint. By setting include-existing-validators to true, we ensure that the @Past constraint still can be used at the JDK date types.

As demanded by the Bean Validation API we then register the constraint mapping file within the central configuration file validation.xml:

<?xml version="1.0" encoding="UTF-8"?>
<validation-config
    xmlns="http://jboss.org/xml/ns/javax/validation/configuration"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://jboss.org/xml/ns/javax/validation/configuration validation-configuration-1.0.xsd">

    <constraint-mapping>META-INF/validation/custom-constraints.xml</constraint-mapping>

</validation-config>

Trying it out

Now it's time to test how that all works out. To do so, we define an examplary domain class Customer which has an attribute birthday of the Joda type DateMidnight:

public class Customer {

    private final String name;

    private final DateMidnight birthday;

    public Customer(String name, DateMidnight birthday) {

        this.name = name;
        this.birthday = birthday;
    }

    @NotNull
    public String getName() {
        return name;
    }

    @NotNull
    @Past
    public DateMidnight getBirthday() {
        return birthday;
    }
}

A simple test finally shows that creating a customer with a future birthday causes a constraint violation, while a customer with a birthday in the past doesn't:

public class CustomerTest {

    private static Validator validator;

    @BeforeClass
    public static void setUpValidatorAndDates() {

        ValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();
        validator = validatorFactory.getValidator();
    }

    @Test
    public void customerWithFutureBirthdayCausesConstraintViolation() {

        Customer customer = new Customer("Bob", new DateMidnight(2020, 11, 3));
        Set<ConstraintViolation<Customer>> constraintViolations = validator.validate(customer);

        assertEquals(1, constraintViolations.size());
        assertEquals("must be in the past", constraintViolations.iterator().next().getMessage());
    }

    @Test
    public void customerWithPastBirthdayCausesNoConstraintViolation() {

        Customer customer = new Customer("Bob", new DateMidnight(1960, 11, 3));
        Set<ConstraintViolation<Customer>> constraintViolations = validator.validate(customer);

        assertTrue(constraintViolations.isEmpty());
    }

}

The complete source code in form of a Maven project can be found in my Git repository.

So just try it out and don't hesistate to post any feedback. It is also planned to add support for the Joda types in an ucoming version of Hibernate Validator.

Slides from JUG presentation on Bean Validation API available

noreply@blogger.com (Gunnar Morling) — Fri, 09 Apr 2010 19:52:00 +0000

Recently I gave a presentation on JSR 303 ("Bean Validation") at the Java User Group in Hamburg, Germany.

I did also some live coding during the talk and mentioned some things only verbally. Nevertheless I thought the slides (which are in German) might be of interest, so I decided to put them online.

You can also find the presentation at slideshare.

The talk went pretty well, there were many questions and people generally seemed quite interested :-) One question related to the automatic validation of constraints at JPA entities I couldn't answer immediately, though.

The question was, whether lazy properties are loaded from the database during validation of class-level constraints (for constraint validation at fields/properties lazy attributes must not be loaded, which is ensured by checking each attribute's load state using a TraversableResolver).

Actually this can happen, depending on the attributes accessed by the validator implementation for the class-level constraint. I think, generally this is alright, as the validator needs to know the values of all attributes relevant for the evaluation of the constraint. If in certain scenarios this behavior is not acceptable, one could examine the attributes' load states manually using javax.validation.PersistenceUtil and depending on that access only certain attributes.

Latest Bean Validation Links

noreply@blogger.com (Gunnar Morling) — Wed, 24 Mar 2010 23:22:00 +0000

When I started blogging on JSR 303 ("Bean Validation"), there was not too much information available on the web concerning the BV API, its usage and its integration with other technologies.

In between JSR 303 got approved, BV is part of Java EE 6 and as it generally gains wider adoption, more and more blog posts and other information related to Bean Validation come available.

That's why I thought it might be a good idea to collect the most interesting pieces and publish those links here every once in a while.

And there you go, here is the first couple of links related to JSR 303:

How to write a custom ConstraintValidatorFactory (Hardy Ferentschik, March 23rd, 2010)
Bean Validation with JPA 1.0 (Antonio Goncalves, March 3rd, 2010)
JSF 2.0 ClientBehavior: Bean Validation in JavaScript (Jan-Kees van Andel, March 17th, 2010)
Unit Testing a Bean Validation ConstraintValidator (Jan-Kees van Andel, March 12th, 2010)
JSR 303 Bean Validation Using Spring 3 (Balaji, March 10th, 2010)
Wicket JSR-303 Validators (Ophelie Salm, February 25rd, 2010)

I plan to post follow-ups, whenever I gathered some interesting links, so stay tuned.

Import code style settings into IntelliJ IDEA

noreply@blogger.com (Gunnar Morling) — Tue, 16 Mar 2010 21:04:00 +0000

Recently I received an IntelliJ IDEA code style settings file for Hibernate Validator, the reference implementation of JSR 303 ("Bean Validation"), to which I'm contributing.

I wanted to import it into IntelliJ in order to format any code changes I make in the project's standard style. But as it turned out, there is no functionality within the IDE for importing code style settings. Instead one has to do the following:

Copy the settings XML file to INTELLIJ_SETTINGS_DIR/config/codestyles (where INTELLIJ_SETTINGS_DIR is the folder containing your IntelliJ settings; typically it is situated within your home directory, the name depends on your version of IntelliJ; in my case the complete path is "~/.IdeaIC90/config/codestyles")
Start IntelliJ
Go to "File" - "Settings" - "Code Style", select "Use global settings" and choose the previously imported style from the drop-down box
Optionally apply the style to one project only by clicking on "Copy to Project" and selecting "Use per project settings" afterwards

Runtime Configuration of Schema Validation using Metro

noreply@blogger.com (Gunnar Morling) — Tue, 09 Mar 2010 14:01:00 +0000

When working with XML-based web services, it usually a good idea to validate all requests and responses against their associated XML schema in order to ensure the integrity of the incoming/outgoing messages.

Unfortunately JAX-WS, the standard API for SOAP-based web services of the Java Platform doesn't specify a standard way for schema validation. Therefore most of the JAX-WS implementations such as Metro or CXF provide a proprietary mechanism to perform that task.

Using Metro, this is simply done by annotating the endpoint class with @SchemaValidation:

@WebService(endpointInterface = "...")
@SchemaValidation
public class VideoRentalPort implements VideoRentalPortType {
    //...
}

This works as expected, but has one big flaw in my eyes: to enable or disable validation for a given endpoint, the application code must be modified, followed by a re-deployment of the application.

This is not viable in many scenarios. Taking a large enterprise application with a whole lot of services for example, schema validation might be turned off by default for performance reasons. But for the purpose of bug analysis it might be required to temporarily enable validation for single endpoints. Re-deploying the application is not an option in this scenario.

That's why I had a look into Metro's implementation of the validation feature and tried to find a way to make schema validation configurable during runtime.

Custom Metro tubes

Schema validation in Metro is realized using in form of a so-called "tube". Metro tubes are conceptually similar to JAX-WS message handlers, but a magnitude more powerful. Since Metro 2.0 the tubes to be applied for a given application can be configured by providing so-called custom "tubelines".

So the basic idea is to extend the standard validation tube provided by Metro in a way which makes it runtime-configurable and register this customized tube instead of the original one.

Note: Before going into details, it should be said that as of Metro 2.0 the tube-related APIs are regarded as Metro-internal APIs, so they could be changed in future versions, causing the approach described here not to work anymore. But as we don't write very much code, this shouldn't really scare us.

Managing configuration state

First of all, some sort of data structure is needed, which will store whether validation is enabled for a given web service endpoint. For this purpose a simple map is sufficient (as this class must be accessible for multiple threads at the same time, a ConcurrentMap is used):

public class ValidationConfigurationHolder {

    private static ConcurrentMap<String, Boolean> configuration = 
        new ConcurrentHashMap<String, Boolean>();

    public static boolean isValidationEnabled(String portName) {

        Boolean theValue = configuration.get(portName);
        return theValue != null ? theValue : Boolean.TRUE;
    }

    public static void setValidationEnabled(String portName, boolean enabled) {
        configuration.put(portName, enabled);
    }
}

Next we need a way to manipulate this structure during application runtime. Java's standard API for management purposes as the one at hand is JMX. The following listing shows a JMX MBean, which later can be invoked to enable or disable validation for a given port:

//MBean interface
public interface EndpointConfigurationMBean {

    public String getName();

    public boolean isSchemaValidationEnabled();

    public void setSchemaValidationEnabled(boolean enabled);

}

//MBean implementation
public class EndpointConfiguration implements EndpointConfigurationMBean {

    private String name;

    public EndpointConfiguration() {}

    public EndpointConfiguration(String name) {
        this.name = name;
    }

    public String getName() {
        return name;
    }

    public boolean isSchemaValidationEnabled() {
        return ValidationConfigurationHolder.isValidationEnabled(name);
    }

    public void setSchemaValidationEnabled(boolean enabled) {
        ValidationConfigurationHolder.setValidationEnabled(name, enabled);
    }

}

The customized validation tube

The schema validation support of Metro is basically realized in three classes: AbstractSchemaValidationTube and ServerSchemaValidationTube resp. ClientSchemaValidationTube which extend the former. To make schema validation configurable on the server side, we create a sub-class of ServerSchemaValidationTube:

public class ConfigurableServerSchemaValidationTube extends ServerSchemaValidationTube {

    private String name;

    public ConfigurableServerSchemaValidationTube(WSEndpoint<?> endpoint, WSBinding binding,
            SEIModel seiModel, WSDLPort wsdlPort, Tube next) {

        super(endpoint, binding, seiModel, wsdlPort, next);

        name = seiModel.getServiceQName().getLocalPart() + "-" + wsdlPort.getName().getLocalPart();
        ValidationConfigurationHolder.setValidationEnabled(name, true);
        registerMBean();
    }

    private void registerMBean() {

        MBeanServer mbs = ManagementFactory.getPlatformMBeanServer(); 

        try {
            mbs.registerMBean(
                new EndpointConfiguration(name),
                new ObjectName("de.gmorling.moapa.videorental.jmx:type=Endpoints,name=" + name));
        }
        catch (Exception e) {
            throw new RuntimeException(e);
        }
    }

    @Override
    protected boolean isNoValidation() {
        return !ValidationConfigurationHolder.isValidationEnabled(name);
    }

    protected ConfigurableServerSchemaValidationTube(ConfigurableServerSchemaValidationTube that, TubeCloner cloner) {
        super(that,cloner);
        this.name = that.name;
    }

    public ConfigurableServerSchemaValidationTube copy(TubeCloner cloner) {
        return new ConfigurableServerSchemaValidationTube(this, cloner);
    }

}

The important thing here is, that the method isNoValidation() is overridden. This method is defined within the base class AbstractSchemaValidationTube and is invoked whenever a request/response is processed by this tube. The implementation of this method simply delegates to the ValidationConfigurationHolder shown above.

Within the constructor an instance of the EndpointConfiguration MBean for the given endpoint is registered with the platform MBean server, which later can be used to toggle validation for this endpoint.

Providing a TubeFactory

Metro tubes are instantiated by implementations of the TubeFactory interface. The following implementation allows the Metro runtime to retrieve instances of the ConfigurableServerSchemaValidationTube:

public class ConfigurableValidationTubeFactory implements TubeFactory {

    //...

    public Tube createTube(ServerTubelineAssemblyContext context)
            throws WebServiceException {

        ServerTubeAssemblerContext wrappedContext = context.getWrappedContext();
        WSEndpoint<?> endpoint = wrappedContext.getEndpoint();
        WSBinding binding = endpoint.getBinding();
        Tube next = context.getTubelineHead();
        WSDLPort wsdlModel = wrappedContext.getWsdlModel();
        SEIModel seiModel = wrappedContext.getSEIModel();

        if (binding instanceof SOAPBinding && binding.isFeatureEnabled(SchemaValidationFeature.class) && wsdlModel != null) {
            return new ConfigurableServerSchemaValidationTube(endpoint, binding, seiModel, wsdlModel, next);
        } else
            return next;
    }
}

The code resembles Metro's instantiation logic for the standard validation tube, the only difference being that a ConfigurableServerSchemaValidationTube is created. Note that we also check whether the SchemaValidationFeature is enabled or not. That way given endpoints can be completey excluded from validation by simply not annotating them with @SchemaValidation.

To register the tube factory with Metro as part of a custom tubeline the configuration file META-INF/metro.xml has to be provided:

<?xml version="1.0" encoding="UTF-8"?>
<metro  xmlns:xsi='http://www.w3.org/2001/XMLSchema-instance'
   xmlns='http://java.sun.com/xml/ns/metro/config'
   version="1.0">
    <tubelines default="#custom-tubeline">
        <tubeline name="custom-tubeline">
            <client-side>
                ...
            </client-side>
            <endpoint-side>
                ...
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.HandlerTubeFactory" />
                <tube-factory className="de.gmorling.moapa.videorental.metro.ConfigurableValidationTubeFactory" />
                <tube-factory className="com.sun.xml.ws.assembler.jaxws.TerminalTubeFactory" />
            </endpoint-side>
        </tubeline>
    </tubelines>
</metro>

As suggested in a post by Metro developer Marek Potociar it's a good idea to take Metro's standard tube configuration, metro-default.xml, as template and adapt it as needed. In our case the ConfigurableValidationTubeFactory is registered instead of the standard ValidationTubeFactory.

Configuring Schema Validation using VisualVM

Having registered the tube factory, it's time to give the whole thing a test run. A complete project containing all sources of this post together with an examplary video rental web service can be found in my Git repo.

When starting the project's main class the service will be fired up and waiting for requests. Any JMX client such as VisualVM can now be used to connect to the running JVM. The following screenshot shows VisualVM connected to the video rental application:

By setting the value of the "SchemaValidationEnabled" property of the MBean named "VideoRentalService-VideoRentalPort", schema validation now can be enabled or disabled for the corresponding endpoint.

Update (march 10, 2010): I created an request for enhancement for that feature: Allow schema validation to be enabled/disabled at runtime. So let's see, whether this will be part of some future Metro version :-)

A generic class-level constraint for the Bean Validation API

noreply@blogger.com (Gunnar Morling) — Mon, 15 Feb 2010 23:41:00 +0000

One question I'm being asked pretty often when talking about the Bean Validation API (JSR 303) is, how cross-field validation can be done. The canonical example for this is a class representing a calendar event, where the end date of an event shall always be later than the start date.

This and other scenarios where validation depends on the values of multiple attributes of a given object can be realized by implementing a class-level constraint.

That basically works pretty well, nevertheless this is one part of the BV spec, I'm not too comfortable with. This is mainly for two reasons:

You'll probably need a dedicated constraint for every reasonably complex business object. Providing an annotation, a validator implementation and an error message for each can become pretty tedious.
Business objects typically know best themselves, whether they are in a consistent, valid state or not. By putting validation logic into a separate constraint validator class, objects have to expose their internal state, which otherwise might not be required.

To circumvent these problems, I suggested a while ago a generic constraint annotation, which allows the use of script expressions written in languages such as Groovy to implement validation logic directly at the validated class.

This approach frees you from the need to implement dedicated constraints for each relevant business object, but also comes at the cost of losing type-safety at compile-time.

The constraint presented in the following therefore tries to combine genericity with compile-time type safety. The basic idea is to implement validation logic within the business objects themselves and to invoke this logic from within a generic constraint class.

In order to do so let's first define an interface to be implemented by any validatable class:

1234	public interface Validatable { public boolean isValid();}

Next we define a constraint annotation, @SelfValidating, which we'll use later on to annotate Validatable implementations:

@Target( { TYPE })
@Retention(RUNTIME)
@Constraint(validatedBy = SelfValidatingValidator.class)
@Documented
public @interface SelfValidating {

    String message() default "{de.gmorling.moapa.self_validating.SelfValidating.message}";

    Class<?>[] groups() default {};

    Class<? extends Payload>[] payload() default {};

}

Of course we also need a constraint validator implementation, which is able to evaluate that constraint:

public class SelfValidatingValidator implements
    ConstraintValidator<SelfValidating, Validatable> {

    public void initialize(SelfValidating constraintAnnotation) {}

    public boolean isValid(Validatable value,
        ConstraintValidatorContext constraintValidatorContext) {

        return value.isValid();
    }
}

The implementation is trivial, as nothing is to do in initialize() and the isValid() method just delegates the call to the validatable object itself.

Finally we need a properties file named ValidationMessages.properties containing the default error message for the constraint:

1	de.gmorling.moapa.self_validating.SelfValidating.message=Validatable object couldn't be validated successfully.

Taking the calendar event example from the beginning, usage of the constraint might look as follows:

@SelfValidating
public class CalendarEvent implements Validatable {

    @NotNull
    private final String title;

    private final Date startDate;

    private final Date endDate;

    public CalendarEvent(String title, Date startDate, Date endDate) {

        this.title = title;
        this.startDate = startDate;
        this.endDate = endDate;
    }

    public boolean isValid() {
        return startDate == null || endDate == null || startDate.before(endDate);
    }

    @Override
    public String toString() {
        DateFormat format = new SimpleDateFormat("dd.MM.yyyy");

        return 
            title + 
            " from " +  (startDate == null ? "-" : format.format(startDate)) + 
            " till " + (endDate == null ? "-" : format.format(endDate));
    }

}

A short unit test shows that the constraint works as expected:

public class SelfValidatingTest {

    private static Validator validator;

    private static Date startDate;

    private static Date endDate;

    @BeforeClass
    public static void setUpValidatorAndDates() {

        ValidatorFactory validatorFactory = Validation.buildDefaultValidatorFactory();
        validator = validatorFactory.getValidator();

        startDate = new GregorianCalendar(2009, 8, 20).getTime();
        endDate = new GregorianCalendar(2009, 8, 21).getTime();
    }

    @Test
    public void calendarEventIsValidAsEndDateIsAfterStartDate() {

        CalendarEvent testEvent = 
            new CalendarEvent("Team meeting", startDate, endDate);

        assertTrue(validator.validate(testEvent).isEmpty());
    }

    @Test
    public void calendarEventIsInvalidAsEndDateIsBeforeStartDate() {

        CalendarEvent testEvent = 
            new CalendarEvent("Team meeting", endDate, startDate);

        Set<ConstraintViolation<CalendarEvent>> constraintViolations = 
            validator.validate(testEvent);
        assertEquals(1, constraintViolations.size());

        assertEquals(
            "Object couldn't be validated successfully.",
            constraintViolations.iterator().next().getMessage());
    }
}

This works like a charm, only the error message returned by the BV runtime is not yet very expressive. This can easily be solved, as the BV API allows to override error messages within constraint annotations:

1234	@SelfValidating(message="{de.gmorling.moapa.self_validating.CalendarEvent.message}")public class CalendarEvent implements Validatable { ...}

Again we need an entry in ValidationMessages.properties for the specified message key:

1	de.gmorling.moapa.self_validating.CalendarEvent.message=End date of event must be after start date.

Conclusion

Providing dedicated class-level constraints for all business objects that require some sort of cross-field validation logic can be quite a tedious task as you need to create an annotation type, a validator implementation and an error message text.

The @SelfValidating constraint reduces the required work by letting business objects validate themselves. That way all you have to do is implement the Validatable interface, annotate your class with @SelfValidating and optionally provide a customized error message. Furthermore business objects are not required to expose their internal state to make it accessible for an external validator implementation.

The complete source code can be found in my GitHub repository. As always I'd be happy about any feedback.

Integrating JAX-WS with XmlBeans

noreply@blogger.com (Gunnar Morling) — Sat, 06 Feb 2010 12:01:00 +0000

JAX-WS as Java's standard API for web services comes with a close integration of JAXB as XML binding framework. More precisely JAXB is actually the only binding technology directly supported by JAX-WS. As JAXB basically does its job pretty well, that's nothing bad per se.

Nevertheless there might be situations where you would like to integrate JAX-WS with other XML binding solutions such as Apache XmlBeans.

For instance you might have used another web service stack and binding framework in the past and now want to migrate your services to JAX-WS. Depending on the number of services, changing your XML binding framework can create quite a lot of work, as you have to rewrite the mapping code which converts between the types generated by the binding framework and your domain objects.

Provider-based endpoints

The key idea for integrating JAX-WS with another binding framework is to create a Provider based endpoint for your web service. Contrary to standard SEI (service endpoint interface) implementations, which solely operate on JAXB generated classes, a provider endpoint has access to the raw XML of incoming and outgoing messages.

That way you can take care of XML marshalling yourself, e.g. by converting incoming XML messages into their corresponding XmlBeans types and the other way around.

In the following a web service for a video rental store shall be built. The service has a single operation, getMovieById, with request and response types in an accompanying XML schema (the service's WSDL and all other sources for this post can be found in my Git repository):

<?xml version="1.0" encoding="UTF-8"?>
<schema 
    targetNamespace="http://www.gunnarmorling.de/moapa/videorental/types"
    xmlns="http://www.w3.org/2001/XMLSchema"
    xmlns:videorental="http://www.gunnarmorling.de/moapa/videorental/types">

    <element name="GetMovieByIdRequest" type="videorental:GetMovieByIdRequest" />
    <element name="GetMovieByIdResponse" type="videorental:GetMovieByIdResponse" />

    <complexType name="GetMovieByIdRequest">
        <sequence>
            <element name="Id" type="long" />
        </sequence>
    </complexType>

    <complexType name="GetMovieByIdResponse">
        <sequence>
            <element type="videorental:Movie" name="Movie" minOccurs="0" />
        </sequence>
    </complexType>

    <complexType name="Movie">
        <sequence>
            <element name="Id" type="long" />
            <element name="Title" type="string" />
            <element name="RunTime" type="int" />
        </sequence>
    </complexType>
</schema>

XmlBeans will generate two document types for the elements (GetMovieByIdRequestDocument, GetMovieByIdResponseDocument) as well as types for each of the complex types.

For the service implementation I recommend to work only with the classes representing the complex types (instead of the document types). An interface representing the service's port type and its implementation therefore might look like this:

public interface VideoRentalPortType {

    public GetMovieByIdResponse getMovieById(GetMovieByIdRequest request);

}

...

public class VideoRentalPort implements VideoRentalPortType {

    private MovieRepository movieRepository = new MovieRepositoryMockImpl();

    public GetMovieByIdResponse getMovieById(GetMovieByIdRequest request) {

        GetMovieByIdResponse response = GetMovieByIdResponse.Factory.newInstance();

        de.gmorling.moapa.videorental.domain.Movie movie = movieRepository.getMovieById(request.getId());

        if(movie != null) {
            response.setMovie(convert(movie));
        }       

        return response;
    }

    private Movie convert(de.gmorling.moapa.videorental.domain.Movie movie) {

        Movie theValue = Movie.Factory.newInstance();

        theValue.setId(movie.getId());
        theValue.setTitle(movie.getTitle());
        theValue.setRunTime(movie.getRunTime());

        return theValue;
    }
}

This looks pretty similar to a typical SEI-based implementation. The only difference is, that the types in use are generated by XmlBeans instead of JAXB. The implementation is straight forward. It takes the movie id from the incoming request, invokes some backend business service and creates a GetMovieByIdResponse from the result.

Next we need to create the actual Provider implementation which will be called by the JAX-WS runtime, whenever the service is invoked:

@WebServiceProvider
@ServiceMode(value=Mode.MESSAGE)
public class VideoRentalProvider implements Provider<SOAPMessage> {

    private VideoRentalPortType videoRentalPort = new VideoRentalPort();

    public SOAPMessage invoke(SOAPMessage request) {

        try {

            Node root = request.getSOAPBody().getFirstChild();

            if(root.getNodeName().contains(GetMovieByIdRequest.class.getSimpleName())) {

                GetMovieByIdRequestDocument requestDocument = GetMovieByIdRequestDocument.Factory.parse(root);
                GetMovieByIdResponseDocument responseDocument = GetMovieByIdResponseDocument.Factory.newInstance();
                responseDocument.setGetMovieByIdResponse(videoRentalPort.getMovieById(requestDocument.getGetMovieByIdRequest()));

                return createSOAPMessage(responseDocument);
            }
            else {
                throw new UnsupportedOperationException();
            }
        }
        catch(Exception e) {
            throw new RuntimeException(e);
        }
    }

    private SOAPMessage createSOAPMessage(XmlObject responseDocument) {

        try {

            SOAPMessage message = MessageFactory.newInstance().createMessage();
            Node node = message.getSOAPBody().getOwnerDocument().importNode(responseDocument.getDomNode().getFirstChild(), true);
            message.getSOAPBody().appendChild(node);
            return message;
        }
        catch(Exception e) {
            throw new RuntimeException(e);
        }
    }

}

A provider implementation must be annotated with @WebServiceProvider. By binding the type parameter to SOAPMessage (a comparison with the alternatives Source and DataSource can be found here) and specifying Mode.MESSAGE within the @ServiceMode annotation we achieve, that we can access complete SOAP messages within the implementation.

The Provider interface defines only one method, invoke(). This method is called whenever any of the service's operations is invoked. Therefore we first have to determine the currently invoked operation, which can be done by peeking at the node name of the first body element.

In case of the getMovieById operation then a GetMovieByIdRequestDocument instance representing the contents of the message body is created using a XmlBeans-generated factory class. From that document we retrieve the actual request element and pass it to the port implementation.

The result is put into a new GetMovieByIdResponseDocument instance, which itself is finally wrapped into a SOAPMessage by importing the root DOM node into the message body.

Conclusion

Creating Provider-based endpoints makes it possible to use JAX-WS together with binding frameworks other than JAXB. Whether it should be done depends as always on the specific circumstances.

For new projects working with SEI endpoints and therefore JAXB should be preferred. The JAX-WS tooling will smoothly generate JAXB binding classes as well as port type interfaces, making the creation of new web services pretty simple.

In migration scenarios things can be different though. Re-writing a whole lot of mapping code originally created for another binding framework such as XmlBeans can be quite a time-consuming and error-prone task. In that case implementing Provider-based services can be an interesting alternative.

When pursuing that approach some performance tests should be executed first. A short load test on my machine didn't show significant execution time differences between JAXB/XmlBeans for the video rental service. But things might look different for larger message types due to the involved DOM manipulations.

Implementing the Builder Pattern using the Bean Validation API

noreply@blogger.com (Gunnar Morling) — Sun, 17 Jan 2010 13:08:00 +0000

In his excellent book "Effective Java (2nd edition)" Joshua Bloch describes a variation of the Builder design pattern for instantiating objects with multiple optional attributes.

Sticking to this pattern frees you from providing multiple constructors with the different optional attributes as parameters (hard to maintain and hard to read for clients) or providing setter methods for the optional attributes (require objects to be mutable, can leave objects in inconsistent state).

As Bloch points out, it's a very good idea to check any invariants applying to the object to be created within the builder's build() method. That way it is ensured, that clients can only retrieve valid object instances from the builder.

If you are using the Bean Validation API (JSR 303) to define constraints for your object model, this can be realized by validating these constraints within the build() method.

The following listing shows an example:

public class Customer {

    private long id;
    private String firstName;
    private String lastName;
    private Date birthday;

    private Customer(Builder builder) {

        this.id = builder.id;
        this.firstName = builder.firstName;
        this.lastName = builder.lastName;
        this.birthday = builder.birthday;
    }

    public static class Builder {

        private static Validator validator = 
            Validation.buildDefaultValidatorFactory().getValidator();

        private long id;
        private String firstName;
        private String lastName;
        private Date birthday;

        public Builder(long id, String lastName) {
            this.id = id;
            this.lastName = lastName;
        }

        public Builder firstName(String firstName) {
            this.firstName = firstName;
            return this;
        }

        public Builder birthday(Date birthday) {
            this.birthday = birthday;
            return this;
        }

        public Customer build() throws ConstraintViolationException {

            Customer customer = new Customer(this);
            Set<ConstraintViolation<Customer>> violations = 
                validator.validate(customer);

            if (!violations.isEmpty()) {
                throw new ConstraintViolationException(
                    new HashSet<ConstraintViolation<?>>(violations));
            }

            return customer;
        }
    }

    @Min(1)
    public long getId() {
        return id;
    }

    @Size(min = 3, max = 80)
    public String getFirstName() {
        return firstName;
    }

    @Size(min = 3, max = 80)
    @NotNull
    public String getLastName() {
        return lastName;
    }

    @Past
    public Date getBirthday() {
        return birthday;
    }

}

The listing shows an exemplary model class Customer for which some invariants apply (e.g. a customer's last name must not be null and must be between 3 and 80 characters long). These invariants are expressed using constraint annotations from the Bean Validation API at the getter methods of the Customer class.

The inner class Builder is in charge of creating Customer instances. All mandatory fields – either primitive (e.g. id) or annotated with @NotNull (e.g. lastName) – are part of the builder's constructor. For all optional fields setter methods on the builder are provided.

Within the build() method the newly created Customer instance is validated using the Validator#validate() method. If any constraint violations occur, a ConstraintViolationException is thrown. That way it's impossible to retrieve an invalid Customer instance. The following unit test shows an example:

public class CustomerTest {

    @Test
    public void validCustomer() {
        Customer c = 
            new Customer.Builder(1, "Smith")
                .firstName("Bob")
                .birthday(new GregorianCalendar(1970, 3, 10).getTime())
                .build();

        assertNotNull(c);
    }

    @Test
    public void lastNameNullAndBirthdayInFuture() {
        try {
            new Customer.Builder(1, null)
                .birthday(new GregorianCalendar(2020, 3, 10).getTime())
                .build();
            fail("Expected ConstraintViolationException wasn't thrown.");
        }
        catch (ConstraintViolationException e) {
            assertEquals(2, e.getConstraintViolations().size());
        }
    }
}

If there are multiple classes for which you want to provide a builder in the described way, it is useful to extract the validation routine into a base class:

public abstract class AbstractBuilder<T> {

    private static Validator validator = 
        Validation.buildDefaultValidatorFactory().getValidator();

    protected abstract T buildInternal();

    public T build() throws ConstraintViolationException {

        T object = buildInternal();

        Set<ConstraintViolation<T>> violations = validator.validate(object);
        if (!violations.isEmpty()) {
            throw new ConstraintViolationException(
                new HashSet<ConstraintViolation<?>>(violations));
        }

        return object;
    }
}

Concrete builder classes have to extend AbstractBuilder and must implement the buildInternal() method:

...
public static class Builder extends AbstractBuilder<Customer> {

    private long id;
    private String firstName;
    private String lastName;
    private Date birthday;

    public Builder(long id, String lastName) {
        this.id = id;
        this.lastName = lastName;
    }

    public Builder firstName(String firstName) {
        this.firstName = firstName;
        return this;
    }

    public Builder birthday(Date birthday) {
        this.birthday = birthday;
        return this;
    }

    @Override
    protected Customer buildInternal() {
        return new Customer(this);
    }
}
...

The complete source code for this post can be found in my Git repository over at github.com.

JPA 2 and Bean Validation in Action

noreply@blogger.com (Gunnar Morling) — Tue, 05 Jan 2010 23:27:00 +0000

Version 2 of the Java Persistence API (JPA) comes with an out-of-the-box integration of the Bean Validation API (BV). If a BV implementation is found in the runtime environment, any BV constraints placed at JPA entities will be validated whenever an entity is written to the database. In the following I'm going to show how the both APIs play together.

Project setup

Assuming you are working with Apache Maven, begin by adding the following repositories to your settings.xml or the pom.xml of your project:

...
<repository>
    <id>JBoss Repo</id>
    <url>http://repository.jboss.com/maven2</url>
</repository>
<repository>
    <id>EclipseLink Repo</id>
    <url>http://www.eclipse.org/downloads/download.php?r=1&nf=1&file=/rt/eclipselink/maven.repo</url>
</repository>   
...

In order to use the reference implementations of both APIs (EclipseLink resp. Hibernate Validator) add the following dependencies to you pom.xml:

...
<!-- JPA API and RI -->
<dependency>
    <groupId>javax.persistence</groupId>
    <artifactId>javax.persistence</artifactId>
    <version>2.0-SNAPSHOT</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.eclipse.persistence</groupId>
    <artifactId>eclipselink</artifactId>
    <version>2.0.0</version>
    <scope>runtime</scope>
</dependency>
...
<!-- Bean Validation API and RI -->
<dependency>
    <groupId>javax.validation</groupId>
    <artifactId>validation-api</artifactId>
    <version>1.0.0.GA</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-validator</artifactId>
    <version>4.0.2.GA</version>
    <scope>runtime</scope>
</dependency>
<dependency>
    <groupId>org.slf4j</groupId>
    <artifactId>slf4j-jdk14</artifactId>
    <version>1.5.6</version>
    <scope>runtime</scope>
</dependency>
...

Instead of EclipseLink you might also use Hibernate 3.5 (currently beta) as JPA provider:

...
<dependency>
    <groupId>org.hibernate.java-persistence</groupId>
    <artifactId>jpa-api</artifactId>
    <version>2.0-cr-1</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.hibernate</groupId>
    <artifactId>hibernate-entitymanager</artifactId>
    <version>3.5.0-Beta-2</version>
    <scope>runtime</scope>
</dependency>
...

Finally we need a database to execute some unit tests against it. I recommend using Apache Derby as it provides an in-memory mode, which is perfectly suited for unit tests:

...
<dependency>
    <groupId>org.apache.derby</groupId>
    <artifactId>derby</artifactId>
    <version>10.5.3.0_1</version>
    <scope>test</scope>
</dependency>
...

The model class

Now let's create a simple model class. It's just a POJO with some annotations stemming from JPA (@Entity, @Id etc.) and some from Bean Validation (@NotNull, @Size):

@Entity
@NamedQueries( { @NamedQuery(name = Customer.FIND_ALL_CUSTOMERS, query = "SELECT c FROM Customer c") })
public class Customer {

    public final static String FIND_ALL_CUSTOMERS = "findAllCustomers";

    @Id
    @GeneratedValue
    @NotNull
    private Long id;

    @NotNull
    @Size(min = 3, max = 80)
    private String name;

    private boolean archived;

    public Customer() {

    }

    public Customer(String name) {
        this.name = name;
        archived = false;
    }

    //getters and setters ...

}

Configuration

Next we have to setup the file persistence.xml which defines the persistence unit to be used for our module tests:

<?xml version="1.0" encoding="UTF-8"?>
<persistence 
    xmlns="http://java.sun.com/xml/ns/persistence"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
    version="2.0">

    <persistence-unit name="testPU" transaction-type="RESOURCE_LOCAL">

        <class>de.gmorling.jpa2.model.Customer</class>

        <properties>
            <property name="eclipselink.target-database" value="DERBY" />
            <property name="eclipselink.ddl-generation" value="create-tables" />
            <property name="javax.persistence.jdbc.driver" value="org.apache.derby.jdbc.EmbeddedDriver" />
            <property name="javax.persistence.jdbc.url" value="jdbc:derby:memory:testDB;create=true" />
            <property name="javax.persistence.jdbc.user" value="APP" />
            <property name="javax.persistence.jdbc.password" value="APP" />
        </properties>
    </persistence-unit>
</persistence>

JPA 2 standardizes the property names for driver, user etc. When working with EclipseLink therefore only two provider-specific properties for the target database and the DDL strategy are required.

Using Hibernate the properties would look like the following (at the time of writing this post the standard properties don't seem to be supported yet by Hibernate):

...
<property name="hibernate.dialect" value="org.hibernate.dialect.DerbyDialect" />
<property name="hibernate.hbm2ddl.auto" value="create" />
<property name="hibernate.connection.driver_class" value="org.apache.derby.jdbc.EmbeddedDriver" />
<property name="hibernate.connection.username" value="APP" />
<property name="hibernate.connection.password" value="APP" />
<property name="hibernate.connection.url" value="jdbc:derby:memory:testDB;create=true" />
...

Note that not a single line of configuration is required to enable the Bean Validation integration, it's working out of the box. If JPA detects a BV implementation on the classpath, it will use it by default to validate any BV constraints, whenever an entity is persisted or updated.

And action ...

To try that, let's write a simple unit test for our model class:

public class CustomerTest {

    private static EntityManagerFactory emf;

    private EntityManager em;

    @BeforeClass
    public static void createEntityManagerFactory() {
        emf = Persistence.createEntityManagerFactory("testPU");
    }

    @AfterClass
    public static void closeEntityManagerFactory() {
        emf.close();
    }

    @Before
    public void beginTransaction() {
        em = emf.createEntityManager();
        em.getTransaction().begin();
    }

    @After
    public void rollbackTransaction() {

        if (em.getTransaction().isActive())
            em.getTransaction().rollback();

        if (em.isOpen())
            em.close();
    }

    @Test
    public void nameTooShort() {

        try {
            Customer customer = new Customer("Bo");
            em.persist(customer);
            fail("Expected ConstraintViolationException wasn't thrown.");
        } 
        catch (ConstraintViolationException e) {
            assertEquals(1, e.getConstraintViolations().size());
            ConstraintViolation<?> violation = 
                e.getConstraintViolations().iterator().next();

            assertEquals("name", violation.getPropertyPath().toString());
            assertEquals(
                Size.class, 
                violation.getConstraintDescriptor().getAnnotation().annotationType());
        }
    }

    @Test
    public void validCustomer() {

        Customer customer = new Customer("Bob");
        em.persist(customer);

        Query query = em.createNamedQuery(Customer.FIND_ALL_CUSTOMERS);

        assertEquals(1, query.getResultList().size());
    }
}

The first four methods are just for setting up resp. closing down an entity manager factory for our persistence unit as well as the entity manager to be used.

In the test method nameTooShort() a ConstraintViolationException is raised, as the @Size constraint of the "name" attribute isn't fulfilled. The method validCustomer() on the other hand shows how a valid Customer instance is persisted and successfully retrieved later on.

Specifying validation groups

By default the constraint annotations of the Default validation group are validated upon inserting a new entity. The same holds true when an existing entity is updated, while no validation takes place by default if an entity is deleted.

If needed this behavior can be overridden by specifying the following properties in the persistence.xml (where values must be comma separated lists of fully-qualified class names of the groups to be validated):

123	javax.persistence.validation.group.pre-persistjavax.persistence.validation.group.pre-updatejavax.persistence.validation.group.pre-remove

Let's assume for example that when a customer account is closed the concerned record from the Customer table is moved to some kind of archive storage. For all migrated records the "archived" flag should be set to true. Using a constraint annotation we would like to ensure now, that only archived Customer records are allowed to be deleted.

To do so we first define a new validation group by declaring an empty interface:

1	public interface DeletionAttributes {}

Now we add an @AssertTrue constraint to the "archived" attribute, which is part of this validation group:

public class Customer {

    ...
    @AssertTrue(groups = DeletionAttributes.class)
    private boolean archived;
    ...
}

Then we specify that constraints of the DeletionAttributes group shall be evaluated upon entity removal:

123	...<property name="javax.persistence.validation.group.pre-remove" value="de.gmorling.jpa2.model.DeletionAttributes" />...

As an unit test shows, a ConstraintViolationException will be raised now, if we try to delete a non-archived customer:

...
@Test(expected = ConstraintViolationException.class)
public void nonArchivedCustomerDeleted() {

    Customer customer = new Customer("Bob");
    em.persist(customer);
    em.remove(customer);
}...

But everything will be fine, if an archived customer gets deleted:

...
@Test
public void archivedCustomerDeleted() {

    Customer customer = new Customer("Bob");
    em.persist(customer);

    customer.setArchived(true);
    em.remove(customer);
    assertTrue(
        em.createNamedQuery(Customer.FIND_ALL_CUSTOMERS).getResultList().isEmpty());
}
...

Specifying the validation groups to be evaluated allows a very fine-grained configuration of the constraint checking process. But there might also be situations where you don't want any validation to take place at all. In that case the validation can be turned off completely by setting the validation mode to "NONE" within your persistence.xml:

...
<persistence-unit name="testPU" transaction-type="RESOURCE_LOCAL">
    <validation-mode>NONE</validation-mode> 
    ...
</persistence-unit>
...

Conclusion

As this post shows, JPA and BV API are integrated very well. Validating your entities before they are written to the database is a very powerful tool for improving data quality, as it ensures that all your persisted data adheres to the constraints of your object model.

I really recommend you to try it out yourself and of course I would be very happy on any feedback.

2009 in numbers

noreply@blogger.com (Gunnar Morling) — Sun, 03 Jan 2010 19:39:00 +0000

2009 was my first complete year of blogging, so I thought it might be the right time to present some statistics of the last 12 months:

17,738 visits total
25,394 page views total
best month: March (1,958 visits)
best day: March, 13 th (335 visits due to the Adam Bien effect ;-))

These were the most visited posts:

Getting started with JSR 303 (Bean Validation) – part 1 (4,332 views)
Guice Tutorial part 3 – Integrating Guice with EJB (3,148 views)
Writing and testing JAX-WS clients using the Spring framework (2,129 views)

The visitors came from 118 different countries, the top 5 being:

United States: 26.18%
Germany: 14.95%
United Kingdom: 7.00%
France 4.71%
India: 3.00%

Thank you all for reading and commenting. Stay tuned :-)

Running JSF 2 on embedded Jetty

noreply@blogger.com (Gunnar Morling) — Thu, 31 Dec 2009 16:36:00 +0000

Jetty is widely appreciated as low-footprint and lightning-fast web container. That makes it also a perfect fit to be used as development runtime, where short turnaround times are an absolut must.

I used to work with the Jetty Maven plugin, which supports hot-deploying applications after any code changes while Jetty is running. This works pretty well, but comes at the cost that your session data is lost during re-deployment and depending on your application's complexity it also can take some seconds to get it up running again.

So I tried another option: running Jetty in embedded mode. For that purpose Jetty provides a comprehensive API, which we can use to write a simple main class that starts up a Jetty instance serving the application we are currently developing:

public class JettyRunner {

    public static void main(String[] args) throws Exception {

        Server server = new Server();

        Connector connector = new SelectChannelConnector();
        connector.setPort(8080);
        connector.setHost("127.0.0.1");
        server.addConnector(connector);

        WebAppContext wac = new WebAppContext();
        wac.setContextPath("/myapp");
        wac.setBaseResource(
            new ResourceCollection(
                new String[] {"./src/main/webapp"}));

        server.setHandler(wac);
        server.setStopAtShutdown(true);
        server.start();
        server.join();
    }
}

The code is pretty much straight forward: first a connector with port and hostname is configured, then a context for the application is created and registered with the server, which finally is started up.

When we launch this class in debugging mode from within our IDE, code changes are immediately applied to the running application without the need to re-deploy or restart it due to Java's hot code replacement mechanism.

Furthermore all changes to the files under "src/main/webapp" are instantly visible, as the files are served directly from there.

The reduced number of required restarts/redeployments greatly improves development productivity. Basically restarting is only required when modifying deployment descriptors (such as web.xml) or when class signatures are modified (e.g. by adding new methods).

Running JSF applications

This works like a charm for basic servlets, but things are getting a bit more complicated, when JSF comes into play.

The reason is that JSF searches for all classes carrying any of the JSF annotations (such as @ManagedBean) when starting up. This scan takes place in the directory "META-INF/classes". As this folder doesn't exist in our case, no single managed bean will be detected.

How can this problem be solved? First of all the output folder of the application must be added to the WebAppContext's resource collection. In case of a Maven-based project we have to add the "target" directory:

...
wac.setBaseResource(
    new ResourceCollection(
        new String[] { "./src/main/webapp", "./target" }));
...

But the problem remains that JSF searches class files in "WEB-INF/classes", although in our case they are located under "classes".

We could modify the destination of class files (by setting Maven's property ${project.build.outputDirectory}, but I wouldn't really recommend this. Diverging from Maven's conventions makes your project harder to understand for other developers and as rumors go there still are Maven plugins around that directly access "target/classes" instead of referencing said property.

Resource aliases

I studied Jetty's API for a while and came across the concept of resource aliases which provides a neat solution to our problem. To define an alias for "WEB-INF/classes" just do the following:

1234	...WebAppContext wac = new WebAppContext();wac.setResourceAlias("/WEB-INF/classes/", "/classes/");...

Unfortunately this only works for single resources. While everything is fine when the folder "WEB-INF/classes" itself is accessed, the alias won't be applied when accessing resources contained within this folder, e.g. "WEB-INF/classes/MyManagedBean.class".

To tackle this problem I extended Jetty's WebAppContext to provide a means of pattern based alias resolution. The only overridden method is getResourceAlias():

public class AliasEnhancedWebAppContext extends WebAppContext {

    @Override
    public String getResourceAlias(String alias) {

        @SuppressWarnings("unchecked")
        Map<String, String> resourceAliases = 
            (Map<String, String>) getResourceAliases();

        if (resourceAliases == null) {
            return null;
        }

        for (Entry<String, String> oneAlias : 
            resourceAliases.entrySet()) {

            if (alias.startsWith(oneAlias.getKey())) {
                return alias.replace(
                    oneAlias.getKey(), oneAlias.getValue());
            }
        }

        return null;
    }
}

Whenever an alias for a given resource is looked up, it is checked whether the resource name starts with one of the registered aliases. If that's the case, the aliased part will be replaced. Having registered the alias from the previous listing, e.g. "WEB-INF/classes/MyManagedBean.class" will be aliased with "classes/MyManagedBean.class".

It's certainly not perfect (e.g. nested replacements are not considered), but I would regard it good enough for being used in the scenario at hand. So let's look how all this fits together:

public class JettyRunner {

    public static void main(String[] args) throws Exception {

        Server server = new Server();

        Connector connector = new SelectChannelConnector();
        connector.setPort(8080);
        connector.setHost("127.0.0.1");
        server.addConnector(connector);

        WebAppContext wac = new AliasEnhancedWebAppContext();
        wac.setContextPath("/myapp");
        wac.setBaseResource(
            new ResourceCollection(
                new String[] {"./src/main/webapp", "./target"}));
        wac.setResourceAlias("/WEB-INF/classes/", "/classes/");

        server.setHandler(wac);
        server.setStopAtShutdown(true);
        server.start();
        server.join();
    }
}

That way we are finally able to run a JSF application on an embedded Jetty instance, providing us with a very efficient way of development.

EL libraries

Unfortunately my happiness was short lasting as I ran into another problem: Using method parameters within EL expressions gave me parsing errors wrapped into a javax.faces.view.facelets.TagAttributeException.

The reason is that method invocations with parameters are a feature of Unified EL version 2.2 which is leveraged by JSF 2. As others already pointed out, you need to replace the EL JARs (API and impl) of you web container with the new ones.

Using Maven this can be done by adding the following dependencies to your project's pom.xml (if required, add the java.net Maven repository to your settings.xml first):

...
<dependency>
    <groupId>javax.el</groupId>
    <artifactId>el-api</artifactId>
    <version>2.2</version>
    <scope>compile</scope>
</dependency>
<dependency>
    <groupId>org.glassfish.web</groupId>
    <artifactId>el-impl</artifactId>
    <version>2.2</version>
    <scope>runtime</scope>
</dependency>
...

When working with the JSF 2 reference implementation Mojarra furthermore the expression factory to be used must be set to the one from the new EL implementation by specifying the following context parameter within your web.xml:

...
<context-param>
  <param-name>com.sun.faces.expressionFactory</param-name>
  <param-value>com.sun.el.ExpressionFactoryImpl</param-value>
</context-param>
...

Having done that, you are now able to use parametrized method invocations within EL expressions, which is especially useful when performing actions on the rows of a data table.

A generic and yet type-safe DTO - part 2

noreply@blogger.com (Gunnar Morling) — Sat, 21 Nov 2009 15:52:00 +0000

In a recent post I presented a generic DTO implementation which allows a type-safe way of accessing its contents.

The presented approach reduces the efforts of writing a lot of dedicated DTOs but comes at the cost that it is not obvious, which attributes are allowed to be put into or can be retrieved from a given DTO instance. Therefore methods using such a generic DTO as parameter or return value define a rather loose contract.

In the following I'm going to show a way to solve this problem. The basic idea is to introduce the concept of "attribute groups". Each attribute belongs to such a group, and each GenericDTO instance is created for exactly one attribute group.

Let's first define a marker interface AttributeGroup from which all concrete attribute groups will derive:

123	public interface AttributeGroup {}

The Attribute class doesn't differ much from the version introduced in the first post. It's just parametrized with the type of group to which a given attribute belongs:

public class Attribute<G extends AttributeGroup, T> implements Serializable {

    private static final long serialVersionUID = 1L;

    private String name;

    public Attribute(String name) {

        if (name == null) {
            throw new IllegalArgumentException();
        }

        this.name = name;
    }

    public static <F extends AttributeGroup, S> Attribute<F, S> getInstance(
            String name) {
        return new Attribute<F, S>(name);
    }

    @Override
    public String toString() {
        return name;
    }

    // equals(), hashCode() ...
}

As in the previous post Attribute instances are declared as constants on interfaces, e.g. PersonAttributes. But now each of these interfaces extends AttributeGroup, while the Attribute instances are parametrized with the attribute group:

public interface PersonAttributes extends AttributeGroup {

    public static final Attribute<PersonAttributes, String> FIRST_NAME = 
        Attribute.getInstance("FIRST_NAME");

    public static final Attribute<PersonAttributes, Integer> AGE = 
        Attribute.getInstance("AGE");
}

...

public class OrderAttributes implements AttributeGroup {

    public static final Attribute<OrderAttributes, Long> 
        TOTAL_PRICE = Attribute.getInstance("TOTAL_PRICE");
}

Also the GenericDTO class now has a type parameter specifying for which attribute group a given instance is declared:

public class GenericDTO<G extends AttributeGroup> implements Serializable {

    private static final long serialVersionUID = 1L;

    private Class<G> attributeGroup;

    private Map<Attribute<G, ?>, Object> attributes = new LinkedHashMap<Attribute<G, ?>, Object>();

    private GenericDTO(Class<G> attributeGroup) {
        this.attributeGroup = attributeGroup;
    }

    public static <B extends AttributeGroup> GenericDTO<B> getInstance(
            Class<B> clazz) {
        return new GenericDTO<B>(clazz);
    }

    public <T> GenericDTO<G> set(Attribute<G, T> identifier, T value) {

        attributes.put(identifier, value);

        return this;
    }

    public <T> T get(Attribute<G, T> identifier) {

        @SuppressWarnings("unchecked")
        T theValue = (T) attributes.get(identifier);

        return theValue;
    }

    public <T> T remove(Attribute<G, T> identifier) {

        @SuppressWarnings("unchecked")
        T theValue = (T) attributes.remove(identifier);

        return theValue;
    }

    public void clear() {
        attributes.clear();
    }

    public int size() {
        return attributes.size();
    }

    public Set<Attribute<G, ?>> getAttributes() {
        return attributes.keySet();
    }

    public boolean contains(Attribute<G, ?> identifier) {

        return attributes.containsKey(identifier);
    }

    @Override
    public String toString() {
        return attributeGroup.getSimpleName() + " [" + attributes + "]";
    }

    // equals(), hashCode() ...
}

That way it is now clear at compile time which attributes are supported by a given GenericDTO instance.

When for instance having a GenericDTO instance at hand, only attributes of the PersonAttributes group can be put into this DTO or can be retrieved from it. Trying to insert attributes of another group will yield in a compiler error:

...
GenericDTO dto = GenericDTO.getInstance(PersonAttributes.class);

//that's fine
dto.set(PersonAttributes.FIRST_NAME, "Bob").set(PersonAttributes.AGE, 28);

//compiler error
dto.set(OrderAttributes.TOTAL_PRICE, 9990);
...

By introducing the group concept Attribute declaration is a bit more verbose than in the first version, but real compile-time safety and more explicit contracts should be worth the effort, which is still way below than having to implement dedicated DTOs with getters and setters for each attribute as well as proper equals()-, hashCode()- and toString()-Methods.

What do you think – is a generic DTO implemented that way a good idea? As always I'm looking forward to receiving your feedback.

Article on Bean Validation API available for download

noreply@blogger.com (Gunnar Morling) — Sat, 07 Nov 2009 11:06:00 +0000

My article "Objekt: Zur Prüfung bitte!" covering the Bean Validation API (JSR 303) is available for download now. It originally appeared in Java Magazin 09.09.

Since the time of writing JSR 303 reached its final state, but besides some minor changes the article is still up to date (e.g. it's "Payload" instead of "ConstraintPayload" now). More in-depth information on using the Bean Validation API and its reference implementation Hibernate Validator 4 can be found in Hibernate Validator's reference guide, which I co-authored.