eXo Platform 3.0

- Prev
- Next

## Chapter 7. REST Service Operations

The eXo IDE gadget 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 Output tab.

## Validate REST Service

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

## Deploy/Undeploy REST Service

To deploy some REST Services, do as follows:

- Step 1: Save the file before deploying.

- Step 2: Open the file in the Content Panel.

- Step 3: Click the Deploy REST Service button on the toolbar;

or Go to Run > Deploy. 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:

- Step 1: Find the service which was previously deployed in the Workspace.

- Step 2: Open this service in the Content Panel.

- Step 3: Click the Undeploy REST Service button on the toolbar, and verify if there is no error message in the Output Tab.

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.

## Use Autoload Property

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

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

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:

- Step 1: Create, save and deploy REST Service.

- Step 2: Click the Launch REST Service... button to get the REST Service form. The gadget is filling this form, based on WADL-description of REST Service.

- Step 3: Select and type the path to the service in the Path field. Path parameters are enclosed in curly braces.

- Step 4: Select one of the supported methods from the Method combo-box.

- Step 5: Select the appropriate Request Media Type.

- Step 6: Check the Response Media Type.

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

- Step 8: Go to the Header Parameters middle tab and set appropriate values.

- Step 9: Set request with the body content within the Body tab. This tab is disabled for the GET request.

- Step 10: Press the Send button.

After this gadget has verified whether the path is correct and send the formed request to the service or display the error message, the Response 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 out 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

## Get URL of REST Service

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

- Step 1: Create, save and deploy REST Service.

- Step 2: Click the Launch REST Service... button to get the REST Service form.

- Step 3" Click the Get URL button to view the URL of REST Service.

## Review the Response Headers from REST Service

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

## Examples of REST Service Usage

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

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

    }

- Step 2: Select Run > Launch REST Service... on the top menu.

- Step 3: Select the Path field as "/testMediaTypes", method OPTIONS, then click the Send button.

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

- Step 4: Call the Launch REST Service dialog and select the Path field.

    "/testMediaTypes/InnerPath/{pathParam}"

- Step 5: Select the Response Media Type = "text/html" item.

- Step 6: Type in the Path filed as "/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".

- Step 7: Click the Send button.

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

- Prev
- Up
- Home
- Next