XMOJO 5 API Docs

javax.management.modelmbean
Class RequiredModelMBean

java.lang.Object
  |
  +--javax.management.modelmbean.RequiredModelMBean
All Implemented Interfaces:
DynamicMBean, ModelMBean, ModelMBeanNotificationBroadcaster, NotificationBroadcaster, PersistentMBean

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


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)
          Register3s an object which implements the NotificationListener interface as a listener for AttributeChangeNotifications.
 void addNotificationListener(NotificationListener listener, NotificationFilter filter, java.lang.Object handback)
          Enables a couple (listener,handback) for a registered MBean to be added.
 java.lang.Object getAttribute(java.lang.String attribute)
          Gets the value of a specific attribute of this MBean.
 AttributeList getAttributes(java.lang.String[] attributes)
          Enables the values of several attributes of this MBean.
 MBeanInfo getMBeanInfo()
          This method discovers the attributes and operations this MBean exposes for management.
 MBeanNotificationInfo[] getNotificationInfo()
          Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent.
 java.lang.Object invoke(java.lang.String actionName, java.lang.Object[] params, java.lang.String[] signature)
          Invokes an action on this MBean.
 void load()
          Locates the MBean in a persistent store and primes this instance of the MBean with the stored values.Any currently set values are overwritten.
 void removeAttributeChangeNotificationListener(NotificationListener inlistener, java.lang.String inAttributeName)
          Removes a listener for attributeChangeNotifications from the MBean.
 void removeNotificationListener(NotificationListener listener)
          Enables a listener for an MBean to be removed.
 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 ModelMBean.
 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 ModelMBean as a jmx.modelmbean.general notification.
 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 this MBean.
 AttributeList setAttributes(AttributeList attributes)
          Sets the values of several attributes of this MBean.
 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()
          Writes the MBean in a persistent store.Should only be called by the RequiredModelMBean class to store itself according to persistence policy for the MBean.When used,it may be called with every setAttribute or on a periodic basis.
 
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

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. Current Implementation of RequiredModelMBean supports only ObjectReference.
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.

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.

load

public void load()
          throws MBeanException,
                 RuntimeOperationsException,
                 InstanceNotFoundException
Locates the MBean in a persistent store and primes this instance of the MBean with the stored values.Any currently set values are overwritten.
Specified by:
load in interface PersistentMBean
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
Writes the MBean in a persistent store.Should only be called by the RequiredModelMBean class to store itself according to persistence policy for the MBean.When used,it may be called with every setAttribute or on a periodic basis. Currently the store supports only the flat file persistence.
Specified by:
store in interface PersistentMBean
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

getMBeanInfo

public MBeanInfo getMBeanInfo()
This method discovers the attributes and operations this MBean exposes for management.
Specified by:
getMBeanInfo in interface DynamicMBean
Returns:
An instance of MBeanInfo allowing to retrieve all attributes and operations of this MBean.

getAttribute

public java.lang.Object getAttribute(java.lang.String attribute)
                              throws AttributeNotFoundException,
                                     MBeanException,
                                     ReflectionException
Gets the value of a specific attribute of this MBean.
Specified by:
getAttribute in interface DynamicMBean
Parameters:
attribute - A String specifying the name of the attribute to be retrieved.
Returns:
The value of the retrieved attribute.

getAttributes

public AttributeList getAttributes(java.lang.String[] attributes)
Enables the values of several attributes of this MBean.
Specified by:
getAttributes in interface DynamicMBean
Parameters:
attributes - A list of attributes to be retrieved.
Returns:
The value of the retrieved attributes as attributeList.

invoke

public java.lang.Object invoke(java.lang.String actionName,
                               java.lang.Object[] params,
                               java.lang.String[] signature)
                        throws MBeanException,
                               ReflectionException
Invokes an action on this MBean.
Specified by:
invoke in interface DynamicMBean
Parameters:
actionName - The name of the action to be invoked.
params - An array containing the parameters to be set when the action is invoked
signature - An array containing the signature of the action. The class objects will be loaded using the same class loader as the one used for loading the MBean on which the action was invoked.
Returns:
The object returned by the action, which represents the result of invoking the action on the specified MBean.
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.

setAttribute

public void setAttribute(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
Sets the value of a specific attribute of this MBean.
Specified by:
setAttribute in interface DynamicMBean
Parameters:
attribute - The identification 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.
MBeanException - - Wraps an exception thrown by the MBean's setter.
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.

setAttributes

public AttributeList setAttributes(AttributeList attributes)
Sets the values of several attributes of this MBean.
Specified by:
setAttributes in interface DynamicMBean
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 list of attributes that were set, with their new values.

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    java.lang.Object handback)
                             throws java.lang.IllegalArgumentException
