Looking over our requirements, we see that all paths in our DAP are capable of performing CRUD operations. Therefore, it makes sense for us to define a base upon which individual resources can build, while giving persistence capabilities to create, read, update, and delete. In GeekSeek, we’ll handle this by making a generic RepositoryResource base to give us a hook into the Repository abstractions detailed in Chapter 5. Let’s walk through org.cedj.geekseek.web.rest.core.RepositoryResource:

public abstract class RepositoryResource<
  DOMAIN extends Identifiable&Timestampable,
  REP extends Representation<DOMAIN>>
    implements Resource {

Simple enough; an abstract class notes we’ll be extending this later for more specific resources that interact with a Respository. Let’s define the base media types our application will be using. Remember; media types are a key part of the maturity model in handling the types of responses to be returned given the input from the request. For example, a JSON request should yield a JSON response in our known format.

protected static final String BASE_XML_MEDIA_TYPE = "application/vnd.ced+xml";
protected static final String BASE_JSON_MEDIA_TYPE = "application/vnd.ced+json";

Next up, some fields which will be set later by subclasses; this composes our abstraction point which will need specialization later.

private Class<? extends Resource> resourceClass;
private Class<DOMAIN> domainClass;
private Class<REP> representationClass;

We’ll also use some instance members to be injected by either the CDI (@Inject) or JAX-RS (@Context) containers:

@Context
private UriInfo uriInfo;

@Context
private HttpHeaders headers;

@Inject
private Repository<DOMAIN> repository;

@Inject
private RepresentationConverter<REP, DOMAIN> converter;

The @Context annotation will help us gain access into the context of the request in-flight; information about the URI or HTTP headers. The Repository is how we’ll access the persistence layer, and the RepresentationConverter will be responsible for mapping between the client payload and our own entity object model.

Now let’s make sure that subclasses set our extension fields properly:

public RepositoryResource(Class<? extends Resource> resourceClass,
  Class<DOMAIN> domainClass,
  Class<REP> representationClass) {
        this.resourceClass = resourceClass;
        this.domainClass = domainClass;
        this.representationClass = representationClass;
    }

That should do it for the fields needed by our RepositoryResource. Time to do something interesting; we want to map HTTP POST requests of our JSON and XML media types defined above to create a new entity. With a couple of annotations and a few lines of logic in a business method, JAX-RS can handle that for us:

@POST
@Consumes({ BASE_JSON_MEDIA_TYPE, BASE_XML_MEDIA_TYPE })
public Response create(REP representation) {
    DOMAIN entity = getConverter().to(
      uriInfo,representation);
    getRepository().store(entity);
    return Response.created(
            UriBuilder.fromResource(getResourceClass()).segment("{id}").build(entity.getId())).build();
}

The @POST annotation defines that this method will service HTTP POST requests, and the @Consumes annotation designates the valid media types. The JAX-RS container will then map requests meeting those criteria to this create method, passing along the Representation of our Domain object. From there we may get a hook to the Repository, store the entity, and issue an HTTP Response to the client. Of importance is that we let the client know the ID of the entity which was created as part of the response.

We’ll handle the other CRUD operations in similar fashion:

@DELETE
@Path("/{id}")
public Response delete(@PathParam("id") String id) {
    DOMAIN entity = getRepository().get(id);
    if (entity == null) {
        return Response.status(Status.NOT_FOUND).build();
    }
    getRepository().remove(entity);
    return Response.noContent().build();
}

@GET
@Path("/{id}")
@Produces({ BASE_JSON_MEDIA_TYPE, BASE_XML_MEDIA_TYPE })
public Response get(@PathParam("id") String id) {
    DOMAIN entity = getRepository().get(id);
    if (entity == null) {
        return Response.status(Status.NOT_FOUND).type(
            getMediaType()).build();
    }

    return Response.ok(
      getConverter().from(uriInfo, entity))
          .type(getMediaType())
          .lastModified(entity.getLastModified())
          .build();
}

@PUT
@Path("/{id}")
@Consumes({ BASE_JSON_MEDIA_TYPE, BASE_XML_MEDIA_TYPE })
public Response update(@PathParam("id") String id,
    REP representation) {
    DOMAIN entity = getRepository().get(id);
    if (entity == null) {
        return Response.status(Status.BAD_REQUEST)
          .build();
    }

    getConverter().update(
        uriInfo, representation, entity);
    getRepository().store(entity);

    return Response.noContent().build();
}

Note that for GET, PUT, and DELETE operations we must know which entity to work with, so we use the @Path annotation to define a path parameter as part of the request, and pass this along as a PathParam to the method when it’s invoked. We also are sure to use the correct HTTP response codes when the situation warrants:

With this base class in place, we have effectively made a nice mapping between the DAP API as part of our requirements and the backend Repository and JPA. Incoming client requests to are mapped to business methods, which in turn delegate the appropriate action to the persistence layer and supply a response.

Let’s have a look at a concrete implementation of the RepositoryResource, one that handles interaction with User domain objects. We’ve aptly named this the org.cedj.geekseek.web.rest.user.UserResource:

@ResourceModel
@Path("/user")
public class UserResource
    extends RepositoryResource<User, UserRepresentation> {

    private static final String USER_XML_MEDIA_TYPE =
        BASE_XML_MEDIA_TYPE + "; type=user";
    private static final String USER_JSON_MEDIA_TYPE =
        BASE_JSON_MEDIA_TYPE + "; type=user";

    public UserResource() {
        super(UserResource.class, User.class, UserRepresentation.class);
    }

    @Override
    public String getResourceMediaType() {
        return USER_XML_MEDIA_TYPE;
    }

    @Override
    protected String[] getMediaTypes() {
        return new String[]{USER_XML_MEDIA_TYPE, USER_JSON_MEDIA_TYPE};
    }
}

Because we inherit all of the support to interact with JPA from the parent RepositoryResource, this class needs to do little more than:

Now we can handle CRUD operations for User domain objects; similar implementations to this are also in place for Conference, Session, etc.

We’ve seen that the underlying domain model implemented in JPA is not the same as the REST model we’re exposing to clients. While EE allows us to annotate JPA models with JAX-B bindings etc, we likely would like to keep the two models separate as the REST model may:

Additionally, some resources act as proxy resources and has no representation on their own. To allow these resources to operate in a modular fashion we need a way to describe conversion, for example: the relation resource links users to a conference (attendees, speakers). The relation it self knows nothing about the source or target types, but it knows how to get a converter that supports converting between these types. To handle this, we supply the org.cedj.geekseek.web.rest.core.RepresentationConverter:

public interface RepresentationConverter<REST, SOURCE> {

    Class<REST> getRepresentationClass();

    Class<SOURCE> getSourceClass();

    REST from(UriInfo uriInfo, SOURCE source);

    Collection<REST> from(UriInfo uriInfo, Collection<SOURCE> sources);

    SOURCE to(UriInfo uriInfo, REST representation);

    SOURCE update(UriInfo uriInfo, REST representation, SOURCE target);

    Collection<SOURCE> to(UriInfo uriInfo, Collection<REST> representations);

Inside the above interface is also a base implementation to handle the conversion, RepresentationConverter.Base:

public abstract static class Base<REST, SOURCE>
    implements RepresentationConverter<REST, SOURCE> {

    private Class<REST> representationClass;
    private Class<SOURCE> sourceClass;

    protected Base() {}

    public Base(Class<REST> representationClass,
        Class<SOURCE> sourceClass) {
        this.representationClass = representationClass;
        this.sourceClass = sourceClass;
    }

    @Override
    public Collection<REST> from(UriInfo uriInfo,
        Collection<SOURCE> ins) {
        Collection<REST> out = new ArrayList<REST>();
        for(SOURCE in : ins) {
            out.add(from(uriInfo, in));
        }
        return out;
    }

    @Override
    public Collection<SOURCE> to(UriInfo uriInfo,
        Collection<REST> ins) {
        Collection<SOURCE> out = new ArrayList<SOURCE>();
        for(REST in : ins) {
             out.add(to(uriInfo, in));
        }
            return out;
    }

    ...
}

CDI will dutifully inject the appropriate instance of this converter where required, for instance in this field of the org.cedj.geekseek.web.rest.conference.ConferenceResource:

@Inject
private RepresentationConverter<SessionRepresentation,
    Session> sessionConverter;

Through these converters we may easily delegate the messy business of parsing the media type payload formats to and from our own interal domain objects.

As JAX-RS 1.x does not define an interceptor model, we need to apply these on our own in order to activate cross-cutting concerns such as security, validation, and resource linking to our JAX-RS endpoints. This is easily enough accomplished by using the stereotype feature of CDI, where we may create our own annotation type (which itself has annotations); wherever our custom type is applied, the metadata we specify upon the stereotype will propagate. So we may create an annotation to apply all of the features we’d like upon a RepositoryResource, and we call it org.cedj.geekseek.web.rest.core.annotation.ResourceModel:

@Secured
@Linked
@Validated
@RequestScoped
@Stereotype
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface ResourceModel {

}

By placing this @ResourceModel annotation atop, for instance, UserResource as we’ve done above, this JAX-RS resource will now be @Secured, @Linked, @Validated, and @RequestScoped. This is a nice shortcut provided by CDI to compose behaviours together in one definition.

As you may have noticed from our DAP, we have a series of paths which accept a source media type and return another media type representing the data in question. These are modeled by our org.cedj.geekseek.web.rest.core.Representation:

public interface Representation<X> {

    Class<X> getSourceType();

    String getRepresentationType();
}

Some paths are linkable; they contain pointers to resources that aren’t in the domain model itself. For example, a Session in a Conference is in the Conference domain, because a Conference contains N Session entities. A Conference may have a tracker (User), someone “following” the Conference for updates; this further links into the User domain via a Relation domain. While each domain entity is separate, once we start to draw relationships between them, it’s helpful to consider a mechanism to link together these bonds.

So while domain model links are handled directly by JPA, the Representation and a RepresentationConverter into the target formats, the relationships need to be addressed slightly differently.

For this we may introduce the notion of a org.cedj.geekseek.web.rest.core.LinkableRepresentation; a Representation type capable of coupling a source type with a series of links:

public abstract class LinkableRepresenatation<X> implements Representation<X> {

    private List<ResourceLink> links;
    private Class<X> sourceType;
    private String representationType;
    private UriInfo uriInfo;

    protected LinkableRepresenatation() {}

    public LinkableRepresenatation(Class<X> sourceType, String representationType, UriInfo uriInfo) {
        this.sourceType = sourceType;
        this.representationType = representationType;
        this.uriInfo = uriInfo;
    }

    @XmlElement(name = "link", namespace = "urn:ced:link")
    public List<ResourceLink> getLinks() {
        if (this.links == null) {
            this.links = new ArrayList<ResourceLink>();
        }
        return links;
    }

    public void addLink(ResourceLink link) {
        getLinks().add(link);
    }

    public boolean doesNotContainRel(String rel) {
        return !containRel(rel);
    }

    public boolean containRel(String rel) {
        if(links == null || links.size() == 0) {
            return false;
        }
        for(ResourceLink link : links) {
            if(rel.equals(link.getRel())) {
                return true;
            }
        }
        return false;
    }

    @Override @XmlTransient
    public Class<X> getSourceType() {
        return sourceType;
    }

    @Override @XmlTransient
    public String getRepresentationType() {
        return representationType;
    }

    @XmlTransient
    public UriInfo getUriInfo() {
        return uriInfo;
    }
}

In the previous section above, we see that our @ResourceModel stereotype is org.cedj.geekseek.web.rest.core.annotation.Linked, a custom annotation of our own:

@InterceptorBinding
@Retention(RetentionPolicy.RUNTIME)
@Target(ElementType.TYPE)
public @interface Linked {

}

This indicates that we’ll apply an interceptor called org.cedj.geekseek.web.rest.core.interceptor.LinkedInterceptor to anything with this annotation. LinkedInterceptor has the responsibility to determine if the invocation has a linkable representation, and if so, link all of the LinkableRepresentation view together. Anything with the @Linked annotation will run this interceptor, including our @ResourceModel.

The reasoning behind this approach is: some Representation objects are linkable. Via the @ResourceModel (which contains @Linked), a link provider may link a given resource to some other resource. This way, we may draw relationships between resources (entities) that are not described in the by JPA. The interceptor is implemented like so:

@Linked
@Interceptor
public class LinkedInterceptor {

    @Inject
    private Instance<LinkProvider> linkProviers;

    @AroundInvoke
    public Object link(InvocationContext ic) throws Exception {
        Object obj = ic.proceed();
        if(hasLinkableRepresentations(obj)) {
            linkAllRepresentations(obj);
        }
        return obj;
    }

    private boolean hasLinkableRepresentations(Object obj) {
        return locateLinkableRepresenatation(obj) != null;
    }

    private LinkableRepresenatation<?> locateLinkableRepresenatation(Object obj) {
        if(obj instanceof Response) {
            Object entity = ((Response)obj).getEntity();
            if(entity instanceof LinkableRepresenatation) {
                return (LinkableRepresenatation<?>)entity;
            }
        }
        return null;
    }

    private void linkAllRepresentations(Object obj) {
        LinkableRepresenatation<?> linkable = locateLinkableRepresenatation(obj);
        for(LinkProvider linker : linkProviers) {
            linker.appendLinks(linkable);
        }
    }
}

Recall from our DAP that many requests are to return a link to other resources as the client makes its way through state changes in the application. A link is really a value object to encapsulate a media type, href (link), and relation. We provide this in org.cedj.geekseek.web.rest.core.ResourceLink:

public class ResourceLink {

    private String rel;
    private URI href;
    private String type;

    public ResourceLink(String rel, URI href, String media) {
        this.rel = rel;
        this.href = href;
        this.type = media;
    }

    @XmlAttribute
    public String getHref() {
        if (href == null) {
            return null;
        }
        return href.toASCIIString();
    }

    @XmlAttribute
    public String getRel() {
        return rel;
    }

    @XmlAttribute
    public String getMediaType() {
        return type;
    }

    public void setHref(String href) {
        this.href = URI.create(href);
    }

    public void setRel(String rel) {
        this.rel = rel;
    }

    public void setType(String type) {
        this.type = type;
    }
}

LinkableRepresentation will use this value object in particular to handle its linking strategy between disparate entities that are not related in the JPA model.

Arquillian Warp fills the void between client- and server-side testing.

Using Warp, we may initiate an HTTP request using a client-side testing tool such as WebDriver and, in the same request cycle, execute in-container server-side tests. This powerful combination lets us cover integration across client and server.

Warp effectively removes the need for mocking and opens new possibilities for debugging. It also allows us to know as little or as much of the application under test as you want.

We’ll start by enabling the Arquillian Warp in the POM’s dependencyManagement section:

<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-warp-bom</artifactId>
    <version>${version.arquillian_warp}</version>
    <scope>import</scope>
    <type>pom</type>
</dependency>

The above will lock down the versions correctly such that all Warp modules are of the expected version. A dependency declaration in the dependencies section will make Warp available for our use:

<dependency>
    <groupId>org.jboss.arquillian.extension</groupId>
    <artifactId>arquillian-warp-impl</artifactId>
    <scope>test</scope>
</dependency>

The general flow of our first test will be to model a user’s actions as she navigates through the site. To accomplish execution of the test methods in sequence, we’ll use Arquilian’s @InSequence annotation to signal the order of test execution. This will follow the normal REST client flow from point A to B to C and so on. We’re going to execute requests to:

This will be a pure client-side test; it requires something deployed which will talk to the REST APIs. We have provided this logic in org.cedj.geekseek.web.rest.conference.test.integration.story.CreateConferenceAndSessionStory:

@RunWith(Arquillian.class)
public class CreateConferenceAndSessionStory {

    private static String uri_conference = null;
    private static String uri_conferenceInstance = null;
    private static String uri_session = null;
    private static String uri_sessionInstance = null;

    @ArquillianResource
    private URL base;

    @BeforeClass
    public static void setup() {
        RestAssured.filters(
                ResponseLoggingFilter.responseLogger(),
                new RequestLoggingFilter());
    }

The @RunWith annotation above should be familiar by now; Arquillian will be handling the test lifecycle for us. As noted above, it’s good practice to allow Arquillian to inject the base URL of the application by using +@ArquillianResource_. And because we’re not bound to any frameworks in particular, we may also use the REST-assured project to provide us with a clean DSL to validate our REST services.

Notably missing from this declaration is the @Deployment method, which we supply in CreateConferenceAndSessionStoryTestCase so we may decouple the test scenario from the test deployment logic; this encourages re-use for running the same tests with different deployments so we may further integrate other layers later. The deployment method for our purposes here looks like:

@Deployment(testable = false)
public static WebArchive deploy() {
    return ConferenceRestDeployments.conference()
      .addAsWebInfResource(new File("src/main/resources/META-INF/beans.xml"));
}

Because this is a black-box test, we set testable to false to tell Arquillian not to equip the deployment with any additional test runners; we don’t want to test in-container here, but rather run requests from the outside of the server and analyze the response. The test should verify a behavior; sharing of objects might be easier to code and update, but could also sneak in unexpected client changes which should have been caught by the tests. We’re interested only in testing the contract between the client and the server, which is specified by our DAP. Thus, black-box testing is an appropriate solution in this case.

In this deployment, we’ll also use “fake” implementations for the Repository / JPA layer; these are provided by the TestConferenceRepository and TestConferenceRepository test classes which simulate the JPA layer for testing purposes; we won’t be hitting the database for the tests at this level of integration. Later on, when we fully-integrate the application, we’ll bring JPA back into the picture.

@ApplicationScoped
public abstract class TestRepository<
  T extends Identifiable> implements Repository<T> { .. }

public class TestConferenceRepository extends
  TestRepository<Conference> { .. }

On to the tests:

// Story: As a 3rd party Integrator I should be able locate the Conference root Resource
@Test @InSequence(0)
public void shouldBeAbleToLocateConferenceRoot() throws Exception {
        //uri_conference = new URL(base, "api/conference").toExternalForm();
        uri_conference =
              given().
              then().
                  contentType(BASE_MEDIA_TYPE).
                  statusCode(Status.OK.getStatusCode()).
                  root("root").
                      body("link.find {it.@rel == 'conference'}.size()", equalTo(1)).
              when().
                  get(new URL(base, "api/").toExternalForm()).
              body().
                  path("root.link.find {it.@rel == 'conference'}.@href");
    }

Our first test is charged with locating the conference root at the base URL + “api” (as we’d implemented using the @ApplicationPath annotation in our application). We set the media type and expect to have our links for the conference returned to the client matching the @Path annotation we have sitting atop our ConferenceResource class (baseURL + “api” + “conference”). The @InSequence annotation set to value of 0 will ensure that this test is run first.

Assuming that’s successful, we may move on to our next test, creating a conference:

// Story: As a 3rd party Integrator I should be able create a Conference
@Test @InSequence(1)
public void shouldBeAbleToCreateConference() throws Exception { .. }
...

The rest of the test class contains test logic to fulfill our test requirements above.

Now we’d like to test details of the REST service behavior; we’ll use Warp to allow easy control over permutations of data. Again, we’ll be swapping out alternate Repository implementations to bypass JPA and real peristence; we’re just interested in the HTTP request/response interactions at this stage.

What we’d like to do in this test is create Conference domain objects on the client side and transfer them to the server. Warp will allow us to control which data to fetch through the JAX-RS layer. For instance, from the abstract base of the ConferenceResourceSpecificationTestCase, which is annotated with @WarpTest to activate Warp:

@Test
public void shouldReturnOKOnGETResource() throws Exception {
    final DOMAIN domain = createDomainObject();

    Warp.initiate(new Activity() {
        @Override
        public void perform() {
            responseValidation(
                given().
                then().
                    contentType(getTypedMediaType())
            , domain).
            when().
                get(createRootURL() + "/{id}",
                    domain.getId()).body();
        }
    }).inspect(
        new SetupRepository<DOMAIN>(
            getDomainClass(), domain));
}

Here we use Warp to produce the data we want the REST layer to receive, and validate that we obtain the correct HTTP response for a valid GET request.

There are plenty of other detailed Warp examples throughout the tests of the REST modules in the GeekSeek application code; we advise readers to peruse the source for additional ideas in using this very powerful tool for white-box testing of the request/response model.