cytoscape.data.attr
Interface MultiHashMap

All Known Implementing Classes:

ExtensibleMultiHashMapModel

public interface MultiHashMap

This interface consists of the API specification to bind attribute values to objects. A sibling API is MultiHashMapDefinition, which is used to define attribute spaces in which attribute values can be bound to objects; attribute space definition is the first thing that happens.

Method Summary

void	addDataListener(MultiHashMapListener listener) Registers a listener for receiving events having to do with attribute values being assigned and removed.
CountedIterator	getAttributeKeyspan(String objectKey, String attributeName, Object[] keyPrefix) For all key sequences, having specified prefix, that map into bound values on objectKey in attributeName, returns the [unique] representatives from dimension keyPrefix.length + 1.
Object	getAttributeValue(String objectKey, String attributeName, Object[] keyIntoValue) Retrieves a bound attribute value from an object.
CountedIterator	getObjectKeys(String attributeName) Returns all objectKeys that have at least one attribute value assigned in attributeName.
boolean	removeAllAttributeValues(String objectKey, String attributeName) Removes all values bound to objectKey in attributeName.
Object	removeAttributeValue(String objectKey, String attributeName, Object[] keyIntoValue) This method is the same as getAttributeValue(), only the retrieved attribute value is also deleted.
void	removeDataListener(MultiHashMapListener listener) Unregisters a listener; this method has the opposite effect as addDataListener(listener).
Object	setAttributeValue(String objectKey, String attributeName, Object attributeValue, Object[] keyIntoValue) Binds an attribute value to an object.

Method Detail

setAttributeValue

Object setAttributeValue(String objectKey,
                         String attributeName,
                         Object attributeValue,
                         Object[] keyIntoValue)

Binds an attribute value to an object.

Parameters:

objectKey - the object to which to bind a new attribute value.

attributeName - the attribute definition in which to assign an attribute value.

attributeValue - the attribute value to bind; the type of this object must be of the appropriate type based on the value type of specified attribute definition.

keyIntoValue - an array of length equal to the dimensionality of the key space of specified attribute definition; entry at index i is a "representative" from dimension i + 1 of the key space; if specified attribute definition has a zero-dimensional key space (this is perhaps the most common scenario) then this array may either be null or the empty array.

Returns:

previous attribute value bound at specified key sequence, or null if no attribute value was previously bound.

Throws:

IllegalStateException - if attributeName is not an existing attribute definition; see MultiHashMapDefinition.

NullPointerException - if objectKey, attributeName, or attributeValue is null, or if keyIntoValue is [not null and] of positive length and any one of its entries is null.

ClassCastException - if attributeValue is not of the appropriate object type or if any one of keyIntoValue's representatives is not of the appropriate object type; see MultiHashMapDefinition.

IllegalArgumentException - if keyIntoValue's length does not match the key space dimensionality of attributeName.

getAttributeValue

Object getAttributeValue(String objectKey,
                         String attributeName,
                         Object[] keyIntoValue)

Retrieves a bound attribute value from an object.

Parameters:

objectKey - the object from which to retrieve a bound attribute value.

attributeName - the attribute definition in which assigned attribute value exists.

keyIntoValue - an array of length equal to the dimensionality of the key space of specified attribute definition; entry at index i is a "representative" from dimension i + 1 of the key space; if specified attribute definition has a zero-dimensional key space (this is perhaps the most commen scenario) then this array may either be null or the empty array.

Returns:

the same value that was set with setAttributeValue() with parameters specified or null if no such value is bound.

Throws:

IllegalStateException - if attributeName is not an existing attribute definition; see MultiHashMapDefinition.

NullPointerException - if objectKey or attributeName is null, or if keyIntoValue is [not null and] of positive length and any one of its entries is null.

ClassCastException - if any one of keyIntoValue's representatives is not of the appropriate object type; see MultiHashMapDefinition.

IllegalArgumentException - if keyIntoValue's length does not match the key space dimensionality of attributeName.

removeAttributeValue

Object removeAttributeValue(String objectKey,
                            String attributeName,
                            Object[] keyIntoValue)

