diff options
Diffstat (limited to 'libjava/classpath/javax/management/Descriptor.java')
| -rw-r--r-- | libjava/classpath/javax/management/Descriptor.java | 392 |
1 files changed, 0 insertions, 392 deletions
diff --git a/libjava/classpath/javax/management/Descriptor.java b/libjava/classpath/javax/management/Descriptor.java deleted file mode 100644 index 9a50b9e..0000000 --- a/libjava/classpath/javax/management/Descriptor.java +++ /dev/null @@ -1,392 +0,0 @@ -/* 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); - -} |