Earthly Powers

Jersey 1.1.4 is released

We have just released version 1.1.4 of Jersey, the open source, production quality, reference implementation of JAX-RS. The JAX-RS 1.0 specification and the 1.1 change log is available at the JCP web site and also available in non-normative HTML here.

It will be available soon from the GlassFish v2 and v3 update centers, is included in the latest GlassFish v3 builds and, assuming there are no show stoppers, this version will be included in the final GlassFish v3 release scheduled for December 10th.

For an overview of JAX-RS features read the Jersey user guide. To get started with Jersey read the getting started section of that guide. To understand more about what Jersey depends on read the dependencies section of that guide.

This release integrates with other Java EE 6 technologies such as Servlet 3.0, EJB 3.1, managed beans and JCDI 1.0 and contains many bug fixes. See change log here.

The next release, 1.1.5, is tentatively scheduled for December or January. Hopefully this time we can fully resolve the OSGi'ification of Jersey that we have been promising for a while. In addition, now that the Java EE 6 features are done, we hope to resume some experimentation and new features and ensure we have good integration with Atmosphere.

For feedback send email to:

users@jersey.dev.java.net (archived here)

Posted at 04:12PM Nov 12, 2009 by Paul Sandoz in REST  |  Comments[2]

Naming, buying and reading

The title of this blog may be misconstrued as a pithy philosophical statement about life, the universe and everything.

Naming things can be tricky and inspiration comes from many sources.

While pondering a name for this blog a reoccurring thought distracted my consciousness yet again: "I must buy and read Earthly Powers by Anthony Burgess!". Free association did the rest, and the title would serve a duel purpose as a memento.

This week my copy of Earthly Powers arrived in the post.

Now i have to remind myself to read it, and an opportunity presents itself. I am on holiday from the 8th September for 2 weeks. This is a big tome, 650 pages of small print, requiring sustained concentration and time, both of which are a scarce commodity when an energetic toddler demands a 100% of both. So... we shall see...

Posted at 02:25PM Sep 05, 2009 by Paul Sandoz in General  |  Comments[0]

Guice 2.0 is almost there, but not quite

Guice 2.0 is a clean and well-thought-out framework for modularization and dependency injection. It is really good, but it could be really really good with a couple of tweaks.

James Strachan created GuiceyFruit in an effort to move Guice from "really good" to "really really good", or say from 95% there to 99% there. Some patches from GuiceFruit got accepted in Guice 2.0 but some are still pending so GuiceyFruit maintains a patched version of Guice 2.0 for it's own needs.

Jersey depends on GuiceyFruit and the patched Guice 2.0 for it's Guice support (although it is possible to use "native" Guice if you are not using any GuiceyFruit features).

Currently with Guice 2.0 i cannot integrate support for the binding of JAX-RS types and annotations. I would like to be able to do the the following with Guice/Jersey/JAX-RS:

@RequestScoped
@Encoded
public class MyResource {
  private final String q;

  @Inject
  public class MyResource(@DefaultValue("foo") @QueryParam("q") String q) {
    this.q = q;
  }

}

But, currently as far as i am aware, it is not possible for two reasons:

1. a provider binding does not have any context to what it is providing to; and
   
2. an annotation that is not meta-annotated with @BindingAnnotation cannot be utilized as a binding annotation.
   

A good example of the complexity that results due to lack of support for 1) is presented in the section on Custom Injections of the Guice User's Guide. This section presents an example of how to support injection of a org.apache,log4j.Logger instance with fields annotated with the custom annotation @InjectLogger. The logger instance is initiated with the declaring class of the field.

The developer is required to implement a TypeListener that iterates through the fields of the class to find an appropriate field to inject a Logger, and a MembersInjector that injects the instance of the Logger onto the appropriate field.

While these interfaces are useful they are over-complex for such a use-case and the developer cannot use @Inject with Logger for constructor, method and field injection.

The injection of Logger can be reduced to a provider method of a module if Guice could support the injection of InjectionPoint:

 @Provides
 public Logger providerLogger(InjectionPoint ip) {
   return Logger.getLogger(ip.getMember().getDeclaringClass());
 }

With respect to the JAX-RS example a provider of the String type annotated with @QueryParam requires access to the annotations declared on the constructor parameter and the annotations declared on the defining class (it does not appear possible to get access to the former with InjectionPoint so that would require some tweaks as well).

Moving on to reason 2). If Guice supported the following binding in a module:

declareAnnotationAsBindingAnnotation(QueryParam.class);
bind(String.class)
  .annotatedWith(QueryParam.class)
  .toProvider(QueryParamProvider.class);

