001: /* JFox, the OpenSource J2EE Application Server
002: *
003: * Copyright (C) 2002 huihoo.org
004: * Distributable under GNU LGPL license
005: * See the GNU Lesser General Public License for more details.
006: */
007:
008: package javax.management.openmbean;
009:
010: import java.util.Set;
011: import java.util.Collection;
012: import javax.management.openmbean.CompositeData;
013:
014: /**
015: * The <tt>TabularData</tt> interface specifies the behaviour of a specific type of complex <i>open data</i> objects
016: * which represent <i>tabular data</i> structures.
017: *
018: * @author <a href="mailto:young_yy@hotmail.org">Young Yang</a>
019: */
020:
021: public interface TabularData {
022:
023: /* *** TabularData specific information methods *** */
024:
025: /**
026: * Returns the <i>tabular type</i> describing this
027: * <tt>TabularData</tt> instance.
028: *
029: * @return the tabular type.
030: */
031: public TabularType getTabularType();
032:
033: /**
034: * Calculates the index that would be used in this <tt>TabularData</tt> instance to refer to the specified
035: * composite data <var>value</var> parameter if it were added to this instance.
036: * This method checks for the type validity of the specified <var>value</var>,
037: * but does not check if the calculated index is already used to refer to a value in this <tt>TabularData</tt> instance.
038: *
039: * @param value the composite data value whose index in this
040: * <tt>TabularData</tt> instance is to be calculated;
041: * must be of the same composite type as this instance's row type;
042: * must not be null.
043: *
044: * @return the index that the specified <var>value</var> would have in this <tt>TabularData</tt> instance.
045: *
046: * @throws NullPointerException if <var>value</var> is <tt>null</tt>
047: *
048: * @throws InvalidOpenTypeException if <var>value</var> does not conform to this <tt>TabularData</tt> instance's
049: * row type definition.
050: */
051: public Object[] calculateIndex(CompositeData value);
052:
053: /* *** Content information query methods *** */
054:
055: /**
056: * Returns the number of <tt>CompositeData</tt> values (ie the
057: * number of rows) contained in this <tt>TabularData</tt>
058: * instance.
059: *
060: * @return the number of values contained.
061: */
062: public int size();
063:
064: /**
065: * Returns <tt>true</tt> if the number of <tt>CompositeData</tt>
066: * values (ie the number of rows) contained in this
067: * <tt>TabularData</tt> instance is zero.
068: *
069: * @return true if this <tt>TabularData</tt> is empty.
070: */
071: public boolean isEmpty();
072:
073: /**
074: * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains a <tt>CompositeData</tt> value
075: * (ie a row) whose index is the specified <var>key</var>. If <var>key</var> is <tt>null</tt> or does not conform to
076: * this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition, this method simply returns <tt>false</tt>.
077: *
078: * @param key the index value whose presence in this <tt>TabularData</tt> instance is to be tested.
079: *
080: * @return <tt>true</tt> if this <tt>TabularData</tt> indexes a row value with the specified key.
081: */
082: public boolean containsKey(Object[] key);
083:
084: /**
085: * Returns <tt>true</tt> if and only if this <tt>TabularData</tt> instance contains the specified
086: * <tt>CompositeData</tt> value. If <var>value</var> is <tt>null</tt> or does not conform to
087: * this <tt>TabularData</tt> instance's row type definition, this method simply returns <tt>false</tt>.
088: *
089: * @param value the row value whose presence in this <tt>TabularData</tt> instance is to be tested.
090: *
091: * @return <tt>true</tt> if this <tt>TabularData</tt> instance contains the specified row value.
092: */
093: public boolean containsValue(CompositeData value);
094:
095: /**
096: * Returns the <tt>CompositeData</tt> value whose index is
097: * <var>key</var>, or <tt>null</tt> if there is no value mapping
098: * to <var>key</var>, in this <tt>TabularData</tt> instance.
099: *
100: * @param key the key of the row to return.
101: *
102: * @return the value corresponding to <var>key</var>.
103: *
104: * @throws NullPointerException if the <var>key</var> is
105: * <tt>null</tt>
106: * @throws InvalidKeyException if the <var>key</var> does not
107: * conform to this <tt>TabularData</tt> instance's *
108: * <tt>TabularType</tt> definition
109: */
110: public CompositeData get(Object[] key);
111:
112: /* *** Content modification operations (one element at a time) *** */
113:
114: /**
115: * Adds <var>value</var> to this <tt>TabularData</tt> instance.
116: * The composite type of <var>value</var> must be the same as this
117: * instance's row type (ie the composite type returned by
118: * <tt>this.getTabularType().{@link TabularType#getRowType
119: * getRowType()}</tt>), and there must not already be an existing
120: * value in this <tt>TabularData</tt> instance whose index is the
121: * same as the one calculated for the <var>value</var> to be
122: * added. The index for <var>value</var> is calculated according
123: * to this <tt>TabularData</tt> instance's <tt>TabularType</tt>
124: * definition (see <tt>TabularType.{@link
125: * TabularType#getIndexNames getIndexNames()}</tt>).
126: *
127: * @param value the composite data value to be added as a new row to this <tt>TabularData</tt> instance;
128: * must be of the same composite type as this instance's row type;
129: * must not be null.
130: *
131: * @throws NullPointerException if <var>value</var> is <tt>null</tt>
132: * @throws InvalidOpenTypeException if <var>value</var> does not conform to this <tt>TabularData</tt> instance's
133: * row type definition.
134: * @throws KeyAlreadyExistsException if the index for <var>value</var>, calculated according to
135: * this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition
136: * already maps to an existing value in the underlying HashMap.
137: */
138: public void put(CompositeData value);
139:
140: /**
141: * Removes the <tt>CompositeData</tt> value whose index is <var>key</var> from this <tt>TabularData</tt> instance,
142: * and returns the removed value, or returns <tt>null</tt> if there is no value whose index is <var>key</var>.
143: *
144: * @param key the index of the value to get in this <tt>TabularData</tt> instance;
145: * must be valid with this <tt>TabularData</tt> instance's row type definition;
146: * must not be null.
147: *
148: * @return previous value associated with specified key, or <tt>null</tt>
149: * if there was no mapping for key.
150: *
151: * @throws NullPointerException if the <var>key</var> is <tt>null</tt>
152: * @throws InvalidKeyException if the <var>key</var> does not conform to this <tt>TabularData</tt> instance's
153: * <tt>TabularType</tt> definition
154: */
155: public CompositeData remove(Object[] key);
156:
157: /* *** Content modification bulk operations *** */
158:
159: /**
160: * Add all the elements in <var>values</var> to this <tt>TabularData</tt> instance.
161: * If any element in <var>values</var> does not satisfy the constraints defined in {@link #put(CompositeData) <tt>put</tt>},
162: * or if any two elements in <var>values</var> have the same index calculated according to this <tt>TabularData</tt>
163: * instance's <tt>TabularType</tt> definition, then an exception describing the failure is thrown
164: * and no element of <var>values</var> is added, thus leaving this <tt>TabularData</tt> instance unchanged.
165: *
166: * @param values the array of composite data values to be added as new rows to this <tt>TabularData</tt> instance;
167: * if <var>values</var> is <tt>null</tt> or empty, this method returns without doing anything.
168: *
169: * @throws NullPointerException if an element of <var>values</var> is <tt>null</tt>
170: * @throws InvalidOpenTypeException if an element of <var>values</var> does not conform to
171: * this <tt>TabularData</tt> instance's row type definition
172: * @throws KeyAlreadyExistsException if the index for an element of <var>values</var>, calculated according to
173: * this <tt>TabularData</tt> instance's <tt>TabularType</tt> definition
174: * already maps to an existing value in this instance,
175: * or two elements of <var>values</var> have the same index.
176: */
177: public void putAll(CompositeData[] values);
178:
179: /**
180: * Removes all <tt>CompositeData</tt> values (ie rows) from this <tt>TabularData</tt> instance.
181: */
182: public void clear();
183:
184: /* *** Collection views of the keys and values *** */
185:
186: /**
187: * Returns a set view of the keys (ie the index values) of the <tt>CompositeData</tt> values (ie the rows)
188: * contained in this <tt>TabularData</tt> instance. The returned Set can then be used to iterate over the keys.
189: *
190: * @return a set view of the index values used in this <tt>TabularData</tt> instance.
191: */
192: public Set keySet();
193:
194: /**
195: * Returns a collection view of the <tt>CompositeData</tt> values (ie the rows)
196: * contained in this <tt>TabularData</tt> instance.
197: * The returned collection can then be used to iterate over the values.
198: *
199: * @return a collection view of the rows contained in this <tt>TabularData</tt> instance.
200: */
201: public Collection values();
202:
203: /* *** Commodity methods from java.lang.Object *** */
204:
205: /**
206: * Compares the specified <var>obj</var> parameter with this <code>TabularData</code> instance for equality.
207: * <p>
208: * Returns <tt>true</tt> if and only if all of the following statements are true:
209: * <ul>
210: * <li><var>obj</var> is non null,</li>
211: * <li><var>obj</var> also implements the <code>TabularData</code> interface,</li>
212: * <li>their row types are equal</li>
213: * <li>their contents (ie index to value mappings) are equal</li>
214: * </ul>
215: * This ensures that this <tt>equals</tt> method works properly for <var>obj</var> parameters which are
216: * different implementations of the <code>TabularData</code> interface.
217: * <br>
218: * @param obj the object to be compared for equality with this <code>TabularData</code> instance;
219: *
220: * @return <code>true</code> if the specified object is equal to this <code>TabularData</code> instance.
221: */
222: public boolean equals(Object obj);
223:
224: /**
225: * Returns the hash code value for this <code>TabularData</code> instance.
226: * <p>
227: * The hash code of a <code>TabularData</code> instance is the sum of the hash codes
228: * of all elements of information used in <code>equals</code> comparisons
229: * (ie: its <i>tabular type</i> and its content, where the content is defined as all the index to value mappings).
230: * <p>
231: * This ensures that <code> t1.equals(t2) </code> implies that <code> t1.hashCode()==t2.hashCode() </code>
232: * for any two <code>TabularDataSupport</code> instances <code>t1</code> and <code>t2</code>,
233: * as required by the general contract of the method
234: * {@link <a href="http://java.sun.com/j2se/1.3/docs/api/java/lang/Object.html#hashCode()">
235: * <code>Object.hashCode</code> </a>}.
236: *
237: * @return the hash code value for this <code>TabularDataSupport</code> instance
238: */
239: public int hashCode();
240:
241: /**
242: * Returns a string representation of this <code>TabularData</code> instance.
243: * <p>
244: * The string representation consists of the name of the implementing class,
245: * and the tabular type of this instance.
246: *
247: * @return a string representation of this <code>TabularData</code> instance
248: */
249: public String toString();
250:
251: }
|