Module  java.management
软件包  javax.management.modelmbean

Class RequiredModelMBean

  • All Implemented Interfaces:
    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和Descriptors。 通过ModelMBeanInfo为ModelMBean公开的属性和操作可以从MBean，连接器/适配器（如其他MBean）访问。 通过描述符，可以将托管应用程序中的值和方法定义并映射到ModelMBean的属性和操作。 该映射可以在XML格式的文件中定义，也可以在运行时以动态和编程方式定义。

    在MBeanServer中实例化的每个RequiredModelMBean变得可管理：
    其属性和操作可以通过连接到该MBeanServer的连接器/适配器进行远程访问。

    除非是符合JMX的MBean，否则不能在MBeanServer中注册Java对象。 通过实例化一个RequiredModelMBean，保证MBean有效的资源。 必须在每个公共方法上抛出MBeanException和RuntimeOperationsException。 这允许从分布式通信（RMI，EJB等）中包装异常

    从以下版本开始：
    1.5

    • 方法详细信息

      • store

        public void store​()
           throws MBeanException,
                  RuntimeOperationsException,
                  InstanceNotFoundException

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

        如果此类的实现不支持持久性，则抛出一个MBeanException包装ServiceNotFoundException 。

        使用MBean和属性描述符的持久性策略来指导该方法的执行。 如果'persistPolicy'字段为：MBean应存储 

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

        如果'persistPolicy'字段为：不存储MBean： 

          = "never"
    = "onUpdate"
    = "onTimer" && now < 'lastPersistTime' + 'persistPeriod'
        Specified by:
        store在接口 PersistentMBean
        异常
        MBeanException - 包装另一个异常，或不支持持久性
        RuntimeOperationsException - 从持久性机制中包装异常
        InstanceNotFoundException - 找不到/访问永久存储

      • getMBeanInfo

        public MBeanInfo getMBeanInfo​()
        返回此RequiredModelMBean所管理的属性，操作，构造函数和通知。
        Specified by:
        getMBeanInfo在接口 DynamicMBean
        结果
        ModelMBeanInfo的一个实例允许检索此MBean的所有属性，操作和通知。

      • invoke

        public Object invoke​(String opName,
                     Object[] opArgs,
                     String[] sig)
              throws MBeanException,
                     ReflectionException
        通过或者通过RequiredModelMBean调用方法，并返回方法执行的结果。

        如果要调用的给定方法与所提供的签名一起匹配RequiredModelMbean可访问方法之一，则将调用该方法。 否则，将对被管理的资源进行对给定方法的调用。

        操作返回的最后一个值可以缓存在ModelMBeanOperationInfo描述符中的操作描述符中。 有效值将在“值”字段中，如果有的话。 如果描述符中的'currencyTimeLimit'字段是：

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

        注意：由于本规范的先前版本不一致，建议不要对currencyTimeLimit使用负值或零值。 要指示缓存值永远无效，请忽略currencyTimeLimit字段。 要指示它始终有效，请在此字段中使用非常大的数字。

        Specified by:
        invoke在接口 DynamicMBean
        参数
        opName - 要调用的方法的名称。 如果在操作描述符的'class'字段中定义了类名称，则该名称可以是包含类名称的完全限定方法名称，也可以是方法名称。
        opArgs - 包含在调用操作时要设置的参数的数组
        sig - 包含操作签名的数组。 将使用与用于加载调用操作的MBean相同的类加载器来加载类对象。
        结果
        该方法返回的对象，表示在指定的受管资源上调用方法的结果。
        异常
        MBeanException - 包含以下其中一个异常：
        ReflectionException - 在尝试调用该方法时抛出一个异常 。
        RuntimeOperationsException - 包装IllegalArgumentException方法名称为null。

      • getAttribute

        public Object getAttribute​(String attrName)
                    throws AttributeNotFoundException,
                           MBeanException,
                           ReflectionException
        返回为此ModelMBean定义的特定属性的值。 属性返回的最后一个值可以缓存在属性的描述符中。 有效值将在“值”字段中，如果有的话。 如果描述符中的'currencyTimeLimit'字段是：
        • <0然后该值不缓存并且永远无效。 为属性调用getter方法。 'value'和'lastUpdatedTimeStamp'字段被清除。
        • = 0然后值始终被缓存并且始终有效。 返回“值”字段。 如果没有'value'字段，那么为该属性调用getter方法。 'lastUpdatedTimeStamp'字段和'value'字段设置为属性的值和当前时间戳。
        • > 0表示“值”字段有效的秒数。 当'lastUpdatedTimeStamp'+'currencyTimeLimit'> Now时，'值'字段不再有效。
          • 当'value'有效时，返回'value'。
          • 当“值”不再有效时，该属性将调用getter方法。 'lastUpdatedTimeStamp'字段和`value'字段被更新。

        注意：由于本规范的先前版本不一致，建议不要对currencyTimeLimit使用负值或零值。 要指示缓存值永远无效，请忽略currencyTimeLimit字段。 要指示它始终有效，请在此字段中使用非常大的数字。

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

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

        属性的声明类型是由MBeanAttributeInfo.getType()返回的字符串 。 如果满足以下条件之一，则该值与此类型兼容：

        • 该值为null;
        • 声明的名称是一个原始类型名称（如“int”），该值是相应包装器类型的实例（如java.lang.Integer）;
        • 该值的名称与声明的名称相同;
        • 声明的名称可以由值的类加载器加载，并生成可以分配该值的类。

        在这个实现中，在需要调用getMethod的每一种情况下，由于通过标准的“invoke”方法调用该方法，因此需要使用operationInfo，因此必须为该getMethod指定一个操作，以便调用工作正常。

        Specified by:
        getAttribute在接口 DynamicMBean
        参数
        attrName - 指定要检索的属性名称的字符串。 它必须匹配ModelMBeanAttributeInfo的名称。
        结果
        从描述符'value'字段检索属性的值，或从描述符的'getMethod'字段中的操作的调用。
        异常
        AttributeNotFoundException - MBean中无法访问指定的属性。 以下情况可能会导致AttributeNotFoundException：
        • 没有为Model MBean找到ModelMBeanInfo。
        • 没有找到指定的属性名称的ModelMBeanAttributeInfo。
        • ModelMBeanAttributeInfo isReadable方法返回'false'。
        MBeanException - 包装以下其中一个异常：
        ReflectionException - 包裹一个异常在尝试调用吸气剂时抛出。
        RuntimeOperationsException - 包裹一个IllegalArgumentException ：参数中的属性名称为null。
        另请参见：
        setAttribute(javax.management.Attribute)

      • setAttribute

        public void setAttribute​(Attribute attribute)
                  throws AttributeNotFoundException,
                         InvalidAttributeValueException,
                         MBeanException,
                         ReflectionException
        设置命名的ModelMBean的特定属性的值。 如果属性描述符的“setMethod”字段包含有效的操作描述符的名称，则执行操作描述符描述的方法。 在此实现中，必须正确指定操作描述符并分配给modelMBeanInfo，以使“setMethod”正常工作。 该方法的响应被设置为描述符中属性的值。

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

        如果属性描述符的持久字段不为空，则使用属性描述符的持久性策略来指导将属性存储在持久存储中。
        如果'persistPolicy'字段是存储MBean：

        • ！=“从不”
        • =“永远”
        • =“onUpdate”
        • =“onTimer”，现在>'lastPersistTime'+'persistPeriod'
        • =“NoMoreOftenThan”，现在>'lastPersistTime'+'persistPeriod'
        如果'persistPolicy'字段为：不存储MBean：
        • =“从不”
        • = =“onTimer”&& now <'lastPersistTime'+'persistPeriod'
        • =“onUnregister”
        • = =“NoMoreOftenThan”，现在<'lastPersistTime'+'persistPeriod'

        模型MBean的ModelMBeanInfo存储在一个文件中。

        Specified by:
        setAttribute在接口 DynamicMBean
        参数
        attribute - 包含要设置的属性的名称和要设置的值的属性实例。
        异常
        AttributeNotFoundException - MBean中无法访问指定的属性。
        以下情况可能会导致AttributeNotFoundException：
        • 没有找到指定属性的ModelMBeanAttributeInfo。
        • ModelMBeanAttributeInfo的isWritable方法返回'false'。
        InvalidAttributeValueException - 没有为指定的属性定义描述符。
        MBeanException - 包装以下其中一个异常：
        • 被管理对象的setter抛出的异常。
        • A ServiceNotFoundException如果在属性的描述符中定义了setMethod字段，并且被管理资源为null; 或者如果没有定义setMethod字段，并且没有为该属性启用缓存。 请注意，如果没有getMethod字段，则会自动启用缓存。
        • InvalidTargetObjectTypeException'targetType '字段值不是'objectReference'。
        • 被管理对象的getter抛出的异常。
        ReflectionException - 在尝试调用设置器时抛出一个异常 。
        RuntimeOperationsException - 包裹一个IllegalArgumentException ：参数中的属性为null。
        另请参见：
        getAttribute(java.lang.String)

      • removeNotificationListener

        public void removeNotificationListener​(NotificationListener listener,
                                       NotificationFilter filter,
                                       Object handback)
                                throws ListenerNotFoundException
        描述从接口NotificationEmitter复制

        从这个MBean中删除一个监听器。 该MBean必须有一个与给定匹配的侦听listener ， filter ，并handback参数。 如果有多个这样的听众，只有一个被删除。

        如果且仅当在要删除的侦听器中为空时， filter和handback参数可能为空。

        Specified by:
        removeNotificationListener在接口 NotificationEmitter
        参数
        listener - 以前添加到此MBean的侦听器。
        filter - 添加侦听器时指定的过滤器。
        handback - 添加侦听器时指定的 handback 。
        异常
        ListenerNotFoundException - 监听器未注册到MBean，或者没有向给定的过滤器和回传注册。

      • getNotificationInfo

        public MBeanNotificationInfo[] getNotificationInfo​()
        返回始终由RequiredModelMBean生成的通知数组。

        RequiredModelMBean可能还会再发送两个附加通知：

        • 一个与描述符"name=GENERIC,descriptorType=notification,log=T,severity=6,displayName=jmx.modelmbean.generic"
        • 二是具有描述符"name=ATTRIBUTE_CHANGE,descriptorType=notification,log=T,severity=6,displayName=jmx.attribute.change"的标准属性更改通知
        因此，这两个通知总是添加到应用程序指定的那些。
        Specified by:
        getNotificationInfo在接口 NotificationBroadcaster
        结果
        的MBeanNotificationInfo []

      • sendAttributeChangeNotification

        public void sendAttributeChangeNotification​(Attribute inOldVal,
                                            Attribute inNewVal)
                                     throws MBeanException,
                                            RuntimeOperationsException
        说明从界面ModelMBeanNotificationBroadcaster复制
        发送一个attributeChangeNotification，其中包含该属性的旧值和新值到ModelMBean上注册的AttributeChangeNotification侦听器。
        Specified by:
        sendAttributeChangeNotification在接口 ModelMBeanNotificationBroadcaster
        参数
        inOldVal - 属性的原始值
        inNewVal - 属性的当前值 
          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()
        异常
        MBeanException - 包装分布式通信异常。
        RuntimeOperationsException - 包裹一个IllegalArgumentException：在参数中传递的属性对象为null或参数中两个Attribute对象的名称不相同。

      • getClassLoaderRepository

        protected ClassLoaderRepository getClassLoaderRepository​()
        返回用于执行类加载的Class Loader Repository。 子类可能希望重新定义此方法，以返回应在此对象中使用的适当的ClassLoaderRepository 。
        结果
        Class Loader Repository。

      • preRegister

        public ObjectName preRegister​(MBeanServer server,
                              ObjectName name)
                       throws 异常
        允许MBean在MBean服务器注册之前执行所需的任何操作。 如果未指定MBean的名称，则MBean可以为其注册提供一个名称。 如果引发异常，MBean将不会在MBean服务器中注册。

        为了确保RequireModelMBean的正确运行时语义，RequiredModelMBean的super.preRegister(server, name)类重载或覆盖此方法都应在其自身的preRegister调用super.preRegister(server, name) 。

        Specified by:
        preRegister在接口 MBeanRegistration
        参数
        server - MBean将在其中注册的MBean服务器。
        name - MBean的对象名称。 此名称为null如果名称参数的一个createMBean或者registerMBean方法在MBeanServer接口为空。 在这种情况下，此方法必须为新的MBean返回非空的ObjectName。
        结果
        要注册MBean的名称。 此值不能为空。 如果name参数不为空，则通常不一定是返回值。
        异常
        异常 - 此异常将被MBean服务器捕获，并重新抛出为MBeanRegistrationException 。

      • postRegister

        public void postRegister​(Boolean registrationDone)
        允许MBean在MBean服务器中注册或注册失败后执行所需的操作。

        为了确保RequireModelMBean的正确运行时语义，RequiredModelMBean的super.postRegister(registrationDone)类重载或覆盖此方法都应在其自身的postRegister调用super.postRegister(registrationDone) 。

        Specified by:
        postRegister在接口 MBeanRegistration
        参数
        registrationDone - 指示MBean是否已在MBean服务器中成功注册。 值false表示注册阶段失败。

      • preDeregister

        public void preDeregister​()
                   throws 异常
        允许MBean在MBean服务器取消注册之前执行所需的任何操作。

        为了确保RequireModelMBean的正确运行时语义，RequiredModelMBean的super.preDeregister()类重载或覆盖此方法都应在其自身的preDeregister调用super.preDeregister() 。

        Specified by:
        preDeregister在接口 MBeanRegistration
        异常
        异常 - 此异常将被MBean服务器捕获，并重新抛出为MBeanRegistrationException 。

      • postDeregister

        public void postDeregister​()
        允许MBean在MBean服务器中取消注册后执行所需的任何操作。

        为了确保RequireModelMBean的正确的运行时语义，RequiredModelMBean的super.postDeregister()类重载或覆盖此方法都应在其自身的postDeregister调用super.postDeregister() 。

        Specified by:
        postDeregister在接口 MBeanRegistration