MonitoringRegistrationHelper Utility

Provides for collection of monitoring statistics from JSR77 compliant Stats implementations through the JMX API. Various J2EE server components can expose their JSR 77 compliant Stats implementations to a JMX client with the help of this package.
The J2EE server components register their `Stats` implementations through a `MonitoringRegistrationHelper` utility class that provides the ability to register and unregister components to make them available (or unavailable) to JMX clients. The registration interface introspects the `Stats` implementation, creates a `DynamicMBean` out of the introspected parts, and exposes this derived management interface to JMX clients by registering the `DynamicMBean` with the `MBeanServer.` Any calls to the MBean's public API is delegated to the `Stats` implementation and the underlying `Statistic`'s monitored attribute value is returned.
The magnitude of monitoring and corresponding number of attributes involved in monitoring is dependent on the level at which monitoring of each component is set. A change in monitoring level to `OFF, LOW` or`HIGH` from a prior setting results in a change in the extent to which monitoring is performed for that component. Following each such change in state, the J2EE server component has to unregister its previous `Stats` implementation. The `MonitoringRegistrationHelper` unregisters the `DynamicMBean` from the `MBeanServer` as a result. If the change in state results in monitoring level being either `HIGH` or `LOW`(i.e. not `OFF`), the component will now register a `Stats` implementation that reflects the higher or lower set of attributes that are monitored. The `MonitoringRegistrationHelper` will now generate a new `DynamicMBean` that will expose the revised higher or lower level of observed attributes as a result of the change in setting.

### Client Perspective

When a non-JSR 77 compliant client calls the MBean to access attribute specified in the underlying Stats implementation, it cannot handle the returned object of `Statistic` type. To address this, the JMX clients make requests for specific statistical observation.
As an example, an implementation of the `JVMStats` interface returns a `BoundedRangeStatistic` object when the method `getHeapSize()` or `getStatistic("HeapSize")` is called on it. The `BoundedRangeStatistic` object in turn, has several statistical observations provided as methods such as `getUpperBound(), getLowerBound(), getHighWaterMark(), getLowWaterMark(),` etc. The JMX client would have to make a request that specifies the particular observation such as the `UpperBound` value of the statistic `HeapSize`. The client passes in the attribute name `HeapSize.UpperBound` through `MBeanServer.getAttribute(ObjectName, AttributeName)` call. This would result in a call to `JVMStatsImpl.getHeapSize()` or `JVMStatsImpl.getStatistic("HeapSize")` and a further call to `BoundedRangeStatistic.getUpperBound()`. These calls are performed by the `DynamicMBean` implementation that gets generated on registration through its `getAttribute()` method.
In order for the above pattern to work, `Stats` implementations should guarantee that all names returned by the call to `getStatisticNames()` are indeed the only statistic attributes defined in the implementation.

## Package Specification

The registration utility and its related classes are defined in the `com.sun.enterprise.admin.monitor.stats.spi` and `com.sun.enterprise.admin.monitor.stats.spi.util` packages. The following classes are part of these packages.

- `MonitoringRegistrationHelper` class - implementation of the `MonitoringRegistration` interface.
- `ManagedResourceIntrospector` class - a helper utility that is used by `MonitoringRegistrationHelper` to introspect a `Stats` implementation and derive a JMX compliant `MBeanInfo` object that composes attributes, operations and operational parameters of the `Stats` object.
- `GeneratedMonitoringMBeanImpl` class - is a template class used to apply the introspection in the form of a `DynamicMBean` implementation. An instance of this class is created for each component registration and registered with the `MBeanServer.` Clients can now use standard JMX API calls such as `MBeanServer.invoke()` and `MBeanServer.getAttribute()` passing in the `ObjectName` of this MBean and the associated parameters to access JSR 77 compliant statistics objects.
- `MonitoringMBeansFactory` class - produces the above generated MBean and returns it to the `MonitoringRegistrationHelper`.
- `MonitoringRegistrationException` class - reports exceptions that may occur during registration or unregistration process.

## Related Documentation

@see com.sun.enterprise.admin.monitor.registry package