javax.management.modelmbean
Class RequiredModelMBean

java.lang.Object
  |
  +--javax.management.modelmbean.RequiredModelMBean

public class RequiredModelMBean

extends java.lang.Object

implements ModelMBean

This class is the implementation of a ModelMBean. An appropriate implementation of a ModelMBean must be shipped with every JMX Agent and the class must be named RequiredModelMBean.

Java resources wishing to be manageable instatiate the RequiredModelMBean using the MBeanServer's createMBean method. The resource then sets the MBeanInfo and Descriptors for the RequiredModelMBean instance. The attributes and operations exposed via the ModelMBeanInfo for the ModelMBean are accessible from Mbeans, connectors/adapters like other MBeans. Through the Descriptors, values and methods in the managed application can be defined and mapped to attributes and operations of the ModelMBean. This mapping can be defined in an XML formatted file or dynamically and programmatically at runtime.

Every RequiredModelMBean which is instantiated in the MBeanServer becomes manageable: its attributes and operations become remotely accessible through the connectors/adaptors connected to that MBeanServer. A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. By instantiating a RequiredModelMBean, resources are guaranteed that the MBean is valid. MBeanException and RuntimeOperatiosException must be thrown on every public method. This allows for wrappering exceptions from distributed communications (RMI, EJB, etc.).

Version:

1.10

Author:

Max Parlione, Ken Barron, Massimo Tarquini

Constructor Summary

RequiredModelMBean()
Constructs an RequiredModelMBean with an empty ModelMBeanInfo.

RequiredModelMBean(ModelMBeanInfo mbi)
Constructs a RequiredModelMBean object using ModelMBeanInfo passed in.

Method Summary

void	addAttributeChangeNotificationListener(NotificationListener inlistener, java.lang.String inAttributeName, java.lang.Object inhandback) Registers an object which implements the NotificationListener interface as a listener.
void	addNotificationListener(NotificationListener inlistener, NotificationFilter infilter, java.lang.Object inhandback) Registers an object which implements the NotificationListener interface as a listener.
java.lang.Object	getAttribute(java.lang.String attrName) Returns the value of a specific attribute defined for this ModelMBean.
AttributeList	getAttributes(java.lang.String[] attrNames) Returns the values of several attributes in the ModelMBean.
MBeanInfo	getMBeanInfo() Returns the attributes, operations, and notifications that this RequiredModelMBean exposes for management.
MBeanNotificationInfo[]	getNotificationInfo() Returns the array of Notifications always generated by the RequiredModelMBean.
java.lang.Object	invoke(java.lang.String opName, java.lang.Object[] opArgs, java.lang.String[] sig) Invokes a method on or through a RequiredModelMBean and returns the result of the method execution.
void	load() The load method instantiates this RequiredModelMBean instance with the data found for the RequiredModelMBean in the persistent store.
void	removeAttributeChangeNotificationListener(NotificationListener inlistener, java.lang.String inAttributeName) Removes a listener for attributeChangeNotifications from the RequiredModelMBean.
void	removeNotificationListener(NotificationListener inlistener) Removes a listener for Notifications from the RequiredModelMBean.
void	sendAttributeChangeNotification(Attribute inOldVal, Attribute inNewVal) Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the RequiredModelMBean.
void	sendAttributeChangeNotification(AttributeChangeNotification ntfyObj) Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.
void	sendNotification(Notification ntfyObj) Sends a Notification which is passed in to the registered Notification listeners on the RequiredModelMBean.
void	sendNotification(java.lang.String ntfyText) Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.
void	setAttribute(Attribute attribute) Sets the value of a specific attribute of a named ModelMBean.
AttributeList	setAttributes(AttributeList attributes) Sets the values of an array of attributes of this ModelMBean.
void	setManagedResource(java.lang.Object mr, java.lang.String mr_type) Sets the instance handle of the object against which to execute all methods in this RequiredModelMBean management interface (ModelMBeanInfo and Descriptors).
void	setModelMBeanInfo(ModelMBeanInfo mbi) Initializes a RequiredModelMBean object using ModelMBeanInfo passed in.
void	store() Captures the current state of this RequiredModelMBean instance and writes it out to the persistent store.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

RequiredModelMBean