then it would be possible for Jersey to supply a Jersey-specific Guice module that supported all the Jersey and JAX-RS annotations in addition to enabling developers to easily add their own providers for such annotations.

If Guice could do that it would be 99% there IMHO and would be a really really good dependency injection framework.

Posted at 03:30PM Aug 28, 2009 by Paul Sandoz in Java  |  Comments[1]

Jersey 1.0.3.1 and 1.1.2-ea are released

We have just released versions 1.0.3.1 and 1.1.2-ea of Jersey, the open source, production quality, reference implementation of JAX-RS.

Version 1.0.3.1

Version 1.0.3.1 implements the JAX-RS 1.0 API. The JAX-RS 1.0 specification is available here.

It will be available soon from the GlassFish v2 and v3 update centers, and will ship with GlassFish v2.1.1.

To get started read the getting started document. For an overview of JAX-RS features read the Jersey user guide. To understand more about what Jersey depends on read the dependencies document.

This release contains a few important fixes (most notably a security fix for XML processing). See change log here.

Version 1.1.2-ea

Version 1.1.2-ea of Jersey, implements the draft JAX-RS 1.1 API. The draft JAX-RS 1.1 specification is available here.

It will be available soon from the GlassFish v2 and v3 update centers, and will ship with Glassfish v3 Milestone 6 (see schedule) in addition to the nightly and promoted builds.

To get started with Jersey read the getting started document. For an overview of JAX-RS features read the Jersey user guide. To understand more about what Jersey depends on read the dependencies document.

This is mostly a minor enhancement and bug fixing release.  See change log here.

Naresh and I worked on improving the Jersey Test Framework. This breaks compatibility with the previous version in 1.1.1-ea but hopefully developers will see the improvements (note that many but not all Jersey samples use the test framework and eventually all samples will use it). See the API here.

Pavel worked on integrating some very basic GlassFish probes into the hierarchical matching algorithm and has wired them up to the GlassFish monitoring framework so it is possible to report simple statistics on which resource classes get matched to request URIs.

Two interesting developments of note:

• The Glassfish v3 RESTful interface for management and monitoring is progressing nicely. It needs to use a Jersey container request filter to massage the Accept header such that if HTML and XML-based media types are present the former always has the higher quality. Then the HTML representations will be returned when Safari is used.
• Akka is an Actor-based framework with Software Transactional Memory that is written in Scala. It can expose it's components RESTfully using Jersey and Cometfully ( ;-) ) using Atmosphere.
  

Next release

The next release, 1.1.3, is tentatively scheduled for the final release of Glassfish v3 in November and is dependent on alignment with other EE 6 technologies such as Servlet 3.0 and JSR 299/330. In addition we plan to implement full OSGi support thanks to the help and guidance of Richard Wallace (unfortunately we had no time to implement that for 1.1.2).

For feedback send email to:

users@jersey.dev.java.net (archived here)

Posted at 02:44PM Aug 26, 2009 by Paul Sandoz in REST  |  Comments[0]

The course of true love never did run smooth

Posted at 07:47PM Jul 16, 2009 by Paul Sandoz in Java  |  Comments[0]

Jersey 1.1.1-ea is released

We have just released version 1.1.1-ea of Jersey, the open source, production quality, reference implementation of the draft JAX-RS 1.1 API. The JAX-RS 1.0 specification and the 1.1 change log is available at the JCP web site and also available in non-normative HTML here.

It will be available soon from the GlassFish v2 and v3 update centers, and will be shipped with the latest GlassFish v3 builds.

To get started with Jersey read the getting started document. For an overview of JAX-RS features read the Jersey user guide. To understand more about what Jersey depends on read the dependencies document.

Between releases there has been some very interesting developments with a "sister" projected called Atmosphere. If you are interested in portable Comet support and how to avail of high-level ease of use support with Jersey check out JFA's latest blog entries.

This release took a little longer than expected with holidays post JavaOne, alignment with a version of JAXB for JSON namespace related features, a last minute XML-related security fix, and being hindered by the java.net infrastructure:

• Jakub has implemented the eagerly anticipated JSON namespace support for "mapped" (the default) and the "natural" conventions. In addition we have re-factored the JSONJAXBContext such that developers can use it to marshal and unmarshal JSON with JSONMarshaller and JSONUnmarshaller respectively.
  
• Paul Bryan and Hubert Le Van Gong have added OAuth which comprises Jersey client and server support that leverages an OAuth signature library. The modules are currently located here, but for 1.1.2-ea-SNAPSHOT and future releases they are located here.
  
