Overview of JAX-RS Annotations (Part 2)

This is a three-part series looking at the annotation that is used to implement REST endpoints.

In part one of JAX-RS annotations you learn about:

• The @ApplicationPath Annotation
• The @Path Annotation
• The @GET HTTP Method Annotation
• The @POST HTTP Method Annotation
• The @PUT HTTP Method Annotation
• The @DELETE HTTP Method Annotation
• The @OPTIONS HTTP Method Annotation
• The @HEAD HTTP Method Annotation

In this part, you will learn more about JAX-RS annotations. Are you ready, so let’s get started.

The @Path Annotation (again) and @PathParam

As I am sure you have noticed the @Path annotation can be used on the resource method to further refined the location of a resource. In the above example, the path was specified as @Path(“isbn”). This is referred to as a path variable, which means that when a request is made to the URI /api/books/1234 the path variable 1234 is retrieved and assigned to the method parameter marked with the @PathParam annotation. So in the code snippet, the value 1234 is assigned to the variable isbn.

@Path("{isbn}") 
public Response aMethod(@PathParam("isbn") String isbn)

So in the code snippet, the value 1234 is assigned to the variable isbn.

The @QueryParamter Annotation

A query parameter is the value associated with the key/value pair appended to a URL after the ? symbol. So for example, in the URL http://localhost:8080/api/books/search?keyword=Java&limit=10 the query parameters are keyword and limit and the query values are Java and 10. To retrieve these values use the @QueryParam annotation and pass the name of the query parameter as a value to the annotation, then annotated a method parameter in the resource method that responds to a request to the URI resource /books/search.

@GET
@Produces(MediaType.APPLICATION_JSON)
@Path("search")
public Response searchBook(@QueryParam("keyword") String keyword, @QueryParam("limit") int limit) {
    List<Book> books = bookRepository.searchBook(keyword, limit);
    return Response.ok(new GenericEntity<List<Book>>(books) {}).build();
}

In the code snippet above the value of the keyword query parameter is assigned to the method parameter keyword and the value of the limit query parameter is assigned to the limit method parameter.

The @Produces Annotation

The @Produces annotations specify the media type or types that the method returned to the caller.

@GET
@Produces({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})
public Response getAllNewBooks() {
    return Response.ok(
            new GenericEntity<List<Book>>(
                    bookRepository.getAllNewBooks()
            ) {}).build();
}

The getAllNewBooks method is capable of returning a list of all books in either JSON or XML format. Alternatively, the media type can be expressed as a String: “application/json” and “application/xml”.

@Produces({"application/json", "application/xml"})

The @Consumes Annotation

The media type that a method is capable of consuming can be specified with the annotation @Consumes.

@Consumes({MediaType.APPLICATION_JSON, MediaType.APPLICATION_XML})

The type can also be specified as String values: “application/json“ and “application/xml“.

Code Repository

The source code for this article is in my GitHub repository. Code for all my articles is in the ReadLearnCode Articles repository.

What Next?

That is it for part two, coming up next is the last part in this three-part series. You will learn more about more advanced annotations that aid with the construction of RESTful endpoints including:

• The @FormParam Annotation
• The @MatrixParam Annotation
• The @CookieParam Annotation
• The @HeaderParam Annotation
• The @Provider Annotation

Further Reading

I have published more articles about JAX-RS which I hope you find interesting:

• JAX-RS Resource Entities is an article about creating resource entities
• Ever wondered what @javax.ws.rs.core.Context annotation is all about?
• Learn more about @Consumes and @Produces annotations, and finally
• you cannot write robust endpoints without knowing about bean validation failure management

Learn More

Give you Java EE career a boost with my video training courses. They are hosted on Lynda.com and cover a selection of Java EE technologies:

• RESTful Service with JAX-RS 2.0
• WebSocket Programming with Java EE
• JSON Processing with Java EE and
• Learning Java Enterprise Edition