| Frames | No Frames |
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: }