• James Strachen has integrated support for lift templates with Jersey's MVC framework. The module is located here. To see Jersey, Scala and lift in action check out the RestMQ project.

See change log here.

The next release, 1.1.2-ea or 1.1.2, is tentatively scheduled for late August 2009 and is dependent on alignment with other EE 6 technologies such as Servlet 3.0 and JSR 299/330. In addition we plan to implement full OSGi support thanks to the help and guidance of Richard Wallace.

For feedback send email to:

users@jersey.dev.java.net (archived here)

or log a bugs/features here.

Posted at 05:02PM Jul 15, 2009 by Paul Sandoz in REST  |  Comments[9]

Devoxx 2008 interview with Ted Neward

Hot on the heals of the my JAX-RS Devoxx 08 presentation on Parleys (2,094 views so far, that is my biggest audience yet :-) ) is the interview i did with Ted Neward. This was the first time i have done something like that, but i found Ted put me at ease and i enjoyed the discussion.

Posted at 11:27AM Jun 29, 2009 by Paul Sandoz in REST  |  Comments[0]

Devoxx 2008 video presentation online

See here for the video presentation i did @ Devoxx 2008 on JAX-RS.

The Parleys interface is really slick, perhaps the best interface combination of slides/video i have seen.

Posted at 03:10PM Jun 08, 2009 by Paul Sandoz in REST  |  Comments[1]

JavaOne slides for JAX-RS and Jersey

Here are the slides for the JAX-RS technical session Marc and I presented on Wednesday.

Here are the slides for the Jersey BOF @ 7.30pm on Thursday.

Posted at 11:28PM Jun 04, 2009 by Paul Sandoz in Java  |  Comments[1]

Jersey 1.1.0-ea is released

We have just released version 1.1.0-ea of Jersey, the open source, production quality, reference implementation of the draft JAX-RS 1.1 API. The JAX-RS 1.0 specification and the 1.1 change log is available at the JCP web site and also available in non-normative HTML here.

This is an early access (ea) release until Marc and I complete the maintenance process with the JCP (the review period completed on the 3rd March) and we have implemented all EE 6 related integration features. You can expect the same level of quality as for the previous releases, and JAX-RS 1.1 is binary backwards compatible with JAX-RS 1.0 so existing JAX-RS 1.0 applications should work without recompilation.

It will be available soon from the GlassFish v2 and v3 update centers.

To get started with Jersey read the getting started document. For an overview of JAX-RS features read the Jersey user guide. To understand more about what Jersey depends on read the dependencies document.

The following JavaDoc is available:

• Client, Server, Grizzly, WADL, JSON APIs.
• Spring integration API.
• Guice integration API.
  
• MIME Multipart API.
• Client using Apache HTTP client API.
  
• Atom with Apache Abdera API.
• Simple HTTP server integration API.

Given the short time-frame between 1.0.3 and 1.1.0-ea there are not too many bug fixes and features (see change log here):

• I implemented some fixes and improvements to the EJB integration. Resource classes can be singleton beans and Provider-based classes can be singleton or no-interface view stateless session beans.
  
• Pavel has added a sample showing how to use Jersey with HTTPS and GlassFish.
• James contributed the jersey-scala module. This module will contain classes and components that make it easier to build JAX-RS/Jersey-based applications in Scala. Currently it contains a message body writer to serialize XML nodes, so one can do this:
  
    @Path("markup")
    class MarkupResource {
      val name = "James"
  
      @Produces(Array("text/html"))
      @GET
      def get() = <html>
        <body>
        <h1>Hello {name}</h1>
        <p>Markup generated by Scala code at {new Date()}</p>
        </body>
      </html>
    }
  

The next release, 1.1.1-ea, is tentatively scheduled for the end of May 2009. However, it depends on how much progress we make with our JavaOne preparations.

For feedback send email to:

users@jersey.dev.java.net (archived here)

or log a bugs/features here.

Posted at 02:26PM May 04, 2009 by Paul Sandoz in REST  |  Comments[0]

Jersey 1.0.3 is released

We have just released version 1.0.3 of Jersey, the open source, production quality, reference implementation of the JAX-RS 1.0 API. The JAX-RS specification is available at the JCP web site and also available in non-normative HTML here.

It will be available soon from the Glassfish v2 and v3 update centers.

To get started with Jersey read the getting started document. For an overview of JAX-RS features read the Jersey user guide. To understand more about what Jersey depends on read the dependencies document.

The following JavaDoc is available:

• Client, Server, Grizzly, WADL, JSON APIs.
• Spring integration API.
• Guice integration API.
  
