1/* 2 * Copyright (c) 2000, 2017, Oracle and/or its affiliates. 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. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle 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 Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25/* 26 * @author IBM Corp. 27 * 28 * Copyright IBM Corp. 1999-2000. All rights reserved. 29 */ 30 31package javax.management.modelmbean; 32 33import javax.management.Descriptor; 34import javax.management.MBeanAttributeInfo; 35import javax.management.MBeanConstructorInfo; 36import javax.management.RuntimeOperationsException; 37import javax.management.MBeanException; 38import javax.management.MBeanNotificationInfo; 39import 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 66public 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 * <p>Returns the ModelMBean's descriptor which contains MBean wide 160 * policies. This descriptor contains metadata about the MBean and default 161 * policies for persistence and caching.</p> 162 * 163 * <P id="descriptor"> 164 * The fields in the descriptor are defined, but not limited to, the 165 * following. Note that when the Type in this table is Number, a String 166 * that is the decimal representation of a Long can also be used.</P> 167 * 168 * <table class="striped"> 169 * <caption style="display:none">ModelMBean Fields</caption> 170 * <thead> 171 * <tr><th scope="col">Name</th><th scope="col">Type</th><th scope="col">Meaning</th></tr> 172 * </thead> 173 * <tbody style="text-align:left"> 174 * <tr><th scope="row">name</th><td>String</td> 175 * <td>MBean name.</td></tr> 176 * <tr><th scope="row">descriptorType</th><td>String</td> 177 * <td>Must be "mbean".</td></tr> 178 * <tr><th scope="row">displayName</th><td>String</td> 179 * <td>Name of MBean to be used in displays.</td></tr> 180 * <tr><th scope="row">persistPolicy</th><td>String</td> 181 * <td>One of: OnUpdate|OnTimer|NoMoreOftenThan|OnUnregister|Always|Never. 182 * See the section "MBean Descriptor Fields" in the JMX specification 183 * document.</td></tr> 184 * <tr><th scope="row">persistLocation</th><td>String</td> 185 * <td>The fully qualified directory name where the MBean should be 186 * persisted (if appropriate).</td></tr> 187 * <tr><th scope="row">persistFile</th><td>String</td> 188 * <td>File name into which the MBean should be persisted.</td></tr> 189 * <tr><th scope="row">persistPeriod</th><td>Number</td> 190 * <td>Frequency of persist cycle in seconds, for OnTime and 191 * NoMoreOftenThan PersistPolicy</td></tr> 192 * <tr><th scope="row">currencyTimeLimit</th><td>Number</td> 193 * <td>How long cached value is valid: <0 never, =0 always, 194 * >0 seconds.</td></tr> 195 * <tr><th scope="row">log</th><td>String</td> 196 * <td>t: log all notifications, f: log no notifications.</td></tr> 197 * <tr><th scope="row">logfile</th><td>String</td> 198 * <td>Fully qualified filename to log events to.</td></tr> 199 * <tr><th scope="row">visibility</th><td>Number</td> 200 * <td>1-4 where 1: always visible 4: rarely visible.</td></tr> 201 * <tr><th scope="row">export</th><td>String</td> 202 * <td>Name to be used to export/expose this MBean so that it is 203 * findable by other JMX Agents.</td></tr> 204 * <tr><th scope="row">presentationString</th><td>String</td> 205 * <td>XML formatted string to allow presentation of data to be 206 * associated with the MBean.</td></tr> 207 * </tbody> 208 * </table> 209 * 210 * <P> 211 * The default descriptor is: name=className,descriptorType="mbean", displayName=className, 212 * persistPolicy="never",log="F",visibility="1" 213 * If the descriptor does not contain all these fields, they will be added with these default values. 214 * 215 * <p><b>Note:</b> because of inconsistencies in previous versions of 216 * this specification, it is recommended not to use negative or zero 217 * values for <code>currencyTimeLimit</code>. To indicate that a 218 * cached value is never valid, omit the 219 * <code>currencyTimeLimit</code> field. To indicate that it is 220 * always valid, use a very large number for this field.</p> 221 * 222 * @return the MBean descriptor. 223 * 224 * @exception MBeanException Wraps a distributed communication 225 * Exception. 226 * 227 * @exception RuntimeOperationsException a {@link 228 * RuntimeException} occurred while getting the descriptor. 229 * 230 * @see #setMBeanDescriptor 231 */ 232 public Descriptor getMBeanDescriptor() 233 throws MBeanException, RuntimeOperationsException; 234 235 /** 236 * Sets the ModelMBean's descriptor. This descriptor contains default, MBean wide 237 * metadata about the MBean and default policies for persistence and caching. This operation 238 * does a complete replacement of the descriptor, no merging is done. If the descriptor to 239 * set to is null then the default descriptor will be created. 240 * The default descriptor is: name=className,descriptorType="mbean", displayName=className, 241 * persistPolicy="never",log="F",visibility="1" 242 * If the descriptor does not contain all these fields, they will be added with these default values. 243 * 244 * See {@link #getMBeanDescriptor getMBeanDescriptor} method javadoc for description of valid field names. 245 * 246 * @param inDescriptor the descriptor to set. 247 * 248 * @exception MBeanException Wraps a distributed communication Exception. 249 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for invalid descriptor. 250 * 251 * 252 * @see #getMBeanDescriptor 253 */ 254 255 public void setMBeanDescriptor(Descriptor inDescriptor) 256 throws MBeanException, RuntimeOperationsException; 257 258 259 /** 260 * Returns a ModelMBeanAttributeInfo requested by name. 261 * 262 * @param inName The name of the ModelMBeanAttributeInfo to get. 263 * If no ModelMBeanAttributeInfo exists for this name null is returned. 264 * 265 * @return the attribute info for the named attribute, or null 266 * if there is none. 267 * 268 * @exception MBeanException Wraps a distributed communication 269 * Exception. 270 * @exception RuntimeOperationsException Wraps an 271 * IllegalArgumentException for a null attribute name. 272 * 273 */ 274 275 public ModelMBeanAttributeInfo getAttribute(String inName) 276 throws MBeanException, RuntimeOperationsException; 277 278 279 /** 280 * Returns a ModelMBeanOperationInfo requested by name. 281 * 282 * @param inName The name of the ModelMBeanOperationInfo to get. 283 * If no ModelMBeanOperationInfo exists for this name null is returned. 284 * 285 * @return the operation info for the named operation, or null 286 * if there is none. 287 * 288 * @exception MBeanException Wraps a distributed communication Exception. 289 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null operation name. 290 * 291 */ 292 293 public ModelMBeanOperationInfo getOperation(String inName) 294 throws MBeanException, RuntimeOperationsException; 295 296 297 /** 298 * Returns a ModelMBeanNotificationInfo requested by name. 299 * 300 * @param inName The name of the ModelMBeanNotificationInfo to get. 301 * If no ModelMBeanNotificationInfo exists for this name null is returned. 302 * 303 * @return the info for the named notification, or null if there 304 * is none. 305 * 306 * @exception MBeanException Wraps a distributed communication Exception. 307 * @exception RuntimeOperationsException Wraps an IllegalArgumentException for a null notification name. 308 * 309 */ 310 public ModelMBeanNotificationInfo getNotification(String inName) 311 throws MBeanException, RuntimeOperationsException; 312 313 /** 314 * Creates and returns a copy of this object. 315 * @return a copy of this object 316 */ 317 public java.lang.Object clone(); 318 319 /** 320 * Returns the list of attributes exposed for management. 321 * Each attribute is described by an <CODE>MBeanAttributeInfo</CODE> object. 322 * 323 * @return An array of <CODE>MBeanAttributeInfo</CODE> objects. 324 */ 325 public MBeanAttributeInfo[] getAttributes(); 326 327 /** 328 * Returns the name of the Java class of the MBean described by 329 * this <CODE>MBeanInfo</CODE>. 330 * 331 * @return the Java class name. 332 */ 333 public java.lang.String getClassName(); 334 335 /** 336 * Returns the list of the public constructors of the MBean. 337 * Each constructor is described by an <CODE>MBeanConstructorInfo</CODE> object. 338 * 339 * @return An array of <CODE>MBeanConstructorInfo</CODE> objects. 340 */ 341 public MBeanConstructorInfo[] getConstructors(); 342 343 /** 344 * Returns a human readable description of the MBean. 345 * 346 * @return the description. 347 */ 348 public java.lang.String getDescription(); 349 350 /** 351 * Returns the list of the notifications emitted by the MBean. 352 * Each notification is described by an <CODE>MBeanNotificationInfo</CODE> object. 353 * <P> 354 * In addition to any notification specified by the application, 355 * a ModelMBean may always send also two additional notifications: 356 * <UL> 357 * <LI> One with descriptor name "GENERIC" and displayName "jmx.modelmbean.generic" 358 * <LI> Second is a standard attribute change notification 359 * with descriptor name "ATTRIBUTE_CHANGE" and displayName "jmx.attribute.change" 360 * </UL> 361 * Thus any implementation of ModelMBeanInfo should always add those two notifications 362 * in addition to those specified by the application. 363 * 364 * @return An array of <CODE>MBeanNotificationInfo</CODE> objects. 365 */ 366 public MBeanNotificationInfo[] getNotifications(); 367 368 /** 369 * Returns the list of operations of the MBean. 370 * Each operation is described by an <CODE>MBeanOperationInfo</CODE> object. 371 * 372 * @return An array of <CODE>MBeanOperationInfo</CODE> objects. 373 */ 374 public MBeanOperationInfo[] getOperations(); 375 376} 377