Contains a programmer's guide to configuring an RM system, including its hosts, bundles and Database Services, through the System Configuration API.

Overview

An RM system can have several backend server hosts and its modules keep related data on data storage systems, such as RDBMSs and directory servers. RM offers a mechanism for centralized configuration from the control center of system components.

The configuration of the system is managed by the RM configuration manager. The configuration data for an RM system is persistently stored in a special database, called system database. All subsequently added backend hosts retrieve their basic configurations from the system database and configure their local modules.

Accessing the System Configuration API

The front-end System Configuration API is concentrated in the com.prosyst.mprm.admin.system Java package. The APIs main interface is ConfiguratorManager and can be accessed in two ways:

• On the RM backend as a service in the context of the control center or remote access server OSGi framework.
• Through the remote access client (RAC) by using the getService or getRemoteReference method of com.prosyst.mprm.rac.RemoteAccessClient. For more information about using the RAC API refer to the Remote Access to RM document.

For further details on how to access RM front-end APIs, refer to the Common Principles for Using the RM APIs.

Configurator Manager vs. Configurator

The System Configuration API has two usage modes defined by different sets of allowed administration operations.

• Runtime mode - This mode defines the following set of operations that can be executed runtime:
  • Observing the system.
  • Retrieving the persistent configuration of an RM system, including database servers and Database Services as well as backend hosts and deployed bundles.
  • Activate/deactivate backend bundle packages.
  • Deploying/updating/removing standalone backend bundles.
  • Enabling package optional bundles.
  • Modifying backend bundle configurations.

Runtime mode is handled by the Configurator Manager, available as a service (com.prosyst.mprm.admin.system.ConfiguratorManager) in a backend OSGi framework.

• System configuration mode - This mode allows you to modify the system configuration. Applying changes results in rebooting the system including all its backend hosts. An application can enter system configuration mode only if it is running on or is connected to the control center.

The operations available in system configuration mode are:

• • Adding backend hosts to the system.
  • Configuring the roles of registered backend hosts.
  • Managing device contexts of management servers.
  • Managing database servers.
  • Deployment of backend bundle packages.
  • Configuring available Database Services.
  • Adding networks, network filters and host network URLs.
  • The operations available in runtime mode.

System configuration mode is managed by the Configurator. The Configurator is represented by the com.prosyst.mprm.admin.system.Configurator interface and is retrieved from the Configurator Manager.

The Configurator does not set the changes made with it until explicitly applied. It accumulates them so that it is not necessary to apply every modification and needlessly load the system.

As the content of the system database determines the configuration of the entire system, there is a separate Configurator instance for a specific system database.

Using Configurator Manager

Getting the Configurator

You can obtain a Configurator instance from the Configurator Manager in order to edit the current database access and host configurations in the following way:

• Get an empty Configurator with the createConfigurator method.

The Configurator connects to the system database server with the connection properties currently set.

• Call Configurator's init(Dictionary systemDbServer) method to initialize the Configurator with system information from a specific database server.

To use the current system database server, pass null to the init method. If the System Database Service configuration is not set yet, an exception is thrown.

To load system information from another database server, provide the connection properties of the new database server so that the system is able to configure the System Database Service and access the database. For more information about what should be included in the database server properties, refer to the Configuring Database Servers and Services document.

Observing the System

You can observe the system by using the methods defined in the com.prosyst.mprm.admin.system.SystemObserver interface, which is implemented by the Configurator Manager.

With the SystemObserver methods you can also inspect the backend hosts as described in the Backend Server Host Configuration document, the database access components as described in the Configuring Database Servers and Services document and the network configuration as described in the Network Configuration Management document.

You can check the current state of the system with the getSystemState of the Configurator Manager. The returned SystemState object can be used to get:

• The state of the system with the getState method. Then, you can compare the returned state ID with one of the SystemState fields.
• The connection properties of the database server hosting the system database with the getSystemDatabaseConfig method. The returned dictionary contains the following properties, wrapped by DatabaseServerConfiguration fields:

• The persistent configuration of the local/connected backend host with the getHostConfig method. The method returns a dictionary with the host properties, described in Backend Server Host Configuration.
• The errors that occurred in the system with the getErrors method.

Tracking Changes in the System Configuration

You can receive events when the system configuration is changed. Implement com.prosyst.mprm.admin.system.ConfigurationListener and register the listener with the addConfigurationListener method of the Configurator Manager.

Tracking Changes in the State of a Host

You can subscribe for events related to changes in the state of a host. In such case, you should implement com.prosyst.mprm.admin.system.HostListener and register this listener with addHostListener method the Configurator Manager.

Configuring Backend Bundles

You can deploy singleton bundles on all backend hosts with a specific role. You can also executes some basic operations on packages and standalone bundles such as start and stop. See the Backend Bundle Configuration document for more details on these System Configuration API features.

Viewing Uploaded JDBC Drivers

You can view the RDBMS-specific JDBC drivers, currently uploaded to RM backend hosts. Refer to the Configuring Database Servers and Services document for more details about managing JDBC drivers with the System Configuration API.

Getting Unobserved Device Contexts

You can get the device contexts from the device management tree that are not associated with any management server with the unObservedContexts method of Configurator Manager.

Using Configurator

General Issues

• As it was said previously in this document, to save any changes in the system configuration made with the Configurator and put them in use, they should be explicitly applied. This is done with the apply method.
• You can restore the persistent system configuration by calling the importLastSystemConfiguration method of Configurator.
• You can release all resources currently consumed by the Configurator by calling its release method.
• Once applied or released, a Configurator instance is no longer valid.

Observing the System

The Configurator implements the com.prosyst.mprm.admin.system.SystemObserver interface and you can perform most of the operations for retrieving the current system configuration.

The SystemState object, returned when calling the getSystemState method on the Configurator, contains information only that the system is being configured. You can call only the getState method, which returns SystemState.CONFIGURING. The rest of SystemState's methods return null.

Configuring Database Access

With the Configurator you can introduce new database servers as well as edit their connection properties. It is also possible to change configurations of Database Services. Refer to the Configuring Database Servers and Services document for more details about executing this kind of configuration with the System Configuration API.

Configuring Backend Server Hosts

You can use the Configurator to add new backend hosts to the system and edit their roles. See the Backend Server Host Configuration document for more information about executing this kind of configuration with the System Configuration API.

Configuring Backend Bundles

The Configurator enables deployment of packages and standalone backend bundles. You can get further details on package and bundle deployment in the Backend Bundle Configuration document with the System Configuration API.