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    }