Provides information on using the available RM APIs

Each distribution package of theRM provides a rich set of Java APIs which allow system integrators and service application developers to customize the system.

For example, the RM system development can go into some of the following basic directions:

  • Creating custom applications for remote access to the system

  • Supplying the RM backend with custom modules extending or modifying the capabilities of the system

  • Integrating RM with third-party standards, systems, databases, etc.

To be able to perform the above functions (and many more), you need to know how to use the numerous RM API libraries. Although each package provides a different functionality, (most of) their APIs share common principles of usage.

The current document presents the common features of the RM APIs, and the most common ways to use them.

RM APIs Overview

Developers who want to administrate the RM system and access its services can use convenient high-level APIs: the Front-end APIs. They contain all packages starting with com.prosyst.mprm.admin. These APIs are accessible both from non-RM applications/systems through a Remote Access Client, and as OSGi services on backend server hosts. In reality, the Front-end APIs wrap in themselves low-level services that perform the most essential functions of the backend. They operate with raw data structures, such as com.prosyst.util.io.Externalizable, and are rather inconvenient to use.

The Backend APIs (all com.prosyst.mprm.backend.* packages) enable system-level management of RM. They are accessible from services running on backend server hosts only. They provide means for establishing communication between backend modules, creating backend-side applications distributed over numerous backend server hosts, etc.

The communication between backend server hosts is based on the Network APIs. They wrap the RM network communication services.

Common Usage of the Front-end APIs

As already mentioned, the Front-end APIs enable administration of the RM functions without need to work with the low-level services handling the actual work on the RM backend. There are two types of applications that can use the Front-end APIs:

  • Modules on external applications – These can be stand-alone modules, such as GUI applications, or extending modules adding their own logic to the system. These modules establish a connection to the control center over the RM Connection Framework and remotely invoke the services running on the backend.
  • OSGi services installed on the backend – These additional modules developed by a system integrator can communicate with the rest of the services through the means of the OSGi framework model - by getting and releasing OSGi services.

Remote Usage of the Frontend APIs

If you are using the APIs through remote applications, use the getService method of com.prosyst.mprm.rac.RemoteAccessClient for establishing remote connection with the control center or a RAS, and maintaining all information about the state of the system. The connection is acquired over the RM Connection Framework. It requires authentication with a valid backend user. The methods of the Remote Access Client (RAC) retrieve high-level administration interfaces through which you can access the backend services (as shown in the following figure).

More information about using the Remote Access Client utility and remote backend access is available in the Remote Access to RM document.

Local Usage as OSGi Services

You can obtain the front-end service interfaces locally on RM backend server hosts through the standard means defined by the OSGi service model. As you know, you can use the getServiceReference and getService methods of org.osgi.framework.BundleContext to obtain the OSGi service registered under the corresponding interface.

When you invoke a front-end service, it cares to invoke the corresponding low-level service (as shown in the following figure). This process is transparent to users.

You may notice that each backend bundle that registers a front-end service additionally registers a service interface from the com.prosyst.mprm.radmin.* packages. The radmin services are the low-level services referred by the front-end services. They are NOT to be used by custom services! They are for internal use by the system only. The radmin services are not available in the RM APIs either. 

Common Usage of the Backend APIs

The Backend APIs are to be used locally on backend server hosts. For remote access to the system from external applications, use the Front-end APIs instead (see "Remote Usage of the Front-end APIs").

Creating Backend-Distributed Applications

If a service needs to provide custom functionality to the RM backend, most probably it will need to spread the information occurring on a single backend host to other backend hosts participants in the same RM system configuration, in the same MS cluster or in the same device context. Backend hosts from the same MS or RAS cluster must also ensure no information is sent to other MSs or RASs more than once. This might occur if different members of the same cluster handle sending the information outside the cluster.

The distribution of information can be done through the RM RPC Service and/or RM Event Service. The RPC Service allows remote invocation of a service's methods, while the events system enables inter-host communication through events.

RM API Libraries

The API library for each RM distribution package is available in the lib/api folder of RM's installation directory. The remote access library resides in the lib/rac folder. Set class path to them when compiling your applications.