e1bea0c068
2007-05-31 Matthias Klose <doko@ubuntu.com> * javax/management/NotificationBroadcasterSupport.java (getNotificationInfo): Add cast. * native/jni/qt-peer/Makefile.am (AM_CXXFLAGS): Add libstdc++ include directories. * native/jni/qt-peer/Makefile.in: Regenerate. libjava/ChangeLog: 2007-06-03 Matthias Klose <doko@ubuntu.com> * java/io/natFileWin32.cc (setFilePermissions): New (stub only). _access: Handle EXEC query, stub only. 2007-06-03 Matthias Klose <doko@ubuntu.com> Merged from classpath: * gnu/java/nio/SelectorProviderImpl.java: Whitespace merge. * java/lang/System.java(inheritedChannel): New. * java/lang/Character.java: Remove stray`;'. * java/net/MulticastSocket.java: Merged. * java/text/DateFormatSymbols.java(getInstance): New, comment updates. * java/text/Collator.java(getInstance): Merged. * java/util/Calendar.java: New attributes ALL_STYLES, SHORT, LONG. getDisplayName, getDisplayNames: New. * java/util/logging/Logger.java: Merged. * Regenerate .class and .h files. 2007-06-03 Matthias Klose <doko@ubuntu.com> * java/io/File.java: Merge with classpath-0.95, new method setFilePermissions, new attribute EXEC. * java/io/natFilePosix.cc (setFilePermissions): New. _access: Handle EXEC query. * classpath/lib/java/io/File.class, java/io/File.h: Regenerate. 2007-06-03 Matthias Klose <doko@ubuntu.com> Imported GNU Classpath 0.95. * classpath/Makefile.in, classpath/native/jni/midi-dssi/Makefile.in, classpath/native/jni/classpath/Makefile.in, classpath/native/jni/Makefile.in, classpath/native/jni/gconf-peer/Makefile.in, classpath/native/jni/java-io/Makefile.in, classpath/native/jni/native-lib/Makefile.in, classpath/native/jni/java-util/Makefile.in, classpath/native/jni/midi-alsa/Makefile.in, classpath/native/jni/java-lang/Makefile.in, classpath/native/jni/java-nio/Makefile.in, classpath/native/jni/java-net/Makefile.in, classpath/native/jni/xmlj/Makefile.in, classpath/native/jni/qt-peer/Makefile.in, classpath/native/jni/gtk-peer/Makefile.in, classpath/native/Makefile.in, classpath/native/jawt/Makefile.in, classpath/native/fdlibm/Makefile.in, classpath/native/plugin/Makefile.in, classpath/resource/Makefile.in, classpath/scripts/Makefile.in, classpath/tools/Makefile.in, classpath/doc/Makefile.in, classpath/doc/api/Makefile.in, classpath/lib/Makefile.in, classpath/external/Makefile.in, classpath/external/jsr166/Makefile.in, classpath/external/sax/Makefile.in, classpath/external/w3c_dom/Makefile.in, classpath/external/relaxngDatatype/Makefile.in, classpath/include/Makefile.in, classpath/examples/Makefile.in: Regenerate. * classpath/config.guess, classpath/config.sub, classpath/ltmain.sh : Update. * classpath/configure, classpath/depcomp, classpath/missing, classpath/aclocal.m4, classpath/install-sh: Regenerate. * gnu/classpath/Configuration.java (CLASSPATH_VERSION): Now 0.95. * sources.am: Regenerate. * Makefile.in: Regenerate. * Update the .class files and generated CNI header files, add new .class and generated CNI header files. * Remove generated files for removed java source files: classpath/gnu/java/net/BASE64.java, classpath/gnu/java/security/util/Base64.java, classpath/gnu/java/awt/peer/gtk/GThreadMutex.java, classpath/gnu/java/awt/peer/gtk/GThreadNativeMethodRunner.java, classpath/gnu/java/awt/font/autofit/Scaler.java, classpath/gnu/classpath/jdwp/util/Value.java, classpath/gnu/javax/net/ssl/Base64.java. * Remove empty directories. * Makefile.am(nat_source_files): Add natVMOperatingSystemMXBeanImpl.cc. * java/lang/Class.java(setAccessible): Merge from classpath. * java/util/Locale.java: Remove. * gnu/java/lang/management/VMOperatingSystemMXBeanImpl.java, gnu/java/lang/management/natVMOperatingSystemMXBeanImpl.cc: New. * gcj/javaprims.h: Update class declarations. * scripts/classes.pl: Update usage. * HACKING: Mention to build all peers. From-SVN: r125302
393 lines
16 KiB
Java
393 lines
16 KiB
Java
/* 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);
|
|
|
|
}
|