Building RESTful Web Services with JAX-RS – Annotations

Post moved to

http://srinichekuri.com/2016/01/17/building-restful-web-services-with-jax-rs-annotations/

**********************************************************************

Let’s take a look at annotations that are used to build RESTful services. Based on the implementation framework that you are using, there might be many annotations. In this post we will discuss annotations that are supported by JAX-RS specs only.

@Path

  • @Path annotation identifies URI Path template
  • Can be used at class or method level.
  • Always specifies relative url to base url (host)
  • @Path value need not have leading or tailing slashes (/). JAX-RS treats them them the same either ways
  • Variables can be specified in @path as follows 
    • Multiple Variables can be specified. Eg @Path(“/users/{username_1}/{username_2}”)

 

//Variable in path is specified by {}
@Path("/users/{username}")
public class UserResource {

    @GET
    @Produces("text/xml")
    //variable specified in @Path can be accessed by @PathParam
    public String getUser(@PathParam("userName") String userName) {
        ...
    }
}


Request Method Designator Annotations (@GET, @POST, @PUT, @DELETE and @HEAD):

  • @GET – The Java method annotated with this will process HTTP GET requests.
  • @POST – The Java method annotated with this will process HTTP POST requests.
  • @PUT – The Java method annotated with this will process HTTP PUT requests.
  • @DELETE – The Java method annotated with this will process HTTP DELETE requests.
  • @HEAD – The Java method annotated with this will process HTTP HEAD requests.

Few logistics that should be followed to use JAX-RS for request methods designator annotations are as follows

  • Methods decorated with request method designators must return following:
    • void
    • A Java programming language type
    • A javax.ws.rs.core.Response Object.
  • Multiple parameters may be extracted from the URI using @PathParam or @QueryParam (Explained below).
  • The HTTP PUT and POST methods expect an HTTP request body.
  • Both @PUT and @POST can be used to create or update a resource.
  • POST can mean anything, so any semantics can be used. PUT has well defined semantics.When using PUT for creation, the client declares the URI for the newly created resource.
  • A common pattern is to use POST to create a resource and return a 201 response with a location header value is the URI to the newly created resource. In this pattern, the web service declares the URI for the newly created resource.

@Consumes and @Produces

@Produces annotation is used to specify the MIME media type that are sent back to client.

  • If specified on class level, all methods will follow it.
  • One can override class level by specifying this on method level.
  • If no methods in a resource are able to produce the MIME type in a client request, then JAX-RS runtime sends back an HTTP ‘406 Not Acceptable’ error.
  • Multiple MIME-types can be specified as follows
      • @Produces({“image/jpeg,image/png”})

     

 

@Path("/myResource")
@Produces("text/plain")
public class SomeResource {
    @GET
    public String doGetAsPlainText() {
        ...
    }

    @GET
    @Produces("text/html") //overides class level
    public String doGetAsHtml() {
        ...
    }
}


