eXo Platform 3.5

## Chapter 2. Advanced Actions

This chapter includes the following topics:

- Manage REST Service

  Step-by-step instructions on how to validate, deploy, undeploy, run a REST service in sandbox and other operations with REST service.

- Manage Google Gadget

  Ways and steps to create and preview a Google gadget file.

- Manage Templates

  Steps to create, edit and preview a template file.

- Manage Netvibes Widget

  Steps to create, edit, preview a Netvibes Widget file and deploy it to the Netvibes Ecosystem.

- Manage Chromatic Data Object

  Steps to create a Data Object, preview/create a Node Type.

### Note

eXo IDE also supports validating and classpath configuration of POGO files that are similar to REST Service.

## 2.1. Manage REST Service

- Validate a REST Service

  How to verify the REST Service content by using the special validation service before saving.

- Deploy/Undeploy a REST Service

  How to deploy/undeploy a REST Service in eXo IDE.

- Use Autoload property

  How to use the Autoload property for REST Service to be automatically deployed on the server after being saved.

- Launch a REST Service and Preview Server Console Messages

  How to launch a REST Service with set parameters and preview Server Console Messages in the Output Tab.

- Get URL of a REST Service

  How to get the URL of the REST Service from the Launch REST Service form.

- Review the response headers from REST Service

  Introduction to the feature of viewing headers, status code and status text in the Output pane after sending your requests.

- Deploy to Sandbox, Undeploy from Sandbox, Run in Sandbox

  How to deploy to Sandbox, undeploy from Sandbox, and run in Sandbox.

- REST Service Discovery

  How to explore all REST Services which are available from the server.

- Configure classpath

  How to set paths to the source files or folders.

- Sample REST Service with complex media types output preview

  Introduction to a sample 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 server, or installing additional programs:

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:

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

To clear the Output pane, click at the right top corner of this pane.

`See also`

- Manage Google Gadget

- Manage Templates

- Manage Netvibes Widget

- Manage Chromattic Data Object

### 2.1.1. Validate a REST Service

You can verify the REST Service content by using the special validation service before saving.

To do that, simply click on the toolbar;

Or, go to Run → Validate from 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 pane to go to the line containing the 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 pane.

### 2.1.2. Deploy/Undeploy a REST Service

### Note

This function is for users with the administrator role only.

Deploy a REST Service

1. Save the file before deploying.

2. Open the saved file in the Content pane.

3. Click on the toolbar;

Or, go to Run → Deploy from the top menu.

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

- It is impossible to deploy the service with the registered URI pattern if the path (including name) of the new service is different from the original one.

To cope with it, you have to undeploy the service with the registered URI pattern first.

- It is necessary to validate the Groovy scripts used by the service before deploying it by going to Run → Validate from the top menu.

Undeploy a Rest Service

1. Select the service deployed in the Workspace pane.

2. Double-click the selected service to open it in the Content pane.

3. Click on the toolbar.

In case of no errors, there will be a message informs undeploying successfully 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. You have to undeploy the service before deleting it. In other cases, the workaround is to create it again in the same place and then undeploy.

### 2.1.3. Use Autoload property

### Note

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 . 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:

### 2.1.4. Launch a REST Service and Preview Server Console Messages

With eXo IDE, you cannot 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 click on the toolbar,

Or, go to Run → Launch REST Service... from the top menu as follows:

1. Select the deployed REST Service.

2. Click on the toolbar to get the REST Service form which is relied on the WADL-description of REST Service.

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

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

5. Select the appropriate Request Media Type.

6. Check the Response Media Type.

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

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

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

10. Click Send.

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.

The following table shows annotations of reproducing service in the Launch REST Service form:

REST Service Annotation | Element of Launch REST Service form
--- | ---
@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.

### 2.1.5. Get URL of a REST Service

From the Launch REST Service form, you can also get the URL of the REST Service as follows:

1. Select the deployed REST Service.

2. Click on the toolbar to get the Launch REST Service form.

3. Click Get URL to view the REST Service URL.

### 2.1.6. Review the response headers from REST Service

You can view headers, status code and status text in the Output pane after sending your requests as below:

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

### 2.1.7. Deploy to Sandbox, Undeploy from Sandbox, Run in Sandbox

### Note

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

Deploy to Sandbox

In eXo IDE, developers can secure deploy untested REST Service for testing in an isolated environment named Sandbox. Do this by following either of two ways below:

- Click on the toolbar;

- Or, go to Run → Deploy to Sandbox from the top menu.

Undeploy from Sandbox

- Click on the toolbar;

- Or, go to Run → Undeploy from Sandbox from the top menu.

### Note

You cannot deploy REST Services that were previously deployed by other users.

Run in Sandbox

To run the 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. Do this by following either of two ways below:

- Click at the right corner of the toolbar;

