Integration testing custom validation constraints in Jersey 2

I recently joined a team trying to switch a monolithic legacy system into set of RESTful services in Java. They decided to use latest 2.x version of Jersey as a REST container which was not a first choice for me, since I’m not a big fan of JSR-* specs. But now I must admit that JAX-RS 2.x is doing things right: requires almost zero boilerplate code, support auto-discovery of features and prefers convention over configuration like other modern frameworks. Since the spec is still young, it’s hard to find good tutorials and kick-off projects with some working code. I created jersey2-starter project on GitHub which can be used as starting point for your own production-ready RESTful service. In this post I’d like to cover how to implement and integration test your own validation constraints of REST resources. Custom constraints One of the issues which bothers me when coding REST in Java is littering your class model with annotations. Suppose you want to build a simple Todo list REST service, when using Jackson, validation and Spring Data, you can easily end up with this as your entity class: @Document public class Todo { private Long id; @NotNull private String description; @NotNull private Boolean completed; @NotNull private DateTime dueDate; @JsonCreator public Todo(@JsonProperty("description") String description, @JsonProperty("dueDate") DateTime dueDate) { this.description = description; this.dueDate = dueDate; this.completed = false; } // getters and setters } Your domain model is now effectively blured by messy annotations almost everywhere. Let’s see what we can do with validation constraints (@NotNulls). Some may say that you could introduce some DTO layer with own validation rules, but it conflicts for me with pure REST API design, which stands that you operate on resources which should map to your domain classes. On the other hand – what does it mean that Todo object is valid? When you create a Todo you should provide a description and due date, but what when you’re updating? You should be able to change any of description, due date (postponing) and completion flag (marking as done) – but you should provide at least one of these as valid modification. So my idea is to introduce custom validation constraints, different ones for creation and modification: @Target({TYPE, PARAMETER}) @Retention(RUNTIME) @Constraint(validatedBy = ValidForCreation.Validator.class) public @interface ValidForCreation { //... class Validator implements ConstraintValidator<ValidForCreation, Todo> { /... @Override public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) { return todo != null && todo.getId() == null && todo.getDescription() != null && todo.getDueDate() != null; } } } @Target({TYPE, PARAMETER}) @Retention(RUNTIME) @Constraint(validatedBy = ValidForModification.Validator.class) public @interface ValidForModification { //... class Validator implements ConstraintValidator<ValidForModification, Todo> { /... @Override public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) { return todo != null && todo.getId() == null && (todo.getDescription() != null || todo.getDueDate() != null || todo.isCompleted() != null); } } } And now you can move validation annotations to the definition of a REST endpoint: @POST @Consumes(APPLICATION_JSON) public Response create(@ValidForCreation Todo todo) {...} @PUT @Consumes(APPLICATION_JSON) public Response update(@ValidForModification Todo todo) {...} And now you can remove those NotNulls from your model. Integration testing There are in general two approaches to integration testing: test is being run on separate JVM than the app, which is deployed on some other integration environment test deploys the application programmatically in the setup block. Both of these have their pros and cons, but for small enough servoces, I personally prefer the second approach. It’s much easier to setup and you have only one JVM started, which makes debugging really easy. You can use a generic framework like Arquillian for starting your application in a container environment, but I prefer simple solutions and just use emdedded Jetty. To make test setup 100% production equivalent, I’m creating full Jetty’s WebAppContext and have to resolve all runtime dependencies for Jersey auto-discovery to work. This can be simply achieved with Maven resolved from Shrinkwrap – an Arquillian subproject: WebAppContext webAppContext = new WebAppContext(); webAppContext.setResourceBase("src/main/webapp"); webAppContext.setContextPath("/"); File[] mavenLibs = Maven.resolver().loadPomFromFile("pom.xml") .importCompileAndRuntimeDependencies() .resolve().withTransitivity().asFile(); for (File file: mavenLibs) { webAppContext.getMetaData().addWebInfJar(new FileResource(file.toURI())); } webAppContext.getMetaData().addContainerResource(new FileResource(new File("./target/classes").toURI())); webAppContext.setConfigurations(new Configuration[] { new AnnotationConfiguration(), new WebXmlConfiguration(), new WebInfConfiguration() }); server.setHandler(webAppContext); (this Stackoverflow thread inspired me a lot here) Now it’s time for the last part of the post: parametrizing our integration tests. Since we want to test validation constraints, there are many edge paths to check (and make your code coverage close to 100%). Writing one test per each case could be a bad idea. Among the many solutions for JUnit I’m most convinced to the Junit Params by Pragmatists team. It’s really simple and have nice concept of JQuery-like helper for creating providers. Here is my tests code (I’m also using builder pattern here to create various kinds of Todos): @Test @Parameters(method = "provideInvalidTodosForCreation") public void shouldRejectInvalidTodoWhenCreate(Todo todo) { Response response = createTarget().request().post(Entity.json(todo)); assertThat(response.getStatus()).isEqualTo(BAD_REQUEST.getStatusCode()); } private static Object[] provideInvalidTodosForCreation() { return $( new TodoBuilder().withDescription("test").build(), new TodoBuilder().withDueDate(DateTime.now()).build(), new TodoBuilder().withId(123L).build(), new TodoBuilder().build() ); } OK, enough of reading, feel free to clone the project and start writing your REST services! I recently joined a team trying to switch a monolithic legacy system into set of RESTful services in Java. They decided to use latest 2.x version of Jersey as a REST container which was not a first choice for me, since I’m not a big fan of JSR-* specs. But now I must admit that JAX-RS 2.x is doing things right: requires almost zero boilerplate code, support auto-discovery of features and prefers convention over configuration like other modern frameworks. Since the spec is still young, it’s hard to find good tutorials and kick-off projects with some working code. I created jersey2-starter project on GitHub which can be used as starting point for your own production-ready RESTful service. In this post I’d like to cover how to implement and integration test your own validation constraints of REST resources. Custom constraints One of the issues which bothers me when coding REST in Java is littering your class model with annotations. Suppose you want to build a simple Todo list REST service, when using Jackson, validation and Spring Data, you can easily end up with this as your entity class: @Document public class Todo { private Long id; @NotNull private String description; @NotNull private Boolean completed; @NotNull private DateTime dueDate; @JsonCreator public Todo(@JsonProperty("description") String description, @JsonProperty("dueDate") DateTime dueDate) { this.description = description; this.dueDate = dueDate; this.completed = false; } // getters and setters } Your domain model is now effectively blured by messy annotations almost everywhere. Let’s see what we can do with validation constraints (@NotNulls). Some may say that you could introduce some DTO layer with own validation rules, but it conflicts for me with pure REST API design, which stands that you operate on resources which should map to your domain classes. On the other hand – what does it mean that Todo object is valid? When you create a Todo you should provide a description and due date, but what when you’re updating? You should be able to change any of description, due date (postponing) and completion flag (marking as done) – but you should provide at least one of these as valid modification. So my idea is to introduce custom validation constraints, different ones for creation and modification: @Target({TYPE, PARAMETER}) @Retention(RUNTIME) @Constraint(validatedBy = ValidForCreation.Validator.class) public @interface ValidForCreation { //... class Validator implements ConstraintValidator<ValidForCreation, Todo> { /... @Override public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) { return todo != null && todo.getId() == null && todo.getDescription() != null && todo.getDueDate() != null; } } } @Target({TYPE, PARAMETER}) @Retention(RUNTIME) @Constraint(validatedBy = ValidForModification.Validator.class) public @interface ValidForModification { //... class Validator implements ConstraintValidator<ValidForModification, Todo> { /... @Override public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) { return todo != null && todo.getId() == null && (todo.getDescription() != null || todo.getDueDate() != null || todo.isCompleted() != null); } } } And now you can move validation annotations to the definition of a REST endpoint: @POST @Consumes(APPLICATION_JSON) public Response create(@ValidForCreation Todo todo) {...} @PUT @Consumes(APPLICATION_JSON) public Response update(@ValidForModification Todo todo) {...} And now you can remove those NotNulls from your model. Integration testing There are in general two approaches to integration testing: test is being run on separate JVM than the app, which is deployed on some other integration environment test deploys the application programmatically in the setup block. Both of these have their pros and cons, but for small enough servoces, I personally prefer the second approach. It’s much easier to setup and you have only one JVM started, which makes debugging really easy. You can use a generic framework like Arquillian for starting your application in a container environment, but I prefer simple solutions and just use emdedded Jetty. To make test setup 100% production equivalent, I’m creating full Jetty’s WebAppContext and have to resolve all runtime dependencies for Jersey auto-discovery to work. This can be simply achieved with Maven resolved from Shrinkwrap – an Arquillian subproject: WebAppContext webAppContext = new WebAppContext(); webAppContext.setResourceBase("src/main/webapp"); webAppContext.setContextPath("/"); File[] mavenLibs = Maven.resolver().loadPomFromFile("pom.xml") .importCompileAndRuntimeDependencies() .resolve().withTransitivity().asFile(); for (File file: mavenLibs) { webAppContext.getMetaData().addWebInfJar(new FileResource(file.toURI())); } webAppContext.getMetaData().addContainerResource(new FileResource(new File("./target/classes").toURI())); webAppContext.setConfigurations(new Configuration[] { new AnnotationConfiguration(), new WebXmlConfiguration(), new WebInfConfiguration() }); server.setHandler(webAppContext); (this Stackoverflow thread inspired me a lot here) Now it’s time for the last part of the post: parametrizing our integration tests. Since we want to test validation constraints, there are many edge paths to check (and make your code coverage close to 100%). Writing one test per each case could be a bad idea. Among the many solutions for JUnit I’m most convinced to the Junit Params by Pragmatists team. It’s really simple and have nice concept of JQuery-like helper for creating providers. Here is my tests code (I’m also using builder pattern here to create various kinds of Todos): @Test @Parameters(method = "provideInvalidTodosForCreation") public void shouldRejectInvalidTodoWhenCreate(Todo todo) { Response response = createTarget().request().post(Entity.json(todo)); assertThat(response.getStatus()).isEqualTo(BAD_REQUEST.getStatusCode()); } private static Object[] provideInvalidTodosForCreation() { return $( new TodoBuilder().withDescription("test").build(), new TodoBuilder().withDueDate(DateTime.now()).build(), new TodoBuilder().withId(123L).build(), new TodoBuilder().build() ); } OK, enough of reading, feel free to clone the project and start writing your REST services!

I recently joined a team trying to switch a monolithic legacy system into set of RESTful services in Java. They decided to use latest 2.x version of Jersey as a REST container which was not a first choice for me, since I’m not a big fan of JSR-* specs. But now I must admit that JAX-RS 2.x is doing things right: requires almost zero boilerplate code, support auto-discovery of features and prefers convention over configuration like other modern frameworks. Since the spec is still young, it’s hard to find good tutorials and kick-off projects with some working code. I created jersey2-starter project on GitHub which can be used as starting point for your own production-ready RESTful service. In this post I’d like to cover how to implement and integration test your own validation constraints of REST resources.

Custom constraints

One of the issues which bothers me when coding REST in Java is littering your class model with annotations. Suppose you want to build a simple Todo list REST service, when using Jackson, validation and Spring Data, you can easily end up with this as your entity class:

@Document
public class Todo {
    private Long id;
    @NotNull
    private String description;
    @NotNull
    private Boolean completed;
    @NotNull
    private DateTime dueDate;

    @JsonCreator
    public Todo(@JsonProperty("description") String description, @JsonProperty("dueDate") DateTime dueDate) {
        this.description = description;
        this.dueDate = dueDate;
        this.completed = false;
    }
    // getters and setters
}

Your domain model is now effectively blured by messy annotations almost everywhere. Let’s see what we can do with validation constraints (@NotNulls). Some may say that you could introduce some DTO layer with own validation rules, but it conflicts for me with pure REST API design, which stands that you operate on resources which should map to your domain classes. On the other hand – what does it mean that Todo object is valid? When you create a Todo you should provide a description and due date, but what when you’re updating? You should be able to change any of description, due date (postponing) and completion flag (marking as done) – but you should provide at least one of these as valid modification. So my idea is to introduce custom validation constraints, different ones for creation and modification:

@Target({TYPE, PARAMETER})
@Retention(RUNTIME)
@Constraint(validatedBy = ValidForCreation.Validator.class)
public @interface ValidForCreation {
    //...
    class Validator implements ConstraintValidator<ValidForCreation, Todo> {
    /...
        @Override
        public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) {
            return todo != null
                && todo.getId() == null
                && todo.getDescription() != null
                && todo.getDueDate() != null;
        }
    }
}

