libjava/classpath/javax/management/openmbean/TabularData.java

   1 /* TabularData.java -- Tables of composite data structures.
   2    Copyright (C) 2006 Free Software Foundation, Inc.
   3
   4 This file is part of GNU Classpath.
   5
   6 GNU Classpath is free software; you can redistribute it and/or modify
   7 it under the terms of the GNU General Public License as published by
   8 the Free Software Foundation; either version 2, or (at your option)
   9 any later version.
  10
  11 GNU Classpath is distributed in the hope that it will be useful, but
  12 WITHOUT ANY WARRANTY; without even the implied warranty of
  13 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
  14 General Public License for more details.
  15
  16 You should have received a copy of the GNU General Public License
  17 along with GNU Classpath; see the file COPYING.  If not, write to the
  18 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
  19 02110-1301 USA.
  20
  21 Linking this library statically or dynamically with other modules is
  22 making a combined work based on this library.  Thus, the terms and
  23 conditions of the GNU General Public License cover the whole
  24 combination.
  25
  26 As a special exception, the copyright holders of this library give you
  27 permission to link this library with independent modules to produce an
  28 executable, regardless of the license terms of these independent
  29 modules, and to copy and distribute the resulting executable under
  30 terms of your choice, provided that you also meet, for each linked
  31 independent module, the terms and conditions of the license of that
  32 module.  An independent module is a module which is not derived from
  33 or based on this library.  If you modify this library, you may extend
  34 this exception to your version of the library, but you are not
  35 obligated to do so.  If you do not wish to do so, delete this
  36 exception statement from your version. */
  37
  38 package javax.management.openmbean;
  39
  40 import java.util.Collection;
  41 import java.util.Set;
  42
  43 /**
  44  * Provides an interface to a specific type of composite
  45  * data structure, where keys (the columns) map to the
  46  * {@link CompositeData} objects that form the rows of
  47  * the table.
  48  *
  49  * @author Andrew John Hughes (gnu_andrew@member.fsf.org)
  50  * @since 1.5
  51  */
  52 public interface TabularData
  53 {
  54
  55   /**
  56    * Calculates the index the specified {@link CompositeData} value
  57    * would have, if it was to be added to this {@link TabularData}
  58    * instance.  This method includes a check that the type of the
  59    * given value is the same as the row type of this instance, but not
  60    * a check for existing instances of the given value.  The value
  61    * must also not be <code>null</code>.  Possible indices are
  62    * returned by the {@link TabularType#getIndexNames()} method of
  63    * this instance's tabular type.  The returned indices are the
  64    * values of the fields in the supplied {@link CompositeData}
  65    * instance that match the names given in the {@link TabularType}.
  66    *
  67    * @param val the {@link CompositeData} value whose index should
  68    *            be calculated.
  69    * @return the index the value would take on, if it were to be added.
  70    * @throws NullPointerException if the value is <code>null</code>.
  71    * @throws InvalidOpenTypeException if the value does not match the
  72    *                                  row type of this instance.
  73    */
  74   Object[] calculateIndex(CompositeData val);
  75
  76   /**
  77    * Removes all {@link CompositeData} values from the table.
  78    */
  79   void clear();
  80
  81   /**
  82    * Returns true iff this instance of the {@link TabularData} class
  83    * contains a {@link CompositeData} value at the specified index.
  84    * In any other circumstance, including if the given key
  85    * is <code>null</code> or of the incorrect type, according to
  86    * the {@link TabularType} of this instance, this method returns
  87    * false.
  88    *
  89    * @param key the key to test for.
  90    * @return true if the key maps to a {@link CompositeData} value.
  91    */
  92   boolean containsKey(Object[] key);
  93
  94   /**
  95    * Returns true iff this instance of the {@link TabularData} class
  96    * contains the specified {@link CompositeData} value.
  97    * In any other circumstance, including if the given value
  98    * is <code>null</code> or of the incorrect type, according to
  99    * the {@link TabularType} of this instance, this method returns
 100    * false.
 101    *
 102    * @param val the value to test for.
 103    * @return true if the value exists.
 104    */
 105   boolean containsValue(CompositeData val);
 106
 107   /**
 108    * Compares the specified object with this object for equality.
 109    * The object is judged equivalent if it is non-null, and also
 110    * an instance of {@link TabularData} with the same row type,
 111    * and {@link CompositeData} values.  The two compared instances may
 112    * be equivalent even if they represent different implementations
 113    * of {@link TabularData}.
 114    *
 115    * @param obj the object to compare for equality.
 116    * @return true if <code>obj</code> is equal to <code>this</code>.
 117    */
 118   boolean equals(Object obj);
 119
 120   /**
 121    * Retrieves the {@link CompositeData} value for the specified
 122    * key, or <code>null</code> if no such mapping exists.
 123    *
 124    * @param key the key whose value should be returned.
 125    * @return the matching {@link CompositeData} value, or
 126    *         <code>null</code> if one does not exist.
 127    * @throws NullPointerException if the key is <code>null</code>.
 128    * @throws InvalidKeyException if the key does not match
 129    *                             the {@link TabularType} of this
 130    *                             instance.
 131    */
 132   CompositeData get(Object[] key);
 133
 134   /**
 135    * Returns the tabular type which corresponds to this instance
 136    * of {@link TabularData}.
 137    *
 138    * @return the tabular type for this instance.
 139    */
 140   TabularType getTabularType();
 141
 142   /**
 143    * Returns the hash code of the composite data type.  This is
 144    * computed as the sum of the hash codes of each value, together
 145    * with the hash code of the tabular type.  These are the same
 146    * elements of the type that are compared as part of the {@link
 147    * #equals(java.lang.Object)} method, thus ensuring that the
 148    * hashcode is compatible with the equality test.
 149    *
 150    * @return the hash code of this instance.
 151    */
 152   int hashCode();
 153
 154   /**
 155    * Returns true if this {@link TabularData} instance
 156    * contains no {@link CompositeData} values.
 157    *
 158    * @return true if the instance is devoid of rows.
 159    */
 160   boolean isEmpty();
 161
 162   /**
 163    * Returns a {@link java.util.Set} view of the keys or
 164    * indices of this {@link TabularData} instance.
 165    *
 166    * @return a set containing the keys of this instance.
 167    */
 168   Set keySet();
 169
 170   /**
 171    * Adds the specified {@link CompositeData} value to the
 172    * table.  The value must be non-null, of the same type
 173    * as the row type of this instance, and must not have
 174    * the same index as an existing value.  The index is
 175    * calculated using the index names of the
 176    * {@link TabularType} for this instance.
 177    *
 178    * @param val the {@link CompositeData} value to add.
 179    * @throws NullPointerException if <code>val</code> is
 180    *                              <code>null</code>.
 181    * @throws InvalidOpenTypeException if the type of the
 182    *                                  given value does not
 183    *                                  match the row type.
 184    * @throws KeyAlreadyExistsException if the value has the
 185    *                                   same calculated index
 186    *                                   as an existing value.
 187    */
 188   void put(CompositeData val);
 189
 190   /**
 191    * Adds each of the specified {@link CompositeData} values
 192    * to the table.  Each element of the array must meet the
 193    * conditions given for the {@link #put(CompositeData)}
 194    * method.  In addition, the index of each value in the
 195    * array must be distinct from the index of the other
 196    * values in the array, as well as from the existing values
 197    * in the table.  The operation should be atomic; if one
 198    * value can not be added, then none of the values should
 199    * be.  If the array is <code>null</code> or empty, the
 200    * method simply returns.
 201    *
 202    * @param vals the {@link CompositeData} values to add.
 203    * @throws NullPointerException if a value from the array is
 204    *                              <code>null</code>.
 205    * @throws InvalidOpenTypeException if the type of a
 206    *                                  given value does not
 207    *                                  match the row type.
 208    * @throws KeyAlreadyExistsException if a value has the
 209    *                                   same calculated index
 210    *                                   as an existing value or
 211    *                                   of one of the other
 212    *                                   specified values.
 213    */
 214   void putAll(CompositeData[] vals);
 215
 216   /**
 217    * Removes the {@link CompositeData} value located at the
 218    * specified index.  <code>null</code> is returned if the
 219    * value does not exist.  Otherwise, the removed value is
 220    * returned.
 221    *
 222    * @param key the key of the value to remove.
 223    * @return the removed value, or <code>null</code> if
 224    *         there is no value for the given key.
 225    * @throws NullPointerException if the key is <code>null</code>.
 226    * @throws InvalidOpenTypeException if the key does not match
 227    *                                  the {@link TabularType} of this
 228    *                                  instance.
 229    */
 230   CompositeData remove(Object[] key);
 231
 232   /**
 233    * Returns the number of {@link CompositeData} values or rows
 234    * in the table.
 235    *
 236    * @return the number of rows in the table.
 237    */
 238   int size();
 239
 240   /**
 241    * Returns a textual representation of this instance.  The
 242    * exact format is left up to the implementation, but it
 243    * should contain the name of the implementing class and
 244    * the tabular type.
 245    *
 246    * @return a {@link java.lang.String} representation of the
 247    *         object.
 248    */
 249   String toString();
 250
 251   /**
 252    * Returns the values associated with this instance.
 253    *
 254    * @return the values of this instance.
 255    */
 256   Collection values();
 257
 258 }
 259