Standard Management Functions





Standard Management Functions

All JSR 77 models inherit from the base J2EEManagedObject model. That base model provides a way for any managed object to advertise whether it supports some or all of the three standard management functions defined in the specification: state management, performance monitoring, and event generation. We'll look at the details of each.

1 State Management

Being able to start and stop a managed object seems like a fundamental requirement for manageability. But many managed resources in a J2EE application server may not be capable of independent starting or stopping. The stateManageable attribute of the J2EEManagedObject base class indicates whether a managed resource can be started and stopped.

If the stateManageable attribute is set to true, then the J2EEManagedObject supports the StateManageable model of attributes and operations. If the attribute is set to false, then the object does not support the StateManageable model and presumably does not support having its state changed dynamically through the JSR 77 mechanisms. Figure and 10.14 show the attributes and operations, respectively, defined by the StateManageable model.

By supporting the StateManageable model, a component of the application server is really advertising that it follows the finite state machine defined in JSR 77 and illustrated in Figure. The object stores a value for its state independently from the rest of the system components, and returns its current state to management programs at any point in time.

Figure. State Machine Defined by the StateManageable Model

graphics/10fig06.gif

Figure StateManageable Attributes

Attribute

Type

state

int

startTime

long

Figure StateManageable Operations

Operation

Return Type

start()

void

startRecursive()

void

stop()

void

There are five possible states in which an instance of J2EEManagedObject, supporting the StateManageable model, can exist: STARTING, RUNNING, STOPPING, STOPPED, and FAILED (see Figure). As StateManageable objects make the transition from one state to another, they may generate events to notify interested parties of the change in their state. Some notifications are required by the specification, and others are optional. Section 10.5.2 covers the event notification mechanism defined by JSR 77, so we will present details there.

The required notifications for StateManageable objects are j2ee.state.running, when an object transitions into a RUNNING state; j2ee.state.stopped, to be generated when the object moves to the STOPPED state; and j2ee.state.failed, to be issued when an object enters the FAILED state. Optional state transition events are j2ee.state.starting, issued when the object enters the STARTING state; and j2ee.state.stopping, to be generated when the object enters the STOPPING state.

Let's assume that the StateManageable object begins in the STOPPED state. The management program can invoke a start() operation on the object, which will cause the object to enter the STARTING state (and optionally issue a j2ee.state.starting event). The object will remain in the STARTING state until it makes the transition out of that state under one of two possible conditions: (1) It may succeed in initializing and move to the RUNNING state (at which time it must generate a j2ee.state.running event), or (2) it may fail to initialize and enter the FAILED state (when it must issue a j2ee.state.failed event).

Figure StateManageable States

State

Meaning

STARTING

This object is in the process of getting to the RUNNING state.

RUNNING

This object is in its normal running condition in the server.

STOPPING

This object is in the process of getting to the STOPPED state.

STOPPED

This object is not running but is ready to be started.

FAILED

This object has unexpectedly stopped running.

If the management program needs to stop an instance of an object that supports the StateManageable model, it will invoke a stop() operation on the object. The stop() operation causes the object to move to the STOPPING state, and it may optionally issue a j2ee.state.stopping event. The object leaves this state through one of two paths: It may succeed in stopping and enter the STOPPED state (and issue a j2ee.state.stopped event), or it may fail to cleanly stop and enter the FAILED state (issuing an event at that time).

The StateManageable object provides a startTime attribute that tells the management program the time that the object entered the RUNNING state. Different managed objects within the same application server process may have different startTime values.

StateManageable objects also support a startRecursive() operation that is intended to tell the object that the managed objects that are its children, and that support the StateManageable model, should be started in addition to the target object. There is no corollary operation for stopping a managed object. The stop() operation on a managed object stops all child objects in addition to the original target.

2 Event Generation

Most useful management programs need to know the states of the systems they are managing. But polling for attribute changes is an inefficient technique for monitoring the condition of a server. So JSR 77 has incorporated the asynchronous event notification mechanism defined by JMX. This system allows the management program to register as a listener for only the events that are of interest. When, if ever, the significant event occurs, the registered management program will receive a callback notification.

All J2EEManagedObject subclasses that support the eventProvider model (note that this set implicitly includes all StateManageable objects) provide an eventTypes attribute that is a list of the types of notifications that the object produces. Event types are dot-separated strings that identify the event that caused the notification to be generated. There are eight standard event types defined in JSR 77, and server vendors generally extend that set with proprietary notifications. Server vendors cannot reuse the type prefix j2ee, however, because that is reserved for the specification-defined events. The set of standard event types defined by JSR 77 is shown in Figure.

