This page provides a brief introduction to the unified rest RA framework, with an emphasis on how an API, described using an OpenAPI specification, is mapped to a Rhino Resource Adaptor type.

Features of the Unified REST RA Framework

The unified REST RA framework has the following features:

Feature Description

Sentinel SDK based

The REST RA Framework uses Sentinel SDK tools in the following way:

  • Module-packs: There is a set of API prototype modules, one per type of API (Client API, Server API, Client + Server API). Each type of API is a group module, with sub-modules for all the components required for a generated RA type and a plugin for a Unified REST RA.

  • Ivy dependency based deploy

Openapi-generator

A tool for processing OpenApi specifications and generating code.

Openapi-generator-slee: a generator, for openapi-generator, for generating an RA type and a plugin for a REST API.

slee-annotations

Generated code includes required slee-annotations so deployment descriptors can be automatically generated.

java.util.ServiceLoader

The Unified REST RA uses a ServiceLoader API to find REST API plugins on RA activation.

Ant tasks and macros

These wrap/call openapi-generator. There are additional tasks for packaging and producing deployable units
Tip See: About OpenAPI for a brief introduction to OpenAPI and what it enables.

REST RA Framework Workflow

A developer uses the REST RA Framework to produce a REST RA that supports all of their required REST APIs. There exist two main workflows:

  1. Creating REST API Modules — Each REST API module generates the artifacts related to a particular API such Events, Provider interfaces and so on.

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

Follow these steps to build Rhino support for one or more REST APIs.

Creating REST API Modules

api module workflow.drawio
API Module workflow

Step 1: Create an API module

The first step is to use the SDK tool sdkadm to create an API module from a module-pack. The REST RA framework provides a set of module-packs:

  • rest-api-prototypes/serveronly-rest-api: An RA type that supports the server role of a REST API

  • rest-api-prototypes/clientonly-rest-api: An RA type that supports the client role of a REST API

  • rest-api-prototypes/clientserver-rest-api: An RA type that supports both the client and server roles of a REST API

Tip The command to use is: sdkadm create-module …​

The result of this step is a group Ant/Ivy module containing an OpenAPI document, and sub-modules that generate the required SLEE components to support the REST API. For example, the generated server RA rtype modules for a PingPong API would be:

pingpong-rest-api 1
pingpong-rest-api/pingpong-api 2
pingpong-rest-api/pingpong-api/src/api.yaml 3
pingpong-rest-api/pingpong-api/src/api.properties 4
pingpong-rest-api/pingpong-api-server 5
pingpong-rest-api/pingpong-api-server-plugin 6
pingpong-rest-api/pingpong-api-server-plugin/resources/services 7
pingpong-rest-api/pingpong-api-server-sbbpart 8

  1. The group module

  2. This sub-module holds the API specification and a properties file. The other sub-modules have an ivy dependency on this module.

  3. An OpenAPI formatted description of the API

  4. A properties file the developer can use to define java packages and the names of deployable units

  5. Generates a RA type that includes events, provider interfaces and so on for an RA type that can be deployed in Rhino

  6. Generates a library component that the Unified REST RA uses to load and drive the API

  7. Contains a com.opencloud.slee.rest.spi.RestRATypeLoader file, that is used by the java.util.ServiceLoader API. The Unified REST RA uses the ServiceLoader API to find all API plugins on RA activation

  8. Generates a Jar that contains a super-class that developers can extend to create an sbb-part for their application. The generated super-class includes all event handlers and slee-annotations required to deploy such an sbb-part in Rhino

Step 2: Configure the API module

The only files the developer needs to edit is the API specification file, and the API properties file in the API submodule. Everything else is generated by the REST RA framework toolchain.

The generated REST API module contain a default (trivial) api.yaml that is a placeholder for the REST API specification. The generated properties file contains suitable default property values. For example a PingPong (server) API properties would be:

api.properties
# properties related to the package structure of the API

api.shortname = pingpong

# optional - a required license function
api.requiredLicenseFunction =

# packages
api.invokerPackage = com.opencloud.openapi.pingpong
api.apiPackage =     com.opencloud.openapi.pingpong.api
api.modelPackage =   com.opencloud.openapi.pingpong.model
api.implPackage =    com.opencloud.openapi.pingpong.impl

# artifact names
api.server.ratype.artifactname  = pingpong-api-server
api.server.plugin.artifactname  = pingpong-api-server-plugin
api.server.sbbpart.artifactname = pingpong-api-server-sbbpart

The developer copies their OpenAPI document into the API Module and customizes the API properties to specify information like package names, or artifact names and versions. The finished API Module can be checked into source control.

Tip The only parts of an API Module that need to be edited by the developer are its properties files and the OpenAPI document itself. The API Module can be regenerated at any time, the developer just needs to retain the properties files and OpenAPI document to preserve its configuration.

Step 3: Build the API module

When the API Module builds, it generates code using OpenAPI SLEE Generator and publishes artifacts including:

  • A SLEE RA Type deployable unit, which defines the application (SBB) interface to the REST RA.

  • A REST RA Plugin deployable unit, which provides the implementation used by the REST RA when sending or receiving HTTP messages.

  • A superclass jar for SBB Parts that may be used as a starting point for developing services.

At this point the developer can depend on these generated artifacts in their project, and write service code using the classes and methods from the generated RA Types.

To actually deploy the service and interact with real REST API clients or servers, the developer must also create their REST RA using a REST RA Module.

Tip The developer repeats steps one, two and three as they update their API specification.

Creating a REST RA Module

ra module workflow.drawio
RA Module workflow

Step 1: Create a REST RA module

The first step is to use the SDK tool sdkadm to create a_REST RA Module_. The REST RA module creates a deployable REST RA.

Tip The module-pack is: rest-api-prototypes/raname-unified-rest-ra

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. 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 of 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: Introduction to the Unified REST RA

OpenAPI SLEE Generator

The OpenAPI SLEE Generator is an extension to openapi-generator. It is used by the REST RA framework to generate the various SLEE components from OpenAPI documents.

The openapi-generator tool provides an extension mechanism so that generators for new languages and frameworks can be added. The OpenAPI SLEE Generator is a Java library, which is loaded by openapi-generator when it is available on the JVM’s classpath (openapi-generator itself is implemented in Java, but can generate output for any language).

The REST RA framework provides Ant macros for running openapi-generator with the necessary command-line options to invoke the OpenAPI SLEE Generator. API Modules include Ant build files to invoke the generator, which can be customized by the SDK user. For example, a user may want to pass additional options to openapi-generator, or override some default templates.

The OpenAPI SLEE Generator uses "libraries", which is an openapi-generator term for sets of templates that can be used with the same generator. The available libraries are:

  • Client RA Type — Interface for an API that provides a client role.

  • Server RA Type — Interface for an API that provides a server role.

  • Client REST RA Plugin — Extension to the REST RA Core that implements a Client RA Type.

  • Server REST RA Plugin — Extension to the REST RA Core that implements a Server RA Type.

  • Client + Server RA Type — Interface for an API that provides a client and server role.

  • Client + Server RA Plugin — Extension to the REST RA Core that implements a Client + Server RA Type.

  • Server SBB Part — Superclass for an SBB Part that implements event handlers for the request events defined in a REST RA Type.

  • Client SBB Part — Superclass for an SBB Part that implements event handlers for the response events defined in a REST RA Type.

The Ant macros provided by the REST RA framework use the appropriate libraries for the component being generated.

Previous page Next page