eXo Platform 3.0

- Prev
- Next

## Chapter 7. REST Service Operations

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

Picture 23. REST Service operations

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

To clear Output Panel use special button at the right top corner of Output Tab.

## Validate REST Service

You can verify the content of REST Service content by using special validation service before saving. Just click on "Validate REST Service" button or select "Run->Validate" from top menu. If there are no errors in service, then the alike message will be shown 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

## Deploy/Undeploy REST Service

To deploy some REST Service, please:

1. Save file before deploying.

2. Open file in the Content Panel.

3. Click on "Deploy REST Service" button of Toolbar or call "Run->Deploy".

After that the deploy request will be sent to the server, and if there are no errors - the message like following:

    [INFO]rennes.groovy deployed successfully

will be displayed in the Output Tab. Otherwise, error message will be shown, e.g.:

    [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 URI pattern, that has been already registered, if the path(including name) of new service is different than original one. To cope with it, please, first undeploy the service with the registered URI pattern.

### Warning

It is necessary to validate groovy scripts (open and select "Run->Validate" from top menu), that are used by service before deploying it.

Calling the "Undeploy" operation is similar to the "Deploy" you should:

1. Find out deployed earlier service in the Workspace and open this one in the Content Panel.

2. Click on "Undeploy REST Service" button of Toolbar and verify if there is no error message in the Output Tab.

If everything is fine, then you will get message like that:

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

You can deploy as many REST Services as you want, and double deploying is also possible. But you can't undeploy earlier non-deployed service - in this case you will get the error feedback from the server like this:

    [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. So, please, undeploy service before deleting it. In other case, the workaround is to create it again in the same place and then undeploy.

## Using Autoload Property

REST Service will be deployed automaticaly on the server just after saving, if the "Autoload" service property is set (has value true). You can view this property in the Property Tab which is shown by clicking "Show Properties" button. To set/unset "Autoload" property, please, use "Set REST Service autoload" or "Unset REST Service autoload" commands respectively. This commands are displayed according to the current state of autoload property so that you will be able to invert this property. Default value autoload property = false. See the picture below for details:

Picture 24. Change Autoload service property

## Launch REST Service with set parameters and Preview Server Console Messages in Output Tab

You can not only write and deploy service With eXo IDE, but make request to them 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 these just call "Launch REST Service..." command by clicking on appropriate button or select "Run" menu item:

1. Create, save and deploy REST Service.

2. Click on "Launch REST Service..." button to get REST service launching form. Gadget is filling this form, based on WADL-description of REST Service.

3. Select or/and type path to the service in the "Path" field. Path parameters are enclosed in curly braces.

4. Select one of the supported methods from "Method" combobox.

5. Select correct "Request Media Type".

6. Check "Response Media Type".

7. Uncheck redundant query parameters and set values of the rest in the table at the bottom of dialog window.

8. Go to middle tab "Header Parameters" and set appropriate values.

9. You can set request body content within the tab "Body". This tab is disabled for GET request.

10. Press "Send" button.

After this gadget verify whether path is correct and send formed request to the service or display error message, Response Service will be displayed in the Output Tab.

See example of launching in the illustration "REST Service operations" above.

Table 7.1.

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

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

## Get REST Service URL

From the send request window you can also get REST Service URL by clicking on "Get URL" button:

1. Create, save and deploy REST Service.

2. Click on "Launch REST Service..." button to get REST service launching form.

3. Press "Get URL" button to view REST Service URL.

## Review of the response headers from REST Service

It is possible to view headers, status code and status text in the Output Panel after sending request. The message will be like this:

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

## Examples of using the REST Service

### Example1: REST service with complex media types output preview

1. Create, save and deploy REST service with next content:

    // 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;
      }

    }

1. Call the "Run->Launch REST Service..." top menu command.

2. Select Path field item "/testMediaTypes", method OPTIONS and the click on "Send" button. After this gadget will send OPTIONS-request and display received response in the Output Tab. E.g.:

    <?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>

1. Call "Launch REST Service" dialog and select Path field item

    "/testMediaTypes/InnerPath/{pathParam}"

1. Select Response Media Type = "text/html" item.

2. Type in Path filed "/testMediaTypes/InnerPath/value1". In the Query Parameter tab set "Test Query Parameter 1"="value2". In the Header Parameter tab set "Test-Header1"="value3". In the Body tab type "example". Then click on "Send" button.

Then eXo IDE will create request to the service and send it. Response will be added into 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

- Prev
- Up
- Home
- Next