Package 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 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

    • Method Detail

      • createPersistenceInstance

        @Deprecated
void createPersistenceInstance​(String name,
                               String dsClassName,
                               ConfigProperty[] configProperties)
                        throws NullPointerException,
                               InvalidArgumentException,
                               DuplicateNameException,
                               ConfigurationException
        Deprecated.
        use createPersistenceInstance(String, PersistenceInstanceType, String, ConfigProperty[]) instead.

        Create a new JDBC 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

      • createPersistenceInstance

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

        Create a new persistence instance of the specified type.

        The following Java types are supported for persistence instance 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 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.
        type - the type of persistence instance to create.
        dsClassName - the fully-qualified class name of the datasource class provided by the JDBC driver. This parameter must have a non-null value for JDBC persistence instances and is ignored for other types.
        configProperties - the set of configuration properties used to configure the persistence instance. May be null if there are no configuration properties.
        Throws:
        NullPointerException - if name or type is null, or if the type is JDBC and dsClassName is null.
        InvalidArgumentException - if name is zero-length, or if the type is JDBC and 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.6.1

      • updatePersistenceInstance

        void updatePersistenceInstance​(String name,
                               PersistenceInstanceType type,
                               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.
        type - the new type of persistence instance.
        dsClassName - the new fully-qualified class name of the datasource class provided by the JDBC driver. This parameter must have a non-null value for JDBC persistence instances and is ignored for other types.
        configProperties - the new set of configuration properties used to configure the persistence instance. 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 type is null, or if the type is JDBC and dsClassName is null.
        InvalidArgumentException - if name is zero-length, or if the type is JDBC and 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.6.1

      • 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.

        type

        String

        The persistence instance type, eg. 'jdbc' or 'cassandra'.

        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

      • 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

      • 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

      • 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

      • 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

      • 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