public RequiredModelMBean()
                   throws MBeanException,
                          RuntimeOperationsException

Constructs an RequiredModelMBean with an empty ModelMBeanInfo. After the RequiredModelMBean's MBeanInfo and Descriptors are customized, the RequiredModelMBean should be registered with the MBeanServer.

Throws:

MBeanException - The constructor of the object has thrown an exception.

RuntimeOperationsException - Wraps an IllegalArgumentException.

RequiredModelMBean

public RequiredModelMBean(ModelMBeanInfo mbi)
                   throws MBeanException,
                          RuntimeOperationsException

Constructs a RequiredModelMBean object using ModelMBeanInfo passed in. The RequiredModelMBean must be instantiated, but not registered with the MBeanServer. After the RequiredModelMBean's MBeanInfo and Descriptors are customized, the RequiredModelMBean should be registered with the MBeanServer.

Parameters:

mbi - The ModelMBeanInfo object to be used by the RequiredModelMBean.

Throws:

MBeanException - The constructor of the object has thrown an exception.

RuntimeOperationsException - Wraps an IllegalArgumentException: The MBeanInfo passed in parameter is null or invalid.

Method Detail

setModelMBeanInfo

public void setModelMBeanInfo(ModelMBeanInfo mbi)
                       throws MBeanException,
                              RuntimeOperationsException

Initializes a RequiredModelMBean object using ModelMBeanInfo passed in. The RequiredModelMBean should be instantiated, but not registered with the MBeanServer. After the RequiredModelMBean's MBeanInfo and Descriptors are customized, the RequiredModelMBean should be registered with the MBeanServer.

Specified by:

setModelMBeanInfo in interface ModelMBean

Parameters:

mbi - The MBeanInfo object to be used by the RequiredModelMBean.

Throws:

MBeanException - The constructor of the MBeanInfo has return null or thrown an exception.

RuntimeOperationsException - Wraps an IllegalArgumentException: The MBeanInfo passed in parameter is null or invalid.

setManagedResource

public void setManagedResource(java.lang.Object mr,
                               java.lang.String mr_type)
                        throws MBeanException,
                               RuntimeOperationsException,
                               InstanceNotFoundException,
                               InvalidTargetObjectTypeException

Sets the instance handle of the object against which to execute all methods in this RequiredModelMBean management interface (ModelMBeanInfo and Descriptors). This setting can be overridden by setting the 'targetObject' field of the ModelMBeanOperationInfo's descriptor.

Specified by:

setManagedResource in interface ModelMBean

Parameters:

mr - Object that is the managed resource

mr_type - The type of reference for the managed resource. Can be: ObjectReference, Handle, IOR, EJBHandle, RMIReference. If the MBeanServer cannot process the mr_type passed in, an exception will be thrown.

Throws:

MBeanException - The initializer of the object has thrown an exception.

RuntimeOperationsException - Wraps an IllegalArgumentException: The managed resource or managed resoure type passed in parameter is null or invalid.

InstanceNotFoundException - The managed resource object could not be found

InvalidTargetObjectType - The managed resource type cannot be processed by the RequiredModelMBean or JMX Agent.

load

public void load()
          throws MBeanException,
                 RuntimeOperationsException,
                 InstanceNotFoundException

The load method instantiates this RequiredModelMBean instance with the data found for the RequiredModelMBean in the persistent store. The data loaded will include a serialized ModelMBeanInfo. If there are object references in the descriptors which are not serializeable, then persistence will fail.

For the reference implementation, it looks for a file with the same name as the RequiredModelMBean. It checks the RequiredModelMBean MBeanDescriptor for a 'PersistLocation' field which would contain the directory where the RequiredModelMBean's whould be stored. It also looks for a 'PersistName' field which contains the file name into which the ModelBMean should be persisted. If these fields are not provided, then persistence is not implemented. This method should be called during construction or inialization of this instance, and before the RequiredModelMBean is registered with the MBeanServer.

Throws:

MBeanException - Wraps another exception or persistence is not supported.

RuntimeOperationsException - Wraps exceptions from the persistence mechanism.

InstanceNotFoundException - Could not find or load this MBean from persistent storage.

store

public void store()
           throws MBeanException,
                  RuntimeOperationsException,
                  InstanceNotFoundException