@Consumes represents the media types a resource  can accept.

  • If specified on class level, all methods will follow it.
  • One can override class level by specifying this on method level.
  • If a resource is unable to consume the MIME type of a client request, the JAX-RS runtime sends back an HTTP “415 (‘Unsupported Media Type’)” error.
  • If @consumes is used on method that returns ‘void’ then HTTP 204 (‘No Content’) error is returned.

    @POST@Consumes(“text/plain”)public void postClichedMessage(String message) {    // Store the message }

@Path("/myResource")
@Consumes("multipart/related")
public class SomeResource {
    @POST
    public String doPost(MimeMultipart mimeMultipartData) {
        ...
    }

    @POST
    @Consumes("application/x-www-form-urlencoded")
    public String doPost2(FormURLEncodedProperties formData) {
        ...
    }
}

 

Request Parameters (@QueryParam, @PathParam, @DefaultValue, @MatrixParam, @HeaderParam, @CookieParam, @FormParam)

Both @QueryParam and @PathParam can be used only on following Java types:

  • All primitive types except char.
  • All wrapper classes of primitive types except Character
  • Any class with a constructor that accepts a single String argument.
  • Any class with static method named valueOf (String) that accepst a single String argument
  • List<T>, Set<T> or SortedSet<T>, where T matches the already listed criteria.

 

@Path(&quot;smooth&quot;)
@GET
public Response smooth(
        @DefaultValue(&quot;4&quot;) @QueryParam(&quot;number&quot;) int colorNumber,
        @DefaultValue(&quot;red&quot;) @QueryParam(&quot;last-color&quot;) String color
        ) { ... }

Advertisements

Step by Step guide – Convert to Maven Project in Eclipse

Post moved to:

http://srinichekuri.com/2016/01/15/step-by-step-guide-convert-to-maven-project-in-eclipse/

**********************************************************************

This post is for step by step guide to convert a single project to Maven project in Eclipse. I recommend going through these links before you read any further.

Step 1: Maven Plugin for Eclipse

First you should make sure that you have Maven Plugin installed in your Eclipse. I am using Eclipse Mars for this demo and this version comes with Maven Plugin. If you are using Eclipse doesn’t have this built in feature then try to install a Maven Plugin. I recommend M2Eclipse Plugin.

Step 2: Convert Java/J2ee Project to Maven Project

Right click on Java Eclipse and select Configure -> Convert to Maven Project.

convert_to_Maven_Project_Eclipse

A popup up that will show build parameters that will be published in pom.xml will be shown.

convert_to_Maven_Project_Eclipse_1

Step 3: Add dependencies to pom.xml

Open pom.xml and Click on Dependencies tab.

Lets try to add log4j.jar as a dependency in pom.xml.

convert_to_Maven_Project_Eclipse_3

convert_to_Maven_Project_Eclipse_4

Step 4: Run Maven Build

Run Maven build by right clicking on pom.xml and selecting Run As -> Maven install.

convert_to_Maven_Project_Eclipse_5

Step 5: Verify Build

You will see that folder is created with naming convention <artifactId>-<version> in build folder. Also you will see that all dependencies are saved to build/<artifactId>-<version>/WEB-INF/lib folder. Also you will see all dependecies are placed in build path under Maven Dependencies.

convert_to_Maven_Project_Eclipse_6

 

convert_to_Maven_Project_Eclipse_7

Multiple dependencies can be added in similar fashion.

 

Step by Step guide for Hello World Page (HTML and JSP)

This post has been moved to http://srinichekuri.com/2016/01/14/step-by-step-guide-for-hello-world-html-and-jsp/

**********************************************************************

This post is a step by step guide to develop your first html and jsp. Traditionally, developers code ‘Hello World !!!’ as first page and I am sticking to this tradition.

I am using a Eclipse IDE and Apache Tomcat for this tutorial. I recommend going through ‘Step by Step guide to configure Eclipse and Apache Tomcat‘ before you proceed any further.

Step-1: Create Dynamic Web Application

Create a new Dynamic Web Project by clicking on FIle -> New -> Dynamic Web Project

dynamic_project.png

Give a project name and click on Finish.

dynamic_project_1

Step-2: Create a HTML page

Create a new html page by right clicking on WebContent and selecting New -> HTML File.

dynamic_project_2.png

Put in a filename helloWorld.html and click on Finish.

dynamic_project_3.png

Put in this code in helloWorld.html.

<!DOCTYPE html>
<html>
<head>
 <meta charset="ISO-8859-1">
 <title>Hello World</title>
</head>
<body>
 <h5>Hello World - html</h5>
</body>
</html>

Step-3: Create a JSP page

Create a new jsp page by right clicking on WEB-INF and selecting New -> JSP File.

dynamic_project_9

 

Put in a filename helloWorld.jsp and click on Finish.

dynamic_project_10

 

You are seeing any compilation errors then make sure that you have right Runtimes checked as shown below.

dynamic_project_5_1

Put in below code into the jsp.

<%@ page language="java" contentType="text/html; charset=ISO-8859-1"
 pageEncoding="ISO-8859-1"%>
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Hello World</title>
</head>
<body>
<h5>Hello World - jsp</h5>
</body>
</html>

Step-4: Add Project to Server.

Add Project server to Server.

dynamic_project_5_2

dynamic_project_5_3.png

Step-5: Access new pages.

Access html page by url in browser. Url will be in “http://localhost:<port>/HelloWorld/helloWorld.html&#8221; format

dynamic_project_6.png

Access jsp page by url in browser. Url will be in “http://localhost:<port>/HelloWorld/helloWorld.jsp&#8221; format

dynamic_project_7.png