How to Use a REST Service

This document is referring to a past Scout release. Please click here for the recent version.

This how-to shows how to provide JAX-RS RESTful services and consume them from a Scout JS Single Page Application.

The goal is to provide a ServerState service in the org.eclipse.scout.hellojs.ui.html module.

Maven Dependencies

Add the following dependencies to the org.eclipse.scout.hellojs.ui.html module.

org.eclipse.scout.hellojs.ui.html/pom.xml

<dependencies>
  ...
  <!-- Scout RS -->
  <dependency>
    <groupId>org.eclipse.scout.rt</groupId>
    <artifactId>org.eclipse.scout.rt.rest</artifactId>
  </dependency>
  <!-- JAX-RS Jersey -->
  <dependency>
    <groupId>org.glassfish.jersey.containers</groupId>
    <artifactId>jersey-container-servlet-core</artifactId>
  </dependency>
  <dependency>
    <groupId>org.glassfish.jersey.inject</groupId>
    <artifactId>jersey-hk2</artifactId>
  </dependency>
  <dependency>
    <groupId>org.glassfish.jersey.media</groupId>
    <artifactId>jersey-media-json-jackson</artifactId>
  </dependency>
</dependencies>

REST Servlet

Register the REST servlet via IServletContributor (i.e. AppServletContributors in org.eclipse.scout.hellojs.ui.html.app).

/**
 * JAX-RS Jersey Servlet.
 */
@Order(20)
public static class ApiServletContributor implements IServletContributor {

  @Override
  public void contribute(ServletContextHandler handler) {
    ServletHolder servlet = handler.addServlet(ServletContainer.class, "/api/*");
    servlet.setInitParameter(ServerProperties.WADL_FEATURE_DISABLE, Boolean.TRUE.toString());
    servlet.setInitParameter(ServletProperties.JAXRS_APPLICATION_CLASS, RestApplication.class.getName());
    servlet.setInitOrder(1); // load-on-startup
  }
}

Provide a RESTful service

Create the server state service in the org.eclipse.scout.hellojs.ui.html module. The service returns a OK status whenever it is accessible.

org.eclipse.scout.hellojs.ui.html/src/main/java/org/eclipse/scout/hellojs/ui/html/helloworld/ServerStateService.java

package org.eclipse.scout.hellojs.ui.html.helloworld;

import jakarta.ws.rs.GET;
import jakarta.ws.rs.Path;
import jakarta.ws.rs.Produces;
import jakarta.ws.rs.core.MediaType;

import org.eclipse.scout.rt.platform.status.IStatus;
import org.eclipse.scout.rt.platform.status.Status;
import org.eclipse.scout.rt.rest.IRestResource;

/**
 * <h3>{@link HelloWorldService}</h3>
 */
@Path("serverstatus") (1)
public class ServerStateService implements IRestResource {

  @GET
  @Produces(MediaType.APPLICATION_JSON)
  public Status getStatus() {
    return new Status(IStatus.OK);
  }
}
1 The path under which the service will be provided. Note: the full path is /api/serverstatus since the apiServlet is mapped to /api/* in the AppServletContributors class.

Test if the service is up an running

Start the dev ui application org.eclipse.scout.hellojs.ui.html.app.dev/[org.eclipse.scout.hellojs] dev ui.launch. Connect to the url http:localhost:[ui server port]/api/serverstatus and ensure the service is up an running.

Use the service from Scout JS

var ajaxOptions = {
  type: 'GET',
  dataType: 'json',
  contentType: 'application/json; charset=UTF-8',
  cache: false,
  url: 'api/serverstatus',
  timeout: 0
};

this.ajaxCall = scout.create('AjaxCall', {
  ajaxOptions: ajaxOptions,
  name: 'server status request'
}, {
  ensureUniqueId: false
});

this.ajaxCall.retryIntervals = []; (1)

this.ajaxCall.call() (2)
  .done(function(result) {  (3)
    // TODO handle the success state. result.severity if filled with the severity code.
  }.bind(this))
  .fail(  (4)
    function() {
      // TODO handle the failure case.
    }.bind(this)
  );
1 The ajax call retries by default 4 times for our example it is not needed to retry at all.
2 The ajax call
3 Success callback
4 Error callback