com.opencloud.rhino.persistence

Interface PersistenceManagementMBean

public interface PersistenceManagementMBean

The PersistenceManagementMBean interface provides methods to modify Rhino's external database persistence configuration.

The following types of entities can be managed by this MBean:

• Persistence instances - A persistence instance represents an external database endpoint that Rhino can connect to.
• Persistence resources - A persistence resource is a set of persistence instances that can be used by Rhino to externally persist the state of an in-memory database. All persistence instances within a given persistence resource are synchronised with the same state.
• JDBC resources - A JDBC resource can be used by a SLEE application to interact with an external database. A JDBC resource can have at most one configured persistence instance, though a JDBC resource without a configured persistence instance will reject all requests made to it by an application.

Since:

Rhino 2.5.0

Field Summary

Fields

Modifier and Type	Field and Description
static String	MBEAN_NAME The name of this MBean, equal to the string "Persistence".
static String	OBJECT_NAME The JMX Object Name of this MBean.

Method Summary

Methods

Modifier and Type	Method and Description
void	addPersistenceResourcePersistenceInstanceRef(String persistenceResourceName, String persistenceInstanceName) Add a persistence instance reference to an existing persistence resource.
void	createJdbcResource(String jndiName) Create a JDBC resource.
ObjectName	createJdbcResourceConnectionPoolConfig(String jndiName) Add a connection pool configuration to a JDBC resource.
void	createPersistenceInstance(String name, String dsClassName, ConfigProperty[] configProperties) Create a new persistence instance.
void	createPersistenceResource(String name) Create a new persistence resource.
ObjectName	getJdbcResourceConnectionPoolConfigMBean(String jndiName) Get the JMX Object Name of a MBean that can be used to configure the connection pool settings for a JDBC resource.
String	getJdbcResourcePersistenceInstanceRef(String jndiName) Get the current persistence instance reference for a JDBC resource.
String[]	getJdbcResources() Get a list of the names of the current JDBC resource configurations.
CompositeData	getPersistenceInstance(String name, boolean expandProperties) Get a description of a persistence instance configuration.
String[]	getPersistenceInstances() Get a list of the names of the current persistence instance configurations.
String[]	getPersistenceResourcePersistenceInstanceRefs(String persistenceResourceName) Get a list of the names of the persistence instances currently referred to by a persistence resource.
String[]	getPersistenceResources() Get a list of the names of the current persistence resource configurations.
boolean	hasJdbcResourceConnectionPoolConfig(String jndiName) Determine if a JDBC resource has a connection pool configuration.
void	removeJdbcResource(String jndiName) Remove an existing JDBC resource.
void	removeJdbcResourceConnectionPoolConfig(String jndiName) Remove the connection pool configuration from a JDBC resource.
void	removePersistenceInstance(String name) Remove an existing persistence instance configuration.
void	removePersistenceResource(String name) Remove an existing persistence resource.
void	removePersistenceResourcePersistenceInstanceRef(String persistenceResourceName, String persistenceInstanceName) Remove a persistence instance reference from a persistence resource.
void	setJdbcResourcePersistenceInstanceRef(String jdbcResourceJndiName, String persistenceInstanceName) Set the persistence instance reference for a JDBC resource.
void	updatePersistenceInstance(String name, String dsClassName, ConfigProperty[] configProperties) Update the configuration of an existing persistence instance.

Field Detail

MBEAN_NAME

static final String MBEAN_NAME

The name of this MBean, equal to the string "Persistence".

Since:

Rhino 2.5.0

See Also:

Constant Field Values

OBJECT_NAME

static final String OBJECT_NAME

The JMX Object Name of this MBean.

Since:

Rhino 2.5.0

See Also:

Constant Field Values

Method Detail

createPersistenceInstance

void createPersistenceInstance(String name,
                             String dsClassName,
                             ConfigProperty[] configProperties)
                               throws NullPointerException,
                                      InvalidArgumentException,
                                      DuplicateNameException,
                                      ConfigurationException

Create a new persistence instance.

The following Java types are supported for datasource configuration properties:

• java.lang.Integer
• java.lang.Long
• java.lang.Double
• java.lang.Float
• java.lang.Short
• java.lang.Byte
• java.lang.Character
• java.lang.Boolean
• java.lang.String

The value of each datasource configuration property may include references to variables defined in the $RHINO_HOME/config/config_variables file, system properties, or environment properties by surrounding the variable name with ${...}, eg ${MANAGEMENT_DATABASE_NAME}.

Parameters:

