1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
|
/* TabularData.java -- Tables of composite data structures.
Copyright (C) 2006, 2007 Free Software Foundation, Inc.
This file is part of GNU Classpath.
GNU Classpath is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2, or (at your option)
any later version.
GNU Classpath is distributed in the hope that it will be useful, but
WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public License
along with GNU Classpath; see the file COPYING. If not, write to the
Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA
02110-1301 USA.
Linking this library statically or dynamically with other modules is
making a combined work based on this library. Thus, the terms and
conditions of the GNU General Public License cover the whole
combination.
As a special exception, the copyright holders of this library give you
permission to link this library with independent modules to produce an
executable, regardless of the license terms of these independent
modules, and to copy and distribute the resulting executable under
terms of your choice, provided that you also meet, for each linked
independent module, the terms and conditions of the license of that
module. An independent module is a module which is not derived from
or based on this library. If you modify this library, you may extend
this exception to your version of the library, but you are not
obligated to do so. If you do not wish to do so, delete this
exception statement from your version. */
package javax.management.openmbean;
import java.util.Collection;
import java.util.Set;
/**
* Provides an interface to a specific type of composite
* data structure, where keys (the columns) map to the
* {@link CompositeData} objects that form the rows of
* the table.
*
* @author Andrew John Hughes (gnu_andrew@member.fsf.org)
* @since 1.5
*/
public interface TabularData
{
/**
* Calculates the index the specified {@link CompositeData} value
* would have, if it was to be added to this {@link TabularData}
* instance. This method includes a check that the type of the
* given value is the same as the row type of this instance, but not
* a check for existing instances of the given value. The value
* must also not be <code>null</code>. Possible indices are
* returned by the {@link TabularType#getIndexNames()} method of
* this instance's tabular type. The returned indices are the
* values of the fields in the supplied {@link CompositeData}
* instance that match the names given in the {@link TabularType}.
*
* @param val the {@link CompositeData} value whose index should
* be calculated.
* @return the index the value would take on, if it were to be added.
* @throws NullPointerException if the value is <code>null</code>.
* @throws InvalidOpenTypeException if the value does not match the
* row type of this instance.
*/
Object[] calculateIndex(CompositeData val);
/**
* Removes all {@link CompositeData} values from the table.
*/
void clear();
/**
* Returns true iff this instance of the {@link TabularData} class
* contains a {@link CompositeData} value at the specified index.
* In any other circumstance, including if the given key
* is <code>null</code> or of the incorrect type, according to
* the {@link TabularType} of this instance, this method returns
* false.
*
* @param key the key to test for.
* @return true if the key maps to a {@link CompositeData} value.
*/
boolean containsKey(Object[] key);
/**
* Returns true iff this instance of the {@link TabularData} class
* contains the specified {@link CompositeData} value.
* In any other circumstance, including if the given value
* is <code>null</code> or of the incorrect type, according to
* the {@link TabularType} of this instance, this method returns
* false.
*
* @param val the value to test for.
* @return true if the value exists.
*/
boolean containsValue(CompositeData val);
/**
* Compares the specified object with this object for equality.
* The object is judged equivalent if it is non-null, and also
* an instance of {@link TabularData} with the same row type,
* and {@link CompositeData} values. The two compared instances may
* be equivalent even if they represent different implementations
* of {@link TabularData}.
*
* @param obj the object to compare for equality.
* @return true if <code>obj</code> is equal to <code>this</code>.
*/
boolean equals(Object obj);
/**
* Retrieves the {@link CompositeData} value for the specified
* key, or <code>null</code> if no such mapping exists.
*
* @param key the key whose value should be returned.
* @return the matching {@link CompositeData} value, or
* <code>null</code> if one does not exist.
* @throws NullPointerException if the key is <code>null</code>.
* @throws InvalidKeyException if the key does not match
* the {@link TabularType} of this
* instance.
*/
CompositeData get(Object[] key);
/**
* Returns the tabular type which corresponds to this instance
* of {@link TabularData}.
*
* @return the tabular type for this instance.
*/
TabularType getTabularType();
/**
* Returns the hash code of the composite data type. This is
* computed as the sum of the hash codes of each value, together
* with the hash code of the tabular type. These are the same
* elements of the type that are compared as part of the {@link
* #equals(java.lang.Object)} method, thus ensuring that the
* hashcode is compatible with the equality test.
*
* @return the hash code of this instance.
*/
int hashCode();
/**
* Returns true if this {@link TabularData} instance
* contains no {@link CompositeData} values.
*
* @return true if the instance is devoid of rows.
*/
boolean isEmpty();
/**
* Returns a {@link java.util.Set} view of the keys or
* indices of this {@link TabularData} instance.
*
* @return a set containing the keys of this instance.
*/
Set<?> keySet();
/**
* Adds the specified {@link CompositeData} value to the
* table. The value must be non-null, of the same type
* as the row type of this instance, and must not have
* the same index as an existing value. The index is
* calculated using the index names of the
* {@link TabularType} for this instance.
*
* @param val the {@link CompositeData} value to add.
* @throws NullPointerException if <code>val</code> is
* <code>null</code>.
* @throws InvalidOpenTypeException if the type of the
* given value does not
* match the row type.
* @throws KeyAlreadyExistsException if the value has the
* same calculated index
* as an existing value.
*/
void put(CompositeData val);
/**
* Adds each of the specified {@link CompositeData} values
* to the table. Each element of the array must meet the
* conditions given for the {@link #put(CompositeData)}
* method. In addition, the index of each value in the
* array must be distinct from the index of the other
* values in the array, as well as from the existing values
* in the table. The operation should be atomic; if one
* value can not be added, then none of the values should
* be. If the array is <code>null</code> or empty, the
* method simply returns.
*
* @param vals the {@link CompositeData} values to add.
* @throws NullPointerException if a value from the array is
* <code>null</code>.
* @throws InvalidOpenTypeException if the type of a
* given value does not
* match the row type.
* @throws KeyAlreadyExistsException if a value has the
* same calculated index
* as an existing value or
* of one of the other
* specified values.
*/
void putAll(CompositeData[] vals);
/**
* Removes the {@link CompositeData} value located at the
* specified index. <code>null</code> is returned if the
* value does not exist. Otherwise, the removed value is
* returned.
*
* @param key the key of the value to remove.
* @return the removed value, or <code>null</code> if
* there is no value for the given key.
* @throws NullPointerException if the key is <code>null</code>.
* @throws InvalidOpenTypeException if the key does not match
* the {@link TabularType} of this
* instance.
*/
CompositeData remove(Object[] key);
/**
* Returns the number of {@link CompositeData} values or rows
* in the table.
*
* @return the number of rows in the table.
*/
int size();
/**
* Returns a textual representation of this instance. The
* exact format is left up to the implementation, but it
* should contain the name of the implementing class and
* the tabular type.
*
* @return a {@link java.lang.String} representation of the
* object.
*/
String toString();
/**
* Returns the values associated with this instance.
*
* @return the values of this instance.
*/
Collection<?> values();
}
|
