| /* |
| * Copyright (c) 2000, 2008, Oracle and/or its affiliates. All rights reserved. |
| * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| * |
| * This code is free software; you can redistribute it and/or modify it |
| * under the terms of the GNU General Public License version 2 only, as |
| * published by the Free Software Foundation. Oracle designates this |
| * particular file as subject to the "Classpath" exception as provided |
| * by Oracle in the LICENSE file that accompanied this code. |
| * |
| * This code is distributed in the hope that it will be useful, but WITHOUT |
| * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| * version 2 for more details (a copy is included in the LICENSE file that |
| * accompanied this code). |
| * |
| * You should have received a copy of the GNU General Public License version |
| * 2 along with this work; if not, write to the Free Software Foundation, |
| * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| * |
| * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
| * or visit www.oracle.com if you need additional information or have any |
| * questions. |
| */ |
| /* |
| * @author IBM Corp. |
| * |
| * Copyright IBM Corp. 1999-2000. All rights reserved. |
| */ |
| |
| package javax.management.modelmbean; |
| |
| import javax.management.Descriptor; |
| import javax.management.MBeanAttributeInfo; |
| import javax.management.MBeanConstructorInfo; |
| import javax.management.RuntimeOperationsException; |
| import javax.management.MBeanException; |
| import javax.management.MBeanNotificationInfo; |
| import javax.management.MBeanOperationInfo; |
| |
| /** |
| * This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface |
| * must be shipped with every JMX Agent. |
| * <P> |
| * 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. |
| * <P> |
| * 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; |
| |
| |
| /** |
| * <p>Returns the ModelMBean's descriptor which contains MBean wide |
| * policies. This descriptor contains metadata about the MBean and default |
| * policies for persistence and caching.</p> |
| * |
| * <P id="descriptor"> |
| * The fields in the descriptor are defined, but not limited to, the |
| * following. Note that when the Type in this table is Number, a String |
| * that is the decimal representation of a Long can also be used.</P> |
| * |
| * <table border="1" cellpadding="5"> |
| * <tr><th>Name</th><th>Type</th><th>Meaning</th></tr> |
| * <tr><td>name</td><td>String</td> |
| * <td>MBean name.</td></tr> |
| * <tr><td>descriptorType</td><td>String</td> |
| * <td>Must be "mbean".</td></tr> |
| * <tr><td>displayName</td><td>String</td> |
| * <td>Name of MBean to be used in displays.</td></tr> |
| * <tr><td>persistPolicy</td><td>String</td> |
| * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never. |
| * See the section "MBean Descriptor Fields" in the JMX specification |
| * document.</td></tr> |
| * <tr><td>persistLocation</td><td>String</td> |
| * <td>The fully qualified directory name where the MBean should be |
| * persisted (if appropriate).</td></tr> |
| * <tr><td>persistFile</td><td>String</td> |
| * <td>File name into which the MBean should be persisted.</td></tr> |
| * <tr><td>persistPeriod</td><td>Number</td> |
| * <td>Frequency of persist cycle in seconds, for OnTime and |
| * NoMoreOftenThan PersistPolicy</td></tr> |
| * <tr><td>currencyTimeLimit</td><td>Number</td> |
| * <td>How long cached value is valid: <0 never, =0 always, |
| * >0 seconds.</td></tr> |
| * <tr><td>log</td><td>String</td> |
| * <td>t: log all notifications, f: log no notifications.</td></tr> |
| * <tr><td>logfile</td><td>String</td> |
| * <td>Fully qualified filename to log events to.</td></tr> |
| * <tr><td>visibility</td><td>Number</td> |
| * <td>1-4 where 1: always visible 4: rarely visible.</td></tr> |
| * <tr><td>export</td><td>String</td> |
| * <td>Name to be used to export/expose this MBean so that it is |
| * findable by other JMX Agents.</td></tr> |
| * <tr><td>presentationString</td><td>String</td> |
| * <td>XML formatted string to allow presentation of data to be |
| * associated with the MBean.</td></tr> |
| * </table> |
| * |
| * <P> |
| * The default descriptor is: name=className,descriptorType="mbean", displayName=className, |
| * persistPolicy="never",log="F",visibility="1" |
| * If the descriptor does not contain all these fields, they will be added with these default values. |
| * |
| * <p><b>Note:</b> because of inconsistencies in previous versions of |
| * this specification, it is recommended not to use negative or zero |
| * values for <code>currencyTimeLimit</code>. To indicate that a |
| * cached value is never valid, omit the |
| * <code>currencyTimeLimit</code> field. To indicate that it is |
| * always valid, use a very large number for this field.</p> |
| * |
| * @return the MBean descriptor. |
| * |
| * @exception MBeanException Wraps a distributed communication |
| * Exception. |
| * |
| * @exception RuntimeOperationsException a {@link |
| * RuntimeException} occurred while getting the descriptor. |
| * |
| * @see #setMBeanDescriptor |
| */ |
| public Descriptor getMBeanDescriptor() |
| throws MBeanException, RuntimeOperationsException; |
| |
| /** |
| * Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide |
| * metadata about the MBean and default policies for persistence and caching. This operation |
| * does a complete replacement of the descriptor, no merging is done. If the descriptor to |
| * set to is null then the default descriptor will be created. |
| * The default descriptor is: name=className,descriptorType="mbean", displayName=className, |
| * persistPolicy="never",log="F",visibility="1" |
| * If the descriptor does not contain all these fields, they will be added with these default values. |
| * |
| * See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names. |
| * |
| * @param inDescriptor the descriptor to set. |
| * |
| * @exception MBeanException Wraps a distributed communication Exception. |
| * @exception RuntimeOperationsException Wraps an IllegalArgumentException for invalid descriptor. |
| * |
| * |
| * @see #getMBeanDescriptor |
| */ |
| |
| public void setMBeanDescriptor(Descriptor inDescriptor) |
| throws MBeanException, RuntimeOperationsException; |
| |
| |
| /** |
| * Returns a ModelMBeanAttributeInfo requested by name. |
| * |
| * @param inName The name of the ModelMBeanAttributeInfo to get. |
| * If no ModelMBeanAttributeInfo exists for this name null is returned. |
| * |
| * @return the attribute info for the named attribute, or null |
| * if there is none. |
| * |
| * @exception MBeanException Wraps a distributed communication |
| * Exception. |
| * @exception RuntimeOperationsException Wraps an |
| * IllegalArgumentException for a null attribute name. |
| * |
| */ |
| |
| public ModelMBeanAttributeInfo getAttribute(String inName) |
| throws MBeanException, RuntimeOperationsException; |
| |
| |
| /** |
| * Returns a ModelMBeanOperationInfo requested by name. |
| * |
| * @param inName The name of the ModelMBeanOperationInfo to get. |
| * If no ModelMBeanOperationInfo exists for this name null is returned. |
| * |
| * @return the operation info for the named operation, or null |
| * if there is none. |
| * |
| * @exception MBeanException Wraps a distributed communication Exception. |
| * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null operation name. |
| * |
| */ |
| |
| public ModelMBeanOperationInfo getOperation(String inName) |
| throws MBeanException, RuntimeOperationsException; |
| |
| |
| /** |
| * Returns a ModelMBeanNotificationInfo requested by name. |
| * |
| * @param inName The name of the ModelMBeanNotificationInfo to get. |
| * If no ModelMBeanNotificationInfo exists for this name null is returned. |
| * |
| * @return the info for the named notification, or null if there |
| * is none. |
| * |
| * @exception MBeanException Wraps a distributed communication Exception. |
| * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null notification name. |
| * |
| */ |
| public ModelMBeanNotificationInfo getNotification(String inName) |
| throws MBeanException, RuntimeOperationsException; |
| |
| /** |
| * Creates and returns a copy of this object. |
| */ |
| public java.lang.Object clone(); |
| |
| /** |
| * Returns the list of attributes exposed for management. |
| * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object. |
| * |
| * @return An array of <CODE>MBeanAttributeInfo</CODE> objects. |
| */ |
| public MBeanAttributeInfo[] getAttributes(); |
| |
| /** |
| * Returns the name of the Java class of the MBean described by |
| * this <CODE>MBeanInfo</CODE>. |
| * |
| * @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 <CODE>MBeanConstructorInfo</CODE> object. |
| * |
| * @return An array of <CODE>MBeanConstructorInfo</CODE> 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 <CODE>MBeanNotificationInfo</CODE> object. |
| * <P> |
| * In addition to any notification specified by the application, |
| * a ModelMBean may always send also two additional notifications: |
| * <UL> |
| * <LI> One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic" |
| * <LI> Second is a standard attribute change notification |
| * with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change" |
| * </UL> |
| * Thus any implementation of ModelMBeanInfo should always add those two notifications |
| * in addition to those specified by the application. |
| * |
| * @return An array of <CODE>MBeanNotificationInfo</CODE> objects. |
| */ |
| public MBeanNotificationInfo[] getNotifications(); |
| |
| /** |
| * Returns the list of operations of the MBean. |
| * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object. |
| * |
| * @return An array of <CODE>MBeanOperationInfo</CODE> objects. |
| */ |
| public MBeanOperationInfo[] getOperations(); |
| |
| } |
