Rest services are very popular now a days in web programming.

1. 4/3/2013
1
Implementing RESTful Services
JAX-RS
CS213
03-Apr-2013
JAX-RS Features
• Annotation based
– No need for any configuration in web.xml
– New version of Servlet specification doesn’t
require a web.xml file at all.
• Flexible Deployment Option
– Servlet container
– JAX-RS aware container
• Easy Data Handling Mechanism

2. 4/3/2013
2
Core Annotations
• URL Templates
– @Path
– Defines URI mappings and templates
– Applied on the resource class (most of other annotations are
for methods)
• MIME handling
– @Provides, @Consumes
– What MIME types does the resource produce and consume
• HTTP methods
– @GET, @POST, @PUT, @DELETE
– Identifies which HTTP method the Java method is interested in
Parameter
• @PathParam
– Allows you to extract URI
template segments
– /customers/1234
– /customers/{id}
• @QueryParam
– Access to specific
parameter URI query string
– /customers?city=Lahore
• @MatrixParam
– /customers;city=Lahore
• @FormParam
• @HeaderParam
– Access to a specific HTTP
Header
• @CoockieParam
– Access to a specific cookie
value
• @Context
– Access to contextual
information such as URI or
Request object
• @DefaultValue

3. 4/3/2013
3
Parameter Handling
• HTTP request values are automatically
mapped to
– String and primitive types
– Class types that have a constructor that takes a
String parameter
– Class types that have a static valueOf(String val)
method to prepare an instance of that class
– List , Arrays or Set of above types when there are
multiple values
– Byte array or string for payload (POST or PUT)
Return Types
• Null (Status 204)
– Nothing is returned or a null value is retuned
• WebApplicationException
• An Entity/Object
– Marshaled/serialized to its string representation
• Response
• GenericEntity (embedded in response object)

4. 4/3/2013
4
Poll Service Example
public class PollService {
String getPoll(int id) {
// return some JSON
}
// other methods
}
public class PollService {
String getPoll(int id) {
// return some JSON
}
// other methods
}
Example with JAX-RS Annotations
@Path("/polls")
public class PollService {
@Path("/{poll-id}")
@GET
@Provides("application/json")
String getPoll(@PathParam("poll-id") int id) {
...
}
}
@Path("/polls")
public class PollService {
@Path("/{poll-id}")
@GET
@Provides("application/json")
String getPoll(@PathParam("poll-id") int id) {
...
}
}
Define base URL of this resource
class. All request starting with this
context shall be routed to this class
This method will be
called for all GET type
requests of the form
/polls/12345
Automatically convert
and inject value of
URL segment into id
parameter.
Defines extension to
base URL and path
segment

5. 4/3/2013
5
Example with POST
@Path("/polls")
public class PollService {
...
@POST
@Consumes("application/json")
Response createPoll(String data) {
...
}
}
@Path("/polls")
public class PollService {
...
@POST
@Consumes("application/json")
Response createPoll(String data) {
...
}
}
We will talk about it in
next slide.
Un-annotated parameters
assumed to be incoming
message body. There can
be only one!
What content types are
expected from client?
To be invoked on POST requests,
i.e. CREATE a resource, message
body will contain poll data.
Response Object
• Core Classes in JAX-RS
– Response and ResponseBuilder
• Objective
– Customize response code
– Specify certain response headers
– Specify redirect URLs
– Lot more..
Response createPoll(String data) {
...
ResponseBuilder rb = Response.status(201);
rb.type("application/json")
.header("Location", "/polls/"+id);
return rb.build();
}
Response createPoll(String data) {
...
ResponseBuilder rb = Response.status(201);
rb.type("application/json")
.header("Location", "/polls/"+id);
return rb.build();
}

6. 4/3/2013
6
Default Response Codes
• GET and PUT
– 200 (OK)
• DELETE and POST
– 200 (OK) if content sent back with response
– 204 (NO CONTENT) if no content sent back or a
null is returned.
Example with Query Parameters
• Process requests of the form
– /polls?sort=title
@Path("/polls")
public class PollService {
...
@GET
@Produces({"application/json","application/xml"})
Response listPoll(
@DefaultValue("cdate") @QueryParam("sort") String order) {
...
}
}
@Path("/polls")
public class PollService {
...
@GET
@Produces({"application/json","application/xml"})
Response listPoll(
@DefaultValue("cdate") @QueryParam("sort") String order) {
...
}
}

7. 4/3/2013
7
Frameworks
• JBoss RESTeasy
• Sun Jersey
• CXF
• Axis2
• Spring
That’s All
• JAX-RS Documentation
– http://jersey.java.net/nonav/documentation/snap
shot/index.html
• Java6 Tutorial
– http://docs.oracle.com/javaee/6/tutorial/doc/gijq
y.html