When an event is generated within the system, all listeners registered for that event will receive a Notification model object. The Notification object contains the information needed by the management program to understand what occurred and when it occurred.

Event Types Defined by JSR 77

Event Type

Meaning

j2ee.object.created

Issued whenever a new managed object is created.

j2ee.object.deleted

Issued whenever an existing managed object is removed.

j2ee.state.starting

Issued whenever a StateManageable object enters the STARTING state.

j2ee.state.running

Issued whenever a StateManageable object enters the RUNNING state.

j2ee.state.stopping

Issued whenever a StateManageable object enters the STOPPING state.

j2ee.state.stopped

Issued whenever a StateManageable object enters the STOPPED state.

j2ee.state.failed

Issued whenever a StateManageable object enters the FAILED state.

j2ee.attribute.changed

Issued whenever an attribute of a managed object changes.

Figure Notification Model Attributes

Attribute

Type

source

OBJECT_NAME

timeStamp

long

sequenceNumber

long

type

String

message

String

userData

Object

Figure lists the attributes of the Notification model. The type attribute will always match one of the event types for which the listener has registered. The source attribute provides identification of the specific managed object that issued the notification because many different objects may be capable of issuing the same notification event. The timeStamp attribute tells the management program when the event occurred. And sequenceNumber allows this event to be correlated with other events that may be related, issued by the same object. Additional information about the event can be obtained from the message attribute and the optional userData attribute.

3 Performance Monitoring

In addition to monitoring the state of an application server and its components, management programs typically gather specific performance data about how well the system is running. Such data allows the management program to understand if parts of the system are under stress and even anticipate failures before they occur.

The J2EE Management specification includes an entire performance data framework to provide this type of information about application servers to management systems. The framework is composed of three components:

  1. The StatisticsProvider model is what managed objects support if they are going to deliver performance data to external management programs.

  2. This performance data for an individual managed object is packaged into a set called Stats. A Stats object is a set of accessor methods that expose a group of related metrics.

  3. The data types of the metrics that are contained within the Stats object must be one of the Statistic model subclasses defined by JSR 77.

For example, a JavaMailResource managed object supports the StatisticsProvider model if the value of its statisticsProvider attribute is set to true. The StatisticsProvider model includes one attribute: stats. JavaMailResource returns this attribute as an object that is a subclass of the Stats model: the JavaMailStats object. The JavaMailStats model includes only one Statistic accessor—the getSentMailCount() operation—which returns an object of type CountStatistic (a subclass of the JSR 77 Statistic model).

In similar fashion, other managed objects that claim to support the StatisticsProvider model return a collection of one or more Statistic objects. The entire collection of Statistic objects for a given managed object is its Stats set. And each Statistic instance in the Stats set has a specific named accessor method.

Note that the defined Stats set of metrics for a particular instance of J2EEManagedObject does not have to be supported completely for the object to be a compliant StatisticsProvider model. The server vendor may elect to provide accessors to a subset of the JSR 77 Stats set for any managed object type. Management programs should always obtain the list of Statistic instances that the object supports by invoking the getStatisticNames() method defined for the Stats model. The list that is returned by the instance of the Stats subclass implemented by a particular vendor is the real set of metrics that the object can provide. The Stats definition in JSR 77 is really just a list of the possible Statistic objects relevant to a managed object type.

Server vendors may augment the Stats definitions for an object. Any metrics returned along with the metrics defined by JSR 77 will be one of the Statistic subclasses. These additional Statistic objects are included in the list returned by the getStatisticNames() method.

All metrics returned to management programs from JSR 77 StatisticsProvider instances are one of the Statistic interface subclasses, which are listed in Figure. These interfaces are defined in the javax.management.j2ee.statistics package.

Each type of J2EEManagedObject has a set of Statistic objects collected into a Stats interface specific to that type of object. Figure lists the Stats interfaces that apply to the various managed objects.

Figure Statistic Interface Subclasses

Class

Description

Statistic

Base class that includes accessors for name, unit of measure, time stamps, and description.

TimeStatistic

Time measurement statistic that has accessors for minimum, maximum, and total time values.

RangeStatistic

Provides lowest, highest, and current value of a metric.

BoundaryStatistic

Provides the limit of upper and lower values of a metric.

BoundedRangeStatistic

Provides the high, low, and current values, along with boundary limits, of a metric.

CountStatistic

Simple counter statistic that has one accessor for count value.

Figure Stats Interfaces

Managed Object

Interface

JVM

JVMStats

