+ * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's + * createMBean method. The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean + * instance. The attributes, operations, and notifications exposed via the ModelMBeanInfo for the + * ModelMBean comprise the management interface and are accessible + * from MBeans, connectors/adaptors 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 during development in a file or dynamically and + * programmatically at runtime. + *
+ * Every ModelMBean which is instantiated in the MBeanServer becomes manageable: + * its attributes, operations, and notifications + * 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 ModelMBean, resources are guaranteed that the MBean is valid. + * + * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows + * for wrapping exceptions from distributed communications (RMI, EJB, etc.) + * + * @since 1.5 + */ + +public interface ModelMBeanInfo +{ + + + /** + * Returns a Descriptor array consisting of all + * Descriptors for the ModelMBeanInfo of type inDescriptorType. + * + * @param inDescriptorType value of descriptorType field that must be set for the descriptor + * to be returned. Must be "mbean", "attribute", "operation", "constructor" or "notification". + * If it is null or empty then all types will be returned. + * + * @return Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType. + * + * @exception MBeanException Wraps a distributed communication Exception. + * @exception RuntimeOperationsException Wraps an IllegalArgumentException when the descriptorType in parameter is + * not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null. + * + * @see #setDescriptors + */ + public Descriptor[] getDescriptors(String inDescriptorType) + throws MBeanException, RuntimeOperationsException; + + /** + * Adds or replaces descriptors in the ModelMBeanInfo. + * + * @param inDescriptors The descriptors to be set in the ModelMBeanInfo. Null + * elements of the list will be ignored. All descriptors must have name and descriptorType fields. + * + * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null or invalid descriptor. + * @exception MBeanException Wraps a distributed communication Exception. + * + * @see #getDescriptors + */ + public void setDescriptors(Descriptor[] inDescriptors) + throws MBeanException, RuntimeOperationsException; + + /** + * Returns a Descriptor requested by name and descriptorType. + * + * @param inDescriptorName The name of the descriptor. + * @param inDescriptorType The type of the descriptor being + * requested. If this is null or empty then all types are + * searched. Valid types are 'mbean', 'attribute', 'constructor' + * 'operation', and 'notification'. This value will be equal to + * the 'descriptorType' field in the descriptor that is returned. + * + * @return Descriptor containing the descriptor for the ModelMBean + * with the same name and descriptorType. If no descriptor is + * found, null is returned. + * + * @exception MBeanException Wraps a distributed communication Exception. + * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null descriptor name or null or invalid type. + * The type must be "mbean","attribute", "constructor", "operation", or "notification". + * + * @see #setDescriptor + */ + + public Descriptor getDescriptor(String inDescriptorName, String inDescriptorType) + throws MBeanException, RuntimeOperationsException; + + /** + * Sets descriptors in the info array of type inDescriptorType + * for the ModelMBean. The setDescriptor method of the + * corresponding ModelMBean*Info will be called to set the + * specified descriptor. + * + * @param inDescriptor The descriptor to be set in the + * ModelMBean. It must NOT be null. All descriptors must have + * name and descriptorType fields. + * @param inDescriptorType The type of the descriptor being + * set. If this is null then the descriptorType field in the + * descriptor is used. If specified this value must be set in + * the descriptorType field in the descriptor. Must be + * "mbean","attribute", "constructor", "operation", or + * "notification". + * + * @exception RuntimeOperationsException Wraps an + * IllegalArgumentException for illegal or null arguments or + * if the name field of the descriptor is not found in the + * corresponding MBeanAttributeInfo or MBeanConstructorInfo or + * MBeanNotificationInfo or MBeanOperationInfo. + * @exception MBeanException Wraps a distributed communication + * Exception. + * + * @see #getDescriptor + */ + + public void setDescriptor(Descriptor inDescriptor, String inDescriptorType) + throws MBeanException, RuntimeOperationsException; + + + /** + * Returns the ModelMBean's descriptor which contains MBean wide policies. This descriptor contains + * metadata about the MBean and default policies for persistence and caching. + *
+ * The fields in the descriptor are defined, but not limited to, the following: + *
+ * name : MBean name + * descriptorType : must be "mbean" + * displayName : name of attribute to be used in displays + * persistPolicy : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never + * persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate) + * persistFile : File name into which the MBean should be persisted + * persistPeriod : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy + * currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds + * log : where t: log all notifications f: log no notifications + * logfile : fully qualified filename to log events to + * visibility : 1-4 where 1: always visible 4: rarely visible + * export : name to be used to export/expose this MBean so that it is findable by + * other JMX Agents. + * presentationString : xml formatted string to allow presentation of data to be associated with the MBean. + *+ *
+ * The default descriptor is: name=className,descriptorType="mbean", displayName=className, + * persistPolicy="never",log="F",export="F",visibility="1" + * If the descriptor does not contain all these fields, they will be added with these default values. + * + *
Note: because of inconsistencies in previous versions of
+ * this specification, it is recommended not to use negative or zero
+ * values for currencyTimeLimit. To indicate that a
+ * cached value is never valid, omit the
+ * currencyTimeLimit field. To indicate that it is
+ * always valid, use a very large number for this field.
MBeanAttributeInfo object.
+ *
+ * @return An array of MBeanAttributeInfo objects.
+ */
+ public MBeanAttributeInfo[] getAttributes();
+
+ /**
+ * Returns the name of the Java class of the MBean described by
+ * this MBeanInfo.
+ *
+ * @return the Java class name.
+ */
+ public java.lang.String getClassName();
+
+ /**
+ * Returns the list of the public constructors of the MBean.
+ * Each constructor is described by an MBeanConstructorInfo object.
+ *
+ * @return An array of MBeanConstructorInfo objects.
+ */
+ public MBeanConstructorInfo[] getConstructors();
+
+ /**
+ * Returns a human readable description of the MBean.
+ *
+ * @return the description.
+ */
+ public java.lang.String getDescription();
+
+ /**
+ * Returns the list of the notifications emitted by the MBean.
+ * Each notification is described by an MBeanNotificationInfo object.
+ * + * In addition to any notification specified by the application, + * a ModelMBean may always send also two additional notifications: + *
MBeanNotificationInfo objects.
+ */
+ public MBeanNotificationInfo[] getNotifications();
+
+ /**
+ * Returns the list of operations of the MBean.
+ * Each operation is described by an MBeanOperationInfo object.
+ *
+ * @return An array of MBeanOperationInfo objects.
+ */
+ public MBeanOperationInfo[] getOperations();
+
+}