@Target({TYPE, PARAMETER})
@Retention(RUNTIME)
@Constraint(validatedBy = ValidForModification.Validator.class)
public @interface ValidForModification {
    //...
    class Validator implements ConstraintValidator<ValidForModification, Todo> {
    /...
        @Override
        public boolean isValid(Todo todo, ConstraintValidatorContext constraintValidatorContext) {
            return todo != null
                && todo.getId() == null
                && (todo.getDescription() != null || todo.getDueDate() != null || todo.isCompleted() != null);
        }
    }
}

And now you can move validation annotations to the definition of a REST endpoint:

@POST
@Consumes(APPLICATION_JSON)
public Response create(@ValidForCreation Todo todo) {...}

@PUT
@Consumes(APPLICATION_JSON)
public Response update(@ValidForModification Todo todo) {...}

And now you can remove those NotNulls from your model.

Integration testing

There are in general two approaches to integration testing:

  • test is being run on separate JVM than the app, which is deployed on some other integration environment
  • test deploys the application programmatically in the setup block.

Both of these have their pros and cons, but for small enough servoces, I personally prefer the second approach. It’s much easier to setup and you have only one JVM started, which makes debugging really easy. You can use a generic framework like Arquillian for starting your application in a container environment, but I prefer simple solutions and just use emdedded Jetty. To make test setup 100% production equivalent, I’m creating full Jetty’s WebAppContext and have to resolve all runtime dependencies for Jersey auto-discovery to work. This can be simply achieved with Maven resolved from Shrinkwrap – an Arquillian subproject:

    WebAppContext webAppContext = new WebAppContext();
    webAppContext.setResourceBase("src/main/webapp");
    webAppContext.setContextPath("/");
    File[] mavenLibs = Maven.resolver().loadPomFromFile("pom.xml")
                .importCompileAndRuntimeDependencies()
                .resolve().withTransitivity().asFile();
    for (File file: mavenLibs) {
        webAppContext.getMetaData().addWebInfJar(new FileResource(file.toURI()));
    }
    webAppContext.getMetaData().addContainerResource(new FileResource(new File("./target/classes").toURI()));

    webAppContext.setConfigurations(new Configuration[] {
        new AnnotationConfiguration(),
        new WebXmlConfiguration(),
        new WebInfConfiguration()
    });
    server.setHandler(webAppContext);

