JAX-RS stands for Java API for XML RESTful Services (JAX-RS). It's a Java EE 6 specification that introduces the REST support in the Java EE platform.
Its goal is to provide an easy to use REST development model based on annotations for the Java platform. It's a server-side only specification (no client API is described).
The developer is responsible to declare REST resources that will act as entry point to its application:
// The Java class will be hosted at the URI path "/helloworld" @Path("/helloworld") public class HelloWorldResource { // The Java method will process HTTP GET requests @GET // The Java method will produce content identified by the MIME Media type "text/plain" @Produces("text/plain") public String helloWorld() { // Return some cliched textual content return "Hello World"; } }
A JAX-RS application is an application model abstraction that allows the developer to specify the list of resources and singleton classes that will be exposed by the REST container.
// Identifies the application path that serves as the base URI for all resource URIs provided by Path @ApplicationPath("/application") public class MyApplicaton extends Application { // Returns the list of resources that will be managed by the container public Set<Class<?>> getClasses() { Set<Class<?>> s = new HashSet<Class<?>>(); s.add(HelloWorldResource.class); return s; } }
Resources are the main concept manipulated all along JAX-RS.
Root resource classes are POJOs (Plain Old Java Objects) that are
annotated with @Path
, have at least one method
annotated with @Path
or a resource method
designator annotation such as @GET
,
@PUT
, @POST
, or
@DELETE
. Resource methods are methods of a
resource class annotated with a resource method designator.
HelloWorldResource
is a root
resource:
@Path("/helloworld") public class HelloWorldResource { // Resource method @GET public String getClichedMessage() { return "Hello World"; } }
Root resource methods can return types that are also resources
(annotated with @Path
), that allows application
decomposition.
HelloResource
:
@Path("/hello") public class HelloResource { // Resource method @GET public WorldResource getClichedMessage() { return new WorldResource(); } }
And it's sub-resource
WorldResource
:
@Path("/world") public class WorldResource { @GET public String getClichedMessage() { return "Hello World"; } }
@Path
declares an URI path
template: it can contains variable definition. This
variable can then be accessed as a resource method parameter:
@GET @Path("/hello/{username}") public String hello(@PathParam("username") String username) { return "Hello " + username; }
A callable URI:
/hello/Guillaume
Resources can be configured to accept and produces specific input (respectively output) types.
The @Consumes
annotation declares the
expected MIME type that will be accepted by a resource.
Only HTTP requests with the right Accept
header
will be dispatched to the resource method:
@POST @Consumes("text/plain") public void postClichedMessage(String message) { // ... }
In order to activate JAX-RS on JOnAS, the 'jaxrs'
service must be declared in the
$JONAS_BASE/conf/jonas.properties
in the
jonas.services
property.
jonas.services registry,jmx,... ,jaxrs
JOnAS is using Jersey (the reference implementation) as default JAX-RS provider.
Warning | |
---|---|
The JAX-RS support in JOnAS is currently limited to Web Applications |
Note | |
---|---|
JAX-RS Supports needs a Servlet 3.0 container: JOnAS
' # ###################### JOnAS Web container service configuration # # Set the name of the implementation class of the web container service. jonas.service.web.class org.ow2.jonas.web.tomcat7.Tomcat7Service |
Representational State Transfer (REST)
Oracle Jersey (Reference Implementation) + Documentation
Apache CXF (ASL2 Licensed Implementation) + Documentation