/* * @(#)file ModelMBeanInfo.java * @(#)author IBM Corp. * @(#)version 1.24 * @(#)lastedit 04/02/10 */ /* * Copyright IBM Corp. 1999-2000. All rights reserved. * * The program is provided "as is" without any warranty express or implied, * including the warranty of non-infringement and the implied warranties of * merchantibility and fitness for a particular purpose. IBM will not be * liable for any damages suffered by you or any third party claim against * you regarding the Program. * * Copyright 2004 Sun Microsystems, Inc. All rights reserved. * This software is the proprietary information of Sun Microsystems, Inc. * Use is subject to license terms. * * Copyright 2004 Sun Microsystems, Inc. Tous droits reserves. * Ce logiciel est propriete de Sun Microsystems, Inc. * Distribue par des licences qui en restreignent l'utilisation. * */ package javax.management.modelmbean; import javax.management.Descriptor; import javax.management.DescriptorAccess; import javax.management.*; import javax.management.RuntimeOperationsException; import javax.management.MBeanException; /** * This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface * must be shipped with every JMX Agent. *
* 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|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=mbeanName,descriptorType=mbean, displayName=this.getClassName(), * 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();
}