Captures the current state of this RequiredModelMBean instance and writes it out to the persistent store. The state stored could include attribute and operation values. Persistance policy from the attribute descriptor is used to guide execution of this method. If no persistence policy is defined in the descriptor then the persistence policy (if there is one) defined in the MBeanDescriptor is used.

 Store the MBean if 'persistPolicy' field is:
  != "never"
   = "always"
   = "onTimer" and now < 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'

  Do not store the MBean if 'persistPolicy' field is:
    = "never"
    = "onUpdate"
    = "onTimer" && now > 'lastPersistTime' + 'persistPeriod'
 

The data stored will include a serialized ModelMBeanInfo. If there are object references in the descriptors which are not serializeable, then persistence will fail.

For the reference implementation, it looks for a file with the same name as the RequiredModelMBean. It checks the RequiredModelMBean MBeanDescriptor for a 'PersistLocation' field which would contain the directory where the RequiredModelMBean's whould be stored. It also looks for a 'PersistName' field which contains the file name into which the RequiredModelBMean should be persisted. If these fields are not provided, then persistence is not implemented.

Throws:

MBeanException - Wraps another exception or persistence is not supported

RuntimeOperationsException - Wraps exceptions from the persistence mechanism

InstanceNotFoundException - Could not find/access the persistant store

getMBeanInfo

public MBeanInfo getMBeanInfo()

Returns the attributes, operations, and notifications that this RequiredModelMBean exposes for management.

Returns:

An instance of ModelMBeanInfo allowing retrieval all attributes, operations, and Notifications of this MBean.

invoke

public java.lang.Object invoke(java.lang.String opName,
                               java.lang.Object[] opArgs,
                               java.lang.String[] sig)
                        throws MBeanException,
                               ReflectionException,
                               RuntimeOperationsException

Invokes a method on or through a RequiredModelMBean and returns the result of the method execution.

The last value returned by an operation may be cached in the operation's descriptor which is in the ModelMBeanOperationInfo's descriptor. The valid value will be in the 'value' field if there is one.

 If the 'currencyTimeLimit' field in the descriptor is:
  <0 Then the value is always cached and is never stale.  Hence the first 
     time the method will be invoked, afterwhich the cache is always used.
  =0 Then the value is always stale.  The cache is never used, so the 
     method is invoked.
     The 'value' field is returned.
     The 'lastUpdatedTimeStamp' field is not checked.
  >0 Represents the number of seconds that the 'value' field is valid.
     The 'value' field is no longer valid (the cache is stale) when 
     'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now.
     When 'value' is valid, 'valid' is returned.
     When 'value' is no longer valid then null is returned and 'value' 
     and 'lastUpdatedTimeStamp' fields are cleared.
 
 Note: For this implementation: if the cached value is not a String, then 
 the object must have a constructor which accepts a string in the same 
 format as the objects toString() method creates.
 

Parameters:

operationName - The name of the method to be invoked. The name can be the fully qualified method name including the classname, or just the method name if the classname is defined in the 'class' field of the operation descriptor.

params - An array containing the parameters to be set when the operation is invoked

signature - An array containing the signature of the operation. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the operatoion was invoked.

Returns:

The object returned by the method, which represents the result of invoking the method on the specified managed resource.

Throws:

MBeanException - Wraps an exception thrown by the MBean's invoked method.

ReflectionException - Wraps an java.lang.Exception thrown while trying to invoke the method.

getAttribute

public java.lang.Object getAttribute(java.lang.String attrName)
                              throws AttributeNotFoundException,
                                     MBeanException,
                                     ReflectionException,
                                     RuntimeOperationsException

Returns the value of a specific attribute defined for this ModelMBean.

 The last value returned by an attribute may be cached in the attribute's 
 descriptor.
 The valid value will be in the 'value' field if there is one.
 If the 'currencyTimeLimit' field in the descriptor is:
 <0 Then the value is always cached and is never stale.  Null is returned.
     The 'value' and 'lastUpdatedTimeStamp' fields are cleared.
 =0 Then the value is always stale.  The cache is never used, so the 
    'value' field is returned.
     The 'lastUpdatedTimeStamp' field is not checked.
 >0 Represents the number of seconds that the 'value' field is valid.
     The 'value' field is no longer valid (the cache is stale) when 
     'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now.
     When 'value' is valid, 'valid' is returned.
     When 'value' is no longer valid then null is returned and 'value' and
     'lastUpdatedTimeStamp' fields are cleared.
 

If there is no valid cached value then the 'getMethod' field in the attributes descriptor is analyzed. If 'getMethod' contains the name of a valid operation descriptor, then the method described by the operation descriptor is executed. The response from the method is returned as the value of the attribute. If the operation fails or the response value is not of the same type as the attribute, an exception will be thrown. If currencyTimeLimit is > 0, then the value of the attribute is cached in the attribute descriptor's 'value' field and the 'lastUpdatedTimeStamp' field is set to the current time stamp.

Parameters:

attributeName - A String specifying the name of the attribute to be retrieved. It must match the name of a ModelMBeanAttributeInfo.

Returns:

The value of the retrieved attribute from the descriptor 'value' field or from the invokation of the operation in the 'getMethod' field of the descriptor.

Throws:

AttributeNotFoundException - The specified attribute is not accessible in the MBean.

MBeanException - Wraps an exception thrown by the MBean's getter.

ReflectionException - Wraps an java.lang.Exception thrown while trying to invoke the setter.

RuntimeOperationsException - Wraps an IllegalArgumentException: The object name in parameter is null or the attribute in parameter is null.

getAttributes

public AttributeList getAttributes(java.lang.String[] attrNames)
                            throws RuntimeOperationsException

Returns the values of several attributes in the ModelMBean. Executes a getAttribute for each attribute name in the attrNames array passed in.

Parameters:

attributes - A String array of names of the attributes to be retrieved.

Returns:

The array of the retrieved attributes.

Throws:

RuntimeOperationsException - Wraps an IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException

Sets the value of a specific attribute of a named ModelMBean. If the 'setMethod' field of the attribute's descriptor contains the name of a valid operation descriptor, then the method described by the operation descriptor is executed. The response from the method is set as the value of the attribute in the descriptor. If the operation fails or the response value is not of the same type as the attribute, an exception will be thrown.

If currencyTimeLimit is > 0, then the new value for the attribute is cached in the attribute descriptor's 'value' field and the 'lastUpdatedTimeStamp' field is set to the current time stamp.
If the persist field of the attribute's descriptor is not null then Persistance policy from the attribute descriptor is used to guide storing the attribute in a persistenant store.

 Store the MBean if 'persistPolicy' field is:
   != "never"
   = "always"
   = "onUpdate"
   = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'
 
 Do not store the MBean if 'persistPolicy' field is:
   = "never"
   = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now < 'lastPersistTime' + 'persistPeriod'
  

Parameters:

attribute - The Attribute instance containing the name of the attribute to be set and the value it is to be set to.

Throws:

AttributeNotFoundException - The specified attribute is not accessible in the MBean.

InvalidAttributeValueException - The specified value for the attribute is not valid.

setAttributes

public AttributeList setAttributes(AttributeList attributes)
                            throws RuntimeOperationsException

Sets the values of an array of attributes of this ModelMBean. Executes the setAttribute() method for each attribute in the list.

Parameters:

attributes - A list of attributes: The identification of the attributes to be set and the values they are to be set to.

Returns:

The array of attributes that were set, with their new values in Attribute instances.

Throws:

RuntimeOperationsException - Wraps an IllegalArgumentException: The object name in parameter is null or attributes in parameter is null.

addNotificationListener

public void addNotificationListener(NotificationListener inlistener,
                                    NotificationFilter infilter,
                                    java.lang.Object inhandback)
                             throws java.lang.IllegalArgumentException

Registers an object which implements the NotificationListener interface as a listener. This object's 'handleNotification()' method will be invoked when any notification is issued through or by the ModelMBean. This does not include attributeChangeNotifications. They must be registered for independently.

Parameters:

listener - The listener object which will handles notifications emitted by the registered MBean.

filter - The filter object. If null, no filtering will be performed before handling notifications.

handback - The context to be sent to the listener with the notification when a notification is emitted.

Throws:

java.lang.IllegalArgumentException - - The listener could not be added.

