Introducing the JAX-RS API

 

Introducing the JAX-RS API

In the previous chapters, we covered the basics of RESTful web services and looked at Java APIs for JSON processing. By now, you have a good understanding of the RESTful architectural style and the main components, such as resources, URI, and so on, that form a REST API. It is time for us to put all this knowledge into practice. In this chapter, we will build simple RESTful web services using the JAX-RS APIs. This chapter covers the following topics:

An overview of JAX-RS

  • There are many tools and frameworks available in the market today for building RESTful web services. You can use tools of your choice as long as the REST implementation meets the RESTful architectural constraints discussed in the first chapter. There are some recent developments with respect to the standardization of various framework APIs by providing unified interfaces for a variety of implementations. Let's take a quick look at this effort.

    As you may know, Java EE is the industry standard for developing portable, robust, scalable, and secure server-side Java applications. The Java EE 6 release took the first step towards standardizing RESTful web service APIs by introducing a Java API for RESTful web services (JAX-RS). JAX-RS is an integral part of the Java EE platform, which ensures portability of your REST API code across all Java EE-compliant application servers. The first release of JAX-RS was based on JSR 311. The next version, JAX-RS 2 (based on JSR 339), was released as part of the Java EE 7 platform. The latest version, JAX-RS 2.1 (based on JSR 370), is part of the Java EE8 platform. There are multiple JAX-RS implementations available today by various vendors. Some of the popular JAX-RS implementations are as follows:

    • Jersey RESTful web service framework: This framework is an open source framework for developing RESTful web services in Java. It serves as a JAX-RS reference implementation. You can learn more about this project at https://jersey.github.io/.
    • Apache CXF: This framework is an open source web services framework. CXF supports both JAX-WS and JAX-RS web services. To learn more about CXF, refer to http://cxf.apache.org.
    • RESTEasy: This framework is an open source project from JBoss, which provides various modules to help you build a RESTful web service. To learn more about RESTEasy, refer to http://resteasy.jboss.org.
    • Restlet: This framework is a lightweight open source RESTful web service framework. It has good support for building both scalable RESTful web service APIs and lightweight REST clients (which suits mobile platforms well). You can learn more about Restlet at http://restlet.com.

    We will be using the Jersey implementation of JAX-RS for running the examples discussed in this book (unless otherwise specified). Remember that you are not locked down to any specific vendor here; the RESTful web service APIs that you build using JAX-RS will run on any JAX-RS implementation as long as you do not use any vendor-specific APIs in the code.


JAX-RS annotations

The main goal of the JAX-RS specification is to make the RESTful web service development easier than it has been in the past. As JAX-RS is a part of the Java EE platform, your code becomes portable across all Java EE-compliant servers. In this section, we will familiarize ourselves with some JAX-RS annotations for building RESTful web services based on their usage context:



Specifying the dependency of the JAX-RS API

To use JAX-RS APIs in your project, you need to add the javax.ws.rs-api JAR file to the class path. If the consuming project uses Maven for building the source, the dependency entry for the javax.ws.rs-api JAR file in the Project Object Model (POM) file may look like the following:

<dependency> 
    <groupId>javax.ws.rs</groupId> 
    <artifactId>javax.ws.rs-api</artifactId> 
    <version>2.0.1</version><!-- set the right version --> 
    <scope>provided</scope><!-- compile time dependency --> 
</dependency>




Using JAX-RS annotations to build RESTful web services

Java annotations provide the metadata for your Java class, which can be used during compilation, deployment, or at runtime in order to perform designated tasks. The use of annotations allows us to create RESTful web services as easily as we develop a POJO class. Here, we leave the interception of the HTTP requests and representation negotiations to the framework and concentrate on the business rules necessary to solve the problem at hand.

If you are not familiar with Java annotations, go through the tutorial available at: http://docs.oracle.com/javase/tutorial/java/annotations/.

We will take a quick look at some of the very frequently used JAX-RS annotations in this section. Note that the next section does not provide a comprehensive list of all the JAX-RS annotations; we will see more annotations as we proceed further in this chapter.



Comments

Post a Comment

Popular posts from this blog

Understanding the JAX-RS resource life cycle

Image
Understanding the JAX-RS resource life cycle The following diagram depicts the sequence of actions taking place on the server when a client invokes the JAX-RS RESTful web service: For an incoming REST API call, the container identifies the Java servlet configured for handling the REST API calls by parsing the URI, and then delegates the request to the designated servlet. The servlet initializes the JAX-RS runtime and kicks off the RESTful web service request processing cycle for the REST API call in the following sequence: The runtime executes prematching filters ( ContainerRequestFilter  with the  @Prematching  annotation), which happens before resolving the resource method. The prematching filters are useful if you want to influence resource method resolution. The next step is to identify the resource method for serving the request. After the resolution of the resource method, postmatching filters are executed (filters without  @Prematching ). Postmatching filters ...
Read more

Generating a chunked output using Jersey APIs

  Generating a chunked output using Jersey APIs A chunked response means that instead of waiting for the entire result, the results are   split  into chunks (partial results) and sent one after the other. Sending a response in chunks is useful for a RESTful web API if the resource returned by the API is huge in size. With Jersey, you can use the  org.glassfish.jersey.server.ChunkedOutput  class as the return type to send the response to a client in chunks. The chunked output content can be any data type for which  MessageBodyWriter<T>  (entity provider) is available. When you specify  ChunkedOutput  as the return type for a REST resource method, it tells the runtime that the response will be chunked and sent one by one to the client. Seeing  ChunkedOutput  as the return type for a method, Jersey will switch to the asynchronous processing mode while processing this method at runtime, without you having to explicitly use  A...
Read more