Version 15

    IronJacamar management

     

    The goal of this page is to describe the management features of the IronJacamar container, the design and key implementation classes.

     

     

    Requirements

     

    The overall requirements are

     

     

    • Show the configuration of deployed resource adapters and datasources
    • Show statistics for resource adapters and datasources
    • Apply changes to the configuration of deployed resource adapters and datasources
    • Invoke operations on the deployed resource adapters and datasources

     

    Design

     

    We should a central place where the management view of resource adapters and datasources are registered (ManagementRepository).

     

    This repository provides access to classes (Connector / DataSource) that represent a single deployment of either a resource adapter or a datasource.

     

    Each of these classes are split into a hierarchy where information about the deployment and references to the live objects are maintained. It must be a design goal that the management classes uses methods from the public API of the IronJacamar container.

     

      ManagementRepository
        |
        |- Connector
        |    |
        |    |- Resource Adapter 
        |    |
        |    |- Connection Factories
        |    |
        |    |- Admin Objects
        |
        |- DataSource
    

     

    See a description of each class below.

     

    The implementation must be pure POJO, and only depend on the IronJacamar container.

     

    Clients of the management repository contains the management specific technology, such as

     

    • Java Management Extensions (JMX)
    • JBoss Application Server 7 domain model
    • RHQ

     

    That way we can provide an API that can be used from all client types.

     

    ManagementRepository

     

    Method
    Description
    getConnectors()The active resource adapters
    getDataSources()The active datasources

     

    Connector

     

    Method
    Description
    getUniqueId()The unique identifier for the deployment
    getResourceAdapter()The resource adapter
    getConnectionFactories()The connection factories
    getAdminObjects()The admin objects

     

    Resource Adapter

     

    Method
    Description
    getResourceAdapter()A reference to the live object
    getConfigProperties()The config-property's for the resource adapter
    getStatistics()A reference to the statistics module for the resource adapter

     

    Connection Factory

     

    Method
    Description
    getJndiName()The JNDI name of the connection factory
    getConnectionFactory()A reference to the connection factory
    getManagedConnectionFactory()A reference to the managed connection factory
    getPool()A reference to the pool
    getPoolConfiguration()A reference to the pool configuration

     

    ManagedConnectionFactory

     

    Method
    Description
    getManagedConnectionFactory()A reference to the live object
    getConfigProperties()The config-property's for the managed connection factory
    getStatistics()A reference to the statistics module for the managed connection factory

     

     

    AdminObject

     

    Method
    Description
    getJndiName()The JNDI name for the admin object
    getAdminObject()A reference to the live object
    getConfigProperties()The config-property's for the admin object
    getStatistics()A reference to the statistics module for the admin object

     

    ConfigProperty

     

    Method
    Description
    getName()The name of the config-property
    isDynamic()Is the config-property dynamic - e.g. supports live updates
    isConfidential()Is the config-property confidential

     

    DataSource

     

    Method
    Description
    getJndiName()The JNDI name of the datasource
    isXA()Is the datasource XA capable
    getPool()A reference to the pool
    getPoolConfiguration()A reference to the pool configuration

     

     

    Features

     

    TBD

     

    Operations

     

    Description of the operations that can be invoked are listed below.

     

    • "Per request" -- Once an update has been performed it will be used at the next invocation of a method which uses the property in question
    • "Per container" -- Is applied once a container is started/restarted

     

     

    Pool

     

    Operation
    Description
    flushFlushes the pool for idle connections
    flush(boolean)Flushes the pool for either idle connections (false) or the entire pool (true)
    testConnectionTests if a connection can be obtained

     

    PoolConfiguration

     

     

    Property
    ReadWriteApplied
    MinSizeYYPer request
    MaxSizeYYPer request
    BlockingTimeoutYYPer request
    IdleTimeoutYYPer container
    BackgroundValidationYYPer container
    BackgroundValidationMinutesYYPer container
    PrefillYYPer container
    StrictMinYYPer request
    UseFastFailYYPer request

     

     

    Statistics

     

    Statistics should be handled through an SPI using the following two interfaces

     

     

    org.jboss.jca.core.spi.statistics.Statistics
    org.jboss.jca.core.spi.statistics.StatisticsPlugin
    

     

    The "Statistics" interface identifies that the component in question supports statistics. The "StatisticsPlugin" interface defines the contract for the statistics module.

     

    Implementation

     

    The implementation is located in the core module of the IronJacamar repository. The package is

     

    org.jboss.jca.core.api.management
    

     

    The implementing classes must use java.lang.ref.WeakReference for all live object references, such that won't prevent a garbage collection of the object in question.

     

    Operations

     

    Pool

     

    Access can be done directly on the reference.

     

    PoolConfiguration

     

    Access can be done directly on the reference.

     

    Statistics

     

    It is possible to enable/disable statistics collection, as well as clear current values.

     

    All statistics are read-only.

     

    PoolStatistics

    Property
    Description
    ActiveCountThe active count
    AvailableCountThe available count
    AverageBlockingTimeThe average time spent blocking on a connection
    AverageCreationTimeThe average time spent on creating a physical connection
    CreatedCountThe created count
    DestroyedCountThe destroyed count
    MaxCreationTimeThe maximum time spent on creating a physical connection
    MaxUsedCountThe maximum number of connections used
    MaxWaitCountThe maximum number of threads waiting for a connection
    MaxWaitTimeThe maximum time waiting for a connection
    TimedOutThe timed out connections
    TotalBlockingTimeThe total time spent blocking for connections
    TotalCreationTimeThe total time spent creating physical connections

     

     

    Note, that is part of the core statistics of the IronJacamar container. Hence statistics will always be collected in order to provide internal feedback to the container. Therefore this module can't be cleared either.

     

    Test suite

     

    The management model is currently tested through the RHQ plugin.

     

    JDBC

     

    The JDBC resource adapter has the following statistics exposed

     

    Statistics
    Description
    PreparedStatementCacheAccessCountThe number of times that the statement cache was accessed
    PreparedStatementCacheAddCountThe number of statements added to the statement cache
    PreparedStatementCacheCurrentSizeThe number of prepared and callable statements currently cached in the statement cache
    PreparedStatementCacheDeleteCountThe number of statements discarded from the cache
    PreparedStatementCacheHitCountThe number of times that statements from the cache were used
    PreparedStatementCacheMissCountThe number of times that a statement request could not be satisfied with a statement from the cache