A key/value store is configured in a node’s rhino-config.xml configuration file using the optional key-value-store element.

The element content is defined as follows:

<!-- Key/Value store definition -->
<!ELEMENT key-value-store (parameter*, persistence-resource-ref?)>
<!-- the name of this key/value store -->
<!ATTLIST key-value-store name CDATA #REQUIRED>
<!-- fully-qualified class name of the key/value store service provider class -->
<!ATTLIST key-value-store service-provider-class-name CDATA #REQUIRED>

<!-- a configuration parameter -->
<!ELEMENT parameter EMPTY>
<!ATTLIST parameter name CDATA #REQUIRED>
<!ATTLIST parameter type CDATA #REQUIRED>
<!ATTLIST parameter value CDATA #REQUIRED>

<!-- reference to a persistence resource defined in persistence.xml -->
<!ELEMENT persistence-resource-ref EMPTY>
<!ATTLIST persistence-resource-ref name CDATA #REQUIRED>

At minimum, a name for the key/value store and a service provider class name need to be specified. Multiple key/value stores may be specified in the configuration file and each must have a unique name. The service provider class name is expected to be documented by the key/value store, as are any parameters that may be configured by the user.

A key/value store that can utilise Rhino’s persistence framework may also require a <persistence-resource-ref>. This element refers to a persistence resource defined in the separate persistence.xml configuration file.

Warning As with all other persistence related configurations, key/value stores should be configured the same way on all nodes in a Rhino cluster for them to function correctly.

Configuring an in-memory database to use a key/value store

A local (non-replicated) in-memory database can be configured to use a key/value store by simply adding a <key-value-store-ref> element to its configuration in rhino-config.xml. The element contains a name attribute specifying the name of a key/value store defined and configured as specified above.

The example rhino-config.xml fragment below shows a configuration for a local in-memory database called KeyValueDatabase that contains a reference to a key/value store named cassandra.

<memdb-local>
  <jndi-name>KeyValueDatabase</jndi-name>
  <committed-size>300M</committed-size>
  <stripe-count>1</stripe-count>
  <uses-state-pool>true</uses-state-pool>
  <key-value-store-ref name="cassandra"/>
</memdb-local>
Tip Replicated in-memory databases configured using the <memdb> element use the savanna framework to replicate database state and cannot be configured with a key/value store.

Configuring the replicated storage resource for the default namespace

The default namespace always exists, consequently the decision on which replicated storage resource the default namespace will use must be statically declared in rhino-config.xml.

This is done using the <replicated-storage> sub-element of the <default-namespace> element within <persistence-resources>. This element specifies the JNDI name of a configured in-memory database that will be used for replicated state storage for the namespace. The specified name must be one of:

  • a configured <memdb> instance, which replicates using the traditional savanna framework

  • a configured <memdb-local> instance that contains a <key-value-store-ref>, which replicates using the key/value store.

The example rhino-config.xml fragment below shows the default namespace configured to use the KeyValueDatabase as its replicated storage resource.

<persistence-resources>
  <default-namespace>
    <replicated-storage>KeyValueDatabase</replicated-storage>
  </default-namespace>
  ...
</persistence-resources>
Note A Rhino node will fail to start if the specified database resource doesn’t exist or is not a resource that replicates.

Configuring the replicated storage resource for user-defined namespaces

The replicated storage resource for a user-defined namespace can be declared when that namespace is created.

The namespace creation MBean operation accepts a set of options that allow the resources used by the namespace to be configured. One of these options specifies the replicated storage resource to be used for the namespace. The options parameter should be set according to the required configuration. If a replicated storage resource is not specified in the options, then the namespace uses the same replicated storage resource as the default namespace.

The rhino-console example below illustrates the creation of a namespace called my-namespace that uses the KeyValueDatabase as the replicated storage resource:

$ ./rhino-console createnamespace my-namespace -replication-resource KeyValueDatabase
Namespace my-namespace created

Typical configuration process

The end-to-end process to configure and use a key/value store typically follows the below steps:

  1. If necessary, a persistence resource and associated persistence instances are created using, for example, rhino-console commands while the Rhino cluster is up and running.

  2. The cluster nodes are shut down and rhino-config.xml is modified on each node to add the key/value store store configuration and create the necessary in-memory database configuration.

  3. The replicated storage resource for the default namespace is updated if necessary.

    • Whenever the replicated storage resource for the default namespace is changed, Rhino’s management database must be reinitialised. If there are SLEE components, etc, that wish to be retained across the change, an export of current SLEE state can be made before the change and then re-imported after the change and management database reinitialisation.

  4. Finally, the cluster nodes are restarted.

Note During the installation of production Rhino, the installer will ask for the name of the desired replicated storage resource for the default namespace. If the key/value store replicated storage resource is selected, the installer will automatically configure the persistence resources and rhino-config.xml appropriately with default settings for the Cassandra key/value store included with Rhino.
Previous page Next page
Rhino Version 3.0.0