javax.management.modelmbean
类 RequiredModelMBean

java.lang.Object
  javax.management.modelmbean.RequiredModelMBean

所有已实现的接口：

DynamicMBean, MBeanRegistration, ModelMBean, ModelMBeanNotificationBroadcaster, NotificationBroadcaster, NotificationEmitter, PersistentMBean

public class RequiredModelMBean
     

      extends 
      Object
     
     

      implements 
      ModelMBean, 
      MBeanRegistration, 
      NotificationEmitter
     

此类是 ModelMBean 的实现。每个发行的 JMX Agent 必须带有 ModelMBean 的适当实现，且该类必须是指定的 RequiredModelMBean。

Java 资源使用 MBeanServer 的 createMBean 方法来实例化 RequiredModelMBean，希望以这种方式获得可管理性。然后该资源设置 RequiredModelMBean 实例的 MBeanInfo 和 Descriptor。通过 ModelMBean 的 ModelMBeanInfo 公开的属性和操作像其他 MBean 一样可以从 MBean、连接器/适配器进行访问。通过使用 Descriptor，可以定义托管应用程序中的值和方法，并可以将它们映射到 ModelMBean 的属性和操作。此映射可以在 XML 格式的文件中定义，也可以以编程方式在运行时动态定义。

MBeanServer 中实例化的每个 RequiredModelMBean 都将是可管理的：
通过连接到该 MBeanServer 的连接器/适配器，可以远程访问其属性和操作。

Java 对象不能在 MBeanServer 中进行注册，除非它是 JMX 兼容的 MBean。通过实例化 RequiredModelMBean，资源得到了保证，因此 MBean 是有效的。每个公共方法必须抛出 MBeanException 和 RuntimeOperationsException，允许使用这些异常包装来自分布式通信（RMI、EJB 等）的异常。

从以下版本开始：

1.5

RequiredModelMBean

public RequiredModelMBean()
                   throws MBeanException,
                          RuntimeOperationsException

构造带有空 ModelMBeanInfo 的 RequiredModelMBean。

可以使用 setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo) 方法来自定义 RequiredModelMBean 的 MBeanInfo 和 Descriptor。自定义 RequiredModelMBean 的 MBeanInfo 和 Descriptor 之后，可以在 MBeanServer 中注册 RequiredModelMBean。

抛出：

MBeanException - 包装了一个分布式通信异常。

RuntimeOperationsException - 在对象的构造期间包装了一个 RuntimeException。

RequiredModelMBean

public RequiredModelMBean(ModelMBeanInfo mbi)
                   throws MBeanException,
                          RuntimeOperationsException

使用传入的 ModelMBeanInfo 构造 RequiredModelMBean 对象。只要尚未在 MBeanServer 中注册 RequiredModelMBean，就可以使用 setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo) 方法自定义 RequiredModelMBean 的 MBeanInfo 和 Descriptor。自定义 RequiredModelMBean 的 MBeanInfo 和 Descriptor 之后，可以向 MBeanServer 注册 RequiredModelMBean。

参数：

mbi - RequiredModelMBean 要使用的 ModelMBeanInfo 对象。给定的 ModelMBeanInfo 根据 setModelMBeanInfo(javax.management.modelmbean.ModelMBeanInfo) 指定的方式进行复制和修改

抛出：

MBeanException - 包装了一个分布式通信异常。

RuntimeOperationsException - 包装了一个 {link java.lang.IllegalArgumentException}：传入参数中的 MBeanInfo 为 null。

setModelMBeanInfo

public void setModelMBeanInfo(ModelMBeanInfo mbi)
                       throws MBeanException,
                              RuntimeOperationsException

使用传入的 ModelMBeanInfo 实例化 ModelMBean 对象。此方法能够设置 ModelMBean 上的自定义 ModelMBeanInfo（只要它尚未在 MBeanServer 中注册）。
一旦自定义 ModelMBean 的 ModelMBeanInfo 并在 ModelMBean 上设置它（带有 Descriptor）之后，就可以在 MBeanServer 中注册 ModelMBean。

如果目前已经注册了 ModelMBean，则此方法抛出包装 IllegalStateException 的 RuntimeOperationsException

如果给定的 inModelMBeanInfo 不包含任何 GENERIC 或 ATTRIBUTE_CHANGE 通知的 ModelMBeanNotificationInfo，则 RequiredModelMBean 将为这些缺少的通知提供它自己的默认 ModelMBeanNotificationInfo。

指定者：

接口 ModelMBean 中的 setModelMBeanInfo

参数：

mbi - ModelMBean 要使用的 ModelMBeanInfo 对象。

抛出：

MBeanException - 包装了一个分布式通信异常。

RuntimeOperationsException -

