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}