Supporting Accept-Post in JAX-RS applications

Recently in the W3C Linked Data Platform working group we did a survey of the various discovery (or also referred to as affordances) there are for various methods or actions a client may want to introspect or learn from error responses.  One specific scenario is the case of which resource formats (content-types) are accepted by a server when a client wants to send the representation of a resource using POST with the intent of giving birth to a new resource.  The current approaches rely on trial-and-error or some out-of-band knowledge the client application has.  The trial-and-error approach relies on the client sending content of the content-type it believes the server accepts, if the server does accept it and successfully processes the request, it will send back a friendly 201 (maybe 202 or other 200-range) status code.  If the server doesn't like the content-type the client is giving it, it can kindly reply with a 415 (Unsupported Media Type).  Well the client knows what doesn't work but has to guess what might.  Let me introduce you to Accept-Post which is being proposed as a way for a server to tell a client what content-types it prefers.  Accept-Post is somewhat like the Accept header but more closely matches the newer (and less supported) Accept-Patch header.

Ok, that is a enough about the motivation and usage.  I thought I'd share the few lines of Java code needed to support this in JAX-RS 2.0 based implementations.  Since I want the HTTP response header Accept-Post to be returned for a variety of use scenarios such as: when JAX-RS returns a 415, on OPTIONS and HEAD requests, and so on, I decided to always return the header.  To do this, I implemented the ContainerResponseFilter with a simple Class and filter() method as:

import javax.ws.rs.container.ContainerRequestContext;
import javax.ws.rs.container.ContainerResponseContext;
import javax.ws.rs.container.ContainerResponseFilter;
import javax.ws.rs.ext.Provider;

public class AcceptPostResponseFilter 
       implements ContainerResponseFilter {
   @Override
   public void filter(ContainerRequestContext requestContext,
                      ContainerResponseContext responseContext) 
                      throws IOException {
      responseContext.getHeaders().putSingle(
         "Accept-Post", 
         "text/turtle", "application/ld+json", "image/png");
   }
}

That is about it, except of course you needs to register this filter with your JAX-RS Application, such as:

import java.util.HashSet;
import java.util.Set;
import javax.ws.rs.core.Application;

public class MyApplication extends Application {
   @Override
   public Set<Class<?>> getClasses() {
      Set<Class<?>> classes = new HashSet<Class<?>>();
      classes.add(AcceptPostResponseFilter.class);
      return classes;
   }
}

I've made this change for the in-progress LDP reference implementation occurring at Eclipse Lyo.

Similar approaches to other web server implementations or configurations make implementing Accept-Post quite trivial as well. Feel free to provide feedback on the IETF working draft for Accept-Post as well.

OSLC Resource Models - pictures are worth a thousand words

Pardon the metaphor but seems quite accurate here that in order to scale, OSLC working groups (WGs) operate as near-independent groups.  These WGs all produced their piece of the overall picture of resources, their properties and relationships to other types of resources.  The resource models (sometimes referred to as data models) were driven based on a key set of integration scenarios and defined following guidance produced by the Core WG.  The Core WG itself even has various models to support a number of cases such as: describing service providers, resource shapes, discussions, and other commonly used terms.  With all these pieces often laying around in separate specifications (Wiki pages, vocabulary documents, etc) it can be quite helpful to pull these all together...especially using visualization of the resource models.

This first figure is an example of a diagram from the perspective of an OSLC Change Management Change Request definition.

I'll go into a bit more detail about this model a bit later.

In an attempt to simply view these resource models, I started with some work that Scott Rich had done, along with some approaches I had experimented with using Rational Software Architect (RSA)

To keep things very simple, I'll highlight some guidelines on how to develop this model in a UML modeling tool:

• This is just a picture (for now), semantics are not clearly defined and they are not those of OO design.
• All properties are modeled as an  'Attribute', they are just visualized in the diagram as an association (since property values/objects in RDF are nothing special).
• Each domain, which has its own vocabulary document, is a separate package.  Also give each domain/package its own color
• No special profile is used (I attempted to use OWL profile from OMG).
• Even though there isn't an example restriction on the resource types (range) of properties, an explicit expected Class is still set.  A diagram with everything pointing to rdf:Resource wouldn't be too interesting.  Note to self: create a stereotype/visualization to make this obvious.

Ideally (and I know my modeling geek friends are going to like this) we can transform to/from some other descriptive form (OSLC Resource Shapes + RDFSchema).

The current model has been shared in the Eclipse Lyo project and additional examples are highlighted over on the OSLC Core wiki page.  I tucked the RSA model file into an Eclipse project titled org.eclipse.lyo.model which you can find in expected git location.  For those that use some tool other than RSA, I have also provided the .uml file.  I'd be interested to hear if anyone has another tool (and/or approach) to modeling these.  I'll try to advance in my spare time, including improving the diagrams.