- Or, go to Run → Run in Sandbox from the top menu.

### 2.1.8. REST Service Discovery

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

### 2.1.9. Configure classpath

The classpath 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 is not visible in the browser tree because it cannot be directly edited by user.

View the sources paths of the project

1. Select the created project item in the Workspace pane.

2. Go to File → Configure Classpath... from the top menu to open the Configure Classpath form as below:

3. Add or remove source in the tree.

4. Click Save save changes in the classpath configuration, or Cancel to discard changes.

### Note

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

Add sources to classpath

1. Click Add... in the Configure Classpath form to open the Choose source path form.

2. Select one or more sources in the tree.

3. Click OK.

### Tip

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

### Note

The OK button is disabled if the workspace root folder is selected in the Choose source path form.

Remove sources from classpath

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

### Note

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

### 2.1.10. Sample REST Service with complex media types output preview

1. Create, save and deploy the REST Service with the 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;
      }

    }

2. Select Run → Launch REST Service... from the top menu, or click on the toolbar.

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

The OPTIONS request is sent. You will see the response in the Output tab. For example:

    <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" name="pathParam" style="template" type="xs:string"/>

                <method id="post1" name="POST">

                   <request>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test-Header1" style="header" type="xs:string"/>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test Query Parameter 1" style="query" type="xs:string"/>

                      <representation mediaType="application/xml"/>

                   </request>

                   <response>

                      <representation mediaType="text/html"/>

                   </response>

                </method>

                <method id="post2" name="POST">

                   <request>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test-Header2" style="header" type="xs:string"/>

                      <param xmlns:xs="http://www.w3.org/2001/XMLSchema" name="Test Query Parameter 2" style="query" type="xs:string"/>

                      <representation mediaType="application/xml"/>

                   </request>

                   <response>

                      <representation mediaType="application/json"/>

                   </response>

                </method>

             </resource>

          </resource>

       </resources>

    </application>

4. Open the Launch REST Service... form again and select the another Path field:

    "/testMediaTypes/InnerPath/{pathParam}"

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

6. Enter "/testMediaTypes/InnerPath/value1" in the Path field. 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".

7. Click Send.

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

## 2.2. Manage Google Gadget

The Google Gadget file is in the .xml format with the special MIME type "application/x-google-gadget". In eXo IDE, you can:

- Create a Google Gadget

- Preview a Google Gadget

Create a Google Gadget

To create the Google Gadget within eXo IDE, do one of the following ways:

The first way: Click on the toolbar and then select Google Gadget from the drop-down menu.

The second way: Go to File → New → Google Gadget from the top menu.

The third way: Open the existing gadget from the local system by going to File → Open Local File from the top menu.

The forth way: Upload the existing gadget directly to JCR by going to File → Upload File... from the top menu.

For the third and forth way, you must select the MIME type: "application/x-google-gadget".

Preview a Google Gadget

1. Open your desired Google Gadget file which was previously saved.

2. Click on the toolbar;

Or, go to Run → Show Preview from the top menu.

The gadget is opened in the Gadget Container of the Preview tab as described in the Google Gadget Operations illustration above.

`See also`

- Manage REST Service

- Manage Templates

- Manage Netvibes Widget

- Manage Chromattic Data Object

## 2.3. Manage Templates

The Template file is a combination of HTML code and Groovy code blocks. In eXo IDE, you can create and edit those files in editor.

The following topics are covered:

- Create and Edit a template

- View template's properties

- Preview a template

Create and Edit a template

1. Click on the toolbar and then select Template from the drop-down menu; or select File → New → Template from the top menu. A new file is opened in the editor.

2. Add content.

3. Save the file by selecting File → Save As from the top menu, or by clicking on the toolbar.

Both Outline pane and Auto-complete form can be used to edit the Groovy Template.

View template's properties

To view properties of the template, click on the right corner of the toolbar.

Preview a template

1. Open your desired Groovy template in the Content pane.

2. Click on the toolbar;

Or, go to Run → Show Preview from the top menu.

The selected template is opened in the Gadget Container of the Preview tab as below:

`See also`

- Manage REST Service

- Manage Google Gadget

- Manage Netvibes Widget

- Manage Chromattic Data Object

## 2.4. Manage Netvibes Widget

This section includes the following topics:

- Create Netvibes widget

- Preview Netvibes widget

- Deploy Netvibes widget to Netvibes Ecosystem

- View Netvibes documentation

The Netvibes widget uses Universal Widget API (UWA) - a powerful framework for Web widgets development - for both Netvibes widgets and many various environments.

The UWA widget consists of combinations from XHTML/XML, JavaScript/Ajax, CSS code with the MIME type application/x-uwa-widget. In eXo IDE, you can create the Netvibes widget, preview it and deploy to the Netvibes Ecosystem.

### Note

