TabularData


1   /*
2    * @(#)TabularData.java 3.19 04/02/10
3    * 
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   
9   package javax.management.openmbean;
10  
11  
12  // java import
13  //
14  import java.io.Serializable  ;
15  import java.util.Map  ;
16  import java.util.Set  ;
17  import java.util.Collection  ;
18  
19  // jmx import
20  //
21  
22  
23  /**
24   * The <tt>TabularData</tt> interface specifies the behavior of a specific type of complex <i>open data</i> objects
25   * which represent <i>tabular data</i> structures.
26   *
27   * @version     3.19  04/02/10
28   * @author      Sun Microsystems, Inc.
29   *
30   * @since 1.5
31   * @since.unbundled JMX 1.1
32   */
33  public interface TabularData /*extends Map*/ { 
34  
35  
36      /* *** TabularData specific information methods *** */
37  
38  
39      /**
40       * Returns the <i>tabular type</i> describing this
41       * <tt>TabularData</tt> instance.
42       *
43       * @return the tabular type.
44       */
45      public TabularType   getTabularType();
46  
47  
48      /**
49       * Calculates the index that would be used in this <tt>TabularData</tt> instance to refer to the specified
50       * composite data <var>value</var> parameter if it were added to this instance.
51       * This method checks for the type validity of the specified <var>value</var>, 
52       * but does not check if the calculated index is already used to refer to a value in this <tt>TabularData</tt> instance.
53       *
54       * @param  value              the composite data value whose index in this 
55       *                    <tt>TabularData</tt> instance is to be calculated;
56       *                    must be of the same composite type as this instance's row type;
57       *                    must not be null.
58       *
59       * @return the index that the specified <var>value</var> would have in this <tt>TabularData</tt> instance.
60       * 
61       * @throws NullPointerException       if <var>value</var> is <tt>null</tt> 
62       * 
63       * @throws InvalidOpenTypeException   if <var>value</var> does not conform to this <tt>TabularData</tt> instance's 
64       *                        row type definition.
65       */
66      public Object  [] calculateIndex(CompositeData   value) ;
67  
68  
69  
70  
71      /* *** Content information query methods *** */
72  
73      /**
74       * Returns the number of <tt>CompositeData</tt> values (ie the
75       * number of rows) contained in this <tt>TabularData</tt>
76       * instance.
77       *
78       * @return the number of values contained.
79       */
80      public int size() ;
81  
82      /**
83       * Returns <tt>true</tt> if the number of <tt>CompositeData</tt>
84       * values (ie the number of rows) contained in this
85       * <tt>TabularData</tt> instance is zero.
86       *
87       * @return true if this <tt>TabularData</tt> is empty.
88       */
89      public boolean isEmpty() ;
90  
91      /**
92       * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains a <tt>CompositeData</tt> value 
93       * (ie a row) whose index is the specified <var>key</var>. If <var>key</var> is <tt>null</tt> or does not conform to
94       * this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition, this method simply returns <tt>false</tt>.
95       * 
96       * @param  key  the index value whose presence in this <tt>TabularData</tt> instance is to be tested.
97       *
98       * @return  <tt>true</tt> if this <tt>TabularData</tt> indexes a row value with the specified key.
99       */ 
100     public boolean containsKey(Object  [] key) ;
101 
102     /**
103      * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains the specified
104      * <tt>CompositeData</tt> value. If <var>value</var> is <tt>null</tt> or does not conform to
105      * this <tt>TabularData</tt> instance's row type definition, this method simply returns <tt>false</tt>.
106      *
107      * @param  value  the row value whose presence in this <tt>TabularData</tt> instance is to be tested.
108      *
109      * @return  <tt>true</tt> if this <tt>TabularData</tt> instance contains the specified row value.
110      */
111     public boolean containsValue(CompositeData   value) ;
112 
113     /**
114      * Returns the <tt>CompositeData</tt> value whose index is
115      * <var>key</var>, or <tt>null</tt> if there is no value mapping
116      * to <var>key</var>, in this <tt>TabularData</tt> instance.
117      *
118      * @param key the key of the row to return.
119      *
120      * @return the value corresponding to <var>key</var>.
121      *
122      * @throws NullPointerException if the <var>key</var> is
123      * <tt>null</tt>
124      * @throws InvalidKeyException if the <var>key</var> does not
125      * conform to this <tt>TabularData</tt> instance's *
126      * <tt>TabularType</tt> definition
127      */
128     public CompositeData   get(Object  [] key) ;
129 
130 
131 
132 
133     /* *** Content modification operations (one element at a time) *** */
134 
135 
136     /**
137      * Adds <var>value</var> to this <tt>TabularData</tt> instance.
138      * The composite type of <var>value</var> must be the same as this
139      * instance's row type (ie the composite type returned by
140      * <tt>this.getTabularType().{@link TabularType#getRowType
141      * getRowType()}</tt>), and there must not already be an existing
142      * value in this <tt>TabularData</tt> instance whose index is the
143      * same as the one calculated for the <var>value</var> to be
144      * added. The index for <var>value</var> is calculated according
145      * to this <tt>TabularData</tt> instance's <tt>TabularType</tt>
146      * definition (see <tt>TabularType.{@link
147      * TabularType#getIndexNames getIndexNames()}</tt>).
148      *
149      * @param  value              the composite data value to be added as a new row to this <tt>TabularData</tt> instance;
150      *                    must be of the same composite type as this instance's row type;
151      *                    must not be null.
152      *
153      * @throws NullPointerException       if <var>value</var> is <tt>null</tt> 
154      * @throws InvalidOpenTypeException   if <var>value</var> does not conform to this <tt>TabularData</tt> instance's 
155      *                        row type definition.
156      * @throws KeyAlreadyExistsException  if the index for <var>value</var>, calculated according to 
157      *                    this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition 
158      *                    already maps to an existing value in the underlying HashMap.
159      */
160     public void put(CompositeData   value) ;
161 
162     /**
163      * Removes the <tt>CompositeData</tt> value whose index is <var>key</var> from this <tt>TabularData</tt> instance,
164      * and returns the removed value, or returns <tt>null</tt> if there is no value whose index is <var>key</var>.
165      *
166      * @param  key  the index of the value to get in this <tt>TabularData</tt> instance;
167      *          must be valid with this <tt>TabularData</tt> instance's row type definition;
168      *          must not be null.
169      * 
170      * @return previous value associated with specified key, or <tt>null</tt>
171      *         if there was no mapping for key.  
172      *
173      * @throws NullPointerException  if the <var>key</var> is <tt>null</tt> 
174      * @throws InvalidKeyException   if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's 
175      *                   <tt>TabularType</tt> definition 
176      */
177     public CompositeData   remove(Object  [] key) ;
178 
179 
180 
181 
182     /* ***   Content modification bulk operations   *** */
183 
184 
185     /**
186      * Add all the elements in <var>values</var> to this <tt>TabularData</tt> instance. 
187      * If any  element in <var>values</var> does not satisfy the constraints defined in {@link #put(CompositeData) <tt>put</tt>},
188      * or if any two elements in <var>values</var> have the same index calculated according to this <tt>TabularData</tt> 
189      * instance's <tt>TabularType</tt> definition, then an exception describing the failure is thrown 
190      * and no element of <var>values</var> is added,  thus leaving this <tt>TabularData</tt> instance unchanged.
191      *
192      * @param  values  the array of composite data values to be added as new rows to this <tt>TabularData</tt> instance;
193      *             if <var>values</var> is <tt>null</tt> or empty, this method returns without doing anything.
194      * 
195      * @throws NullPointerException       if an element of <var>values</var> is <tt>null</tt> 
196      * @throws InvalidOpenTypeException   if an element of <var>values</var> does not conform to 
197      *                    this <tt>TabularData</tt> instance's row type definition 
198      * @throws KeyAlreadyExistsException  if the index for an element of <var>values</var>, calculated according to 
199      *                    this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition 
200      *                    already maps to an existing value in this instance,
201      *                    or two elements of <var>values</var> have the same index.
202      */
203     public void putAll(CompositeData  [] values) ;
204 
205     /**
206      * Removes all <tt>CompositeData</tt> values (ie rows) from this <tt>TabularData</tt> instance.
207      */
208     public void clear();
209 
210 
211 
212 
213     /* ***   Collection views of the keys and values   *** */
214 
215 
216     /**
217      * Returns a set view of the keys (ie the index values) of the <tt>CompositeData</tt> values (ie the rows) 
218      * contained in this <tt>TabularData</tt> instance. The returned Set can then be used to iterate over the keys.
219      *
220      * @return a set view of the index values used in this <tt>TabularData</tt> instance.
221      */
222     public Set   keySet();
223 
224     /**
225      * Returns a collection view of the <tt>CompositeData</tt> values (ie the rows) 
226      * contained in this <tt>TabularData</tt> instance. 
227      * The returned collection can then be used to iterate over the values.
228      *
229      * @return a collection view of the rows contained in this <tt>TabularData</tt> instance.
230      */
231     public Collection   values();
232 
233 
234 
235 
236     /* ***  Commodity methods from java.lang.Object  *** */
237 
238 
239     /**
240      * Compares the specified <var>obj</var> parameter with this <code>TabularData</code> instance for equality. 
241      * <p>
242      * Returns <tt>true</tt> if and only if all of the following statements are true:
243      * <ul>
244      * <li><var>obj</var> is non null,</li>
245      * <li><var>obj</var> also implements the <code>TabularData</code> interface,</li>
246      * <li>their row types are equal</li>
247      * <li>their contents (ie index to value mappings) are equal</li>
248      * </ul>
249      * This ensures that this <tt>equals</tt> method works properly for <var>obj</var> parameters which are
250      * different implementations of the <code>TabularData</code> interface.
251      * <br>&nbsp;
252      * @param  obj  the object to be compared for equality with this <code>TabularData</code> instance;
253      * 
254      * @return  <code>true</code> if the specified object is equal to this <code>TabularData</code> instance.
255      */
256     public boolean equals(Object   obj);
257 
258     /**
259      * Returns the hash code value for this <code>TabularData</code> instance. 
260      * <p>
261      * The hash code of a <code>TabularData</code> instance is the sum of the hash codes
262      * of all elements of information used in <code>equals</code> comparisons 
263      * (ie: its <i>tabular type</i> and its content, where the content is defined as all the index to value mappings). 
264      * <p>
265      * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code> 
266      * for any two <code>TabularDataSupport</code> instances <code>t1</code> and <code>t2</code>, 
267      * as required by the general contract of the method
268      * {@link Object#hashCode() Object.hashCode()}.
269      *
270      * @return  the hash code value for this <code>TabularDataSupport</code> instance
271      */
272     public int hashCode();
273 
274     /**
275      * Returns a string representation of this <code>TabularData</code> instance. 
276      * <p>
277      * The string representation consists of the name of the implementing class, 
278      * and the tabular type of this instance.
279      * 
280      * @return  a string representation of this <code>TabularData</code> instance
281      */
282     public String   toString();
283 
284 }
285
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags