A persistence resource links a Rhino in-memory database with one or more persistence instances. State stored in the in-memory database is replicated to the external databases for persistence, so that if the Rhino SLEE cluster is shut down then management and provisioned data can be restored.
The persistence resources that Rhino requires are defined in the config/rhino-config.xml file.
An in-memory database, identified by a <memdb> element in this file, that persists its state externally
contains a reference to a persistence resource using a <persistence-resource-ref> element.
In the default configuration, Rhino requires the persistence resources named below:
| Persistence Resource | What it’s used for |
|---|---|
management |
Persistence of installed deployable units, component activation states, configuration information, and so on. |
profiles |
Persistence of all provisioned data in profile tables. |
While it is possible to add and remove persistence resources from Rhino, there is typically never a need to do so.
Rhino only utilises the persistence resources named in config/rhino-config.xml, and all must exist for Rhino to function correctly.
|
Active session state is stored in an in-memory database that is not backed by a persistence resource. |
Persistence resources and persistence instances
A persistence resource can be associated with zero or more persistence instances. By associating a persistence resource with a persistence instance, in-memory database state corresponding with that resource will be persisted to the external database endpoint identified by that persistence instance. Any given persistence instance may be used concurrently by multiple persistence resources. Each persistence resource uses a unique set of tables such that overlap in a single database will not occur.
Upon a successful connection, Rhino will keep each persistence instance synchronised with the state of the persistence resource. Naturally, at least one persistence instance reference must be configured for persistence to occur.
When the first node of a cluster boots, Rhino will attempt to connect to all persistence instances used by a persistence resource, and will initialise corresponding in-memory database state from a connected persistence instance that contains the most recent data. The node will fail to boot if it cannot successfully connect to at least one persistence instance for each required persistence resource.
If Rhino connects to any persistence instance that contain out-of-date data, it will be resynchronised with the latest data. Native database replication should not be used between the persistence instances that Rhino connects to — Rhino will handle the synchronisation itself.
|
A persistence resource should never be associated with two persistence instances that connect to the same physical database. Due to table locking this causes a deadlock when the first Rhino cluster node boots, and it can also cause corruption to database state. |
Using multiple persistence instances for a persistence resource
While only a single PostgreSQL or Oracle database is required for the entire Rhino SLEE cluster, the Rhino SLEE supports communications with multiple database servers.
Multiple servers add an extra level of fault tolerance for the runtime configuration and the working state of the Rhino SLEE. Rhino’s in-memory databases will be constantly synchronized to each persistence instance so if the cluster is restarted it will be able to restore state if any of the databases are operational. If a persistence instance database fails or is no longer network-reachable, Rhino will continue to persist updates to the other instances associated with the persistence resource. Updates will be queued for unreachable instances and stored when the instances come back online.
Configuring multiple instances
Prepare the database servers
Before adding a database to a persistence resource you must prepare the database, by executing $RHINO_NODE_HOME/init-management-db.sh for each server.
$ init-management-db.sh -h dbhost-1 -p dbport -u dbuser -d database postgres
$ init-management-db.sh -h dbhost-2 -p dbport -u dbuser -d database postgresYou will be prompted for a password on the command line
Create persistence instances for the databases
Once the databases are initialised on each database server, configure new persistence instances in Rhino and attach them to the persistence resources. To create persistence instances, follow the instructions at Creating persistence instances.
Add the new persistence instances to the configured persistence resources
When persistence instances have been created for each database, add them to the persistence resources. Instructions to do so are at Adding persistence instances to a persistence resource. An example of the procedure is shown below:
$ ./rhino-console createpersistenceinstance oracle \
oracle.jdbc.pool.OracleDataSource \
URL java.lang.String jdbc:oracle:thin:@oracle_host:1521:db \
user java.lang.String ${MANAGEMENT_DATABASE_USER} \
password java.lang.String ${MANAGEMENT_DATABASE_PASSWORD} \
loginTimeout java.lang.Integer 30
Created persistence instance oracle
$ ./rhino-console addpersistenceinstanceref persistence management oracle
Added persistence instance reference 'oracle' to persistence resource management
$ ./rhino-console addpersistenceinstanceref persistence profiles oracle
Added persistence instance reference 'oracle' to persistence resource profilesIt is also possible to configure the persistence instances before starting Rhino by editing the persistence.xml configuration file.
This is useful for initial setup of the cluster but should not be used to change a running configuration as changes to the file cannot be reloaded without restarting.
An example persistence.xml is shown below:
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE rhino-persistence-config PUBLIC "-//Open Cloud Ltd.//DTD Rhino Persistence Config 2.3//EN" "rhino-persistence-config-2.3.dtd">
<rhino-persistence-config config-version="2.3" rhino-version="Rhino (version='2.5', release='0-TRUNK.0-SNAPSHOT.1-DEV13-pburrowes', build='201610251631', revision='6c862fc (dirty)')" timestamp="1477629656508">
<!--Generated Rhino configuration file: 2016-10-28 17:40:56.507-->
<persistence>
<jdbc-resource jndi-name="jdbc">
<persistence-instance-ref name="postgres-jdbc"/>
<connection-pool connection-pool-timeout="5000" idle-check-interval="30" max-connections="15" max-idle-connections="15" max-idle-time="600" min-connections="0"/>
</jdbc-resource>
<persistence-instances>
<persistence-instance datasource-class-name="org.postgresql.ds.PGSimpleDataSource" name="postgres-1">
<parameter name="serverName" type="java.lang.String" value="${MANAGEMENT_DATABASE_HOST}"/>
<parameter name="portNumber" type="java.lang.Integer" value="${MANAGEMENT_DATABASE_PORT}"/>
<parameter name="databaseName" type="java.lang.String" value="${MANAGEMENT_DATABASE_NAME}"/>
<parameter name="user" type="java.lang.String" value="${MANAGEMENT_DATABASE_USER}"/>
<parameter name="password" type="java.lang.String" value="${MANAGEMENT_DATABASE_PASSWORD}"/>
<parameter name="loginTimeout" type="java.lang.Integer" value="30"/>
<parameter name="socketTimeout" type="java.lang.Integer" value="15"/>
<parameter name="prepareThreshold" type="java.lang.Integer" value="1"/>
</persistence-instance>
<persistence-instance datasource-class-name="org.postgresql.ds.PGSimpleDataSource" name="postgres-2">
<parameter name="serverName" type="java.lang.String" value="${MANAGEMENT_DATABASE_HOST2}"/>
<parameter name="portNumber" type="java.lang.Integer" value="${MANAGEMENT_DATABASE_PORT}"/>
<parameter name="databaseName" type="java.lang.String" value="${MANAGEMENT_DATABASE_NAME}"/>
<parameter name="user" type="java.lang.String" value="${MANAGEMENT_DATABASE_USER}"/>
<parameter name="password" type="java.lang.String" value="${MANAGEMENT_DATABASE_PASSWORD}"/>
<parameter name="loginTimeout" type="java.lang.Integer" value="30"/>
<parameter name="socketTimeout" type="java.lang.Integer" value="15"/>
<parameter name="prepareThreshold" type="java.lang.Integer" value="1"/>
</persistence-instance>
</persistence-instances>
<persistence-resource name="management">
<persistence-instance-ref name="postgres-1"/>
<persistence-instance-ref name="postgres-2"/>
</persistence-resource>
<persistence-resource name="profiles">
<persistence-instance-ref name="postgres-1"/>
<persistence-instance-ref name="postgres-2"/>
</persistence-resource>
</persistence>
</rhino-persistence-config>