Enables a couple (listener,handback) for a registered MBean to be added. Specified by : addNotificationListener in interface NotificationBroadcaster
Specified by:
addNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener object which will handles notifications emitted by the registered MBean.
filter - The filter object. If not specified, no filtering will be performed before handling notifications.
handback - The context to be sent to the listener when a notification is emitted.
Throws:
java.lang.IllegalArgumentException - Listener parameter is null.

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException
Enables a listener for an MBean to be removed. All couple (listener, handback) are removed. Specified by: removeNotificationListener in interface NotificationBroadcaster
Specified by:
removeNotificationListener in interface NotificationBroadcaster
Parameters:
listener - The listener object which will handles notifications emitted by the registered MBean.
Throws:
ListenerNotFoundException - The listener is not registered in the MBean.

getNotificationInfo

public MBeanNotificationInfo[] getNotificationInfo()
Returns a NotificationInfo object containing the name of the Java class of the notification and the notification types sent. This getNotificationInfo method will inturn call the original instrumentation object's getNotificationInfo method if the object is an instanceof NotificationBroadcaster.
Specified by:
getNotificationInfo in interface NotificationBroadcaster
Following copied from interface: javax.management.NotificationBroadcaster
Returns:
This returns a array of MBeanNotificationInfo which contains the notification information

addAttributeChangeNotificationListener

public void addAttributeChangeNotificationListener(NotificationListener inlistener,
                                                   java.lang.String inAttributeName,
                                                   java.lang.Object inhandback)
                                            throws MBeanException,
                                                   RuntimeOperationsException,
                                                   java.lang.IllegalArgumentException
Register3s an object which implements the NotificationListener interface as a listener for AttributeChangeNotifications. This object's 'handleNotification()' method will be invoked when any attributeChangeNotification is issued through or by the MBean. This does not include other Notifications. They must be registered for independently. An AttributeChangeNotification will be generated for this attributeName.
Specified by:
addAttributeChangeNotificationListener in interface ModelMBeanNotificationBroadcaster
Parameters:
inlistener - The listener object which will handles notifications emitted by the registered MBean.
inAttributeName - The name of the MBean attribute for which to receive change notifications. If null, then all attribute changes will cause an attributeChangeNotification to be issued.
inhandback - The context to be sent to the listener with the notification when a notification is emitted.
Throws:
MBeanException - Wraps an exception thrown by this method
RuntimeOperationsException - To wrap the Run time Exceptions
java.lang.IllegalArgumentException - Listener is null or attributeName is null.

removeAttributeChangeNotificationListener

public void removeAttributeChangeNotificationListener(NotificationListener inlistener,
                                                      java.lang.String inAttributeName)
                                               throws MBeanException,
                                                      RuntimeOperationsException,
                                                      ListenerNotFoundException
Removes a listener for attributeChangeNotifications from the MBean.
Specified by:
removeAttributeChangeNotificationListener in interface ModelMBeanNotificationBroadcaster
Parameters:
inlistener - The listener name which was handling notifications emitted by the registered MBean. This method will remove all information related to this listener.
inAttributeName - The attribute for which the listener no longer wants to receive attributeChangeNotifications.
Throws:
MBeanException - Wraps an exception thrown while removing AttributeChangeNotificationListener
RuntimeOperationsException - Wraps the exceptions thrown in the run time
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 ModelMBean as a jmx.modelmbean.general notification.
Specified by:
sendNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
ntfyObj - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - The initializer of the object has thrown an exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification object passed in parameter is null or invalid.

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.
Specified by:
sendNotification in interface ModelMBeanNotificationBroadcaster
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 - The initializer of the object has thrown an exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification text string passed in parameter is null or invalid.

sendAttributeChangeNotification

public void sendAttributeChangeNotification(AttributeChangeNotification ntfyObj)
                                     throws MBeanException,
                                            RuntimeOperationsException
Sends an attributeChangeNotification which is passed in to the registered attributeChangeNotification listeners on the ModelMBean.
Specified by:
sendAttributeChangeNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
ntfyObj - The notification which is to be passed to the 'handleNotification' method of the listener object.
Throws:
MBeanException - The initializer of the object has thrown an exception.
RuntimeOperationsException - Wraps an IllegalArgumentException: The Notification object passed in parameter is null or invalid.

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 ModelMBean.
Specified by:
sendAttributeChangeNotification in interface ModelMBeanNotificationBroadcaster
Parameters:
inOldVal - The origional value for the Attribute
inNewVal - The current value for the Attribute

 The constructed attributeChangeNotification will be:
 type        "jmx.attribute.change"
 source      this ModelMBean 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.

XMOJO 5 API Docs

Copyright ©2003 XMOJO.org. All Rights Reserved.