Developing REST Web Services with JREST API

This entry will explain how to create a RestFul Web service using Eclipse Mars and JREST API Annotations. 

Prerequisites: 

• JDK 8.0
• Eclipse Mars JEE Edition
• You need to have a Dynamic Web Project 3.1 created in Eclipse. 
• You need to have the following libraries properly configured in the project assembly:
• JRestAPI.jar
• ParserUtils.jar
• JSON.jar
• Deployment.jar
• ConvertUtils.jar
• velocity-1.6.2-dep.jar
• velocity-1.6.2.jar
• log4j-1.2.16.jar

1. Create a Java Class for your services: 

You need to create a Java Class that will contain the method of your services. Lets create a class called ApiWSBusiness as follows:

public class ApiWSBusiness {
   
}

2. Add methods to your class:

It is assumed that a Web Sevice function will return a response. The response could be a JSON, XML or HTML output that can be represented by a String data type. For that reason every method that is going to be a service function must return a String data type. The argument received by the method must be a HashMap<String, String[]> which corresponds to the return type of the servlet method "getParameterMap". 

public String status(Map<String, String[]> args) {
}

3. Add annotations to your methods:

In order to register the method as a RestFul web service function you need to add the @ServiceFunction annotation. With this annotation you can set the path, description, and service arguments. This annotation will be used also by the help generator program to generate the documentation of the service. The documentation will illustrate the service with an example and with an input form that will help you play with the service calling itself. 

In the @ServiceArgument annotation, you need to specify the name of the argument that will be used in the service url. You need to specify whether the argument is required or not. The other properties will be used by the help generator to create the documentation but are not required. 

The following is the previous example with the @ServiceFunction and @ServiceArgument annotations:

@ServiceFunction(path = "/status", name="Status", 
                 description = "Show status of server if it is alive or down", serviceArguments = {
@ServiceArgument(name = "contentType", description = "Response type", helpLabel="Type", sampleValue="text/json", placeholder="text/json", required=false) }) 
public String status(Map<String, String[]> args) {
   WSNode node = new WSNode("alive");
   node.setValue("true");
   return RestUtils.toMarkup(node, args);
}

4. Create the servlet class:
The last step is to create the servlet class in which you need to register your previous class. This is done by creating a ProcessResolver with you service class in the init method of the servlet as shown:

@Override
public void init(ServletConfig config) throws ServletException {
   resolver=new ProcessResolver<JRestApiWSBusiness>(new JRestApiWSBusiness());

}

The ProcessResovler is created with the name and instance of the class that you created in steps 2 and 3.  

Finally you need to implement the doGet and/or doPost of the service as follows:

protected void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
  try{
    String textResp=resolver.executeService(request);
    if (!ServletHelper.writeResponse(textResp, response)){                 response.getWriter().write(" Not Found..!"));
    }
  }catch(Exception e){
    logger.error("Error:",e);
  }

}