KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > management > openmbean > 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 JavaDoc;
15 import java.util.Map JavaDoc;
16 import java.util.Set JavaDoc;
17 import java.util.Collection JavaDoc;
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 JavaDoc 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 JavaDoc[] calculateIndex(CompositeData JavaDoc 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 JavaDoc[] 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 JavaDoc 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 JavaDoc get(Object JavaDoc[] 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 JavaDoc 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 JavaDoc remove(Object JavaDoc[] 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 JavaDoc[] 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 JavaDoc 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 JavaDoc 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 JavaDoc 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 JavaDoc toString();
283
284 }
285
Popular Tags