• MIME Multipart API.
• Client using Apache HTTP client API.
  
• Atom with Apache Abdera API.
• Simple HTTP server integration API.

This release has many bug fixes, you can see the change log here, as well as the following improvements and features:

• Guice 2.0 integration, leveraging the contribution by Gili Tzabari. Guice integration is on a par with Spring integration.
  The support depends on Guice 2.0 distributed in the GuiceyFruit maven repository. GuiceyFruit, developed by James Strachan, is a set of extensions to Guice 2.0, such as support for Java EE artifacts like @PostConstruct/@PreDestroy, @Resource and @PersistenceContext. Jersey combined with GuiceyFruit makes for a very interesting fruity combination.
  
• Developer defined WADL-based resource classes, inspired by James Strachan's use of WADL and Jersey MVC.
  Injecting WadlApplicationContext enables access to the WADL JAXB representation for the application.
  
• Multipart MIME improvements to the jersey-multipart module.
  The parsing of Multipart MIME now uses the MIMEPull API which provides efficient stream-based processing and the caching of large MIME body parts to disk. Thus very large Multipart MIME may be consumed without running out of memory (as was previously the case).
  The overloaded use of @FormParam with "multipart/form-data" body parts has now been deprecated as this caused much confusion and created an artificial and limited abstraction when processing form data. This has been replaced with @FormDataParam.
  Finally Imran M Yousuf provided a number of useful fixes, tests and improvements, such as client-side uploading files with FileDataBodyPart.
  
• Niall Gallagher contributed container support for the Simple HTTP server. This was an excellent contribution, code, tests and documentation, very easy to integrate.
  
• Enterprise session beans as resource classes.
  Ken and I worked on integration with the latest builds of Glassfish as described here.
  
• Client API listeners when producing/consuming representations.
  Pavel added support via a filter to listen to the client sending and receiving representations, which is useful to present feedback when uploading or downloading files. See ConnectionListenerFilter.
  
• Plug-in Java type support for @*Param annotations.
  JAX-RS defines a set of rules (for example, see @QueryParam) but it is useful to support additional rules.
  The JAX-RS rules are implemented using StringReaderProvider and developers may implement the same provider interface to add their own rules. Jersey provides support for java.util.Date (using the standard HTTP supported date formats) and JAXB for XML-encoded documents.
  
• Pavel has added a sample showing how to use Jersey with HTTPs, client certificates and Grizzly.
  
• Jakub has created the maven infrastructure for a Jersey user guide (also available in PDF). Currently the user guide contains the JAX-RS overview (the same as presented on the Jersey wiki) and documentation on JSON support.
  Documentation is important (and as one person said to me, no documentation, no feature) but it takes time for us developers to write English prose, so the user guide will be developed iteratively. Contributions to this area are most welcome.
• Naresh's Jersey test framework has been included and some samples are already using it. We plan to transition over the other samples and may make breaking changes to the test API as we improve support.
  

The next release, 1.1.0-ea, is scheduled for the end of April 2009. This will be an early access implementation of the JAX-RS 1.1 maintenance release. We will be calling it "early access" because not all EE features will be ready until the full EE 6 implementation is available in the final release GlassFish v3. However, developers can still expect the same degree of quality as that for previous releases of Jersey.

For feedback send email to:

users@jersey.dev.java.net (archived here)

or log a bugs/features here.

Posted at 11:11AM Apr 16, 2009 by Paul Sandoz in REST  |  Comments[7]

Jersey and Spring enterprise tech tip

An new enterprise tech tip explaining how to get started with Jersey and Spring is available.

Additionally, see here for JavaDoc and here for a Spring sample.

Posted at 10:06AM Apr 14, 2009 by Paul Sandoz in REST  |  Comments[0]

Jersey features and documentation

There are a whole bunch of features that Jersey provides in addition to the JAX-RS API. Here are some of the main features:

• WADL
  A WADL can be obtained from the running service for the known resources at deployment or for each resource using OPTIONS.
  Documentation can be connected with the WADL.
  The WADL runtime-model can be used in conjunction with the Model View Controller pattern.
  
• Client API
  Ease of use API for making request to HTTP-based services. Leverages artifacts of JAX-RS for producing and consuming representations as Java types.
  Leverages existing HTTP client solutions like Http(S)UrlConnection or the Apache HTTP client.
  
• Spring integration
  This is also provided by NetBeans 6.5, see the Web services example for RESTful Web services and Spring.
  Stay tuned for an enterprise tech-tip on Jersey & Spring.
  