name - the name of the persistence instance. This name must be unique within the Rhino cluster.

dsClassName - the fully-qualified class name of the datasource class provided by the JDBC driver.

configProperties - the set of configuration properties used to configure the datasource. May be null if there are no configuration properties.

Throws:

NullPointerException - if name or dsClassName is null.

InvalidArgumentException - if name or dsClassName is zero-length.

DuplicateNameException - if a persistence instance with the same name already exists.

ConfigurationException - if the persistence instance could not be created due to a configuration error.

Since:

Rhino 2.5.0

updatePersistenceInstance

void updatePersistenceInstance(String name,
                             String dsClassName,
                             ConfigProperty[] configProperties)
                               throws NullPointerException,
                                      InvalidArgumentException,
                                      NameNotFoundException,
                                      ConfigurationException

Update the configuration of an existing persistence instance.

Refer to the createPersistenceInstance method for details on the supported configuration property types and values.

Parameters:

name - the name of the persistence instance to update.

dsClassName - the new fully-qualified class name of the JDBC datasource class.

configProperties - the new set of configuration properties used to configure the datasource. These entirely replace the current set of properties. May be null if there are no configuration properties, in which case any existing configuration properties will be deleted.

Throws:

NullPointerException - if name or dsClassName is null.

InvalidArgumentException - if name or dsClassName is zero-length.

NameNotFoundException - if a persistence instance with the specified name doesn't exist.

ConfigurationException - if the persistence instance could not be updated due to a configuration error.

Since:

Rhino 2.5.0

removePersistenceInstance

void removePersistenceInstance(String name)
                               throws NullPointerException,
                                      NameNotFoundException,
                                      InvalidStateException,
                                      ConfigurationException

Remove an existing persistence instance configuration.

Parameters:

name - the name of the persistence instance.

Throws:

NullPointerException - if name is null.

NameNotFoundException - if a persistence instance with the specified name doesn't exist.

InvalidStateException - if the persistence instance is currently in use by a persistence or JDBC resource.

ConfigurationException - if the persistence instance could not be removed due to a configuration error.

Since:

Rhino 2.5.0

getPersistenceInstances

String[] getPersistenceInstances()
                                 throws ConfigurationException

Get a list of the names of the current persistence instance configurations.

Returns:

the names of the current persistence instance configurations.

Throws:

ConfigurationException - if the persistence instance names could not be returned due to a configuration error.

Since:

Rhino 2.5.0

getPersistenceInstance

CompositeData getPersistenceInstance(String name,
                                   boolean expandProperties)
                                     throws NullPointerException,
                                            NameNotFoundException,
                                            ConfigurationException

Get a description of a persistence instance configuration.

The CompositeData object returned by this method has the following structure:

Field	Open Type	Description
name	String	The name of the persistence instance.
datasource-class-name	String	The fully-qualified class name of the configured JDBC datasource class.
config-properties	Tabular Data	The configured configuration properties for the persistence instance. The format of this tabular data is given below.

Each configuration property is expressed as a CompositeData object with the following structure:

Field	Open Type	Description
name	String	The name of the configuration property.
type	String	The Java type of the configuration property.
value	String	The value assigned to the configuration property.

Parameters:

name - the name of the persistence instance.

expandProperties - boolean flag indicating whether or not any property identifiers included in a configuration property value will be expanded with their resolved value (if any).

Returns:

a JMX composite data object as described above.

Throws:

NullPointerException - if name is null.

NameNotFoundException - if a persistence instance with the specified name doesn't exist.

ConfigurationException - if the persistence instance description could not be returned due to a configuration error.

Since:

Rhino 2.5.0

createPersistenceResource

void createPersistenceResource(String name)
                               throws NullPointerException,
                                      InvalidArgumentException,
                                      DuplicateNameException,
                                      ConfigurationException

Create a new persistence resource.

Parameters:

name - the name of the persistence resource. This name must be unique within the Rhino cluster.

Throws:

NullPointerException - if name is null.

InvalidArgumentException - if name is zero-length.

DuplicateNameException - if a persistence resource with the same name already exists.

ConfigurationException - if the persistence resource could not be created due to a configuration error.

Since:

Rhino 2.5.0

addPersistenceResourcePersistenceInstanceRef

void addPersistenceResourcePersistenceInstanceRef(String persistenceResourceName,
                                                String persistenceInstanceName)
                                                  throws NullPointerException,
                                                         NameNotFoundException,
                                                         DuplicateNameException,
                                                         ConfigurationException

