Chapter 7. REST Service Operations

Validate REST Service
Deploy/Undeploy REST Service
Use Autoload Property
Launch REST Service with set parameters and Preview Server Console Messages in the Output Tab
Get URL of REST Service
Review the response headers from REST Service
Example: REST service with complex media types output preview

The eXo IDE application provides the original approach to operate with REST Service to validate, deploy/undeploy and launch applications, which are compatible with the JSR-311 specification without restarting the portal, or installing additional programs. With this application, you can validate REST Service before saving, deploying, launching or undeploying the service. Feedback from server is displayed in the Output Tab:

Illustration 23. REST Service operations

All REST Service commands are placed at the right part of the Toolbar and in the Run on the top menu.

To clear the Output Panel, use the special button at the right top corner of the this panel.

You can verify the content of REST Service by using the special validation service before saving. To do that, simply click the Validate REST Service button, or go to Run > Validate on the top menu. In case of no errors in the service, there will be a message in the Output Tab:

[INFO]rennes.groovy validated successfully".

Otherwise, there will be a error message displayed in the Output Tab:

[ERROR] rennes.groovyvalidation failed. Error (400: Bad Request)
Unexpected error. Error occurs when parse stream, compiler error:
startup failed, rennes.groovy: 4: unable to resolve class javax.ws.rs.Path1
@ line 4, column 1.rennes.groovy: 8: unable to resolve class Path , unable to find class for annotation
@ line 8, column 1.rennes.groovy: 11: unable to resolve class Path , unable to find class for annotation
@ line 11, column 3.
3 errors

To deploy some REST Services, do as follows:

The deploy request will be sent to the server. In case of no errors, one message will be displayed in the Output tab as below: 

[INFO]rennes.groovy deployed successfully

Otherwise, one error message will be shown. For example,

[ERROR] rennes.groovy deploy failed. Error (400: Bad Request)
Unexpected error. Error occurs when parse stream, compiler error:
startup failed, rennes.groovy: 4: unable to resolve class javax.ws.rs.Path1
@ line 4, column 1.rennes.groovy: 8: unable to resolve class Path , unable to
find class for annotation
@ line 8, column 1.rennes.groovy: 11: unable to resolve class Path , unable to
find class for annotation
@ line 11, column 3.
3 errors

Warning

It is impossible to deploy service with the registered URI pattern, if the path (including name) of new service is different than original one. To cope with it, first undeploy the service with the registered URI pattern.

Warning

It is necessary to validate groovy scripts used by the service before deploying it by selecting: "Run > Validate" on the top menu.

To do the Undeploy operation, do as follows:

In case of no error, you will receive a message as below:

[INFO] /repository/collaboration/rennes.groovy undeployed successfully.

You can deploy multiple REST Services, and double-deploy the services. But, you cannot undeploy services which were not previously deployed. In this case, you will receive an error message from the server as below:

[ERROR] /repository/collaboration/rennes.groovy
undeploy failed. Error (400: Bad Request)
Can't unbind script rennes.groovy, not bound or has wrong mapping to the
resource class

Warning

The deletion of service will not make it undeploy. Please undeploy the service before deleting it. In other case, the workaround is to create it again in the same place and then undeploy.

The REST Service will be deployed automatically on the server after being saved, if the Autoload service property is set as true. You can view this property in the Property Tab which is shown by clicking the Show Properties button. To set or unset the "Autoload" property, use Set REST Service autoload or Unset REST Service autoload commands respectively. These commands are displayed to the current status of Autoload property, so you can invert this property. The default value of autoload property is set as false. For more details, see the illustration below:

Illustration 24. Change Autoload service property

With the eXo IDE, you can not only write and deploy the service, but also make requests with your own header, query and path parameters and body content using one of supported methods, view WADL-description of method, launch those services methods and view service response in the Output Tab. To do that, simply call the Launch REST Service... command by clicking the appropriate button, or select Run on the top menu as follows:

After this application has verified whether the path is correct and send the formed request to the service or display the error message, the response of service will be displayed in the Output Tab.

