Discusses how to add new database servers to RM and how to configure available Database Services.
Basic Principles
RM allows adding new database servers to the system and configuring available Database Services.
Initially, database servers can be JDBC-enabled RDBMS. The connection properties of a new database server are passed to the configuration manager, which assigns a database connection manager for the server. Then, Database Services can use the connection manager for connecting to and managing data on the server.
A Database Service can declare properties for configuration, including settings for the database server(s) to host service's data.
For more information about developing Database Services, refer to Developing a Database Service.
Accessing the API for Configuration
Database servers and Database Service properties are managed through the System Configuration API. Persistent properties can be retrieved with the Configurator Manager (com.prosyst.mprm.admin.system.ConfiguratorManager) and can be modified with the Configurator (com.prosyst.mprm.admin.system.Configurator) accessible from Configurator Manager.
The Configurator Manager can be obtained in two ways:
- From a backend host OSGi framework as a service.
- Through a remote access client connected to the control center.
For more information about getting and using the Configurator Manager and Configurator, refer to the System Configuration document.
Getting Information about Available Database Servers
You can retrieve information about the database servers added to the RM system by calling the methods of the DatabaseServerConfiguration interface, which is implemented by the Configurator (used in system configuration mode) or of the Configurator Manager (used runtime mode).
Managing JDBC Drivers
RM contacts an RDBMS server through a JDBC driver, which translates JDBC method invocations to SQL statements.
Drivers in RM are identified by their IDs. Conventionally, driver IDs are named after driver JARs.
You should upload a JDBC driver JAR on the RM backend so that the driver can be located in the host local classpath. Call the uploadDriver method of the Configurator to transfer the driver on the backend.
Uploading a JDBC driver:
import com.prosyst.mprm.admin.system.Configurator;import java.io.FileInputStream; . . . String driverPath = "D:/drivers/jdbc/mysql.jar" FileInputStream in = new FileInputStream(driverPath); configurator.uploadDriver("mysql.jar", in); . . .To get the ID of the drivers available in the system, use the getDriverIds method of Configurator Manager or Configurator.
To obtain a stream to a driver, call the getDriver method specifying the driver ID.
Removing a driver can be with the removeDriver method, called from the Configurator. You are not allowed to remove the JDBC driver, used for communication with the RDBMS server hosting the system database.
Adding a New Database Server
It is possible to define a new database server on which specific Database Services will store their data, or edit the connection properties of an already defined one. You can do this with the Configurator's addDBServer method. You should provide the following database server properties in a configuration dictionary (java.util.Dictionary), whose keys are available as fields in the com.prosyst.mprm.admin.system.DatabaseServerConfiguration interface.
Property Key | Property Type | Description | |
|---|---|---|---|
Properties common to both RDBMS and Directory Servers | |||
|
| The name of the database server in the scope of an RM system. | |
| The database server type. Use | ||
| A valid user on the RDBMS or directory server. Usernames of directory servers have more specific syntax, for example: uid=admin,ou=Administrators,ou=TopologyManagement,o=NetscapeRoot | ||
| The password of the user. | ||
Properties for RDBMS Servers | |||
|
| The class name of the JDBC driver that will bridge RM and the target RDBMS server. | |
| The location on the local disk of the JAR file holding the JDBC driver. If the driver is uploaded on the RM backend, you can also use the driver ID. | ||
| The URL of the RDBMS server. It is driver-specific. | ||
| The maximum number of parallel connections to the database server. | ||
| The maximum number of cached prepared statements. | ||
Properties for Directory Servers | |||
|
| The DNS name or IP address of the host running the target directory server. | |
As a result, the system will add/change the database server properties in the system database, and will reboot loading the new/changed data.
Call the testDBServer method of Configurator to check if you have specified correct configuration data and if the server is running.
The following two listings show the basic steps and the properties to specify when adding a new database server to an RM system.
Adding an RDBMS server to RM:
import com.prosyst.mprm.admin.system.ConfiguratorManager;import com.prosyst.mprm.admin.system.Configurator;import com.prosyst.mprm.admin.system.DatabaseServerConfiguration;import com.mysql.jdbc.Driver;import java.util.*;import java.io.*; . . . final static String JDBC_DB_SERVER_NAME = "Example RDBMS Server"; final static String DRIVER_CLAZZ = com.mysql.jdbc.Driver.class.getName(); private Configurator configurator; . . . Hashtable dbServerConfig = new Hashtable(); dbServerConfig.put(DatabaseServerConfiguration.DB_SERVER_NAME, JDBC_DB_SERVER_NAME); dbServerConfig.put(DatabaseServerConfiguration.DB_SERVER_TYPE, DatabaseServerConfiguration.DB_SERVER_TYPE_JDBC); dbServerConfig.put(DatabaseServerConfiguration.DRIVER, DRIVER_CLAZZ); String driverLib = "mysql.jar"; dbServerConfig.put(DatabaseServerConfiguration.DRIVER_LIB_NAME, driverLib); dbServerConfig.put(DatabaseServerConfiguration.URL, "jdbc:mysql://localhost/example"); dbServerConfig.put(DatabaseServerConfiguration.USER, "root"); dbServerConfig.put(DatabaseServerConfiguration.PASSWORD, "root"); dbServerConfig.put(DatabaseServerConfiguration.MAX_CONNECTIONS, String.valueOf(10)); dbServerConfig.put(DatabaseServerConfiguration.MAX_STATEMENTS, String.valueOf(10)); configurator.addDBServer(dbServerConfig); configurator.testDBServer(JDBC_DB_SERVER_NAME); configurator.apply(); . . . Configuring a Database Service
You can configure a Database Service by calling the setDBServiceConfiguration method of the Configurator. This method takes two arguments:
- Host ID - The management server ID on which the target Database Service is running. If the target Database Service has configuration scope ms, then you can use this argument to specially configure a Database Service deployed on a specific management server and overwrite the service's default configuration. If you pass null for this argument, then the specified configuration is set to all Database Service instances (it is considered as default for the Database Service).
- Configuration dictionary - The dictionary with the new configuration parameters.
Basically, you specify one dictionary per Database Service configuration PID. You can include RM-standard properties for Database Services as well as custom ones if supported by the target Database Service.
To identify the Database Service, you must indicate its name in the configuration dictionary - this is the name with which the service is registered in the backend framework and is included in the database configuration XML. The property key string for a Database Service name is "database.name", which is wrapped by the com.prosyst.mprm.admin.system.DatabaseConfiguration.DATABASE_NAME field.
Next, you must provide the Database Service configuration PID identifying this dictionary. The PID property key is "service.pid", which is wrapped by the org.osgi.framework.Constants.SERVICE_PID field. For a singleton configuration the passed service.pid must be the same as the one set with the DatabaseConfig manifest header of the Database Service bundle. For a configuration instantiated out of a factory configuration, the service.pid must be the same as the system-generated one.
Next, you specify the desired configuration parameters in the dictionary.
RM-standard properties are related to the database server where the corresponding Database Service will store its data. You can find more information about these properties in the Developing a Database Service document.
Note that you should provide the same configuration properties as the ones specified in the database configuration XML of the target Database Service. Otherwise, it is possible that the Database Service does not take into account these properties.
After you set the configuration properties of the Database Service, you should invoke the apply method of Configurator to make the system update the changes in the system database and make a reboot, loading the new properties and passing them to the Database Service.
Configuring a Database Service:
import java.util.*;import com.prosyst.mprm.admin.system.Configurator;import com.prosyst.mprm.admin.system.DatabaseConfiguration;import org.osgi.framework.Constants; . . . final static JDBC_SERVER_NAME = "Example RDBMS Server"; . . . Hashtable dbServiceConfig = new Hashtable(); dbServiceConfig.put(DatabaseConfiguration.DATABASE_NAME, LOGICAL_DATABASE_NAME); dbServiceConfig.put(Constants.SERVICE_PID, "exampledb.pid"); String dbServerNameProperty = DatabaseServerConfiguration.DB_SERVER_NAME + '.' + DatabaseServerConfiguration.DB_SERVER_TYPE_JDBC; dbServiceConfig.put(dbServerNameProperty, JDBC_DB_SERVER_NAME); configurator.setDBServiceConfiguration(null, dbServiceConfig); configurator.apply(); . . .Getting Information about the Database Services on a Specific Database Server
RM can keep records about the Database Services storing data on a specific RDBMS server in a Database Service catalog (see Database Access). By writing a catalog entry a Database Service can protect its data from overlapping with the data of a Database Service belonging to another RM system as well as check if the format of existing tables is compliant with data to be recorded.
To get a Database Service catalog, use the getDBServerCatalog method of Configurator specifying the database server of interest. This method returns an array of com.prosyst.mprm.admin.system.DatabaseCatalogRecord objects, representing the Database Service catalog entries.
From a DatabaseCatalogRecord you can retrieve the name of the Database Service, the service version and the ID of the current RM system.