(this Stackoverflow thread inspired me a lot here)

Now it’s time for the last part of the post: parametrizing our integration tests. Since we want to test validation constraints, there are many edge paths to check (and make your code coverage close to 100%). Writing one test per each case could be a bad idea. Among the many solutions for JUnit I’m most convinced to the Junit Params by Pragmatists team. It’s really simple and have nice concept of JQuery-like helper for creating providers. Here is my tests code (I’m also using builder pattern here to create various kinds of Todos):

@Test
@Parameters(method = "provideInvalidTodosForCreation")
public void shouldRejectInvalidTodoWhenCreate(Todo todo) {
    Response response = createTarget().request().post(Entity.json(todo));

    assertThat(response.getStatus()).isEqualTo(BAD_REQUEST.getStatusCode());
}

private static Object[] provideInvalidTodosForCreation() {
    return $(
        new TodoBuilder().withDescription("test").build(),
        new TodoBuilder().withDueDate(DateTime.now()).build(),
        new TodoBuilder().withId(123L).build(),
        new TodoBuilder().build()
    );
}

OK, enough of reading, feel free to clone the project and start writing your REST services!

You May Also Like

Private fields and methods are not private in groovy

I used to code in Java before I met groovy. Like most of you, groovy attracted me with many enhancements. This was to my surprise to discover that method visibility in groovy is handled different than Java!