removeNotificationListener

public void removeNotificationListener(NotificationListener inlistener)
                                throws ListenerNotFoundException

Removes a listener for Notifications from the RequiredModelMBean.

Parameters:

listener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.

Throws:

ListenerNotFoundException - The couple (listener,handback) is not registered in the MBean. The exception message contains either "listener", "handback" or the object name depending on which object cannot be found.

sendNotification

public void sendNotification(Notification ntfyObj)
                      throws MBeanException,
                             RuntimeOperationsException

Sends a Notification which is passed in to the registered Notification listeners on the RequiredModelMBean.

Parameters:

notification - The notification which is to be passed to the 'handleNotification' method of the listener object.

Returns:

void

Throws:

MBeanException - for implementation exceptions

RuntimeOperationsException - to wrapper IllegalArugementExceptions

sendNotification

public void sendNotification(java.lang.String ntfyText)
                      throws MBeanException,
                             RuntimeOperationsException

Sends a Notification which contains the text string that is passed in to the registered Notification listeners on the ModelMBean.

Parameters:

ntfyText - The text which is to be passed in the Notification to the 'handleNotification' method of the listener object. the constructed Notification will be: type "jmx.modelmbean.general" source this ModelMBean instance sequence 1

Throws:

MBeanException - for implementation exceptions

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()

Returns the array of Notifications always generated by the RequiredModelMBean. This will include those specified by the application plus the jmx.modelmbean.generic and jmx.attribute.change notifications.

Returns:

MBeanNotificationInfo[]

addAttributeChangeNotificationListener

public void addAttributeChangeNotificationListener(NotificationListener inlistener,
                                                   java.lang.String inAttributeName,
                                                   java.lang.Object inhandback)
                                            throws MBeanException,
                                                   RuntimeOperationsException,
                                                   java.lang.IllegalArgumentException

Registers an object which implements the NotificationListener interface as a listener. This object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through or by the ModelMBean. This does not include other Notifications. They must be registered for independently. An AttributeChangeNotification will be generated for this attributeName.

Parameters:

listener - The listener object which will handles notifications emitted by the registered MBean.

attributeName - The name of the ModelMBean attribute for which to receive change notifications. If null, then all attribute changes will cause an attributeChangeNotification to be issued.

handback - The context to be sent to the listener with the notification when a notification is emitted.

Throws:

java.lang.IllegalArgumentException - The MBean name doesn't correspond to a registered MBean.

removeAttributeChangeNotificationListener

public void removeAttributeChangeNotificationListener(NotificationListener inlistener,
                                                      java.lang.String inAttributeName)
                                               throws MBeanException,
                                                      RuntimeOperationsException,
                                                      ListenerNotFoundException

Removes a listener for attributeChangeNotifications from the RequiredModelMBean.

Parameters:

listener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.

attributeName - The attribute for which the listener no longer wants to receive attributeChangeNotifications.

Throws:

ListenerNotFoundException - The couple (listener,handback) is not registered in the MBean. The exception message contains either "listener", "handback" or the object name depending on which object cannot be found.

sendAttributeChangeNotification

public void sendAttributeChangeNotification(AttributeChangeNotification ntfyObj)
                                     throws MBeanException,
                                            RuntimeOperationsException

Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.

Parameters:

notification - The notification which is to be passed to the 'handleNotification' method of the listener object.

Throws:

MBeanException -

RuntimeOperationsException -

sendAttributeChangeNotification

public void sendAttributeChangeNotification(Attribute inOldVal,
                                            Attribute inNewVal)
                                     throws MBeanException,
                                            RuntimeOperationsException

Sends an attributeChangeNotification which contains the old value and new value for the attribute to the registered AttributeChangeNotification listeners on the RequiredModelMBean.

Parameters:

oldValue - The origional value for the Attribute

newValue - The current value for the Attribute The constructed attributeChangeNotification will be: type "jmx.attribute.change" source this RequiredModelMBean instance sequence 1 attributeName oldValue.getName() attributeType oldValue's class attributeOldValue oldValue.getValue() attributeNewValue newValue.getValue()

Throws:

MBeanException - to wrapper implementation exceptions

RuntimeOperationsException - to wrapper IllegalArgumentExceptions