Frames | No Frames |
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 59: * the given value is the same as the row type of this instance, 60: * but not a check for existing instances of the given value. 61: * The value must also not be <code>null</code>. Possible indices 62: * are returned by the {@link TabularType#getIndexNames()} method 63: * of this instance's tabular type. 64: * 65: * @param val the {@link CompositeData} value whose index should 66: * be calculated. 67: * @return the index the value would take on, if it were to be added. 68: * @throws NullPointerException if the value is <code>null</code>. 69: * @throws InvalidOpenTypeException if the value does not match the 70: * row type of this instance. 71: */ 72: Object[] calculateIndex(CompositeData val); 73: 74: /** 75: * Removes all {@link CompositeData} values from the table. 76: */ 77: void clear(); 78: 79: /** 80: * Returns true iff this instance of the {@link TabularData} class 81: * contains a {@link CompositeData} value at the specified index. 82: * In any other circumstance, including if the given key 83: * is <code>null</code> or of the incorrect type, according to 84: * the {@link TabularType} of this instance, this method returns 85: * false. 86: * 87: * @param key the key to test for. 88: * @return true if the key maps to a {@link CompositeData} value. 89: */ 90: boolean containsKey(Object[] key); 91: 92: /** 93: * Returns true iff this instance of the {@link TabularData} class 94: * contains the specified {@link CompositeData} value. 95: * In any other circumstance, including if the given value 96: * is <code>null</code> or of the incorrect type, according to 97: * the {@link TabularType} of this instance, this method returns 98: * false. 99: * 100: * @param val the value to test for. 101: * @return true if the value exists. 102: */ 103: boolean containsValue(CompositeData val); 104: 105: /** 106: * Compares the specified object with this object for equality. 107: * The object is judged equivalent if it is non-null, and also 108: * an instance of {@link TabularData} with the same row type, 109: * and index to value mappings. The two compared instances may 110: * be equivalent even if they represent different implementations 111: * of {@link TabularData}. 112: * 113: * @param obj the object to compare for equality. 114: * @return true if <code>obj</code> is equal to <code>this</code>. 115: */ 116: boolean equals(Object obj); 117: 118: /** 119: * Retrieves the {@link CompositeData} value for the specified 120: * key, or <code>null</code> if no such mapping exists. 121: * 122: * @param key the key whose value should be returned. 123: * @return the matching {@link CompositeData} value, or 124: * <code>null</code> if one does not exist. 125: * @throws NullPointerException if the key is <code>null</code>. 126: * @throws InvalidOpenTypeException if the key does not match 127: * the {@link TabularType} of this 128: * instance. 129: */ 130: CompositeData get(Object[] key); 131: 132: /** 133: * Returns the tabular type which corresponds to this instance 134: * of {@link TabularData}. 135: * 136: * @return the tabular type for this instance. 137: */ 138: TabularType getTabularType(); 139: 140: /** 141: * Returns the hash code of the composite data type. 142: * This is computed as the sum of the hash codes of the 143: * each index and its value, together with the hash 144: * code of the tabular type. These are the same elements 145: * of the type that are compared as part of the 146: * {@link #equals(java.lang.Object)} method, thus ensuring 147: * that the hashcode is compatible with the equality 148: * 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. 200: * 201: * @param vals the {@link CompositeData} values to add. 202: * @throws NullPointerException if <code>val</code> is 203: * <code>null</code>. 204: * @throws InvalidOpenTypeException if the type of the 205: * given value does not 206: * match the row type. 207: * @throws KeyAlreadyExistsException if the value has the 208: * same calculated index 209: * as an existing value or 210: * of one of the other 211: * specified values. 212: */ 213: void putAll(CompositeData[] vals); 214: 215: /** 216: * Removes the {@link CompositeData} value located at the 217: * specified index. <code>null</code> is returned if the 218: * value does not exist. Otherwise, the removed value is 219: * returned. 220: * 221: * @param key the key of the value to remove. 222: * @return the removed value, or <code>null</code> if 223: * there is no value for the given key. 224: * @throws NullPointerException if the key is <code>null</code>. 225: * @throws InvalidOpenTypeException if the key does not match 226: * the {@link TabularType} of this 227: * instance. 228: */ 229: CompositeData remove(Object[] key); 230: 231: /** 232: * Returns the number of {@link CompositeData} values or rows 233: * in the table. 234: * 235: * @return the number of rows in the table. 236: */ 237: int size(); 238: 239: /** 240: * Returns a textual representation of this instance. The 241: * exact format is left up to the implementation, but it 242: * should contain the name of the implementing class and 243: * the tabular type. 244: * 245: * @return a {@link java.lang.String} representation of the 246: * object. 247: */ 248: String toString(); 249: 250: /** 251: * Returns the values associated with this instance. 252: * 253: * @return the values of this instance. 254: */ 255: Collection values(); 256: 257: }