A REST RA module generates a Rhino resource adaptor (RA) that has support for one or more REST API (modules).

ra module workflow.drawio
RA Module workflow

Follow these steps to build a resource adaptor, that supports one or more REST APIs, for use in Rhino TAS - Telecom Application Server.

Step 1: Create a REST RA module

The first step is to use the SDK tool sdkadm to create an REST RA module from a module-pack. The REST RA module creates a deployable REST RA.

Tip
Use the sdkadm list-modules command to list available module-packs.
> list-modules +module-pack
Listing modules based on module tags.

Modules matching all of the following tags will be listed: module-pack

opencloud#clientonly-rest-api#rest-api-framework/1.0.0;1.0.0.0 1
opencloud#clientserver-rest-api#rest-api-framework/1.0.0;1.0.0.0 2
opencloud#raname-unified-rest-ra#rest-api-framework/1.0.0;1.0.0.0 3
opencloud#serveronly-rest-api#rest-api-framework/1.0.0;1.0.0.0 4

  1. module-pack: a resource adaptor type that supports the client role of a REST API

  2. module-pack: a resource adaptor type that supports both the client and server roles of a REST API

  3. module-pack: a unified REST resource adaptor that can support one or more REST APIs

  4. module-pack: a resource adaptor type that supports the server role of a REST API

1

Create a REST RA module

Create a REST RA module with the sdkadm create-module command.

For example, to create a REST RA module called example-rest-ra:

sdkadm create-module
> create-module example-rest-ra opencloud#raname-unified-rest-ra#rest-api-framework/1.0.0;1.0.0.0
Extracting '/Users/davidp/temp/unified-rest-ra-sdk/build/target/ivy-caches/online-resolvers.cache/opencloud/raname-unified-rest-ra/rest-api-framework/1.0.0/module-packs/raname-unified-rest-ra-module-pack-1.0.0.0.zip' to '/Users/davidp/temp/unified-rest-ra-sdk/example-rest-ra'.

Command line invocation did not contain enough rename arguments to rename all modules.
To specify rename arguments on the command line, include <oldvalue>:<newvalue> pairs as additional arguments.
Missing values will now be prompted for interactively.

2

Confirm the name of REST RA module

The suggested value is the directory name passed in the create-module command. Press return to use the recommended value.

sdkadm top level module
Please enter a name for the top level module, usually this will match the name of the directory for the new module
Rename top level module 'raname-unified-rest-ra' to [example-rest-ra]:

The create-module command will then create your new REST RA module.

create-module for the example REST RA finishes …​
Renaming ivy modules and updating dependencies.

Renaming symbolic property references in source files.
Checking "deps.properties" for missing values.

Done. New module(s) should now be available at: ~/work/unified-rest-ra-sdk/example-rest-ra

The generated module for the example REST RA is:

Example REST RA directory
~/work/unified-rest-ra-sdk$ ls -la example-rest-ra/
total 40
drwxr-xr-x   9 fwuser  staff   288  3 Nov 13:53 .
drwxr-xr-x@ 17 fwuser  staff   544  3 Nov 13:53 ..
-rw-r--r--   1 fwuser  staff    54  3 Nov 13:53 .sdk.root
-rw-r--r--   1 fwuser  staff   830  3 Nov 13:53 HOW-TO-ADD-API.txt 1
-rw-r--r--   1 fwuser  staff   695  3 Nov 13:53 build.xml
drwxr-xr-x   3 fwuser  staff    96  3 Nov 13:53 config 2
-rw-r--r--   1 fwuser  staff  2924  3 Nov 13:53 ivy.xml 3
-rw-r--r--   1 fwuser  staff   183  3 Nov 13:53 module.properties
drwxr-xr-x   3 fwuser  staff    96  3 Nov 13:53 src

  1. Instructions for configuring the REST RA

  2. directory with a configuration file that is updated when you add new REST APIs to the REST RA

  3. Ivy configuration file that you edit to define the REST APIs your RA will support

Step 2: Configure the REST RA module

The developer customizes properties in the REST RA Module, and updates its dependencies to include all required API Modules.

There are two steps to follow:

1

Add dependencies to ivy.xml

Add two Ivy dependencies for each REST API in your project that this REST RA should support. The plugin should be in the api-library Ivy conf. The RA type should be in the api-ratype Ivy conf.

For example, to add support for the PingPing API add:

<!-- pingpong api -->
<dependency org="${sdk.ivy.org}"
            name="pingpong-api-server-plugin"
            rev="latest.${ivy.status}"
            conf="api-library, slee-component -> slee-component" />

<dependency org="${sdk.ivy.org}"
            name="pingpong-api-server"
            rev="latest.${ivy.status}"
            conf="api-ratype -> api; slee-component -> du" />
Note

The REST RA build inspects dependencies in the api-library and api-ratype confs and generates a package-info.java for the REST RA.

2

Update config/raname-unfied-rest-ra-config.yaml

This configuration file defines properties such as the tracer level for the RA, IncomingRequestTimeout and so on.

The finished RA Module can be checked into source control.

Step 3: Build the REST RA module

The REST RA Module build retrives the Unified REST RA Core module artifacts and all dependent API Modules artifacts (including SLEE libraries & RA Types). These artifacts are assembled to produce a deployable REST RA that supports all the given APIs.

The developer can now deploy their REST RA into Rhino, and use all of its supported APIs with their service.

Note For an introduction to the architecture of a Unified REST RA see: Rhino REST API Framework Architecture

Generated package-info.java

The following java code snippet is for an example RA that implements the the Pet Store API and the Ping Pong API.

Generated package-info.java for exampleco REST RA
@ResourceAdaptorDeployableUnit(
  securityPermissions = @SecurityPermissions(
    securityPermissionSpec = "grant {... };"
  )
)
@ResourceAdaptor(
  vendorExtensionID = "unified-rest-ra-id",
  raTypes = {
    @ResourceAdaptorTypeReference(
          raType = @ComponentId(name="petstore-api-server", vendor="ExampleCo", version="1.0")), 1
    @ResourceAdaptorTypeReference(
          raType = @ComponentId(name="pingpong-api-server", vendor="ExampleCo", version="1.0")), 2
    @ResourceAdaptorTypeReference(
          raType = @ComponentId(name="rest-api-common", vendor="OpenCloud", version="1.0.0"))
  },
  libraryRefs = {
    @LibraryReference(
          library = @ComponentId(name="base-rest-api-plugin", vendor="OpenCloud", version="1.0.0")),
    @LibraryReference(
          library = @ComponentId(name="petstore-api-server-plugin", vendor="ExampleCo", version="1.0")), 3
    @LibraryReference(
          library = @ComponentId(name="pingpong-api-server-plugin", vendor="ExampleCo", version="1.0")), 4
    @LibraryReference(
          library = @ComponentId(name="rest-ratype-spi", vendor="OpenCloud", version="1.0.0"))
  }
)
@OcAssociatedType(UnifiedRestFrameworkRA.class) 5
package com.opencloud.slee.rest;

import com.opencloud.slee.rest.impl.UnifiedRestFrameworkRA;

import com.opencloud.slee.annotation.*;
import javax.slee.annotation.*;
import javax.slee.annotation.du.*;

  1. @ResourceAdaptorTypeReference for the Pet Store API RA Type

  2. @ResourceAdaptorTypeReference for the Ping Pong API RA Type

  3. @LibraryReference for the Pet Store API plugin

  4. @LibraryReference for the Ping Pong API plugin

  5. @OcAssociatedType references the Unified REST RA core, where other remaining RA relatred annotations are defined

Previous page Next page