JTAResource

JTAStats

EJB

EJBStats

EntityBean

EntityBeanStats

MessageDrivenBean

MessageDrivenBeanStats

SessionBean

SessionBeanStats

StatefulSessionBean

StatefulSessionBeanStats

StatelessSessionBean

StatelessSessionBeanStats

Servlet

ServletStats

JavaMailResource

JavaMailStats

URLResource

URLStats

JCAResource

JCAStats

JDBCResource

JDBCStats

JMSResource

JMSStats

4 Stats Interface Details

The Stats interfaces are also part of the javax.management.j2ee.statistics package. They are strictly accessor definitions for the underlying application server implementation. As such, they include no attributes as part of their definitions.

The base Stats interface has accessor methods to retrieve the list of statistics for this object in one call, and also to retrieve an individual Statistic object identified by its name (see Figure). The getStatisticNames() method returns an array of the entire set of statistic names that the object exposes. This list includes both statistics defined by JSR 77 and vendor-specific statistics.

The JVMStats class provides accessor methods to retrieve the current JVM heap size and also the amount of time that the JVM has been running (see Figure).

The Stats subclass for JTAResource provides methods to obtain the count of active transactions under the control of the resource (see Figure). The number of committed transactions and number of rolled-back transactions is also available from the JTAStats interface.

The EJBStats interface is the base interface for all types of Enterprise JavaBean managed objects. This base interface exposes methods to access the number of times the create() method on the EJBHome interface has been called, as well as the number of times the remove() method has been called (see Figure).

Figure Stats Interface

Accessor Method

Return Type

getStatistic(String sname)

Statistic

getStatisticNames()

String[]

getStatistics()

Statistic[]

Figure JVMStats Interface

Accessor Method

Return Type

getHeapSize()

CountStatistic

getUpTime()

CountStatistic

Figure JTAStats Interface

Accessor Method

Return Type

getActiveCount()

CountStatistic

getCommittedCount()

CountStatistic

getRolledbackCount()

CountStatistic

Figure EJBStats Interface

Accessor Method

Return Type

getCreateCount()

CountStatistic

getRemoveCount()

CountStatistic

In addition to the base EJBStats data, the EntityBeanStats interface provides a RangeStatistic value for the number of instances of the bean in the ready state, as well as the number of instances in the pooled state (see Figure).

The Stats subclass for MessageDrivenBean provides a count of the number of messages received by MessageDrivenBean (see Figure).

The SessionBeanStats interface exposes the method to obtain the number of instances of this bean that are in the method-ready state, in addition to the base EJBStats data (see Figure).

Figure EntityBeanStats Interface

Accessor Method

Return Type

getReadyCount()

RangeStatistic

getPooledCount()

RangeStatistic

Figure MessageDrivenBeanStats Interface

Accessor Method

Return Type

getMessageCount()

CountStatistic

Figure SessionBeanStats Interface

Accessor Method

Return Type

getMethodReadyCount()

RangeStatistic

StatefulSessionBean objects can be passivated to disk, so the Stats subclass for this managed object augments the SessionBeanStats and EJBStats data with an accessor to get the number of beans that have been passivated (see Figure).

No standard accessor methods are defined for the StatelessSessionBeanStats interface. However, server vendors can implement this interface and use it to expose extended statistics beyond those defined in JSR 77.

The ServletStats interface provides one piece of information: the time taken to execute the servlet's service() method (see Figure).

The JavaMailStats interface provides access to the number of mail messages sent by this managed resource (see Figure).

There are no standard accessor methods defined for the URLStats interface. Server vendors can implement the interface and provide any statistics that they deem relevant.

Figure StatefulSessionBeanStats Interface

Accessor Method

Return Type

getPassiveCount()

RangeStatistic

Figure ServletStats Interface

Accessor Method

Return Type

getServiceTime()

TimeStatistic

Figure JavaMailStats Interface

Accessor Method

Return Type

getSentMailCount()

CountStatistic

Figure JCAStats Interface

Accessor Method

Return Type

getConnections()

JCAConnectionStats[]

getConnectPools()

JCAConnectionPoolStats[]

The JCAStats interface is really an entry point for JCA performance measurements. This top-level interface provides operations to obtain a list of JCAConnectionPoolStats objects. Alternatively, a list of JCAConnectionStats objects can be retrieved. Details of these two Stats subclasses are provided in Figure.

The JCAConnectionStats object represents the statistics associated with a single JCA connection. This interface provides a mechanism for management programs to obtain the handle to its connectionFactory managed object and also its managedConnectionFactory object (see Figure). Those objects exist in the J2EEResource topology and may be used to adjust the system if the performance data from the JCA connection represents a problem in the system.

