Chapter 7. REST Service Operations

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 server, or installing additional programs:

Table. Accessibility of REST Service Operations

Table 7.1. 

Operation User with "developer" role User with "administrator" role
Validate Enabled Enabled
Deploy Disabled Enabled
Undeploy Disabled Enabled
Deploy in Sandbox Enabled Enabled
Undeploy from Sandbox Enabled Enabled
Set/Unset Autoload Disabled Enabled
Run in Sandbox Enabled Enabled
Launch REST Service Disabled Enabled

With eXo IDE, you can validate REST Service before saving, deploying, launching or undeploying the service. The feedback from server is displayed in the Output Tab:

Illustration. 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 this panel.

You can verify the REST Service content 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 an error message displayed in the Output Tab:


[ERROR] rennes.groovy validation 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 classpath , unable to find class for annotation
@ line 8, column 1.rennes.groovy: 11: unable to resolve classpath , unable to find class for annotation
@ line 11, column 3.
3 errors

You can click the error message in the Output Panel to go to the line with error in the REST Service file. In case the file has been closed, eXo IDE will automatically open it. Make sure that you do not delete or rename this file after the error message has been displayed in the Outline Panel.

This function is for users with the administrator role only.

To deploy a REST Service, do as follows:

The deployment request is sent to the server. In case of no errors, the message is displayed in the Output Tab as below:

[INFO]rennes.groovy deployed successfully

Otherwise, there will be an error message, 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

To undeploy a Rest Service, do as follows:

In case of no errors, there is a success message in the Output Tab.

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

You can deploy multiple REST Services, and double-deploy the services. However, 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 not unbind script rennes.groovy, not bound or has wrong mapping to the
resource class

Warning

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

This function is for users with the administrator role only.

REST Service is deployed automatically on the server after being saved, if the Autoload property is set to True. You can view this property in the Property Tab by clicking the Show Properties button. To manage the Autoload property, use Set/Unset Autoload commands respectively. These commands are displayed to the current status of the Autoload property, so you can invert this property. The default value of the Autoload property is set to False. For more details, see the illustration below:

Illustration. Change Autoload service property

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

You will receive a success message if the path is verified to be correct or an error message in the Output Tab.

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

Table. Reproducing service annotations in the Launch REST Service dialog

Table 7.2. 

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 the bottom table.
@QueryParam The Query Parameter tab of the bottom table.
@DefaultValue The By default column of the bottom table.

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 as below:


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

This function is for users with both developer and administrator role.

In eXo IDE, developers can secure deploy untested REST Service for testing in an isolated environment named Sandbox. To do this, click the Deploy REST Service to Sandbox button on the toolbar or go to Run > Deploy to Sandbox on the top menu.

To undeploy from sandbox, select the Undeploy REST Service from Sandbox button on the toolbar, or go to Run > Undeploy from Sandbox on the top menu.

Illustration. Using REST Services Sandbox

Note

If REST Service is previously deployed by other user, you will not be able to deploy it.

To run REST Service faster, you can use the special command Run > Run in Sandbox which is a sequence of next operations: Save, Deploy to Sandbox, Undeploy from Sandbox, Launch REST Service. Simply click the Run in Sandbox button at the right corner of the toolbar, or go to Run > Run in Sandbox on the top menu.

In the eXo IDE, you can explore all REST Services which are available from the server. To open REST Service Discovery form, select Help > REST Service Discovery... from the top menu.

Illustration. REST Service Discovery form

The class path configuration means the setting of paths to the source files or folders. This class path will be used for project sources compilation. Classpath file is located in the root of the project's directory, but it's not visible in browser tree, because can not be directly edited by user. So, to view the sources paths of the project, do as follows:

Illustration. Configure classpath form

Note

If selected in "Workspace Panel" item is not a project or part of it, then you will get an error message.

To add source to classpath, do as follows:

Illustration. Add source to classpath

Tip

Use "CTRL" key to select more than one item in the tree.

Note

The "Ok" button is disabled if workspace root folder is selected in the "Choose source path" dialog.

To remove source(s) from project's classpath, select source in the tree of Configure Classpath dialog and click the Remove button.

Note

The "Remove" button is disabled if there is no source selected in the tree.

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

}

The OPTIONS-request is sent. You will see the 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}"

The request is created and then sent. You will see the response in 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