Source for javax.management.Descriptor

   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: }