| Frames | No Frames |
1: /* Descriptor.java -- Metadata container. 2: Copyright (C) 2007 Free Software Foundation, Inc. 3: 4: This file is part of GNU Classpath. 5: 6: GNU Classpath is free software; you can redistribute it and/or modify 7: it under the terms of the GNU General Public License as published by 8: the Free Software Foundation; either version 2, or (at your option) 9: any later version. 10: 11: GNU Classpath is distributed in the hope that it will be useful, but 12: WITHOUT ANY WARRANTY; without even the implied warranty of 13: MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 14: General Public License for more details. 15: 16: You should have received a copy of the GNU General Public License 17: along with GNU Classpath; see the file COPYING. If not, write to the 18: Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 19: 02110-1301 USA. 20: 21: Linking this library statically or dynamically with other modules is 22: making a combined work based on this library. Thus, the terms and 23: conditions of the GNU General Public License cover the whole 24: combination. 25: 26: As a special exception, the copyright holders of this library give you 27: permission to link this library with independent modules to produce an 28: executable, regardless of the license terms of these independent 29: modules, and to copy and distribute the resulting executable under 30: terms of your choice, provided that you also meet, for each linked 31: independent module, the terms and conditions of the license of that 32: module. An independent module is a module which is not derived from 33: or based on this library. If you modify this library, you may extend 34: this exception to your version of the library, but you are not 35: obligated to do so. If you do not wish to do so, delete this 36: exception statement from your version. */ 37: 38: package javax.management; 39: 40: import java.io.Serializable; 41: 42: /** 43: * <p> 44: * Provides metadata for a management element as a series 45: * of fields, formed from name-value pairs. Descriptors 46: * are usually attached to one of the <code>Info</code> 47: * classes, such as {@link MBeanAttributeInfo}. 48: * </p> 49: * <p> 50: * Field names are not case-sensitive, but are case-preserving 51: * (in that the same use of case will be returned by 52: * {@link #getFields()} and {@link #getFieldNames()}). 53: * The type of the value should match the type returned 54: * by the <code>getType()</code> method of the associated 55: * <code>Info</code> object. In the case of {@link MXBean}s, 56: * this should be the mapped type returned by the mapping rules. 57: * </p> 58: * <p> 59: * The contents of a descriptor may be immutable, in which 60: * case, attempts to change the contents of the descriptor 61: * will cause an exception to be thrown. Immutable descriptors 62: * are usually instances or subclasses of {@link ImmutableDescriptor}, 63: * while mutable descriptors are usually instances or subclasses 64: * of {@link javax.management.modelmbean.DescriptorSupport}. 65: * </p> 66: * <p> 67: * A series of field names are predefined, but additional 68: * ones can be added as needed. Predefined names never include 69: * a period ('.'), and so additional names may safely avoid 70: * conflicts by including this character. It is recommended that 71: * additional names make use of the same syntax as Java package 72: * names e.g. <code>gnu.classpath.ImportantMetadata</code>. 73: * </p> 74: * <p> 75: * The predefined names are as follows: 76: * </p> 77: * <table> 78: * <th> 79: * <td>Name</td><td>Type</td><td>Used In</td><td>Meaning</td> 80: * </th> 81: * <tr> 82: * <td>defaultValue</td><td>Object</td><td>{@link MBeanAttributeInfo}, 83: * {@link MBeanParameterInfo}</td><td>Default value for an attribute 84: * or parameter.</td> 85: * </tr> 86: * <tr> 87: * <td>deprecated</td><td>String</td><td>Any</td><td>The annotated element 88: * has been deprecated. Conventially, the field's value takes the form 89: * of the version in which the element was deprecated, followed by an 90: * explaination.</td> 91: * </tr> 92: * <tr> 93: * <td>descriptionResourceBundleBaseName</td><td>String</td><td>Any</td> 94: * <td>The base name for the bundle in which the <code>descriptionResourceKey</code> 95: * can be found.</td> 96: * </tr> 97: * <tr> 98: * <td>descriptionResourceKey</td><td>String</td><td>Any</td> 99: * <td>The name of the resource key which contains a localized description of 100: * this element.</td> 101: * </tr> 102: * <tr> 103: * <td>enabled</td><td>String</td><td>{@link MBeanAttributeInfo}, 104: * {@link MBeanNotificationInfo}, {@link MBeanOperationInfo}</td> 105: * <td>Specifies whether the annotated element is currently enabled or 106: * not, via a value of either <code>"true"</code> or <code>"false"</code>. 107: * </tr> 108: * <tr> 109: * <td>immutableInfo</td><td>String</td><td>{@link MBeanInfo}</td> 110: * <td>If the value of this field is <code>"true"</code>, this means that 111: * the annotated element will not change and thus may be cached.</td> 112: * </tr> 113: * <tr> 114: * <td>infoTimeout</td><td>String or Long</td><td>{@link MBeanInfo}</td> 115: * <td>If this field is present, and non-zero, it will contain a value 116: * in milliseconds for which the value of the annotated element will 117: * remain unchanged, allowing it to be safely cached for that period.</td> 118: * </tr> 119: * <tr> 120: * <td>interfaceClassName</td><td>String</td><td>{@link MBeanInfo}</td> 121: * <td>The Java interface name associated with the bean, as returned 122: * by {@link Class#getName()}.</td> 123: * </tr> 124: * <tr> 125: * <td>legalValues</td><td>Set<?></td><td>{@link MBeanAttributeInfo}, 126: * {@link MBeanParameterInfo}</td><td>Legal values for an attribute 127: * or parameter.</td> 128: * </tr> 129: * <tr> 130: * <td>maxValue</td><td>Object</td><td><td>{@link MBeanAttributeInfo}, 131: * {@link MBeanParameterInfo}</td><td>Maximum legal value for an attribute 132: * or parameter.</td> 133: * </tr> 134: * <tr> 135: * <td>metricType</td><td>String</td><td>{@link MBeanAttributeInfo}, 136: * {@link MBeanOperationInfo}</td><td>Specifies the type of metric represented 137: * by the annotated element. This will be either <code>"counter"</code> 138: * (an increasing value, which will only be reset and never decrease) 139: * or <code>"gauge"</code> (an increasing and decreasing value).</td> 140: * </tr> 141: * <tr> 142: * <td>minValue</td><td>Object</td><td>{@link MBeanAttributeInfo}, 143: * {@link MBeanParameterInfo}</td><td>Minimum legal value for an attribute 144: * or parameter.</td> 145: * </tr> 146: * <tr> 147: * <td>mxbean</td><td>String</td><td>{@link MBeanInfo}</td> 148: * <td>Specifies whether the annotated element is an {@link MXBean} or 149: * not, via a value of either <code>"true"</code> or <code>"false"</code>. 150: * </tr> 151: * <tr> 152: * <td>openType</td><td>{@link javax.management.openmbean.OpenType}</td> 153: * <td>{@link MBeanAttributeInfo}, {@link MBeanOperationInfo}</td>, 154: * {@link MBeanNotificationInfo}, {@link MBeanParameterInfo}</td> 155: * <td>Specifies the open type of the attribute or parameter, the return 156: * value of the operation or the user data of the notification respectively. 157: * This is present on <code>Open*Info</code> instances and for {@link MXBean}s.</td> 158: * <tr> 159: * <td>originalType</td><td>String</td><td>{@link MBeanAttributeInfo}, 160: * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td> 161: * <td>The original Java type of an element which has been converted 162: * to another type according to the {@link MXBean} typing rules. 163: * For example, {@link java.lang.management.MemoryType} becomes a 164: * String after conversion. This field would contain 165: * <code>"java.lang.management.MemoryType"</code> to represent the 166: * earlier type of an element with the converted type.</td> 167: * </tr> 168: * <tr> 169: * <td>severity</td><td>Integer or String</td> 170: * <td>{@link MBeanNotificationInfo}</td><td>Represents the severity 171: * of the notification, ranging from 1 (most severe) to 6 (least 172: * severe), with 0 representing unknown severity.</td> 173: * </tr> 174: * <tr> 175: * <td>since</td><td>String</td><td>Any</td> 176: * <td>The version in which this field was introduced.</td> 177: * </tr> 178: * <tr> 179: * <td>units</td><td>String</td><td>{@link MBeanAttributeInfo}, 180: * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td> 181: * <td>The units used by the value of an attribute or parameter, 182: * or the return value of an operation, such as <code>"bytes"</code>, 183: * <code>"milliseconds"</code> or <code>"kilogrammes"</code>. 184: * </tr> 185: * </table> 186: * <p>Some names are also defined as part of the Model MBeans package. 187: * See {@link javax.management.modelmbean.ModelMBeanInfo}.</p> 188: * 189: * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 190: * @since 1.5 191: */ 192: public interface Descriptor 193: extends Serializable, Cloneable 194: { 195: 196: /** 197: * Returns a clone of this descriptor, which can then be modified 198: * independently of this descriptor. If the descriptor is 199: * immutable, it is sufficient to return this instance. 200: * 201: * @return a clone of this descriptor. 202: * @throws RuntimeOperationsException if creation of the new 203: * descriptor fails for any 204: * reason. 205: */ 206: Object clone() 207: throws RuntimeOperationsException; 208: 209: /** 210: * <p> 211: * Returns true if this descriptor is equivalent to the 212: * supplied object. This is true if the following holds: 213: * </p> 214: * <ul> 215: * <li>The given object is also a {@link Descriptor}.</li> 216: * <li>Has the same field names, independent of case.</li> 217: * <li>Has the same values, based on the following: 218: * <ul> 219: * <li>If one value is <code>null</code>, the other must be.</li> 220: * <li>If one value is a primitive array, the other must be a 221: * primitive array of the same type with the same elements.</li> 222: * <li>If one value is an {@link Object} array, the other 223: * must be and {@link java.util.Arrays#deepEquals(Object[],Object[])} 224: * must return true.</li> 225: * <li>Otherwise, {@link Object#equals(Object)} must return true.</li> 226: * </ul> 227: * 228: * @param obj the object to compare according to the above. 229: * @return true if the above holds. 230: * @see Object#equals(Object) 231: * @see Object#hashCode() 232: * @since 1.6 233: */ 234: boolean equals(Object obj); 235: 236: /** 237: * Returns the field names of the descriptor. If the 238: * descriptor is empty, an empty array is returned. 239: * 240: * @return the field names as an array of Strings. 241: */ 242: String[] getFieldNames(); 243: 244: /** 245: * <p> 246: * Returns all the field name and value pairs, in the 247: * form <code>name=value</code>. The value is converted 248: * to a String as follows: 249: * </p> 250: * <ul> 251: * <li>If the value is a String, it is used as is.</li> 252: * <li>If the value is <code>null</code>, the printed 253: * value will be empty.</li> 254: * <li>Otherwise, the value will be converted to a 255: * String using its {@link Object#toString()} method, 256: * and included as <code>"(" + string + ")"</code>.</li> 257: * </ul> 258: * <p>If the descriptor is empty, an empty array is returned.</p> 259: * 260: * @return the field names and values as an array of Strings. 261: * @see #setFields(String[],Object[]) 262: */ 263: String[] getFields(); 264: 265: /** 266: * Returns the value of the specified field, or <code>null</code> 267: * if no value is present for the given field name. 268: * 269: * @param name the field name. 270: * @return the value of the field, or <code>null</code> if there 271: * is no value present. 272: * @throws RuntimeOperationsException if the field name is illegal. 273: */ 274: Object getFieldValue(String name); 275: 276: /** 277: * Returns the values corresponding to the fields named in 278: * the specified array, in the same order. If an empty 279: * array is supplied, an empty array is returned. A value 280: * of <code>null</code> leads to behaviour equivalent to 281: * {@link #getFields()}. Field values are obtained as specified 282: * in {@link #getFieldValue(String)}, with <code>null</code> 283: * being returned if the field is not present. This applies 284: * even if the given field name is <code>null</code> or 285: * the empty string. 286: * 287: * @param names an array of field names whose values should 288: * be returned. 289: * @return the values of the specified fields. 290: * @see #getFields() 291: * @see #getFieldValue(String) 292: */ 293: Object[] getFieldValues(String... names); 294: 295: /** 296: * <p> 297: * Returns the hash code of the descriptor. The hashcode 298: * is computed as the sum of the hashcodes for each field, 299: * which in turn is calculated as the sum of 300: * the hashcode of the name, <code>n</code>, computed 301: * using <code>n.toLowerCase().hashCode()</code>, and the 302: * hashcode of the value, <code>v</code>, computed 303: * using: 304: * </p> 305: * <ul> 306: * <li>If <code>v</code> is <code>null</code>, then the 307: * hash code is 0.</li> 308: * <li>If <code>v</code> is a primitive array, then the 309: * hash code is computed using the appropriate method 310: * from {@link java.util.Arrays}.</li> 311: * <li>If <code>v</code> is an {@link java.lang.Object} 312: * array, then the hash code is computed using the 313: * {@link java.util.Arrays#deepHashCode(Object[])} method.</li> 314: * <li>Otherwise, the hashcode is equal to 315: * <code>v.hashCode()</code>. 316: * </ul> 317: * 318: * @return a hashcode for this descriptor. 319: * @since 1.6 320: * @see Object#equals(Object) 321: * @see Object#hashCode() 322: */ 323: int hashCode(); 324: 325: /** 326: * Returns true if all the fields have legal values, given 327: * their names. Validity is determined by the implementation. 328: * 329: * @return true if the values are legal. 330: * @throws RuntimeOperationsException if the validity check 331: * fails for some reason. 332: */ 333: boolean isValid() 334: throws RuntimeOperationsException; 335: 336: /** 337: * Removes a field from the descriptor. If the field name 338: * is illegal or not found, this method fails silently. 339: * 340: * @param name the name of the field to remove. 341: * @throws RuntimeOperationsException if the field exists 342: * and the descriptor is 343: * immutable. This wraps 344: * an {@link UnsupportedOperationException}. 345: */ 346: void removeField(String name); 347: 348: /** 349: * Attempts to set the specified field to the supplied 350: * value. If the field does not exist, it will be created. 351: * If the field value given is invalid, then an exception will 352: * be thrown. Validity is determined by the implementation 353: * of the descriptor. 354: * 355: * @param name the field to set. Can not be <code>null</code> 356: * or empty. 357: * @param value the value to use, the validity of which is 358: * determined by the implementation. 359: * @throws RuntimeOperationsException if the name or value is 360: * illegal (wrapping a 361: * {@link IllegalArgumentException}) 362: * or if the descriptor is 363: * immutable (wrapping a 364: * {@link UnsupportedOperationException}. 365: */ 366: void setField(String name, Object value) 367: throws RuntimeOperationsException; 368: 369: /** 370: * Sets the field named in the first array to the corresponding 371: * value specified in the second. The array sizes must match. 372: * Empty arrays have no effect. An invalid value will cause 373: * an exception to be thrown. 374: * 375: * @param names the names of the fields to change. Neither 376: * the array or its elements may be <code>null</code>. 377: * @param values the values to use. The array must not be 378: * <code>null</code>. The value of the elements 379: * depends on the validity constraints of the 380: * implementation. 381: * @throws RuntimeOperationsException if the arrays differ in 382: * length, or a name or value is 383: * illegal (wrapping a 384: * {@link IllegalArgumentException}) 385: * or if the descriptor is 386: * immutable (wrapping a 387: * {@link UnsupportedOperationException}. 388: * @see #setField(String,Object) 389: */ 390: void setFields(String[] names, Object[] values); 391: 392: }