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

10.5.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. Tables 10.13 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 10.6. 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 10.6. State Machine Defined by the StateManageable Model

Table 10.13. StateManageable Attributes

Attribute	Type
state	int
startTime	long

Table 10.14. 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 Table 10.15). 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).

Table 10.15. 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.

10.5.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 Table 10.16.

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.

Table 10.16. 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.

Table 10.17. Notification Model Attributes

Attribute	Type
source	OBJECT_NAME
timeStamp	long
sequenceNumber	long
type	String
message	String
userData	Object

Table 10.17 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.

10.5.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 Table 10.18. 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. Table 10.19 lists the Stats interfaces that apply to the various managed objects.

Table 10.18. 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.

Table 10.19. 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

10.5.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 Table 10.20). 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 Table 10.21).

The Stats subclass for JTAResource provides methods to obtain the count of active transactions under the control of the resource (see Table 10.22). 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 Table 10.23).

Table 10.20. Stats Interface

Accessor Method	Return Type
getStatistic(String sname)	Statistic
getStatisticNames()	String[]
getStatistics()	Statistic[]

Table 10.21. JVMStats Interface

Accessor Method	Return Type
getHeapSize()	CountStatistic
getUpTime()	CountStatistic

Table 10.22. JTAStats Interface

Accessor Method	Return Type
getActiveCount()	CountStatistic
getCommittedCount()	CountStatistic
getRolledbackCount()	CountStatistic

Table 10.23. 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 Table 10.24).

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

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 Table 10.26).

Table 10.24. EntityBeanStats Interface

Accessor Method	Return Type
getReadyCount()	RangeStatistic
getPooledCount()	RangeStatistic

Table 10.25. MessageDrivenBeanStats Interface

Accessor Method	Return Type
getMessageCount()	CountStatistic

Table 10.26. 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 Table 10.27).

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 Table 10.28).

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

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.

Table 10.27. StatefulSessionBeanStats Interface

Accessor Method	Return Type
getPassiveCount()	RangeStatistic

Table 10.28. ServletStats Interface

Accessor Method	Return Type
getServiceTime()	TimeStatistic

Table 10.29. JavaMailStats Interface

Accessor Method	Return Type
getSentMailCount()	CountStatistic

Table 10.30. 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 Table 10.30.

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 Table 10.31). 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 Table 10.32). 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.

Table 10.31. JCAConnectionStats Interface

Accessor Method	Return Type
getConnectionFactory()	OBJECT_NAME
getManagedConnectFactory()	OBJECT_NAME
getWaitTime()	TimeStatistic
getUseTime()	TimeStatistic

Table 10.32. 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 Table 10.33).

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 Table 10.34).

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

Table 10.33. JDBCStats Interface

Accessor Method	Return Type
getConnections()	JDBCConnectionStats[]
getConnectionPools()	JDBCConnectionPoolStats[]

Table 10.34. JDBCConnectionStats Interface

Accessor Method	Return Type
getJdbcDataSource()	OBJECT_NAME
getWaitTime()	TimeStatistic
getUseTime()	TimeStatistic

Table 10.35. 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 Table 10.36).

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 Table 10.37).

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

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

Table 10.36. JMSStats Interface

Accessor Method	Return Type
getConnections()	JMSConnectionStats[]

Table 10.37. JMSConnectionStats Interface

Accessor Method	Return Type
getSessions()	JMSSessionStats[]
isTransactional()	boolean

Table 10.38. JMSSessionStats Interface

Accessor Method	Return Type
getProducers()	JMSProducerStats[]
getConsumers()	JMSConsumerStats[]
getDurableSubscriptionCount()	CountStatistic
getExpiredMessageCount()	CountStatistic
getMessageCount()	CountStatistic
getMessageWaitTime()	TimeStatistic
getPendingMessageCount()	CountStatistic

Table 10.39. 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 Table 10.40).

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 Table 10.41). The wait time before a message is delivered is exposed also.

Table 10.40. JMSConsumerStats Interface

Accessor Method	Return Type
getOrigin()	String

Table 10.41. JMSEndpointStats Interface

Accessor Method	Return Type
getExpiredMessageCount()	CountStatistic
getMessageCount()	CountStatistic
getMessageWaitTime()	TimeStatistic
getPendingMessageCount()	CountStatistic