/*
* @(#)TabularData.java 3.19 04/02/10
*
* Copyright 2004 Sun Microsystems, Inc. All rights reserved.
* SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
*/
package javax.management.openmbean;
// java import
//
import java.io.Serializable;
import java.util.Map;
import java.util.Set;
import java.util.Collection;
// jmx import
//
/**
* The TabularData interface specifies the behavior of a specific type of complex open data objects
* which represent tabular data structures.
*
* @version 3.19 04/02/10
* @author Sun Microsystems, Inc.
*
* @since 1.5
* @since.unbundled JMX 1.1
*/
public interface TabularData /*extends Map*/ {
/* *** TabularData specific information methods *** */
/**
* Returns the tabular type describing this
* TabularData instance.
*
* @return the tabular type.
*/
public TabularType getTabularType();
/**
* Calculates the index that would be used in this TabularData instance to refer to the specified
* composite data value parameter if it were added 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 value in this TabularData instance.
*
* @param value the composite data value whose index in this
* TabularData instance is to be calculated;
* must be of the same composite type as this instance's row type;
* must not be null.
*
* @return the index that the specified value would have in this TabularData instance.
*
* @throws NullPointerException if value is null
*
* @throws InvalidOpenTypeException if value does not conform to this TabularData instance's
* row type definition.
*/
public Object[] calculateIndex(CompositeData value) ;
/* *** Content information query methods *** */
/**
* Returns the number of CompositeData values (ie the
* number of rows) contained in this TabularData
* instance.
*
* @return the number of values contained.
*/
public int size() ;
/**
* Returns true if the number of CompositeData
* values (ie the number of rows) contained in this
* TabularData instance is zero.
*
* @return true if this TabularData is empty.
*/
public boolean isEmpty() ;
/**
* 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 TabularData instance's TabularType definition, this method simply returns false.
*
* @param key the index value whose presence in this TabularData instance is to be tested.
*
* @return true if this TabularData indexes a row value with the specified key.
*/
public boolean containsKey(Object[] key) ;
/**
* Returns true if and only if this TabularData instance contains the specified
* CompositeData value. If value is null or does not conform to
* this TabularData instance's row type definition, this method simply returns false.
*
* @param value the row value whose presence in this TabularData instance is to be tested.
*
* @return true if this TabularData instance contains the specified row value.
*/
public boolean containsValue(CompositeData value) ;
/**
* Returns the CompositeData value whose index is
* key, or null if there is no value mapping
* to key, in this TabularData instance.
*
* @param key the key of the row to return.
*
* @return the value corresponding to key.
*
* @throws NullPointerException if the key is
* null
* @throws InvalidKeyException if the key does not
* conform to this TabularData instance's *
* TabularType definition
*/
public CompositeData get(Object[] key) ;
/* *** Content modification operations (one element at a time) *** */
/**
* Adds value to this TabularData instance.
* The composite type of value must be the same as this
* instance's row type (ie the composite type returned by
* this.getTabularType().{@link TabularType#getRowType
* getRowType()}), and there must not already be an existing
* value in this TabularData 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 TabularType
* definition (see TabularType.{@link
* TabularType#getIndexNames getIndexNames()}).
*
* @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.
*
* @throws NullPointerException if value is null
* @throws InvalidOpenTypeException if value does not conform to this TabularData instance's
* row type definition.
* @throws KeyAlreadyExistsException if the index for value, calculated according to
* this TabularData instance's TabularType definition
* already maps to an existing value in the underlying HashMap.
*/
public void put(CompositeData value) ;
/**
* Removes the CompositeData value whose index is key from this TabularData instance,
* and returns the removed value, or returns null if there is no value whose index is key.
*
* @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.
*
* @return previous value associated with specified key, or null
* if there was no mapping for key.
*
* @throws NullPointerException if the key is null
* @throws InvalidKeyException if the key does not conform to this TabularData instance's
* TabularType definition
*/
public CompositeData remove(Object[] key) ;
/* *** Content modification bulk operations *** */
/**
* Add all the elements in values to this TabularData instance.
* If any element in values does not satisfy the constraints defined in {@link #put(CompositeData) put},
* or if any two elements in values have the same index calculated according to this TabularData
* instance's TabularType definition, then an exception describing the failure is thrown
* and no element of values is added, thus leaving this TabularData instance unchanged.
*
* @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.
*
* @throws NullPointerException if an element of values is null
* @throws InvalidOpenTypeException if an element of values does not conform to
* this TabularData instance's row type definition
* @throws KeyAlreadyExistsException if the index for an element of values, calculated according to
* this TabularData instance's TabularType definition
* already maps to an existing value in this instance,
* or two elements of values have the same index.
*/
public void putAll(CompositeData[] values) ;
/**
* Removes all CompositeData values (ie rows) from this TabularData instance.
*/
public void clear();
/* *** Collection views of the keys and values *** */
/**
* Returns a set view of the keys (ie the index values) of the CompositeData values (ie the rows)
* contained in this TabularData instance. The returned Set can then be used to iterate over the keys.
*
* @return a set view of the index values used in this TabularData instance.
*/
public Set keySet();
/**
* Returns a collection view of the CompositeData values (ie the rows)
* contained in this TabularData instance.
* The returned collection can then be used to iterate over the values.
*
* @return a collection view of the rows contained in this TabularData instance.
*/
public Collection values();
/* *** Commodity methods from java.lang.Object *** */
/**
* Compares the specified obj parameter with this TabularData instance for equality.
*
* Returns true if and only if all of the following statements are true:
*
* - obj is non null,
* - obj also implements the
TabularData interface,
* - their row types are equal
* - their contents (ie index to value mappings) are equal
*
* This ensures that this equals method works properly for obj parameters which are
* different implementations of the TabularData interface.
*
* @param obj the object to be compared for equality with this TabularData instance;
*
* @return true if the specified object is equal to this TabularData instance.
*/
public boolean equals(Object obj);
/**
* Returns the hash code value for this TabularData instance.
*
* The hash code of a TabularData instance is the sum of the hash codes
* of all elements of information used in equals comparisons
* (ie: its tabular type and its content, where the content is defined as all the index to value mappings).
*
* This ensures that t1.equals(t2) implies that t1.hashCode()==t2.hashCode()
* for any two TabularDataSupport instances t1 and t2,
* as required by the general contract of the method
* {@link Object#hashCode() Object.hashCode()}.
*
* @return the hash code value for this TabularDataSupport instance
*/
public int hashCode();
/**
* Returns a string representation of this TabularData instance.
*
* The string representation consists of the name of the implementing class,
* and the tabular type of this instance.
*
* @return a string representation of this TabularData instance
*/
public String toString();
}