To learn about launching REST Service, see the REST Service operations illustration above.

Table 7.1. 

REST Service Annotation Element of "Launch REST Service" dialog
@Path The Path field
@GET, @POST,... The Method field
@Consumes The Request Media Type field
@Produces The Response Media Type field
@PathParam The path parameters figured in curly braces, for example, /service/{param}/{paramList: .}
@HeaderParam The Header Parameter tab of bottom table
@QueryParam The Query Parameter tab of bottom table
@DefaultValue The By default column of bottom table

Table2. Reproducing service annotations in the "Launch REST Service" dialog

From the send request window, you can also get the URL of REST Service as follows:

You can view headers, status code and status text in the Output Panel after sending your requests. The message will be the following:

[OUTPUT] - -Status - - - - - - - -
200 OK
- -Headers- - - - - - - -
Content-Type : */*
Transfer-Encoding : chunked
Server : Jetty(6.1.x)
- -Text - - - - - - - - -
Hello steve

// simple groovy script
import javax.ws.rs.Path
import javax.ws.rs.POST
import javax.ws.rs.Produces
import javax.ws.rs.Consumes
import javax.ws.rs.PathParam
import javax.ws.rs.HeaderParam
import javax.ws.rs.QueryParam

@Path("/testMediaTypes")
public class TestService {
  @POST
  @Consumes("application/xml")

  @Produces("text/html")
  @Path("InnerPath/{pathParam}")
  public String post1(@PathParam("pathParam") String pathParam,
    @HeaderParam("Test-Header1") String testHeader,
    @QueryParam("Test Query Parameter 1") String testQueryParam,
    String body) {
      return "PathParam 1:" + pathParam + "; Test Query Parameter 1: " + testQueryParam 
      + "; Test-Header1: " + testHeader + "; Body: " + body;
  }

  @POST
  @Consumes("application/xml")

  @Produces("application/json")
  @Path("InnerPath/{pathParam}")
  public String post2(@PathParam("pathParam") String pathParam,
    @HeaderParam("Test-Header2") String testHeader,
    @QueryParam("Test Query Parameter 2") String testQueryParam,
    String body) {
      return "PathParam 2:" + pathParam + "; Test Query Parameter 2: " + testQueryParam 
      + "; Test-Header2: " + testHeader + "; Body: " + body;
  }

}

IDE will send OPTIONS-request and display the received response in the Output Tab. For example:

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<application xmlns="http://research.sun.com/wadl/2006/10">
   <resources base="http://192.168.0.8:8080/rest">
      <resource path="/testMediaTypes">
         <method name="OPTIONS">
            <response>
               <representation mediaType="application/vnd.sun.wadl+xml" />
            </response>
         </method>
         <resource path="InnerPath/{pathParam}">
            <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="template" 
       name="pathParam" />
            <method name="POST" id="post1">
               <request>
                  <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="header" 
       name="Test-Header1" />
                  <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query"
                     name="Test Query Parameter 1" />
                  <representation mediaType="application/xml" />
               </request>
               <response>
                  <representation mediaType="text/html" />
               </response>
            </method>
            <method name="POST" id="post2">
               <request>
                  <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="header" 
       name="Test-Header2" />
                  <param xmlns:xs="http://www.w3.org/2001/XMLSchema" type="xs:string" style="query"
                     name="Test Query Parameter 2" />
                  <representation mediaType="application/xml" />
               </request>
               <response>
                  <representation mediaType="application/json" />
               </response>
            </method>
         </resource>
      </resource>
   </resources>
</application>

"/testMediaTypes/InnerPath/{pathParam}"

Then eXo IDE will create request and send it. The response will be added to the Output Tab:

[OUTPUT] - -Status - - - - - - - -
200 OK
- -Headers- - - - - - - -
Server : Apache-Coyote/1.1
Content-Type : text/html
Transfer-Encoding : chunked
Date : Mon, 05 Jul 2010 09:06:55 GMT
- -Text - - - - - - - - -
PathParam 1:value1; Test Query Parameter 1: value2; Test-Header1: value3; Body: example