This method is the same as getAttributeValue(), only the retrieved attribute value is also deleted.

See Also:

getAttributeValue(String, String, Object[])

removeAllAttributeValues

boolean removeAllAttributeValues(String objectKey,
                                 String attributeName)

Removes all values bound to objectKey in attributeName. Most attribute definitions will have no key space, and such attribute definitions will bind at most one attribute value to any give objectKey; this method is useful with attribute definitions that have nonzero key spaces.

Parameters:

objectKey - the object from which to delete all bound attribute values.

attributeName - the attribute definition in which to delete attribute values.

Returns:

true if and only if objectKey had at least one attribute value bound in attributeName prior to this method invocation.

Throws:

IllegalStateException - if attributeName is not an existing attribute definition; see MultiHashMapDefinition.

NullPointerException - if objectKey or attributeName is null.

getAttributeKeyspan

CountedIterator getAttributeKeyspan(String objectKey,
                                    String attributeName,
                                    Object[] keyPrefix)

For all key sequences, having specified prefix, that map into bound values on objectKey in attributeName, returns the [unique] representatives from dimension keyPrefix.length + 1. This method only makes sense for attributeNames that have nonzero key space dimensionality.

NOTE: The returned iterator does not support the remove() operation.

IMPORTANT: The returned iterator becomes invalid as soon as any attribute value is set or removed for some objectKey in attributeName. Calling methods on an invalid iterator will result in undefined behavior of that iterator.

Parameters:

objectKey - the object to query.

attributeName - the attribute definition to query.

keyPrefix - an array of length K, where K is strictly less than the dimensionality of key space of attributeName; entry at index i contains a "representative" from dimension i + 1 of the key space of attributeName; keyPrefix may be either null or the empty array, in which case the iterator returned consists of the representatives in the first dimension of key space.

Returns:

an iterator of key representatives in key space dimension K + 1 along specified keyPrefix; the iterator returned is never null; the order of the returned keys is arbitrary.

Throws:

IllegalStateException - if attributeName is not an existing attribute definition; see MultiHashMapDefinition.

NullPointerException - if objectKey or attributeName is null, or if keyPrefix is [not null and] of positive length and any one of its entries is null.

ClassCastException - if any one of keyPrefix's representatives is not of the appropriate object type; see MultiHashMapDefinition.

IllegalArgumentException - if keyPrefix's length is not strictly less than the dimensionality of attributeName's key space.

getObjectKeys

CountedIterator getObjectKeys(String attributeName)

Returns all objectKeys that have at least one attribute value assigned in attributeName.

NOTE: The returned iterator does not support the remove() operation.

NOTE: To quickly determine whether or not a given objectKey has at least one attribute value bound to it under attributeName, test for a null return value in getAttributeValue(objectKey, attributeName, null) if attributeName has zero key space dimensionality, or test for an empty iterator return value in getAttributeKeyspan(objectKey, attributeName, null) if attributeName has nonzero key space dimensionality.

IMPORTANT: The returned iterator becomes invalid as soon as any attribute value is set or removed for some objectKey in attributeName. Calling methods on an invalid iterator will result in undefined behavior of that iterator.

Parameters:

attributeName - the attribute definition to query.

Returns:

an iterator of objectKey strings (java.lang.String) that currently have value[s] assigned to them in the specified attribute definition; the order of the returned strings is arbitrary; null is never returned.

Throws:

IllegalStateException - if attributeName is not an existing attribute definition; to test whether or not attributeName is an existing attribute definition, use MultiHashMapDefinition.getAttributeValueType(attributeName).

NullPointerException - if attributeName is null.

See Also:

MultiHashMapDefinition.getAttributeValueType(String)

addDataListener

void addDataListener(MultiHashMapListener listener)

Registers a listener for receiving events having to do with attribute values being assigned and removed.

Parameters:

listener - the listener to register.

removeDataListener

void removeDataListener(MultiHashMapListener listener)

Unregisters a listener; this method has the opposite effect as addDataListener(listener).

Parameters:

listener - the listener to unregister.