• 如果传入参数的 MBeanInfo 为 null，则包装一个 IllegalArgumentException。
• 如果目前已经在 MBeanServer 中注册了 ModelMBean，则包装一个 IllegalStateException。

setManagedResource

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

设置对象的实例句柄，我们将根据该句柄执行此 ModelMBean 管理接口（MBeanInfo 和 Descripto）中的所有方法。

指定者：

接口 ModelMBean 中的 setManagedResource

参数：

mr - 作为托管资源的对象

mr_type - 托管资源的引用类型。
该参数可以是："ObjectReference"、"Handle"、"IOR"、"EJBHandle" 或 "RMIReference"。
在此实现中仅支持 "ObjectReference"。

抛出：

MBeanException - 如果对象初始化程序已抛出异常。

InstanceNotFoundException - 如果找不到托管资源对象

InvalidTargetObjectTypeException - 托管资源对象应为 "ObjectReference"。

RuntimeOperationsException - 如果设置资源时包装一个 RuntimeException。

load

public void load()
          throws MBeanException,
                 RuntimeOperationsException,
                 InstanceNotFoundException

使用在持久存储中找到的 MBean 的数据实例化此 MBean。加载的数据可以包括属性和操作值。

此方法的调用应在此实例的构造或实例化期间，且在向 MBeanServer 注册该 MBean 之前。

如果此类的实例不支持持久存储，则抛出包装 ServiceNotFoundException 的 MBeanException。

指定者：

接口 PersistentMBean 中的 load

抛出：

MBeanException - 包装另一个异常，或者不支持持久存储

RuntimeOperationsException - 包装来自持久机制的异常

InstanceNotFoundException - 不能从持久存储找到或加载此 MBean

store

public void store()
           throws MBeanException,
                  RuntimeOperationsException,
                  InstanceNotFoundException

捕获此 MBean 实例的当前状态，并将它写出到持久存储中。存储的状态可以包括属性和操作值。

如果此类的实例不支持持久存储，则抛出包装 ServiceNotFoundException 的 MBeanException。

来自 MBean 和属性描述符的持久策略用于指导此方法的执行。如果 'persistPolicy' 是以下值，则应存储 MBean：

  != "never"
   = "always"
   = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
   = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'
   = "onUnregister"
 

如果 'persistPolicy' 字段是以下值，则不存储 MBean：

    = "never"
    = "onUpdate"
    = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'
 

指定者：

接口 PersistentMBean 中的 store

抛出：

MBeanException - 包装另一个异常，或者如果不支持持久存储

RuntimeOperationsException - 包装来自持久机制的异常

InstanceNotFoundException - 不能找到/访问持久存储

getMBeanInfo

public MBeanInfo getMBeanInfo()

返回此 RequiredModelMBean 公开的属性、操作、构造方法和通知是为了便于管理。

指定者：

接口 DynamicMBean 中的 getMBeanInfo

返回：

允许检索此 MBean 的所有属性、操作和 Notification 的 ModelMBeanInfo 的实例。

invoke

public Object invoke(String opName,
                     Object[] opArgs,
                     String[] sig)
              throws MBeanException,
                     ReflectionException

调用 RequiredModelMBean 上的（或通过它调用）某个方法，并返回方法的执行结果。

如果要调用的给定方法连同提供的签名与 RequiredModelMbean 可访问方法中的某个方法匹配，则将调用此匹配的方法。否则将在托管资源上尝试调用给定的方法。

该操作返回的最后一个值可以在该操作的描述符中进行缓存，此描述符位于 ModelMBeanOperationInfo 的描述符中。有效值将位于 'value' 字段中（如果有）。如果描述符中的 'currencyTimeLimit' 字段为：

• <0 则不缓存该值，且该值永远无效。调用 operation 方法。清除 'value' 和 'lastUpdatedTimeStamp' 字段。
• =0 则总是缓存该值，且该值总有效。返回 'value' 字段。如果没有 'value' 字段，则调用属性的 operation 方法。将 'lastUpdatedTimeStamp' 字段和 `value' 字段设置为该操作返回的值和当前时间戳。
• >0 表示 'value' 字段有效的秒数。当 'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now 时，'value' 字段不再有效。
  • 当 'value' 有效时，返回 'value'。
  • 当 'value' 不再有效时，调用 operation 方法。更新 'lastUpdatedTimeStamp' 字段和 `value' 字段。

注：由于与此规范以前版本不一致，因此对于 currencyTimeLimit，建议不要使用负值或零。要指示某个缓存的值永远无效，请忽略 currencyTimeLimit 字段。要指示它总是有效，请为此字段使用一个非常大的值。

指定者：

接口 DynamicMBean 中的 invoke

参数：

opName - 要调用的方法名称。此名称可以是包括类名称的完全限定方法名，如果类名称是在操作描述符的 'class' 字段中定义的，则此名称也可以仅为方法名称。