Consider this example:

class Person {
private String name
public String surname

private Person() {}

private String signature() { "${name?.substring(0, 1)}. $surname" }

public String toString() { "I am $name $surname" }
}

How is this class interpreted with Java?

  1. Person has private constructor that cannot be accessed
  2. Field "name" is private and cannot be accessed
  3. Method signature() is private and cannot be accessed

Let's see how groovy interpretes Person:

public static void main(String[] args) {
def person = new Person() // constructor is private - compilation error in Java
println(person.toString())

person.@name = 'Mike' // access name field directly - compilation error in Java
println(person.toString())

person.name = 'John' // there is a setter generated by groovy
println(person.toString())

person.@surname = 'Foo' // access surname field directly
println(person.toString())

person.surname = 'Bar' // access auto-generated setter
println(person.toString())

println(person.signature()) // call private method - compilation error in Java
}

I was really astonished by its output:

I am null null
I am Mike null
I am John null
I am John Foo
I am John Bar
J. Bar

As you can see, groovy does not follow visibility directives at all! It treats them as non-existing. Code compiles and executes fine. It's contrary to Java. In Java this code has several errors, pointed out in comments.

I've searched a bit on this topic and it seems that this behaviour is known since version 1.1 and there is a bug report on that: http://jira.codehaus.org/browse/GROOVY-1875. It is not resolved even with groovy 2 release. As Tim Yates mentioned in this Stackoverflow question: "It's not clear if it is a bug or by design". Groovy treats visibility keywords as a hint for a programmer.

I need to keep that lesson in mind next time I want to make some field or method private!