/* 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);

}