The amount of time spent by the JCA connection waiting for a connection and the amount of time spent using that connection are available as TimeStatistic attributes of the JCAConnectionStats interface.

The JCAConnectionPoolStats interface represents a pool of connections rather than a single connection (see Figure). Several pool-related metrics are available from this interface: size of the connection pool, number of free connections, number of client threads waiting to obtain a connection from the pool, number of times a connection was created, and number of times a connection is closed.

Figure JCAConnectionStats Interface

Accessor Method

Return Type

getConnectionFactory()

OBJECT_NAME

getManagedConnectFactory()

OBJECT_NAME

getWaitTime()

TimeStatistic

getUseTime()

TimeStatistic

Figure JCAConnectionPoolStats Interface

Accessor Method

Return Type

getCloseCount()

CountStatistic

getCreateCount()

CountStatistic

getWaitingThreadCount()

BoundedRangeStatistic

getFreePoolSize()

BoundedRangeStatistic

getPoolSize()

BoundedRangeStatistic

Like JCAStats, the JDBCStats interface is really an entry point for accessing more detailed Stats interfaces for JDBC resources. A list either of individual JDBC connections or of JDBC connection pools may be returned by the interface (see Figure).

The JDBCConnectionStats interface is structured much like the JCAConnectionStats interface. It provides the object name string for the JDBCDataSource resource that supports this connection, as well as the waitTime and useTime counts for the connection (see Figure).

The JDBCConnectionPoolStats interface (see Figure) has the exact same accessors to data as the JCAConnectionPoolStats interface (compare Figure).

Figure JDBCStats Interface

Accessor Method

Return Type

getConnections()

JDBCConnectionStats[]

getConnectionPools()

JDBCConnectionPoolStats[]

Figure JDBCConnectionStats Interface

Accessor Method

Return Type

getJdbcDataSource()

OBJECT_NAME

getWaitTime()

TimeStatistic

getUseTime()

TimeStatistic

Figure JDBCConnectionPoolStats Interface

Accessor Method

Return Type

getCloseCount()

CountStatistic

getCreateCount()

CountStatistic

getWaitingThreadCount()

BoundedRangeStatistic

getFreePoolSize()

BoundedRangeStatistic

getPoolSize()

BoundedRangeStatistic

The JMSStats interface is another entry point to more detailed Statistic structures related to Java Message Service resources. It returns a list of JMSConnectionStats objects (see Figure).

The JMSConnectionStats interface supports a boolean flag to indicate if the resource is a transactional one. It also returns a list of JMSSessionStats objects (see Figure).

JMSSessionStats allows access to lists of producers and consumers of messages associated with the JMS resource (see Figure).

The destination data provided by the JMSProducerStats interface represents the identity of the message destination (see Figure). JMSProducerStats extends the JMSEndpointStats interface, so it also provides all of the data associated with that interface.

Figure JMSStats Interface

Accessor Method

Return Type

getConnections()

JMSConnectionStats[]

Figure JMSConnectionStats Interface

Accessor Method

Return Type

getSessions()

JMSSessionStats[]

isTransactional()

boolean

Figure JMSSessionStats Interface

Accessor Method

Return Type

getProducers()

JMSProducerStats[]

getConsumers()

JMSConsumerStats[]

getDurableSubscriptionCount()

CountStatistic

getExpiredMessageCount()

CountStatistic

getMessageCount()

CountStatistic

getMessageWaitTime()

TimeStatistic

getPendingMessageCount()

CountStatistic

Figure JMSProducerStats Interface

Accessor Method

Return Type

getDestination()

String

The JMSConsumerStats interface also extends the JMSEndpointStats interface. In addition to the end point data provided, the identity of the message origin is available through the getOrigin() accessor method (see Figure).

JMSEndpointStats is the base interface for both message producers and message consumers. Statistics are available for the number of messages expired, exchanged, and pending (see Figure). The wait time before a message is delivered is exposed also.

Figure JMSConsumerStats Interface

Accessor Method

Return Type

getOrigin()

String

Figure JMSEndpointStats Interface

Accessor Method

Return Type

getExpiredMessageCount()

CountStatistic

getMessageCount()

CountStatistic

getMessageWaitTime()

TimeStatistic

getPendingMessageCount()

CountStatistic


     Python   SQL   Java   php   Perl 
     game development   web development   internet   *nix   graphics   hardware 
     telecommunications   C++ 
     Flash   Active Directory   Windows