Add a persistence instance reference to an existing persistence resource. Upon a successful connection to the external database, the persistence instance will be kept synchronised with other persistence instances in the persistence resource.

Parameters:

persistenceResourceName - the name of the persistence resource.

persistenceInstanceName - the name of the persistence instance to add to the persistence resource.

Throws:

NullPointerException - if either argument is null.

NameNotFoundException - if a persistence resource or persistence instance with the specified name doesn't exist.

DuplicateNameException - if the persistence instance has already been added to the persistence resource.

ConfigurationException - if the persistence instance could not be added to the persistence resource due to a configuration error.

Since:

Rhino 2.5.0

getPersistenceResourcePersistenceInstanceRefs

String[] getPersistenceResourcePersistenceInstanceRefs(String persistenceResourceName)
                                                       throws NullPointerException,
                                                              NameNotFoundException,
                                                              ConfigurationException

Get a list of the names of the persistence instances currently referred to by a persistence resource.

Parameters:

persistenceResourceName - the name of the persistence resource.

Returns:

the names of the persistence instances currently referred to by the specified persistence resource.

Throws:

NullPointerException - if name is null.

NameNotFoundException - if a persistence resource with the specified name doesn't exist.

ConfigurationException - if the persistence instance names could not be returned due to a configuration error.

Since:

Rhino 2.5.0

removePersistenceResourcePersistenceInstanceRef

void removePersistenceResourcePersistenceInstanceRef(String persistenceResourceName,
                                                   String persistenceInstanceName)
                                                     throws NullPointerException,
                                                            NameNotFoundException,
                                                            ConfigurationException

Remove a persistence instance reference from a persistence resource.

Parameters:

persistenceResourceName - the name of the persistence resource.

persistenceInstanceName - the name of the persistence instance to remove from the persistence resource.

Throws:

NullPointerException - if either argument is null.

NameNotFoundException - if a persistence resource with the specified name doesn't exist, or if a persistence instance with the specified name has not been added to the persistence resource.

ConfigurationException - if the persistence instance could not be removed from the persistence resource due to a configuration error.

Since:

Rhino 2.5.0

removePersistenceResource

void removePersistenceResource(String name)
                               throws NullPointerException,
                                      NameNotFoundException,
                                      ConfigurationException

Remove an existing persistence resource.

Parameters:

name - the name of the persistence resource.

Throws:

NullPointerException - if name is null.

NameNotFoundException - if a persistence resource with the specified name doesn't exist.

ConfigurationException - if the persistence resource could not be removed due to a configuration error.

Since:

Rhino 2.5.0

getPersistenceResources

String[] getPersistenceResources()
                                 throws ConfigurationException

Get a list of the names of the current persistence resource configurations.

Returns:

the names of the current persistence resource configurations.

Throws:

ConfigurationException - if the persistence resource names could not be returned due to a configuration error.

Since:

Rhino 2.5.0

createJdbcResource

void createJdbcResource(String jndiName)
                        throws NullPointerException,
                               InvalidArgumentException,
                               DuplicateNameException,
                               ConfigurationException

Create a JDBC resource.

A JDBC resource is bound into Rhino's JNDI namespace at java:resource/jdbc/<jndi-name>. A SLEE application can use the <res-jndi-name> value of jdbc/<jndi-name> (in a <resource-ref> element) to refer to the JDBC resource, as this value is relative to the java:resource/ namespace.

Parameters:

jndiName - the name of the JDBC resource. This name must be unique within the Rhino cluster.

Throws:

NullPointerException - if jndiName is null.

InvalidArgumentException - if jndiName is zero-length.

DuplicateNameException - if a JDBC resource with the same name already exists.

ConfigurationException - if the JDBC resource could not be created due to a configuration error.

Since:

Rhino 2.5.0

setJdbcResourcePersistenceInstanceRef

void setJdbcResourcePersistenceInstanceRef(String jdbcResourceJndiName,
                                         String persistenceInstanceName)
                                           throws NullPointerException,
                                                  NameNotFoundException,
                                                  ConfigurationException

Set the persistence instance reference for a JDBC resource. This persistence instance represents the external database that JDBC connections will be made to for this resource.

Parameters:

jdbcResourceJndiName - the name of the JDBC resource.

persistenceInstanceName - the name of the persistence instance to set for the JDBC resource. May be null to remove an existing persistence instance reference from the JDBC resource.

Throws:

NullPointerException - if jdbcResourceJndiName is null.

NameNotFoundException - if a JDBC resource or persistence instance with the specified name doesn't exist.

ConfigurationException - if the persistence instance could not be set for the JDBC resource due to a configuration error.

