If you are attending JavaOne we'd love to see you at any or all of the following sessions:
I'll also be on Glen's panel "REST Versus SOA: Can We All Just Get Along?" which follows our BOF in the same room at 21:30 (Tuesday is shaping up to be a busy day).
]]>The graph below shows the monthly totals for emails sent to the dev, users, issues and commits mailing lists for both JAX-RS and Jersey.
As you can see, traffic on the lists has picked up quite a bit over the last few months and a good proportion of the increase is due to the additional implementation work flushing out issues. We've also been working through our issues list with a view to publishing a JCP public review draft in the not too distant future.
]]>Obviously you're going to need all the ingredients listed above. I'm using NetBeans which came bundled with Glassfish and Derby so all I had to do was install the RESTful Web Services plug-in, YMMV.
Next you need a database to store username, password and group information. Here's the table definitions I used:
CREATE TABLE users (
id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
username VARCHAR(64) UNIQUE NOT NULL,
password VARCHAR(64) NOT NULL,
);
CREATE INDEX username ON users(username);
CREATE TABLE groups (
id INTEGER GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
username VARCHAR(64) NOT NULL REFERENCES users(username) ON DELETE CASCADE,
groupname VARCHAR(64)
);
Depending on your needs you could lose the integer fields, the important thing is to have a column in the group table with the same name as the column in the users table that holds the username. Those two columns are used to join the users table to the groups table. The Glassfish security realm is going to execute a query like this to retrieve the groups (which map to security roles) that a particular user is a member of:
SELECT groupname FROM groups g, users u where g.username = u.username and u.username = ?
Add some users and groups for testing purposes, note that the password should be an md5 hash, not plaintext - there are several web sites that offer online MD5 generators that you can use. I used groups named USERS and ADMINISTRATORS, you'll see where these come in later.
Next you need to define a JDBC data source, connection pool and security realm in Glassfish. The first two are pretty straightforward and will likely be taken care of already if you have deployed a web application using the database. Setting up the security realm is also straightforward once you have a suitable database structure as described above. You do this via the admin console as shown below (there are a couple of additional fields on the form, you can leave those blank):
Its now possible to require authentication for access to a JAX-RS resource via web.xml. Say I have a resource that only authenticated users can use, e.g.:
@Path("dropbox")
public class DropBox {
@Context
SecurityContext security;
@POST
public Response drop(InputStream data) {
String username = security.getUserPrincipal().getName();
...
}
}
Note the use of dependency injection to get an instance of SecurityContext and how that interface provides access to the username. In order for this to work we have to tell the container that authentication is required for access to the /dropbox URI. Add the following lines to your web.xml to restrict use of this resource to members of the USERS group:
<security-constraint>
<display-name>DropBox</display-name>
<web-resource-collection>
<web-resource-name>DropBox</web-resource-name>
<description></description>
<url-pattern>/dropbox</url-pattern>
<http-method>GET</http-method>
<http-method>POST</http-method>
<http-method>HEAD</http-method>
<http-method>PUT</http-method>
<http-method>OPTIONS</http-method>
<http-method>TRACE</http-method>
<http-method>DELETE</http-method>
</web-resource-collection>
<auth-constraint>
<description>Have to be a USER</description>
<role-name>USERS</role-name>
</auth-constraint>
</security-constraint>
<login-config>
<auth-method>BASIC</auth-method>
<realm-name>userauthn</realm-name>
</login-config>
<security-role>
<description/>
<role-name>USERS</role-name>
</security-role>
That about it, after you redeploy the application, the next time you try to access /dropbox you'll get a 401 Unauthorized response unless you include a suitable Authorization header in the request.
With JAX-RS I can write a feed resource pretty easily:
import java.net.URI;
import java.util.Date;
import javax.ws.rs.ConsumeMime;
import javax.ws.rs.GET;
import javax.ws.rs.POST;
import javax.ws.rs.Path;
import javax.ws.rs.ProduceMime;
import javax.ws.rs.UriParam;
import javax.ws.rs.core.HttpContext;
import javax.ws.rs.core.Response;
import javax.ws.rs.core.UriInfo;
import org.apache.abdera.model.Entry;
import org.apache.abdera.model.Feed;
@ProduceMime("application/atom+xml")
@ConsumeMime("application/atom+xml")
@Path("myfeed")
public class FeedResource {
@HttpContext
private UriInfo uriInfo;
@GET
public Feed getFeed() {
Feed f = AbderaSupport.getAbdera().getFactory().newFeed();
f.setTitle("...");
f.setId(...);
f.addAuthor(...);
f.setUpdated(...);
URI feedLink = uriInfo.getRequestUri();
f.addLink(feedLink.toString(),"self");
for (...) {
Entry e = f.addEntry();
URI entryLink = ...
f.addLink(entryLink.toString(),"alternate");
...
}
return f;
}
@POST
public Response addEntry(Entry e) {
Entry newEntry = AbderaSupport.getAbdera().newEntry();
URI entryLink = ...;
...
return Response.created(entryLink).entity(newEntry).build();
}
}
The getFeed method creates an Abdera Feed instance and returns it in response to a GET request on the myfeed URI. The addEntry method is called with an Abdera Entry instance that corresponds to the body of a POST request. It does whatever is necessary to persist the new entry and then creates and returns a 201 Created response with a Location header and a new Entry corresponding to the persisted entry as the body of the response.
To allow use of Abdera's Entry and Feed types in resource method arguments and return types I had to implement the JAX-RS interfaces MessageBodyReader and MessageBodyWriter for those types. This turned out to be quite simple with Abdera:
import java.io.IOException;
import java.io.InputStream;
import java.io.OutputStream;
import javax.ws.rs.ProduceMime;
import javax.ws.rs.core.MediaType;
import javax.ws.rs.core.MultivaluedMap;
import javax.ws.rs.ext.MessageBodyReader;
import javax.ws.rs.ext.MessageBodyWriter;
import javax.ws.rs.ext.Provider;
import org.apache.abdera.Abdera;
import org.apache.abdera.model.Document;
import org.apache.abdera.model.Element;
import org.apache.abdera.model.Entry;
import org.apache.abdera.model.Feed;
@Provider
@ProduceMime("application/atom+xml")
@ConsumeMime("application/atom+xml")
public class AbderaSupport implements MessageBodyWriter<Object>,
MessageBodyReader<Object> {
private final static Abdera abdera = new Abdera();
public static Abdera getAbdera() {
return abdera;
}
public long getSize(Object arg0) {
return -1;
}
public boolean isWriteable(Class<?> type) {
return (Feed.class.isAssignableFrom(type) || Entry.class.isAssignableFrom(type));
}
public void writeTo(Object feedOrEntry, MediaType mediaType,
MultivaluedMap<String, Object> headers,
OutputStream outputStream) throws IOException {
if (feedOrEntry instanceof Feed) {
Feed feed = (Feed)feedOrEntry;
Document<Feed> doc = feed.getDocument();
doc.writeTo(outputStream);
} else {
Entry entry = (Entry)feedOrEntry;
Document<Entry> doc = entry.getDocument();
doc.writeTo(outputStream);
}
}
public boolean isReadable(Class<?> type) {
return (Feed.class.isAssignableFrom(type) || Entry.class.isAssignableFrom(type));
}
public Object readFrom(Class<Object> feedOrEntry, MediaType mediaType,
MultivaluedMap<String, String> headers,
InputStream inputStream) throws IOException {
Document<Element> doc = getAbdera().getParser().parse(inputStream);
Element el = doc.getRoot();
if (feedOrEntry.isAssignableFrom(el.getClass())) {
return el;
} else {
throw new IOException("Unexpected payload, expected "+feedOrEntry.getName()+
", received "+el.getClass().getName());
}
}
}
Notice I actually implemented MessageBodyReader<Object> rather than MessageBodyReader<Entry> and MessageBodyReader<Feed>. This allowed me to support both types in the same class. Same for MessageBodyWriter. The isReadable and isWriteable methods allow a class to reject types it doesn't support.
Abdera is shaping up to be a nice API for working with Atom documents. Hopefully the above demonstrates how easy it is to integrate support for new formats into Jersey.
]]>The main new feature is that you can now retrieve a WADL for an individual resource. The resource can be a static resource which is described in the application WADL or it can be a resource for which you've received a link in some returned representation. For an example, consider the Simple Console example in the Jersey distribution. This example has two resource:
http://127.0.0.1:9998/resources/form http://127.0.0.1:9998/resources/form/colours
If you retrieve the "global" WADL (available at http://127.0.0.1:9998/resources/application.wadl) you get the following:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://research.sun.com/wadl/2006/10"> <resources base="http://localhost:9998/resources/"> <resource path="/form"> <method name="GET"> <response> <representation mediaType="text/html" /> </response> </method> <method name="POST"> <request> <representation mediaType="application/x-www-form-urlencoded" /> </request> <response> <representation mediaType="text/html" /> </response> </method> <resource path="colours" /> </resource> </resources> </application>
From this you can see that you can get the "form" resource and post a HTML form to it and both will return some HTML. Also notice that there's a resource element with path colours but no other information about that resource. This is due to the "colours" resource being dynamically created by the subresource locator in Form.java:
@Path("/form")
@ProduceMime("text/html")
public class Form {
@Path("colours")
public Colours getColours() {
return coloursResource;
}
...
}
With the latest changes to Jersey you can now get information on such dynamic resources by GETing the resource with an Accept: application/vnd.sun.wadl+xml header that specifies that you want WADL rather than another representation. The Jersey runtime will inspect the object returned by the subresource locator and dynamically generate a WADL description. Thus:
GET /resources/form/colours Accept: application/vnd.sun.wadl+xml
will return:
<?xml version="1.0" encoding="UTF-8" standalone="yes"?> <application xmlns="http://research.sun.com/wadl/2006/10"> <resources base="http://localhost:9998/resources/"> <resource path="form/colours"> <method name="GET"> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="match" /> </request> <response> <representation mediaType="text/plain" /> </response> </method> <method name="GET"> <request> <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query" name="match" /> </request> <response> <representation mediaType="application/json" /> </response> </method> </resource> </resources> </application>
which corresponds to the resource class Colours.java.
The above works except in the case that the resource supports the GET method but does not declare the supported media types (equivalent to @ProduceMime("*/*")). In this case the resource GET method will be invoked for any value of the Accept including WADL so we've added an alternate way of getting the WADL. Rather than GETing the resource you can use a HTTP OPTIONS request. The body of the returned response will be a WADL describing the resource.
All of the above is currently implemented in the trunk and will be included in the forthcoming 0.5 snapshot release.
]]>Please send feedback on the specification, Javadocs or current issues to users [at] jsr311.dev.java.net.
]]>The first task was to write a ResourceProvider implementation that uses Spring for resource creation. This is pretty straightforward and the getInstance method turned out to require only a few lines of code:
public Object getInstance(ResourceProviderContext context) {
try {
initSpringContext(context);
initBeanName();
Object resource = springContext.getBean(beanName, resourceClass);
context.injectDependencies(resource);
return resource;
} catch (Exception ex) {
throw new ContainerException("Unable to create resource", ex);
}
}
The ResourceProvider interface only supplies a ResourceProviderContext to the getInstance method so I had to defer some initialization code to that method that would have fit better in the init method. I'll check if it makes sense to add a ResourceProviderContext to the init method but for this experiment I stuck with the SPI as is. The initSpringContext method uses the ResourceProviderContext to get the ServletContext which is then used to get the Spring ApplicationContext which has been initialized in the suggested way.
protected static synchronized void initSpringContext(
ResourceProviderContext context) {
if (springContext==null) {
DummyResource r = new DummyResource();
context.injectDependencies(r);
springContext = WebApplicationContextUtils.getRequiredWebApplicationContext(
r.servletConfig.getServletContext());
}
}
DummyResource is a simple annotated static inner class that is used as an injection target:
public static class DummyResource {
@Resource
public ServletConfig servletConfig;
}
Jersey is based on annotated classes whereas Spring is based on named beans. The Spring ResourceProvider needs to map a class name to a Spring bean name which is accomplished with the initBeanName method:
protected synchronized void initBeanName() {
if (beanName==null) {
String names[] = springContext.getBeanNamesForType(resourceClass);
if (names.length==0)
throw new RuntimeException("No configured bean for "+resourceClass.getName());
else if (names.length>1)
throw new RuntimeException("Multiple configured beans for "+resourceClass.getName());
beanName=names[0];
}
}
I couldn't see any straightforward way to determine which bean to use for a given resource class if there is more than one defined at the top level so the provider requires a single top-level bean for each resource class.
The final task was to define a new annotation that instructs the Jersey runtime to use the Spring resource provider:
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ResourceFactory(SpringProvider.class)
public @interface SpringFactory {}
With the above implemented you can now write a resource class whose instantiation is controlled by Spring:
@UriTemplate("{id}")
@SpringFactory
public class SpringResource {
private String name;
public SpringResource() {
name="unset";
}
public String getName() {
return name;
}
public void setName(String name) {
this.name = name;
}
@HttpMethod("GET")
@ProduceMime("text/plain")
public String getDescription() {
return "Name: "+getName();
}
}
With the following applicationContext.xml in the WEB-INF directory the resource will report its name as "Mr. Bean" thus demonstrating Spring-provided resource injection.
<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-2.0.xsd">
<bean id="bean1" scope="prototype" class="com.sun.ws.rest.spring.resources.SpringResource">
<property name="name" value="Mr. Bean"/>
</bean>
</beans>
The complete code is available here. No libraries are included in the ZIP file so you'll have to patch up the references to the required Jersey and Spring libraries.
I couldn't see any way to add support for Jersey-defined resources as constructor parameters. In an earlier post I described the new support for non-empty constructors. When using the Spring resource provider, the constructor can only include resources defined within the Spring configuration, not values supplied by Jersey. Is there a Spring API I could use to programatically add support for Jersey-defined constructor parameters ?
]]>This is an up-to-date version of the demo we showed in our JavaOne session this year.
]]>Details on these changes below
Prior to the merge the Jersey runtime would create a single instance of a resource class and use that for all requests. Resource classes had to be re-entrant and thread safe. Following the merge the default scope for a resource object is per-request, i.e. the Jersey runtime creates a new instance of a resource class for each request. This change brings Jersey back in line with the current JSR 311 specification which requires a default per-request life-cycle. The old behavior can be recovered by annotating a resource class with the Singleton annotation from the com.sun.ws.rest.spi.resource package. If you want to be explicit about a resource classes life-cycle rather than rely on the default you can also use the PerRequest annotation from the same package. More on how these annotations work in the description of the new SPI below.
Prior to the merge a resource class was required to have a zero argument constructor that the Jersey runtime would use when creating the singleton instance. Following the merge this requirement has been relaxed such that constructors can now have arguments. This in conjunction with the change to a default per-request lifecycle allows a more natural use of constructors to perform instance initialization, e.g.:
@UriTemplate("entries/{id}")
public class Entry {
EntryEntity entity;
public Entry(@UriParam("id") String id) {
entity = findEntryEntity(id);
...
}
@HttpMethod
@ProduceMime({"application/json", "application/xml"})
public EntryEntity getEntity() {
return entity;
}
}
The arguments allowed in a resource class constructor depends on the resource provider used to create an instance of the resource class (see the description of the new SPI below). For default per-request resource classes you can use any combination of parameters annotated with UriParam, UriParam, QueryParam, MatrixParam, HeaderParam or HttpContext. Singleton resource classes must still have a zero argument constructor.
The new resource provider SPI allows plugging-in of custom resource class factories and is used internally to support the per-request and singleton life-cycles. If you're not planning to develop a new resource provider you can safely stop reading here unless of course you are curious as to how the above features are implemented.
A resource provider is responsible for creating instances of resource classes for the Jersey runtime to use. A resource provider implements ResourceProvider and must have a zero-argument constructor. The Jersey runtime will create a new instance of a resource provider for each resource class that uses that provider so there is no need for a provider to maintain a list or map of resource classes and instances thereof.
The Jersey runtime identifies the resource provider to use for a particular resource class by examining the annotations on that resource class. It examines each class-level annotation in turn looking for a ResourceFactory meta-annotation and then uses the value of that annotation or the default per-request provider if none is found as the resource provider. This approach allows you to define new annotations that point to a particular resource provider, e.g. Jersey defines the Singleton annotation as follows:
@Target({ElementType.TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
@ResourceFactory(SingletonProvider.class)
public @interface Singleton {}
Note the ResourceFactory meta-annotation which points to SingletonProvider, the Jersey-supplied resource provider for singleton resource classes.
The getInstance method of ResourceProvider supplies a ResourceProviderContext that a resource provider can use to obtain values for the resource class constructor's arguments and perform dependency injection on a newly created resource class instance, PerRequestProvider shows an example of its use. A resource provider is expected to supply values for constructor arguments unknown to Jersey (anything not annotated with UriParam, UriParam, QueryParam, MatrixParam, HeaderParam or HttpContext) and inject additional dependencies as required.
Its hoped that this SPI will support integration of Jersey with a variety of frameworks. Let us know if anything is unclear or needs improvement.
]]>The first and easiest to address is the license under which the RI (Jersey) is distributed. Rather than GPL as Patrick states, Jersey is actually available under the CDDL license. Apologies if that wasn't entirely clear from the Jersey home page, I've just fixed that.
Patrick also raised a metaphorical eyebrow over some of the non-goals listed in the latest editors draft of the specification (PDF):
Support for Java versions prior to J2SE 5.0: The API will make extensive use of annotations and will require J2SE 5.0 or later. Read: Sorry, J2ME. Sorry, folks stuck on Java 1.4.
Yes, certainly it would have been good to be able to offer something to Java 1.4 users but we felt that an annotation-based approach offered the best solution going forward and decided to focus on that. On the Java ME side, the fact that 311 is primarily a server side API (see the final point) means it is less suitable for the ME environment anyway.
Description, registration and discovery: The specification will neither define nor require any service description, registration or discovery capability. Read: We'll figure this out later; hopefully we won't have to change anything in this spec once we start thinking about this aspect of the problem.
Several folks whose opinions I respect think that description is antithetical to REST and given that there's no accepted standard for describing RESTful Web services (beyond the resource representations themselves) its hard to see what we could have done here. Certainly I have my own favorite description language and Jersey will automatically produce a WADL description of a set of JSR 311 resource classes but it would be wrong to require support for something like WADL in JSR 311.
Client APIs: The specification will not define client-side APIs. Other specifications are expected to provide such functionality. Read: We'll figure this out later; hopefully we won't have to change anything in this spec once we start thinking about this aspect of the problem.
The goal of JSR 311 is to make it simple to write RESTful Web services in Java. Of course we're keeping an eye out for classes and interfaces that might be useful on the client side (those concerned with URI manipulation seem like reasonable candidates) but the primary focus is on exposing Java objects as RESTful services so I don't think there's too much danger of unexpected overlap with any new client-side HTTP API that might emerge in the future.
]]>
We just released the source code for the reference implementation of JSR 311 as project Jersey. Paul's post has more details.
It seems we've already had our first bug report, keep them coming.
]]>Obviously as the author of the WADL specification I think there is some utility in such a language and normally I'd be tempted to write a longer post addressing some of the points raised but rather than do that I'll instead direct you to Leonard Richardson's It's Just A Hypermedia Format which covers most of the things I'd have said had they not already been expressed so well.
One thing I would like to add since many people are concerned with the link to XML schema: the element attribute of the WADL representation element is optional; WADL can use XML schemas but it isn't built on them. In fact WADL doesn't presume XML will be used for entity bodies and it can easily describe an application built using other media types.
]]>Check it out here.
]]>I blogged earlier about JSR 311, I expect the API produced by JSR 311 will differ significantly to the RESTful WS API in SWDP R1 but the experience we gained building it and the runtime to support it has been very useful for testing some of our early assumptions and clarifying our thinking about the JSR. We hope you'll take it for a spin and let us know what you think.
]]>