If you want to get acquainted with writing your own widgets, refer to this page.

Create Netvibes widget

Click on the toolbar and then select Netvibes Widget from the drop-down menu;

Or, go to File → Netvibes Widget from the top menu.

The new Netvibes widget file is opened in the editor, enabling you to edit and save it.

Preview Netvibes widget

1. Open your desired widget file in the Content pane.

2. Click on the toolbar;

Or, go to Run → Show Preview from the top menu.

The selected widget is opened in the Preview tab.

Deploy Netvibes widget to Netvibes Ecosystem

Netvibes widgets are placed in the remote system called Netvibes Ecosystem. This is the location where such widgets can be found and compiled for other platforms.

There are a couple of ways to deploy a Netvibes widget. You can do it manually, or use the deployment mechanism. Manual deployment is easier because you do not need to get an API key from Netvibes.

Manual deployment

1. Get the URL of your Netvibes widget by selecting your widget, then clicking View → Get URL. Copy the URL.

2. Go to the Netvibes Ecosystem, click Create or submit and Submit Widget.

3. Paste the URL of your gadget, and don not forget to remove the /private part from it. If you do not do this, Netvibes will not be able to access it.

4. Fill in the form and finish the process. The widget is now available in the ecosystem.

### Note

For deployment using our wizard, you need to contact Netvibes at `<business@netvibes.com>` and ask for your API key.

Deploy UWA widget:

1. Get the URL of your netvibes widget. To do this, select your widget and click View → Get URL from the menu. Copy the URL.

2. Click on the toolbar;

Or, go to Run → Deploy UWA widget on the top menu to open the Deploy UWA widget to Ecosystem form:

3. Paste the URL of your gadget, and do not forget to remove the "/private" part from it, or netvibes will not be able to access it.

4. Enter the information about the widget in the fields in the Step 2 form. All fields marked with asterisk (*) are required..

Click Next after completing your details.

5. Enter your netvibes credentials and the API key/secret that netvibes gave you by email. All these fields are mandatory.

Details:

Field | Description
--- | ---
Login | Your login at Netvibes Ecosystem.
Password | Your password at Netvibes Ecosystem.
Api Key | The string generated by Netvibes and used for identifying you.
Secret Key | The string generated by Netvibes and used for submitting your actions.

### Tip

Click the Back button to return to the previous step to edit your entered information.

6. Click to start deploying the widget to the Netvibes Ecosyste.

The result is displayed in the Output pane. If the deployment is successful, you will receive the message below:

    [INFO]*[http://78.137.4.16:53081/rest/ide-vfs-webdav/repository/dev-monit/TestWidget.html] deployed successfully.

If unsuccessful, you will receive the error message which varies, depending on each case.

    [ERROR] Error: The link already exists.

### Note

The deployed widget can be found at the Ecosystem page on the My creation tab.

View Netvibes documentation

There is a convenient way to view the developer's documentation, while creating your widget in eXo IDE. When opening Netvibes widget in editor, click Show Documentation on the toolbar or go to View → Documentation.

Top menu item and a pane with loaded documentation will be opened at the right part of the application.

`See also`

- Manage REST Service

- Manage Google Gadget

- Manage Templates

- Manage Chromattic Data Object

## 2.5. Manage Chromatic Data Object

Chromattic Data Object files has MIME type application/x-chromattic+groovy. With eXo IDE you can create Chromattic Data Object files, create and preview node type.

The following topics are covered:

- Create a Data Object

- Preview a Node Type

- Create a Node Type

Create a Data Object

Click → Data Object;

Or, go to File → New → Data Object from the top menu.

Your newly created file will be opened in editor, so you will be able to edit and save it.

Preview a Node Type

1. Click on the Toolbar;

Or, go to Run → Preview node type from the top menu.

2. Select a node type format in the appeared form:

- eXo: the standard XML content type to be used with XML-formatted node type streams.

- CND: the experimental content type for the compact node type definition files.

3. Click Generate. The generated node type definition will be displayed in the separate tab of Operation pane with title Preview node type:

Create a Node Type

1. Click on the toolbar;

Or, go to Run → Deploy node type from the top menu.

2. Select a required node type format in the Deploy Node Type form.

3. Select the action in case such node type already exists:

- ignore if exists: if the pointed node type already exists, the creation operation is ignored.

- fail if exists: if the pointed node type already exists, the creation operation fails.

- replace if exists: if the pointed node type already exists, the existing one will be replaced.

4. Click Deploy.

If the node type has been deployed successfully, you will see the message Node type is successfully deployed. Otherwise, the error message will be shown.

### Note

At present, the CND format is not supported for the deploy operation.

`See also`

- Manage REST Service

- Manage Google Gadget

- Manage Templates

- Manage Netvibes Widget

Copyright © 2009-2012. All rights reserved. eXo Platform SAS