Since:

Rhino 2.5.0

getJdbcResourcePersistenceInstanceRef

String getJdbcResourcePersistenceInstanceRef(String jndiName)
                                             throws NullPointerException,
                                                    NameNotFoundException,
                                                    ConfigurationException

Get the current persistence instance reference for a JDBC resource.

Parameters:

jndiName - the name of the JDBC resource.

Returns:

the name of the current persistence instance reference, or null if one is not set.

Throws:

NullPointerException - if jndiName is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

ConfigurationException - if the persistence instance name could not be returned due to a configuration error.

Since:

Rhino 2.5.0

createJdbcResourceConnectionPoolConfig

ObjectName createJdbcResourceConnectionPoolConfig(String jndiName)
                                                  throws NullPointerException,
                                                         NameNotFoundException,
                                                         InvalidStateException,
                                                         ConfigurationException

Add a connection pool configuration to a JDBC resource. A connection pool allows JDBC connections from the resource to be pooled for reuse.

The connection pool configuration will initially contain default settings. This method returns the JMX Object Name of a MBean that can be used to change these settings. This MBean exposes an interface represented by JDBCResourceConnectionPoolManagementMBean.

Parameters:

jndiName - the name of the JDBC resource.

Returns:

the JMX Object Name of the connection pool configuration MBean.

Throws:

NullPointerException - if jndiName is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

InvalidStateException - if the JDBC resource already has a connection pool configuration.

ConfigurationException - if the connection pool configuration could not be created due to a configuration error.

Since:

Rhino 2.5.0

hasJdbcResourceConnectionPoolConfig

boolean hasJdbcResourceConnectionPoolConfig(String jndiName)
                                            throws NullPointerException,
                                                   NameNotFoundException,
                                                   ConfigurationException

Determine if a JDBC resource has a connection pool configuration.

Parameters:

jndiName - the name of the JDBC resource.

Returns:

true if the JDBC resource has a connection pool configuration, false otherwise.

Throws:

NullPointerException - if jndiName is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

ConfigurationException - if the presence of a connection pool configuration could not be determined due to a configuration error.

Since:

Rhino 2.5.0

getJdbcResourceConnectionPoolConfigMBean

ObjectName getJdbcResourceConnectionPoolConfigMBean(String jndiName)
                                                    throws NullPointerException,
                                                           NameNotFoundException,
                                                           InvalidStateException,
                                                           ConfigurationException

Get the JMX Object Name of a MBean that can be used to configure the connection pool settings for a JDBC resource. This MBean exposes an interface represented by JDBCResourceConnectionPoolManagementMBean.

Parameters:

jndiName - the name of the JDBC resource.

Returns:

the JMX Object Name of the connection pool configuration MBean, or null if no connection pool has been configured for the JDBC resource.

Throws:

NullPointerException - if jndiName is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

InvalidStateException - if the JDBC resource doesn't have a connection pool configuration.

ConfigurationException - if the object name could not be returned due to a configuration error.

Since:

Rhino 2.5.0

removeJdbcResourceConnectionPoolConfig

void removeJdbcResourceConnectionPoolConfig(String jndiName)
                                            throws NullPointerException,
                                                   NameNotFoundException,
                                                   InvalidStateException,
                                                   ConfigurationException

Remove the connection pool configuration from a JDBC resource. Without a connection pool configuration, JDBC connections from the resource will not be pooled for reuse.

Parameters:

jndiName - the name of the JDBC resource.

Throws:

NullPointerException - if jndiName is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

InvalidStateException - if the JDBC resource doesn't have a connection pool configuration.

ConfigurationException - if the connection pool configuration could not be removed due to a configuration error.

Since:

Rhino 2.5.0

removeJdbcResource

void removeJdbcResource(String jndiName)
                        throws NullPointerException,
                               NameNotFoundException,
                               InvalidStateException,
                               ConfigurationException

Remove an existing JDBC resource.

Parameters:

jndiName - the name of the JDBC resource.

Throws:

NullPointerException - if is null.

NameNotFoundException - if a JDBC resource with the specified name doesn't exist.

ConfigurationException - if the JDBC resource could not be removed due to a configuration error.

InvalidStateException

Since:

Rhino 2.5.0

getJdbcResources

String[] getJdbcResources()
                          throws ConfigurationException

Get a list of the names of the current JDBC resource configurations.

Returns:

the names of the current JDBC resource configurations.

Throws:

ConfigurationException - if the JDBC resource names could not be returned due to a configuration error.

Since:

Rhino 2.5.0