J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 1 | /* |
| 2 | * Portions Copyright 2000-2006 Sun Microsystems, Inc. All Rights Reserved. |
| 3 | * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
| 4 | * |
| 5 | * This code is free software; you can redistribute it and/or modify it |
| 6 | * under the terms of the GNU General Public License version 2 only, as |
| 7 | * published by the Free Software Foundation. Sun designates this |
| 8 | * particular file as subject to the "Classpath" exception as provided |
| 9 | * by Sun in the LICENSE file that accompanied this code. |
| 10 | * |
| 11 | * This code is distributed in the hope that it will be useful, but WITHOUT |
| 12 | * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
| 13 | * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
| 14 | * version 2 for more details (a copy is included in the LICENSE file that |
| 15 | * accompanied this code). |
| 16 | * |
| 17 | * You should have received a copy of the GNU General Public License version |
| 18 | * 2 along with this work; if not, write to the Free Software Foundation, |
| 19 | * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
| 20 | * |
| 21 | * Please contact Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, |
| 22 | * CA 95054 USA or visit www.sun.com if you need additional information or |
| 23 | * have any questions. |
| 24 | */ |
| 25 | /* |
| 26 | * @author IBM Corp. |
| 27 | * |
| 28 | * Copyright IBM Corp. 1999-2000. All rights reserved. |
| 29 | */ |
| 30 | |
| 31 | package javax.management.modelmbean; |
| 32 | |
| 33 | import javax.management.Descriptor; |
| 34 | import javax.management.MBeanAttributeInfo; |
| 35 | import javax.management.MBeanConstructorInfo; |
| 36 | import javax.management.RuntimeOperationsException; |
| 37 | import javax.management.MBeanException; |
| 38 | import javax.management.MBeanNotificationInfo; |
| 39 | import javax.management.MBeanOperationInfo; |
| 40 | |
| 41 | /** |
| 42 | * This interface is implemented by the ModelMBeanInfo for every ModelMBean. An implementation of this interface |
| 43 | * must be shipped with every JMX Agent. |
| 44 | * <P> |
| 45 | * Java resources wishing to be manageable instantiate the ModelMBean using the MBeanServer's |
| 46 | * createMBean method. The resource then sets the ModelMBeanInfo and Descriptors for the ModelMBean |
| 47 | * instance. The attributes, operations, and notifications exposed via the ModelMBeanInfo for the |
| 48 | * ModelMBean comprise the management interface and are accessible |
| 49 | * from MBeans, connectors/adaptors like other MBeans. Through the Descriptors, values and methods in |
| 50 | * the managed application can be defined and mapped to attributes and operations of the ModelMBean. |
| 51 | * This mapping can be defined during development in a file or dynamically and |
| 52 | * programmatically at runtime. |
| 53 | * <P> |
| 54 | * Every ModelMBean which is instantiated in the MBeanServer becomes manageable: |
| 55 | * its attributes, operations, and notifications |
| 56 | * become remotely accessible through the connectors/adaptors connected to that MBeanServer. |
| 57 | * A Java object cannot be registered in the MBeanServer unless it is a JMX compliant MBean. |
| 58 | * By instantiating a ModelMBean, resources are guaranteed that the MBean is valid. |
| 59 | * |
| 60 | * MBeanException and RuntimeOperationsException must be thrown on every public method. This allows |
| 61 | * for wrapping exceptions from distributed communications (RMI, EJB, etc.) |
| 62 | * |
| 63 | * @since 1.5 |
| 64 | */ |
| 65 | |
| 66 | public interface ModelMBeanInfo |
| 67 | { |
| 68 | |
| 69 | |
| 70 | /** |
| 71 | * Returns a Descriptor array consisting of all |
| 72 | * Descriptors for the ModelMBeanInfo of type inDescriptorType. |
| 73 | * |
| 74 | * @param inDescriptorType value of descriptorType field that must be set for the descriptor |
| 75 | * to be returned. Must be "mbean", "attribute", "operation", "constructor" or "notification". |
| 76 | * If it is null or empty then all types will be returned. |
| 77 | * |
| 78 | * @return Descriptor array containing all descriptors for the ModelMBean if type inDescriptorType. |
| 79 | * |
| 80 | * @exception MBeanException Wraps a distributed communication Exception. |
| 81 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException when the descriptorType in parameter is |
| 82 | * not one of: "mbean", "attribute", "operation", "constructor", "notification", empty or null. |
| 83 | * |
| 84 | * @see #setDescriptors |
| 85 | */ |
| 86 | public Descriptor[] getDescriptors(String inDescriptorType) |
| 87 | throws MBeanException, RuntimeOperationsException; |
| 88 | |
| 89 | /** |
| 90 | * Adds or replaces descriptors in the ModelMBeanInfo. |
| 91 | * |
| 92 | * @param inDescriptors The descriptors to be set in the ModelMBeanInfo. Null |
| 93 | * elements of the list will be ignored. All descriptors must have name and descriptorType fields. |
| 94 | * |
| 95 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null or invalid descriptor. |
| 96 | * @exception MBeanException Wraps a distributed communication Exception. |
| 97 | * |
| 98 | * @see #getDescriptors |
| 99 | */ |
| 100 | public void setDescriptors(Descriptor[] inDescriptors) |
| 101 | throws MBeanException, RuntimeOperationsException; |
| 102 | |
| 103 | /** |
| 104 | * Returns a Descriptor requested by name and descriptorType. |
| 105 | * |
| 106 | * @param inDescriptorName The name of the descriptor. |
| 107 | * @param inDescriptorType The type of the descriptor being |
| 108 | * requested. If this is null or empty then all types are |
| 109 | * searched. Valid types are 'mbean', 'attribute', 'constructor' |
| 110 | * 'operation', and 'notification'. This value will be equal to |
| 111 | * the 'descriptorType' field in the descriptor that is returned. |
| 112 | * |
| 113 | * @return Descriptor containing the descriptor for the ModelMBean |
| 114 | * with the same name and descriptorType. If no descriptor is |
| 115 | * found, null is returned. |
| 116 | * |
| 117 | * @exception MBeanException Wraps a distributed communication Exception. |
| 118 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null descriptor name or null or invalid type. |
| 119 | * The type must be "mbean","attribute", "constructor", "operation", or "notification". |
| 120 | * |
| 121 | * @see #setDescriptor |
| 122 | */ |
| 123 | |
| 124 | public Descriptor getDescriptor(String inDescriptorName, String inDescriptorType) |
| 125 | throws MBeanException, RuntimeOperationsException; |
| 126 | |
| 127 | /** |
| 128 | * Sets descriptors in the info array of type inDescriptorType |
| 129 | * for the ModelMBean. The setDescriptor method of the |
| 130 | * corresponding ModelMBean*Info will be called to set the |
| 131 | * specified descriptor. |
| 132 | * |
| 133 | * @param inDescriptor The descriptor to be set in the |
| 134 | * ModelMBean. It must NOT be null. All descriptors must have |
| 135 | * name and descriptorType fields. |
| 136 | * @param inDescriptorType The type of the descriptor being |
| 137 | * set. If this is null then the descriptorType field in the |
| 138 | * descriptor is used. If specified this value must be set in |
| 139 | * the descriptorType field in the descriptor. Must be |
| 140 | * "mbean","attribute", "constructor", "operation", or |
| 141 | * "notification". |
| 142 | * |
| 143 | * @exception RuntimeOperationsException Wraps an |
| 144 | * IllegalArgumentException for illegal or null arguments or |
| 145 | * if the name field of the descriptor is not found in the |
| 146 | * corresponding MBeanAttributeInfo or MBeanConstructorInfo or |
| 147 | * MBeanNotificationInfo or MBeanOperationInfo. |
| 148 | * @exception MBeanException Wraps a distributed communication |
| 149 | * Exception. |
| 150 | * |
| 151 | * @see #getDescriptor |
| 152 | */ |
| 153 | |
| 154 | public void setDescriptor(Descriptor inDescriptor, String inDescriptorType) |
| 155 | throws MBeanException, RuntimeOperationsException; |
| 156 | |
| 157 | |
| 158 | /** |
| 159 | * Returns the ModelMBean's descriptor which contains MBean wide policies. This descriptor contains |
| 160 | * metadata about the MBean and default policies for persistence and caching. |
| 161 | * <P> |
| 162 | * The fields in the descriptor are defined, but not limited to, the following: |
| 163 | * <PRE> |
| 164 | * name : MBean name |
| 165 | * descriptorType : must be "mbean" |
| 166 | * displayName : name of attribute to be used in displays |
| 167 | * persistPolicy : OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never |
| 168 | * persistLocation : The fully qualified directory name where the MBean should be persisted (if appropriate) |
| 169 | * persistFile : File name into which the MBean should be persisted |
| 170 | * persistPeriod : seconds - frequency of persist cycle for OnTime and NoMoreOftenThan PersistPolicy |
| 171 | * currencyTimeLimit : how long value is valid, <0 never, =0 always, >0 seconds |
| 172 | * log : where t: log all notifications f: log no notifications |
| 173 | * logfile : fully qualified filename to log events to |
| 174 | * visibility : 1-4 where 1: always visible 4: rarely visible |
| 175 | * export : name to be used to export/expose this MBean so that it is findable by |
| 176 | * other JMX Agents. |
| 177 | * presentationString : xml formatted string to allow presentation of data to be associated with the MBean. |
| 178 | * </PRE> |
| 179 | * <P> |
| 180 | * The default descriptor is: name=className,descriptorType="mbean", displayName=className, |
| 181 | * persistPolicy="never",log="F",export="F",visibility="1" |
| 182 | * If the descriptor does not contain all these fields, they will be added with these default values. |
| 183 | * |
| 184 | * <p><b>Note:</b> because of inconsistencies in previous versions of |
| 185 | * this specification, it is recommended not to use negative or zero |
| 186 | * values for <code>currencyTimeLimit</code>. To indicate that a |
| 187 | * cached value is never valid, omit the |
| 188 | * <code>currencyTimeLimit</code> field. To indicate that it is |
| 189 | * always valid, use a very large number for this field.</p> |
| 190 | * |
| 191 | * @return the MBean descriptor. |
| 192 | * |
| 193 | * @exception MBeanException Wraps a distributed communication |
| 194 | * Exception. |
| 195 | * |
| 196 | * @exception RuntimeOperationsException a {@link |
| 197 | * RuntimeException} occurred while getting the descriptor. |
| 198 | * |
| 199 | * @see #setMBeanDescriptor |
| 200 | */ |
| 201 | public Descriptor getMBeanDescriptor() |
| 202 | throws MBeanException, RuntimeOperationsException; |
| 203 | |
| 204 | /** |
| 205 | * Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide |
| 206 | * metadata about the MBean and default policies for persistence and caching. This operation |
| 207 | * does a complete replacement of the descriptor, no merging is done. If the descriptor to |
| 208 | * set to is null then the default descriptor will be created. |
| 209 | * The default descriptor is: name=className,descriptorType="mbean", displayName=className, |
| 210 | * persistPolicy="never",log="F",export="F",visibility="1" |
| 211 | * If the descriptor does not contain all these fields, they will be added with these default values. |
| 212 | * |
| 213 | * See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names. |
| 214 | * |
| 215 | * @param inDescriptor the descriptor to set. |
| 216 | * |
| 217 | * @exception MBeanException Wraps a distributed communication Exception. |
| 218 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException for invalid descriptor. |
| 219 | * |
| 220 | * |
| 221 | * @see #getMBeanDescriptor |
| 222 | */ |
| 223 | |
| 224 | public void setMBeanDescriptor(Descriptor inDescriptor) |
| 225 | throws MBeanException, RuntimeOperationsException; |
| 226 | |
| 227 | |
| 228 | /** |
| 229 | * Returns a ModelMBeanAttributeInfo requested by name. |
| 230 | * |
| 231 | * @param inName The name of the ModelMBeanAttributeInfo to get. |
| 232 | * If no ModelMBeanAttributeInfo exists for this name null is returned. |
| 233 | * |
| 234 | * @return the attribute info for the named attribute, or null |
| 235 | * if there is none. |
| 236 | * |
| 237 | * @exception MBeanException Wraps a distributed communication |
| 238 | * Exception. |
| 239 | * @exception RuntimeOperationsException Wraps an |
| 240 | * IllegalArgumentException for a null attribute name. |
| 241 | * |
| 242 | */ |
| 243 | |
| 244 | public ModelMBeanAttributeInfo getAttribute(String inName) |
| 245 | throws MBeanException, RuntimeOperationsException; |
| 246 | |
| 247 | |
| 248 | /** |
| 249 | * Returns a ModelMBeanOperationInfo requested by name. |
| 250 | * |
| 251 | * @param inName The name of the ModelMBeanOperationInfo to get. |
| 252 | * If no ModelMBeanOperationInfo exists for this name null is returned. |
| 253 | * |
| 254 | * @return the operation info for the named operation, or null |
| 255 | * if there is none. |
| 256 | * |
| 257 | * @exception MBeanException Wraps a distributed communication Exception. |
| 258 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null operation name. |
| 259 | * |
| 260 | */ |
| 261 | |
| 262 | public ModelMBeanOperationInfo getOperation(String inName) |
| 263 | throws MBeanException, RuntimeOperationsException; |
| 264 | |
| 265 | |
| 266 | /** |
| 267 | * Returns a ModelMBeanNotificationInfo requested by name. |
| 268 | * |
| 269 | * @param inName The name of the ModelMBeanNotificationInfo to get. |
| 270 | * If no ModelMBeanNotificationInfo exists for this name null is returned. |
| 271 | * |
| 272 | * @return the info for the named notification, or null if there |
| 273 | * is none. |
| 274 | * |
| 275 | * @exception MBeanException Wraps a distributed communication Exception. |
| 276 | * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null notification name. |
| 277 | * |
| 278 | */ |
| 279 | public ModelMBeanNotificationInfo getNotification(String inName) |
| 280 | throws MBeanException, RuntimeOperationsException; |
| 281 | |
| 282 | /** |
| 283 | * Creates and returns a copy of this object. |
| 284 | */ |
| 285 | public java.lang.Object clone(); |
| 286 | |
| 287 | /** |
| 288 | * Returns the list of attributes exposed for management. |
| 289 | * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object. |
| 290 | * |
| 291 | * @return An array of <CODE>MBeanAttributeInfo</CODE> objects. |
| 292 | */ |
| 293 | public MBeanAttributeInfo[] getAttributes(); |
| 294 | |
| 295 | /** |
| 296 | * Returns the name of the Java class of the MBean described by |
| 297 | * this <CODE>MBeanInfo</CODE>. |
| 298 | * |
| 299 | * @return the Java class name. |
| 300 | */ |
| 301 | public java.lang.String getClassName(); |
| 302 | |
| 303 | /** |
| 304 | * Returns the list of the public constructors of the MBean. |
| 305 | * Each constructor is described by an <CODE>MBeanConstructorInfo</CODE> object. |
| 306 | * |
| 307 | * @return An array of <CODE>MBeanConstructorInfo</CODE> objects. |
| 308 | */ |
| 309 | public MBeanConstructorInfo[] getConstructors(); |
| 310 | |
| 311 | /** |
| 312 | * Returns a human readable description of the MBean. |
| 313 | * |
| 314 | * @return the description. |
| 315 | */ |
| 316 | public java.lang.String getDescription(); |
| 317 | |
| 318 | /** |
| 319 | * Returns the list of the notifications emitted by the MBean. |
| 320 | * Each notification is described by an <CODE>MBeanNotificationInfo</CODE> object. |
| 321 | * <P> |
| 322 | * In addition to any notification specified by the application, |
| 323 | * a ModelMBean may always send also two additional notifications: |
| 324 | * <UL> |
| 325 | * <LI> One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic" |
| 326 | * <LI> Second is a standard attribute change notification |
| 327 | * with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change" |
| 328 | * </UL> |
| 329 | * Thus any implementation of ModelMBeanInfo should always add those two notifications |
| 330 | * in addition to those specified by the application. |
| 331 | * |
| 332 | * @return An array of <CODE>MBeanNotificationInfo</CODE> objects. |
| 333 | */ |
| 334 | public MBeanNotificationInfo[] getNotifications(); |
| 335 | |
| 336 | /** |
| 337 | * Returns the list of operations of the MBean. |
| 338 | * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object. |
| 339 | * |
| 340 | * @return An array of <CODE>MBeanOperationInfo</CODE> objects. |
| 341 | */ |
| 342 | public MBeanOperationInfo[] getOperations(); |
| 343 | |
| 344 | } |