opArgs - 包含调用操作时要设置的参数的数组

sig - 包含操作签名的数组。用于加载类对象的类加载器与用于加载 MBean（要在其上调用操作）的类加载器相同。

返回：

该方法返回的对象，它表示在指定托管资源上调用方法的结果。

抛出：

MBeanException - 包装以下 Exceptions 之一：

• 由管理对象调用的方法抛出的 Exception。
• ServiceNotFoundException: 为指定操作或托管资源定义的 ModelMBeanOperationInfo 或 descriptor 都不为 null。
• InvalidTargetObjectTypeException: 'targetType' 字段值不为 'objectReference'。

ReflectionException - 包装一个试图调用该方法时抛出的 Exception。

RuntimeOperationsException - 包装一个 IllegalArgumentException。方法名称为 null。

getAttribute

public Object getAttribute(String attrName)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException

返回为此 ModelMBean 定义的指定属性的值。该属性返回的最后一个值可以在该属性的描述符中进行缓存。有效值将位于 'value' 字段中（如果有）。如果描述符中的 'currencyTimeLimit' 字段为：

• <0 则不缓存该值，且该值永远无效。调用该属性的获取方法。清除 'value' 和 'lastUpdatedTimeStamp' 字段。
• =0 则总是缓存该值，且该值总有效。返回 'value' 字段。如果没有 'value' 字段，则调用属性的获取方法。将 'lastUpdatedTimeStamp' 字段和 'value' 字段设置为该属性值和当前时间戳。
• >0 表示 'value' 字段有效的秒数。当 'lastUpdatedTimeStamp' + 'currencyTimeLimit' > Now 时，'value' 字段不再有效。
  • 当 'value' 有效时，返回 'value'。
  • 当 'value' 不再有效时，调用该属性的获取方法。更新 'lastUpdatedTimeStamp' 字段和 `value' 字段。

注：由于与此规范以前版本不一致，因此对于 currencyTimeLimit，建议不要使用负值或零。要指示某个缓存的值永远无效，请忽略 currencyTimeLimit 字段。要指示它总是有效，请为此字段使用一个非常大的值。

如果 'getMethod' 字段包含有效的操作描述符名称，则执行操作描述符所描述的方法。该方法的响应将作为属性值返回。如果操作失败或返回值的类型与属性声明的类型不兼容，则将抛出异常。

如果没有定义 'getMethod' 字段，则返回属性的默认值。如果返回值的类型与属性声明的类型不兼容，则将抛出异常。

属性声明的类型是 MBeanAttributeInfo.getType() 返回的 String。如果以下条件中有一个为真，则值与此类型兼容：

• 值为 null；
• 声明的名称是基本类型名（比如 "int"）且该值是对应包装器类的实例（比如 java.lang.Integer）；
• 值类的名称与声明的名称完全相同；
• 声明的名称可以通过值的类加载器加载，并能生成一个类，且可以将值赋予该类。

在此实现中，对于需要调用 getMethod 的每种情况，因为该方法是通过标准的 "invoke" 方法调用的并因此需要 operationInfo，所以必须为该 getMethod 指定一个操作，以便调用正确工作。

指定者：

接口 DynamicMBean 中的 getAttribute

参数：

attrName - 指定要检索的属性名称的 String。它必须与 ModelMBeanAttributeInfo 名称匹配。

返回：

从描述符 'value' 字段或从描述符的 'getMethod' 字段中的操作调用检索到的属性值。

抛出：

AttributeNotFoundException - 如果指定的属性在 MBean 中不是可访问的。以下情况可能导致 AttributeNotFoundException：

• 未找到 Model MBean 的 ModelMBeanInfo。
• 未找到指定属性名称的 ModelMBeanAttributeInfo。
• ModelMBeanAttributeInfo isReadable 方法返回 'false'。

MBeanException - 包装以下 Exception 之一：

• InvalidAttributeValueException: 从属性的获取方法检索到一个错误值类型，或者描述符中未定义属性的 'getMethod' 字段且默认值不存在。
• ServiceNotFoundException: 没有为属性的获取方法定义 ModelMBeanOperationInfo，或者没有与 ModelMBeanOperationInfo 关联的描述符，或者托管资源为 null。
• InvalidTargetObjectTypeException 'targetType' 字段值不是 'objectReference'。
• 由管理对象的设置方法抛出的 Exception。

ReflectionException - 包装试图调用设置方法时抛出的 Exception。

RuntimeOperationsException - 包装 IllegalArgumentException：参数中的属性名称为 null。

另请参见：

setAttribute(javax.management.Attribute)

getAttributes

public AttributeList getAttributes(String[] attrNames)

返回 ModelMBean 中几个属性的值。执行所传入的 attrNames 数组中每个属性名称的 getAttribute。

指定者：

接口 DynamicMBean 中的 getAttributes

参数：

attrNames - 要检索的属性名称的 String 数组。

返回：

检索到的属性的数组。

抛出：

RuntimeOperationsException - 包装一个 IllegalArgumentException：参数中的对象名称为 null，或参数中的属性为 null。

另请参见：

setAttributes(javax.management.AttributeList)

setAttribute

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

设置指定的 ModelMBean 的指定属性值。如果属性描述符的 'setMethod' 字段包含有效的操作描述符名称，则执行操作描述符所描述的方法。在此实现中，必须正确指定操作描述符，并将它们分配给 modelMBeanInfo，以便 'setMethod' 正确工作。该方法的响应将被设置为描述符中的属性值。

如果 currencyTimeLimit > 0，则在属性描述符的 'value' 字段中缓存属性的新值，并且 'lastUpdatedTimeStamp' 字段设置为当前时间戳。

如果属性描述符的 persist 字段不为 null，则来自属性描述符的 Persistence 策略用于指导在持久存储中存储属性。
如果 'persistPolicy' 字段是以下值，则存储 MBean：

• != "never"
• = "always"
• = "onUpdate"
• = "onTimer" and now > 'lastPersistTime' + 'persistPeriod'
• = "NoMoreOftenThan" and now > 'lastPersistTime' + 'persistPeriod'

如果 'persistPolicy' 字段是以下值，则不存储 MBean：

• = "never"
• = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'
• = "onUnregister"
• = "NoMoreOftenThan" and now < 'lastPersistTime' + 'persistPeriod'

Model MBean 的 ModelMBeanInfo 存储于文件中。

指定者：

接口 DynamicMBean 中的 setAttribute

参数：

attribute - 包含要设置的属性的名称和要设置的值的 Attribute 实例。

抛出：

AttributeNotFoundException - 如果指定的属性在 MBean 中不是可访问的。
以下情况可能导致 AttributeNotFoundException：

• 未找到指定属性的 ModelMBeanAttributeInfo。
• ModelMBeanAttributeInfo 的 isWritable 方法返回 'false'。

InvalidAttributeValueException - 如果没有为指定的属性定义描述符。

MBeanException - 包装以下 Exception 之一：

• 由管理对象的设置方法抛出的 Exception。
• 如果在属性的描述符中定义了一个 setMethod 字段且托管资源为 null，或者没有定义任何 setMethod 字段且该属性没有启用缓存，则抛出 ServiceNotFoundException。注意，如果也没有定义任何 getMethod 字段，则将自动启用缓存。
• InvalidTargetObjectTypeException 'targetType' 字段值不是 'objectReference'。
• 由管理对象的设置方法抛出的 Exception。

ReflectionException - 包装试图调用设置方法时抛出的 Exception。

RuntimeOperationsException - 包装一个 IllegalArgumentException：参数中的属性为 null。

另请参见：

getAttribute(java.lang.String)

setAttributes

public AttributeList setAttributes(AttributeList attributes)

设置此 ModelMBean 的属性数组的值。为列表中每个属性执行 setAttribute() 方法。

指定者：

接口 DynamicMBean 中的 setAttributes

参数：

attributes - 属性列表：要设置的属性的标识和这些属性要设置的值。

返回：

所设置的属性数组，以及 Attribute 实例中它们的新值。

抛出：

RuntimeOperationsException - 包装一个 IllegalArgumentException：参数中的对象名称为 null，或参数中的属性为 null。

另请参见：

getAttributes(java.lang.String[])

addNotificationListener

public void addNotificationListener(NotificationListener listener,
                                    NotificationFilter filter,
                                    Object handback)
                             throws IllegalArgumentException

注册一个将 NotificationListener 接口实现为侦听器的对象。当通过或由 ModelMBean 发布任何通知时，将调用此对象的 'handleNotification()' 方法。这不包括 attributeChangeNotifications。它们必须独立注册。

指定者：

接口 NotificationBroadcaster 中的 addNotificationListener

参数：

listener - 将处理由已注册的 MBean 发出的通知的侦听器对象。

filter - 过滤器对象。如果为 null，则在处理通知之前将不执行过滤。

handback - 当发出通知时，要发送到带有通知的侦听器的上下文。

抛出：

IllegalArgumentException - 侦听器不可以为 null。

另请参见：

removeNotificationListener(javax.management.NotificationListener)

removeNotificationListener

public void removeNotificationListener(NotificationListener listener)
                                throws ListenerNotFoundException

从 RequiredModelMBean 移除一个 Notification 的侦听器。

指定者：

接口 NotificationBroadcaster 中的 removeNotificationListener

参数：

listener - 正在处理由注册的 M