• Web application and resource-specific filtering
  Resource-specific is how the @RolesAllowed support is implemented.
  
• Model view controller with supported provided for JSPs.
  A resource class is a controller, which can return a Viewable that references a view and a model. The view processed the model to render a representation such as an HTML page.
  Developers can plug in support for their own view technology, say for Freemarker or Velocity, by implementing a template processor.
  
• JSON support integrated with JAXB
  Use one annotated JAXB class instances of which can be serialized to XML or JSON.
  
• Multipart MIME ("multipart/*")
  Makes it easier to consume "multipart/form" representations sent from browsers.
  
• Atom support using Apache Abdera
  See also the three samples: server; client; and model.
  
• Embedded container support for monster a.k.a Grizzly and the light wight HTTP server (The Simple container will be available for 1.0.3)
  See here for Grizzly.
  Grizzly makes it really easy to test clients and services.
  
• Plug-in injection support
  Add your own stuff to be injected. See here and here.
  
• Plug-in IoC-framework support
  This framework is used to integrate Spring, Guice and EJB support.
  
• Numerous samples
  See here for a zip of all the samples.
  

Most of these features, and many others, have corresponding documentation in the JavaDoc but we realize this is not sufficient for developers.

With that in mind we have started work on a Jersey users guide, written in DocBook. Jakub has put some nice maven-based DocBook infrastructure in place and we can deploy the users guide to the maven repo.

I have converted the JAX-RS overview, on the wiki, to be a chapter of the users guide. And, Jakub is currently working on some JSON documentation. For a preview see the PDF and the HTML zip. We will slowly build up the users guide over successive iterations/releases.

Let is know what you think. And if you are interested in helping out in this documentation effort please email the Jersey users list: users@jersey.dev.java.net

Posted at 02:36PM Apr 03, 2009 by Paul Sandoz in REST  |  Comments[0]

NetBeans 6.7 m3, maven and Jersey

NetBeans 6.7 milestone 3 has support for maven web projects with RESTful Web services using Jersey:

Posted at 01:25PM Apr 03, 2009 by Paul Sandoz in REST  |  Comments[0]

Glassfish v3, EJB 3.1 and Jersey

With Glassfish V3 promoted build 43 (or greater) and the latest Jersey 1.0.3-SNAPSHOT it is now possible to create no-interface-view session beans (or POJO session beans) deployed in the war and those beans may be either (root) resource or provider classes.

A big thanks to Ken Saks who provided the hooks in the Glassfish EJB module so Jersey can dynamically plug-in if Glassfish EJB support is available.

For example one could develop the following root resource class:

@Stateless
@Path("ssb")
public class StatelessSessionRootResource {

    @Context private UriInfo ui; 

    @GET
    public String get() {
        return "GET: " + ui.getRequestUri().toASCIIString();
    }
}

Notice the annotated field, ui,  to obtain an instance of UriInfo. Jersey will defer to JNDI to obtain an instance of the session bean (using the EJB 3.1 portable naming mechanism) and the EJB module will inform Jersey when an instance of the session bean is constructed so that Jersey gets a chance to inject Jersey/JAX-RS artifacts.

Session beans can also be used for sub-resources. For example one can add another resource class:

@Stateless
public class StatelessSessionResource {

    @Context private UriInfo ui;

    @GET
    public String get() {
        return "GET: " + ui.getRequestUri().toASCIIString();
    }
}

and then modify the StatelessSessionRootResource class to be as follows:

@Stateless
@Path("ssb")
public class StatelessSessionRootResource {

    @Context private UriInfo ui;

    @GET
    public String get() {
        return "GET: " + ui.getRequestUri().toASCIIString();
    }

    @EJB StatelessSessionResource r; 

    @Path("sub")
    public StatelessSessionResource getSub() {
        return r;
    }
}

A reference to StatelessSessionResource is injected onto the root resource class and then the sub-resource locator method, getSub, returns that reference.

Alternatively the same functionality can be achieved using the Jersey specific feature of returning the class:

@Path("sub/class")
public Class<StatelessSessionResource> getSubClass() {
    return StatelessSessionResource.class;
}

See here for a simple maven project, which contains the resource classes presented above, and can be built to create a war file to deploy to Glassfish V3. The following URIs will exercise the application:

http://localhost:8080/ejb-1.0/rs/ssb

http://localhost:8080/ejb-1.0/rs/ssb/sub

http://localhost:8080/ejb-1.0/rs/ssb/sub/class

Posted at 01:44PM Apr 02, 2009 by Paul Sandoz in REST  |  Comments[3]