001: /**
002: * Copyright (C) The MX4J Contributors.
003: * All rights reserved.
004: *
005: * This software is distributed under the terms of the MX4J License version 1.0.
006: * See the terms of the MX4J License in the documentation provided with this software.
007: */package javax.management.openmbean;
008:
009: import java.io.IOException;
010: import java.io.ObjectInputStream;
011: import java.io.Serializable;
012: import java.util.ArrayList;
013: import java.util.Arrays;
014: import java.util.Collection;
015: import java.util.Collections;
016: import java.util.HashMap;
017: import java.util.Iterator;
018: import java.util.List;
019: import java.util.Map;
020: import java.util.Set;
021:
022: /**
023: *
024: * @version $Revision: 1.10 $
025: */
026:
027: /**
028: * The TabularDataSupport class is the open data class which implements the TabularData and the
029: * Map interfaces, and which is internally based on a hash map data structure
030: */
031: public class TabularDataSupport implements TabularData, Map, Cloneable,
032: Serializable {
033: private static final long serialVersionUID = 5720150593236309827L;
034:
035: private Map dataMap;
036: private TabularType tabularType;
037:
038: private transient String[] m_indexNames;
039:
040: /**
041: * Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has a default initial capacity (101) and default load factor (0.75).
042: *
043: * @param tabularType the TabularTypeBackUP describing this TabularData instance, cannot be null
044: */
045: public TabularDataSupport(TabularType tabularType) {
046: this (tabularType, 101, 0.75f);
047: }
048:
049: /**
050: * Creates an empty TabularDataSupport instance whose open-type is tabularType, and whose underlying HashMap has the specified initial capacity and load factor
051: *
052: * @param tabularType - the tabular type describing this instance, cannot be null;
053: * @param initialCapacity - the initial capacity of the Map
054: * @param loadFactor - the load factor of the Map
055: * @throws IllegalArgumentException if the initialCapacity is less than zero, the load factor is negative or the tabularType is null
056: */
057: public TabularDataSupport(TabularType tabularType,
058: int initialCapacity, float loadFactor) {
059: if (tabularType == null)
060: throw new IllegalArgumentException(
061: "TabularTypeBackUP instance cannot be null.");
062: if (initialCapacity < 0)
063: throw new IllegalArgumentException(
064: "The initialCapacity cannot be a negative number.");
065: if (loadFactor < 0)
066: throw new IllegalArgumentException(
067: "The load factor cannot be a negative number.");
068:
069: this .tabularType = tabularType;
070: this .dataMap = new HashMap(initialCapacity, loadFactor);
071: initialize();
072: }
073:
074: /**
075: * can be called by the readObject method to initialize the deserialized instance
076: */
077: private void initialize() {
078: // get the index names list from the tabular type as these will act as the unique index into each row of the TabularData instance
079: List tabularIndexList = tabularType.getIndexNames();
080: m_indexNames = (String[]) tabularIndexList
081: .toArray(new String[tabularIndexList.size()]);
082: }
083:
084: /**
085: * get the TabularType that this instance contains
086: *
087: * @return TabularType describing this TabularData instance
088: */
089: public TabularType getTabularType() {
090: return tabularType;
091: }
092:
093: /**
094: * <p>Calculates the index that would be used in this TabularData instance to refer to the specified composite data value parameter is it were added
095: * to this instance.This method checks for the type validity of the specified value, but does not check if the calculated index is already used to refer to a
096: * value, in this tabular data instance</p>
097: *
098: * @param value - the CompositeData value whose index in this TabularData instance is to be calculated, must be of the same composite type as this instance's row type;
099: * must not be null.
100: * @return - the index that the specified <b><i>value would have</i></b> in this tabularData instance
101: * @throws NullPointerException if value is null
102: * @throws InvalidOpenTypeException if value does not conform to this tabular data instances' row type definition
103: */
104: public Object[] calculateIndex(CompositeData value) {
105: if (value == null)
106: throw new NullPointerException(
107: "CompositeData object cannot be null");
108: if (!(value.getCompositeType().equals(tabularType.getRowType())))
109: throw new InvalidOpenTypeException(
110: "Invalid CompositeData object, its' tabularType is not equal to the row type of this TabularType instance");
111: return Collections.unmodifiableList(
112: Arrays.asList(value.getAll(m_indexNames))).toArray();
113: }
114:
115: /**
116: * returns true if and only if this tabularData instance contains a compositeData value (i.e. a row) whose index is the specified key. If key cannot be cast to a one dimension
117: * array of Object instances, this method returns false, otherwise it returns the result of the call this.containsKey((Object[]) key)
118: *
119: * @param key - the index value
120: * @return true if a CompositeData value is found false otherwise, false if key cannot be cast to an Object[]
121: */
122: public boolean containsKey(Object key) {
123: if (!(key instanceof Object[]))
124: return false;
125: return containsKey((Object[]) key);
126: }
127:
128: /**
129: * Returns true if and only if this TabularData instance contains a CompositeData value (ie a row) whose index is the specified key. If key is null or does not conform to this
130: * TabularData instance's TabularType definition, this method simply returns false.
131: *
132: * @param key the index value whose presence in this TabularData instance is to be tested
133: * @return true if it is found false otherwise
134: */
135: public boolean containsKey(Object[] key) {
136: if (key == null)
137: return false;
138: return dataMap.containsKey(Arrays.asList(key));
139: }
140:
141: /**
142: * Returns true if and only if this TabularData instance contains the specified CompositeData value. If value is null or does not conform to
143: * this TabularData instance's row type definition, this method simply returns false.
144: *
145: * @param value - the row value whose presence in this TabularData instance is to be tested
146: * @return true if this instance contains the specified value
147: */
148: public boolean containsValue(CompositeData value) {
149: return dataMap.containsValue(value);
150: }
151:
152: /**
153: * Returns true if and only if this TabularData instance contains the specified value.
154: *
155: * @param value - the row value whose presence in this TabularData instance is to be tested
156: * @return true if this TabularData instance contains the specified row value
157: */
158: public boolean containsValue(Object value) {
159: return dataMap.containsValue(value);
160: }
161:
162: /**
163: * This method simply calls get((Object[]) key).
164: *
165: * @param key - the key for which to lookup the value
166: * @return the Object found for key "key"
167: */
168: public Object get(Object key) {
169: return get((Object[]) key);
170: }
171:
172: /**
173: * This method validates the key Object[] parameter. It cannot be null, or empty. It must be the same length as the indexNames of the tabularType passed into this instances
174: * constructor, and must be a valid value i.e the value returned by the method call OpenType isValue(Object obj) must be true
175: *
176: * @param key - the Object[] key stored as a key in this instance
177: * @return - the CompositeData value corresponding to the key
178: * @throws NullPointerException if key is null or empty
179: * @throws InvalidKeyException if an item in the array returns false for call OpenType isValue(Object o)
180: */
181: public CompositeData get(Object[] key) {
182: validateKeys(key);
183: return (CompositeData) dataMap.get(Arrays.asList(key));
184: }
185:
186: /**
187: * This method simply calls put((CompositeData) value) and therefore ignores its key parameter which can be null
188: *
189: * @return the value that is put
190: * @throws ClassCastException if value is not an instanceof CompositeData
191: */
192: public Object put(Object key, Object value) {
193: put((CompositeData) value);
194: return value;
195: }
196:
197: /**
198: * Adds "value" to this TabularData instance, if value's composite type is the same as this instance's row type
199: * (ie the composite type returned by this.getTabularType().getRowType()), and if there is not already an existing value in this TabularData
200: * instance whose index is the same as the one calculated for the value to be added. The index for value is calculated according to this TabularData instance's
201: * TabularType definition @see javax.management.openmbean.TabularType#getIndexNames()
202: * <p/>
203: * This method calls calculateIndex(CompositeData value) which validates value the returned Object[] is then converted into an unmodifiableList and stored
204: *
205: * @param value - the composite data value to be added as a new row to this TabularData instance; must be of the same composite type as this instance's row type; must not be null.
206: * @throws NullPointerException if value is null
207: * @throws InvalidOpenTypeException if value does not conform to this TabularData instance's row type definition
208: * @throws KeyAlreadyExistsException if the underlying HashMap already contains the calculated key
209: */
210: public void put(CompositeData value) {
211: // calculateIndex method tests for null and invalid rowType
212: List list = Collections.unmodifiableList(Arrays
213: .asList(calculateIndex(value)));
214: if (dataMap.containsKey(list))
215: throw new KeyAlreadyExistsException(
216: "The list of index names already exists in this instance");
217: dataMap.put(list, value);
218: }
219:
220: /**
221: * This method simply calls remove((Object[]) key).
222: *
223: * @param key - the Object to remove note no checks are done if key can be cast to Object[] hence if not a ClassCastException will be thrown
224: * @throws ClassCastException if key cannot be cast to an Object[]
225: */
226: public Object remove(Object key) {
227: return remove((Object[]) key);
228: }
229:
230: /**
231: * Method validates the key checking for null, zero length and if items in the key are invalid as returned by @see OpenType isValue(Object obj)
232: *
233: * @param key - the index of the value to get in this TabularData instance; must be valid with this TabularData instance's row type definition; must not be null.
234: * @return previous value associated with specified key, or null if there was no mapping for key
235: * @throws NullPointerException if key is null
236: * @throws InvalidKeyException if the key does not conform to this TabularData instance's TabularType definition
237: */
238: public CompositeData remove(Object[] key) {
239: validateKeys(key);
240: return (CompositeData) dataMap.remove(Arrays.asList(key));
241: }
242:
243: /**
244: * Add all the values contained in the specified map t to this TabularData instance. This method converts the collection of values contained in this map into an
245: * array of CompositeData values, if possible, and then calls the method putAll(CompositeData[]). Note that the keys used in the specified map t are ignored.
246: * This method allows, for example to add the content of another TabularData instance with the same row type (but possibly different index names) into this instance.
247: *
248: * @param t - the map whose values are to be added as new rows to this TabularData instance; if t is null or empty, this method returns without doing anything
249: * @throws NullPointerException - if a "value" in t is null
250: * @throws ClassCastException - if a value in t is not an instanceof CompositeData this is a wrapper around the RuntimeException ArrayStoreException
251: * which is generated when an attempt has been made to store the wrong type of object into an array of objects.
252: * @throws InvalidOpenTypeException - if a value in t does not conform to this TabularData instance's row type definition
253: * @throws KeyAlreadyExistsException - if the index for a value in t, calculated according to this TabularData instance's TabularType definition
254: * already maps to an existing value in this instance, or two values in t have the same index.
255: */
256: public void putAll(Map t) {
257: if (t == null || t.size() == 0)
258: return;
259: CompositeData[] compositeData;
260: try {
261: compositeData = (CompositeData[]) t.values().toArray(
262: new CompositeData[t.size()]);
263: } catch (ArrayStoreException e) {
264: throw new ClassCastException(
265: "The values contained in t must all be of type CompositeData");
266: }
267: putAll(compositeData);
268: }
269:
270: /**
271: * Adds all the elements in values to this TabularData instance. If any element in values does not satisfy the constraints defined in put, or if any two elements in values
272: * have the same index calculated according to this TabularData instance's TabularType definition, then an exception describing the failure is thrown
273: * and no element of values is added, thus leaving this TabularData instance unchanged.
274: *
275: * @param values - the array of composite data values to be added as new rows to this TabularData instance; if values is null or empty, this method returns without doing anything
276: * @throws NullPointerException - if an element of values is null
277: * @throws InvalidOpenTypeException - if an element of values does not conform to this TabularData instance's row type definition (ie its TabularType definition)
278: * @throws KeyAlreadyExistsException - if the index for an element of values, calculated according to this TabularData instance's TabularType definition already
279: * maps to an existing value in this instance, or two elements of values have the same index
280: */
281: public void putAll(CompositeData[] values) {
282: // validate values
283: if (values == null || values.length == 0)
284: return;
285:
286: /** creating a list to store all the keys obtained from method calculateIndex this is to check that no keys are duplicated */
287: List storeList = validateNoDuplicates(values);
288:
289: /** Once we have validated that there are no duplicated keys we can add them to the global map if a duplicate is found an exception is thrown leaving instance unchanged */
290: for (int i = 0; i < values.length; i++) {
291: dataMap.put(storeList.get(i), values[i]);
292: }
293: }
294:
295: /**
296: * test that the list returned from calculateIndex for each CompositeData object has no duplicates
297: */
298: private List validateNoDuplicates(CompositeData[] values) {
299: List storeList = new ArrayList();
300: for (int i = 0; i < values.length; i++) {
301: List list = Collections.unmodifiableList(Arrays
302: .asList(calculateIndex(values[i])));
303:
304: /** check no duplicate keys if there is we have an invalid key */
305: if (storeList.contains(list))
306: throw new KeyAlreadyExistsException("value at [" + i
307: + "] has the same index values as: "
308: + storeList.indexOf(list));
309:
310: /** store it to check the next values are not duplicated */
311: storeList.add(list);
312: }
313: return storeList;
314: }
315:
316: /**
317: * clears this instances internal map
318: */
319: public void clear() {
320: dataMap.clear();
321: }
322:
323: /**
324: * @return the size of the map
325: */
326: public int size() {
327: return dataMap.size();
328: }
329:
330: /**
331: * @return true if the map is empty false if not empty
332: */
333: public boolean isEmpty() {
334: return dataMap.isEmpty();
335: }
336:
337: /**
338: * Returns a set view of the keys contained in the underlying map of this TabularDataSupport instance, and used to index the rows.
339: * Each key contained in this set is an unmodifiable List. The set is backed by the underlying map of this TabularDataSupport instance,
340: * so changes to the TabularDataSupport instance are reflected in the set, and vice-versa. The set supports element removal, which removes the
341: * corresponding row from this TabularDataSupport instance, via the Iterator.remove, Set.remove, removeAll, retainAll, and clear operations.
342: * It does not support the add or addAll operations
343: *
344: * @return a set view of the keys used to index the rows of this TabularDataSupport instance
345: */
346: public Set keySet() {
347: return dataMap.keySet();
348: }
349:
350: /**
351: * Returns a collection view of the rows contained in this TabularDataSupport instance. The collection is backed by the underlying map,
352: * so changes to the TabularDataSupport instance are reflected in the collection, and vice-versa. The collection supports element removal,
353: * which removes the corresponding index to row mapping from this TabularDataSupport instance, via the Iterator.remove, Collection.remove, removeAll,
354: * retainAll, and clear operations. It does not support the add or addAll operations
355: *
356: * @return a collection view of the values contained in this TabularDataSupport instance.
357: */
358: public Collection values() {
359: return dataMap.values();
360: }
361:
362: /**
363: * Returns a collection view of the index to row mappings contained in this TabularDataSupport instance. Each element in the returned collection is a Map.Entry.
364: * The collection is backed by the underlying map of this TabularDataSupport instance, in so changes to the TabularDataSupport instance are reflected the collection, and vice-versa.
365: * The collection supports element removal, which removes the corresponding mapping from the map, via the Iterator.remove, Collection.remove, removeAll, retainAll, and clear operations.
366: * It does not support the add or addAll operations.
367: * <p><b>NOTE</b> Do not use the SetValue method of Map.Entry elements contained in the returned collection view.
368: * Doing so would corrupt the index to row mappings contained in this TabularDataSupport instance</p>
369: *
370: * @return a collection view of the mappings contained in this map
371: */
372: public Set entrySet() {
373: return dataMap.entrySet();
374: }
375:
376: /**
377: * Returns a clone of this TabularDataSupport instance: the clone is obtained by calling super.clone(),
378: * and then cloning the underlying map. Only a shallow clone of the underlying map is made, i.e. no cloning of the indexes and row values is made as they are immutable!!
379: *
380: * @return a copy of the TabularDataSupport
381: */
382: public Object clone() {
383: TabularDataSupport dataSupportClone = null;
384: try {
385: dataSupportClone = (TabularDataSupport) super .clone();
386: dataSupportClone.dataMap = (HashMap) ((HashMap) dataMap)
387: .clone();
388: } catch (CloneNotSupportedException e) {
389: // shouldn't happen
390: return null;
391: }
392: return dataSupportClone;
393: }
394:
395: /**
396: * Compares the specified obj parameter with this TabularDataSupport instance for equality
397: *
398: * @return true if and only if all of the following statements are true:
399: * <ul>
400: * <li><obj is instanceof TabularData/li>
401: * <li>their tabular types are equal</li>
402: * <li><their contents (ie all CompositeData values) are equal/li>
403: * </ul>
404: */
405: public boolean equals(Object obj) {
406: if (!(obj instanceof TabularData))
407: return false;
408: TabularData tabularData = (TabularData) obj;
409: for (Iterator i = values().iterator(); i.hasNext();) {
410: CompositeData compositeData = (CompositeData) i.next();
411: if (!(tabularData.containsValue(compositeData)))
412: return false;
413: }
414: return ((getTabularType().equals(tabularData.getTabularType()) && (size() == tabularData
415: .size())));
416: }
417:
418: /**
419: * The hash code of a TabularDataSupport instance is the sum of the hash codes of all elements of information used in equals comparisons
420: * (ie: its tabular type and its content, where the content is defined as all the CompositeData values).
421: *
422: * @return the calculated hashCode for this object
423: */
424: public int hashCode() {
425: int result = tabularType.hashCode();
426: for (Iterator i = values().iterator(); i.hasNext();) {
427: result += i.next().hashCode();
428: }
429: return result;
430:
431: }
432:
433: /**
434: * The string representation consists of the name of this class (ie com.sun.jdmk.TabularDataSupport), the string representation of the tabular type of this instance,
435: * and the string representation of the contents (ie list the key=value mappings as returned by a call to dataMap.toString())
436: *
437: * @return a string representation of this TabularDataSupport instance
438: */
439: public String toString() {
440: return getClass().getName() + "(tabularType = "
441: + tabularType.toString() + ",contains = "
442: + dataMap.toString() + ")";
443: }
444:
445: /**
446: * validate the Object[] of keys they cannot be null or empty. The length must be the same length as the indexNames used for the indexing rows
447: */
448: private void validateKeys(Object[] key) {
449: if (key == null || key.length == 0)
450: throw new NullPointerException(
451: "Object[] key cannot be null or of zero length");
452: if (key.length != m_indexNames.length)
453: throw new InvalidKeyException(
454: "Length of Object[] passed in as a parameter is not equal to the number of items: "
455: + m_indexNames.length
456: + " as specified for the indexing rows in this instance.");
457: for (int i = 0; i < key.length; i++) {
458: OpenType openType = tabularType.getRowType().getType(
459: m_indexNames[i]);
460: if ((key[i] != null) && (!(openType.isValue(key[i]))))
461: throw new InvalidKeyException("expected value is: "
462: + openType + " at index: " + i + " but got: "
463: + key[i]);
464: }
465: }
466:
467: /**
468: * acts as a second constructor so validate all invariants and recreate the object in the correct state
469: */
470: private void readObject(ObjectInputStream inputStream)
471: throws IOException, ClassNotFoundException {
472: inputStream.defaultReadObject();
473: initialize();
474: }
475: }
|