diff options
Diffstat (limited to 'libjava/classpath/javax/management/Descriptor.java')
| -rw-r--r-- | libjava/classpath/javax/management/Descriptor.java | 392 |
1 files changed, 392 insertions, 0 deletions
diff --git a/libjava/classpath/javax/management/Descriptor.java b/libjava/classpath/javax/management/Descriptor.java new file mode 100644 index 000000000..9a50b9e4e --- /dev/null +++ b/libjava/classpath/javax/management/Descriptor.java @@ -0,0 +1,392 @@ +/* Descriptor.java -- Metadata container. + Copyright (C) 2007 Free Software Foundation, Inc. + +This file is part of GNU Classpath. + +GNU Classpath is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by +the Free Software Foundation; either version 2, or (at your option) +any later version. + +GNU Classpath is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU +General Public License for more details. + +You should have received a copy of the GNU General Public License +along with GNU Classpath; see the file COPYING. If not, write to the +Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA +02110-1301 USA. + +Linking this library statically or dynamically with other modules is +making a combined work based on this library. Thus, the terms and +conditions of the GNU General Public License cover the whole +combination. + +As a special exception, the copyright holders of this library give you +permission to link this library with independent modules to produce an +executable, regardless of the license terms of these independent +modules, and to copy and distribute the resulting executable under +terms of your choice, provided that you also meet, for each linked +independent module, the terms and conditions of the license of that +module. An independent module is a module which is not derived from +or based on this library. If you modify this library, you may extend +this exception to your version of the library, but you are not +obligated to do so. If you do not wish to do so, delete this +exception statement from your version. */ + +package javax.management; + +import java.io.Serializable; + +/** + * <p> + * Provides metadata for a management element as a series + * of fields, formed from name-value pairs. Descriptors + * are usually attached to one of the <code>Info</code> + * classes, such as {@link MBeanAttributeInfo}. + * </p> + * <p> + * Field names are not case-sensitive, but are case-preserving + * (in that the same use of case will be returned by + * {@link #getFields()} and {@link #getFieldNames()}). + * The type of the value should match the type returned + * by the <code>getType()</code> method of the associated + * <code>Info</code> object. In the case of {@link MXBean}s, + * this should be the mapped type returned by the mapping rules. + * </p> + * <p> + * The contents of a descriptor may be immutable, in which + * case, attempts to change the contents of the descriptor + * will cause an exception to be thrown. Immutable descriptors + * are usually instances or subclasses of {@link ImmutableDescriptor}, + * while mutable descriptors are usually instances or subclasses + * of {@link javax.management.modelmbean.DescriptorSupport}. + * </p> + * <p> + * A series of field names are predefined, but additional + * ones can be added as needed. Predefined names never include + * a period ('.'), and so additional names may safely avoid + * conflicts by including this character. It is recommended that + * additional names make use of the same syntax as Java package + * names e.g. <code>gnu.classpath.ImportantMetadata</code>. + * </p> + * <p> + * The predefined names are as follows: + * </p> + * <table> + * <th> + * <td>Name</td><td>Type</td><td>Used In</td><td>Meaning</td> + * </th> + * <tr> + * <td>defaultValue</td><td>Object</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanParameterInfo}</td><td>Default value for an attribute + * or parameter.</td> + * </tr> + * <tr> + * <td>deprecated</td><td>String</td><td>Any</td><td>The annotated element + * has been deprecated. Conventially, the field's value takes the form + * of the version in which the element was deprecated, followed by an + * explaination.</td> + * </tr> + * <tr> + * <td>descriptionResourceBundleBaseName</td><td>String</td><td>Any</td> + * <td>The base name for the bundle in which the <code>descriptionResourceKey</code> + * can be found.</td> + * </tr> + * <tr> + * <td>descriptionResourceKey</td><td>String</td><td>Any</td> + * <td>The name of the resource key which contains a localized description of + * this element.</td> + * </tr> + * <tr> + * <td>enabled</td><td>String</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanNotificationInfo}, {@link MBeanOperationInfo}</td> + * <td>Specifies whether the annotated element is currently enabled or + * not, via a value of either <code>"true"</code> or <code>"false"</code>. + * </tr> + * <tr> + * <td>immutableInfo</td><td>String</td><td>{@link MBeanInfo}</td> + * <td>If the value of this field is <code>"true"</code>, this means that + * the annotated element will not change and thus may be cached.</td> + * </tr> + * <tr> + * <td>infoTimeout</td><td>String or Long</td><td>{@link MBeanInfo}</td> + * <td>If this field is present, and non-zero, it will contain a value + * in milliseconds for which the value of the annotated element will + * remain unchanged, allowing it to be safely cached for that period.</td> + * </tr> + * <tr> + * <td>interfaceClassName</td><td>String</td><td>{@link MBeanInfo}</td> + * <td>The Java interface name associated with the bean, as returned + * by {@link Class#getName()}.</td> + * </tr> + * <tr> + * <td>legalValues</td><td>Set<?></td><td>{@link MBeanAttributeInfo}, + * {@link MBeanParameterInfo}</td><td>Legal values for an attribute + * or parameter.</td> + * </tr> + * <tr> + * <td>maxValue</td><td>Object</td><td><td>{@link MBeanAttributeInfo}, + * {@link MBeanParameterInfo}</td><td>Maximum legal value for an attribute + * or parameter.</td> + * </tr> + * <tr> + * <td>metricType</td><td>String</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanOperationInfo}</td><td>Specifies the type of metric represented + * by the annotated element. This will be either <code>"counter"</code> + * (an increasing value, which will only be reset and never decrease) + * or <code>"gauge"</code> (an increasing and decreasing value).</td> + * </tr> + * <tr> + * <td>minValue</td><td>Object</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanParameterInfo}</td><td>Minimum legal value for an attribute + * or parameter.</td> + * </tr> + * <tr> + * <td>mxbean</td><td>String</td><td>{@link MBeanInfo}</td> + * <td>Specifies whether the annotated element is an {@link MXBean} or + * not, via a value of either <code>"true"</code> or <code>"false"</code>. + * </tr> + * <tr> + * <td>openType</td><td>{@link javax.management.openmbean.OpenType}</td> + * <td>{@link MBeanAttributeInfo}, {@link MBeanOperationInfo}</td>, + * {@link MBeanNotificationInfo}, {@link MBeanParameterInfo}</td> + * <td>Specifies the open type of the attribute or parameter, the return + * value of the operation or the user data of the notification respectively. + * This is present on <code>Open*Info</code> instances and for {@link MXBean}s.</td> + * <tr> + * <td>originalType</td><td>String</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td> + * <td>The original Java type of an element which has been converted + * to another type according to the {@link MXBean} typing rules. + * For example, {@link java.lang.management.MemoryType} becomes a + * String after conversion. This field would contain + * <code>"java.lang.management.MemoryType"</code> to represent the + * earlier type of an element with the converted type.</td> + * </tr> + * <tr> + * <td>severity</td><td>Integer or String</td> + * <td>{@link MBeanNotificationInfo}</td><td>Represents the severity + * of the notification, ranging from 1 (most severe) to 6 (least + * severe), with 0 representing unknown severity.</td> + * </tr> + * <tr> + * <td>since</td><td>String</td><td>Any</td> + * <td>The version in which this field was introduced.</td> + * </tr> + * <tr> + * <td>units</td><td>String</td><td>{@link MBeanAttributeInfo}, + * {@link MBeanOperationInfo}, {@link MBeanParameterInfo}</td> + * <td>The units used by the value of an attribute or parameter, + * or the return value of an operation, such as <code>"bytes"</code>, + * <code>"milliseconds"</code> or <code>"kilogrammes"</code>. + * </tr> + * </table> + * <p>Some names are also defined as part of the Model MBeans package. + * See {@link javax.management.modelmbean.ModelMBeanInfo}.</p> + * + * @author Andrew John Hughes (gnu_andrew@member.fsf.org) + * @since 1.5 + */ +public interface Descriptor + extends Serializable, Cloneable +{ + + /** + * Returns a clone of this descriptor, which can then be modified + * independently of this descriptor. If the descriptor is + * immutable, it is sufficient to return this instance. + * + * @return a clone of this descriptor. + * @throws RuntimeOperationsException if creation of the new + * descriptor fails for any + * reason. + */ + Object clone() + throws RuntimeOperationsException; + + /** + * <p> + * Returns true if this descriptor is equivalent to the + * supplied object. This is true if the following holds: + * </p> + * <ul> + * <li>The given object is also a {@link Descriptor}.</li> + * <li>Has the same field names, independent of case.</li> + * <li>Has the same values, based on the following: + * <ul> + * <li>If one value is <code>null</code>, the other must be.</li> + * <li>If one value is a primitive array, the other must be a + * primitive array of the same type with the same elements.</li> + * <li>If one value is an {@link Object} array, the other + * must be and {@link java.util.Arrays#deepEquals(Object[],Object[])} + * must return true.</li> + * <li>Otherwise, {@link Object#equals(Object)} must return true.</li> + * </ul> + * + * @param obj the object to compare according to the above. + * @return true if the above holds. + * @see Object#equals(Object) + * @see Object#hashCode() + * @since 1.6 + */ + boolean equals(Object obj); + + /** + * Returns the field names of the descriptor. If the + * descriptor is empty, an empty array is returned. + * + * @return the field names as an array of Strings. + */ + String[] getFieldNames(); + + /** + * <p> + * Returns all the field name and value pairs, in the + * form <code>name=value</code>. The value is converted + * to a String as follows: + * </p> + * <ul> + * <li>If the value is a String, it is used as is.</li> + * <li>If the value is <code>null</code>, the printed + * value will be empty.</li> + * <li>Otherwise, the value will be converted to a + * String using its {@link Object#toString()} method, + * and included as <code>"(" + string + ")"</code>.</li> + * </ul> + * <p>If the descriptor is empty, an empty array is returned.</p> + * + * @return the field names and values as an array of Strings. + * @see #setFields(String[],Object[]) + */ + String[] getFields(); + + /** + * Returns the value of the specified field, or <code>null</code> + * if no value is present for the given field name. + * + * @param name the field name. + * @return the value of the field, or <code>null</code> if there + * is no value present. + * @throws RuntimeOperationsException if the field name is illegal. + */ + Object getFieldValue(String name); + + /** + * Returns the values corresponding to the fields named in + * the specified array, in the same order. If an empty + * array is supplied, an empty array is returned. A value + * of <code>null</code> leads to behaviour equivalent to + * {@link #getFields()}. Field values are obtained as specified + * in {@link #getFieldValue(String)}, with <code>null</code> + * being returned if the field is not present. This applies + * even if the given field name is <code>null</code> or + * the empty string. + * + * @param names an array of field names whose values should + * be returned. + * @return the values of the specified fields. + * @see #getFields() + * @see #getFieldValue(String) + */ + Object[] getFieldValues(String... names); + + /** + * <p> + * Returns the hash code of the descriptor. The hashcode + * is computed as the sum of the hashcodes for each field, + * which in turn is calculated as the sum of + * the hashcode of the name, <code>n</code>, computed + * using <code>n.toLowerCase().hashCode()</code>, and the + * hashcode of the value, <code>v</code>, computed + * using: + * </p> + * <ul> + * <li>If <code>v</code> is <code>null</code>, then the + * hash code is 0.</li> + * <li>If <code>v</code> is a primitive array, then the + * hash code is computed using the appropriate method + * from {@link java.util.Arrays}.</li> + * <li>If <code>v</code> is an {@link java.lang.Object} + * array, then the hash code is computed using the + * {@link java.util.Arrays#deepHashCode(Object[])} method.</li> + * <li>Otherwise, the hashcode is equal to + * <code>v.hashCode()</code>. + * </ul> + * + * @return a hashcode for this descriptor. + * @since 1.6 + * @see Object#equals(Object) + * @see Object#hashCode() + */ + int hashCode(); + + /** + * Returns true if all the fields have legal values, given + * their names. Validity is determined by the implementation. + * + * @return true if the values are legal. + * @throws RuntimeOperationsException if the validity check + * fails for some reason. + */ + boolean isValid() + throws RuntimeOperationsException; + + /** + * Removes a field from the descriptor. If the field name + * is illegal or not found, this method fails silently. + * + * @param name the name of the field to remove. + * @throws RuntimeOperationsException if the field exists + * and the descriptor is + * immutable. This wraps + * an {@link UnsupportedOperationException}. + */ + void removeField(String name); + + /** + * Attempts to set the specified field to the supplied + * value. If the field does not exist, it will be created. + * If the field value given is invalid, then an exception will + * be thrown. Validity is determined by the implementation + * of the descriptor. + * + * @param name the field to set. Can not be <code>null</code> + * or empty. + * @param value the value to use, the validity of which is + * determined by the implementation. + * @throws RuntimeOperationsException if the name or value is + * illegal (wrapping a + * {@link IllegalArgumentException}) + * or if the descriptor is + * immutable (wrapping a + * {@link UnsupportedOperationException}. + */ + void setField(String name, Object value) + throws RuntimeOperationsException; + + /** + * Sets the field named in the first array to the corresponding + * value specified in the second. The array sizes must match. + * Empty arrays have no effect. An invalid value will cause + * an exception to be thrown. + * + * @param names the names of the fields to change. Neither + * the array or its elements may be <code>null</code>. + * @param values the values to use. The array must not be + * <code>null</code>. The value of the elements + * depends on the validity constraints of the + * implementation. + * @throws RuntimeOperationsException if the arrays differ in + * length, or a name or value is + * illegal (wrapping a + * {@link IllegalArgumentException}) + * or if the descriptor is + * immutable (wrapping a + * {@link UnsupportedOperationException}. + * @see #setField(String,Object) + */ + void setFields(String[] names, Object[] values); + +} |