001/* Descriptor.java -- Metadata container. 002 Copyright (C) 2007 Free Software Foundation, Inc. 003 004This file is part of GNU Classpath. 005 006GNU Classpath is free software; you can redistribute it and/or modify 007it under the terms of the GNU General Public License as published by 008the Free Software Foundation; either version 2, or (at your option) 009any later version. 010 011GNU Classpath is distributed in the hope that it will be useful, but 012WITHOUT ANY WARRANTY; without even the implied warranty of 013MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014General Public License for more details. 015 016You should have received a copy of the GNU General Public License 017along with GNU Classpath; see the file COPYING. If not, write to the 018Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 01902110-1301 USA. 020 021Linking this library statically or dynamically with other modules is 022making a combined work based on this library. Thus, the terms and 023conditions of the GNU General Public License cover the whole 024combination. 025 026As a special exception, the copyright holders of this library give you 027permission to link this library with independent modules to produce an 028executable, regardless of the license terms of these independent 029modules, and to copy and distribute the resulting executable under 030terms of your choice, provided that you also meet, for each linked 031independent module, the terms and conditions of the license of that 032module. An independent module is a module which is not derived from 033or based on this library. If you modify this library, you may extend 034this exception to your version of the library, but you are not 035obligated to do so. If you do not wish to do so, delete this 036exception statement from your version. */ 037 038package javax.management; 039 040import java.io.Serializable; 041 042/** 043 * <p> 044 * Provides metadata for a management element as a series 045 * of fields, formed from name-value pairs. Descriptors 046 * are usually attached to one of the <code>Info</code> 047 * classes, such as {@link MBeanAttributeInfo}. 048 * </p> 049 * <p> 050 * Field names are not case-sensitive, but are case-preserving 051 * (in that the same use of case will be returned by 052 * {@link #getFields()} and {@link #getFieldNames()}). 053 * The type of the value should match the type returned 054 * by the <code>getType()</code> method of the associated 055 * <code>Info</code> object. In the case of {@link MXBean}s, 056 * this should be the mapped type returned by the mapping rules. 057 * </p> 058 * <p> 059 * The contents of a descriptor may be immutable, in which 060 * case, attempts to change the contents of the descriptor 061 * will cause an exception to be thrown. Immutable descriptors 062 * are usually instances or subclasses of {@link ImmutableDescriptor}, 063 * while mutable descriptors are usually instances or subclasses 064 * of {@link javax.management.modelmbean.DescriptorSupport}. 065 * </p> 066 * <p> 067 * A series of field names are predefined, but additional 068 * ones can be added as needed. Predefined names never include 069 * a period ('.'), and so additional names may safely avoid 070 * conflicts by including this character. It is recommended that 071 * additional names make use of the same syntax as Java package 072 * names e.g. <code>gnu.classpath.ImportantMetadata</code>. 073 * </p> 074 * <p> 075 * The predefined names are as follows: 076 * </p> 077 * <table> 078 * <th> 079 * <td>Name</td><td>Type</td><td>Used In</td><td>Meaning</td> 080 * </th> 081 * <tr> 082 * <td>defaultValue</td><td>Object</td><td>{@link MBeanAttributeInfo}, 083 * {@link MBeanParameterInfo}</td><td>Default value for an attribute 084 * or parameter.</td> 085 * </tr> 086 * <tr> 087 * <td>deprecated</td><td>String</td><td>Any</td><td>The annotated element 088 * has been deprecated. Conventially, the field's value takes the form 089 * of the version in which the element was deprecated, followed by an 090 * explaination.</td> 091 * </tr> 092 * <tr> 093 * <td>descriptionResourceBundleBaseName</td><td>String</td><td>Any</td> 094 * <td>The base name for the bundle in which the <code>descriptionResourceKey</code> 095 * can be found.</td> 096 * </tr> 097 * <tr> 098 * <td>descriptionResourceKey</td><td>String</td><td>Any</td> 099 * <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 */ 192public 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}