Source for javax.management.openmbean.TabularData

   1: /* TabularData.java -- Tables of composite data structures.
   2:    Copyright (C) 2006, 2007 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: }