001 /* TabularData.java -- Tables of composite data structures. 002 Copyright (C) 2006, 2007 Free Software Foundation, Inc. 003 004 This file is part of GNU Classpath. 005 006 GNU Classpath is free software; you can redistribute it and/or modify 007 it under the terms of the GNU General Public License as published by 008 the Free Software Foundation; either version 2, or (at your option) 009 any later version. 010 011 GNU Classpath is distributed in the hope that it will be useful, but 012 WITHOUT ANY WARRANTY; without even the implied warranty of 013 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 014 General Public License for more details. 015 016 You should have received a copy of the GNU General Public License 017 along with GNU Classpath; see the file COPYING. If not, write to the 018 Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 019 02110-1301 USA. 020 021 Linking this library statically or dynamically with other modules is 022 making a combined work based on this library. Thus, the terms and 023 conditions of the GNU General Public License cover the whole 024 combination. 025 026 As a special exception, the copyright holders of this library give you 027 permission to link this library with independent modules to produce an 028 executable, regardless of the license terms of these independent 029 modules, and to copy and distribute the resulting executable under 030 terms of your choice, provided that you also meet, for each linked 031 independent module, the terms and conditions of the license of that 032 module. An independent module is a module which is not derived from 033 or based on this library. If you modify this library, you may extend 034 this exception to your version of the library, but you are not 035 obligated to do so. If you do not wish to do so, delete this 036 exception statement from your version. */ 037 038 package javax.management.openmbean; 039 040 import java.util.Collection; 041 import java.util.Set; 042 043 /** 044 * Provides an interface to a specific type of composite 045 * data structure, where keys (the columns) map to the 046 * {@link CompositeData} objects that form the rows of 047 * the table. 048 * 049 * @author Andrew John Hughes (gnu_andrew@member.fsf.org) 050 * @since 1.5 051 */ 052 public interface TabularData 053 { 054 055 /** 056 * Calculates the index the specified {@link CompositeData} value 057 * would have, if it was to be added to this {@link TabularData} 058 * instance. This method includes a check that the type of the 059 * given value is the same as the row type of this instance, but not 060 * a check for existing instances of the given value. The value 061 * must also not be <code>null</code>. Possible indices are 062 * returned by the {@link TabularType#getIndexNames()} method of 063 * this instance's tabular type. The returned indices are the 064 * values of the fields in the supplied {@link CompositeData} 065 * instance that match the names given in the {@link TabularType}. 066 * 067 * @param val the {@link CompositeData} value whose index should 068 * be calculated. 069 * @return the index the value would take on, if it were to be added. 070 * @throws NullPointerException if the value is <code>null</code>. 071 * @throws InvalidOpenTypeException if the value does not match the 072 * row type of this instance. 073 */ 074 Object[] calculateIndex(CompositeData val); 075 076 /** 077 * Removes all {@link CompositeData} values from the table. 078 */ 079 void clear(); 080 081 /** 082 * Returns true iff this instance of the {@link TabularData} class 083 * contains a {@link CompositeData} value at the specified index. 084 * In any other circumstance, including if the given key 085 * is <code>null</code> or of the incorrect type, according to 086 * the {@link TabularType} of this instance, this method returns 087 * false. 088 * 089 * @param key the key to test for. 090 * @return true if the key maps to a {@link CompositeData} value. 091 */ 092 boolean containsKey(Object[] key); 093 094 /** 095 * Returns true iff this instance of the {@link TabularData} class 096 * contains the specified {@link CompositeData} value. 097 * In any other circumstance, including if the given value 098 * is <code>null</code> or of the incorrect type, according to 099 * 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 }