com.ideanest.attributes
Interface Bundle

All Known Implementing Classes:

SimpleBundle

public interface Bundle

A bundle of attributes for some program element. Each attribute is an object. Simple attributes are string pairs, the key being the tag used to introduce the attribute and the value being the tag's argument. Complex attributes can be instances of any class.

The original order in which the attributes were specified is maintained by the iterators and the toArray converter.

Version:

$Revision: 1.2 $ ($Date: 2003/07/31 07:47:23 $)

Author:

Piotr Kaminski

Method Summary

void	add(java.lang.Object attribute) Add the given attribute to this bundle.
void	add(java.lang.Object attribute, Creator creator) Add the given non-serializable attribute to this bundle along with a serializable creator that can be used to recreate it.
void	add(java.lang.String key, java.lang.String value) Add a simple attribute with the given key and value.
void	clear() Clear the contents of this bundle, removing all attributes.
java.lang.Object	get(java.lang.Class klass) Get an object attribute whose type is assignable to the given type.
java.lang.String	get(java.lang.String key) Get the string value matching the given key.
boolean	has(java.lang.Class klass) Return whether this bundle has any object attributes whose type is assignable to the given type.
boolean	has(java.lang.String key) Return whether this bundle has any string attributes for the given key.
Bundle	includingInherited() Return a composite bundle that includes all attributes inherited from supertypes by this element.
java.util.Iterator	iterator() An iterator over all the attributes in this bundle, in declaration order.
java.util.Iterator	iterator(java.lang.Class klass) Get an iterator over all object attributes whose type is assignable to the given type.
java.util.Iterator	iterator(java.lang.String key) Get an iterator over the values of all the simple attributes with the given key.
int	size() Return the number of attributes in this bundle.
java.lang.Object[]	toArray() Return a new array with all the attributes from this bundle.

Method Detail

add

public void add(java.lang.Object attribute)

Add the given attribute to this bundle. If the attribute is not serializable, attempting to save this bundle will fail.

Parameters:

attribute - the attribute to be added

add

public void add(java.lang.Object attribute,
                Creator creator)

Add the given non-serializable attribute to this bundle along with a serializable creator that can be used to recreate it. If this bundle is saved, the creator will be serialized and used to reconstruct the attribute when the bundle is read back in.

Parameters:

attribute - the attribute to be added

creator - a creator that can be used to re-create the attribute

add

public void add(java.lang.String key,
                java.lang.String value)

Add a simple attribute with the given key and value.

Parameters:

key - the key of the attribute to add

value - the value of the attribute to add

clear

public void clear()

Clear the contents of this bundle, removing all attributes.

get

public java.lang.Object get(java.lang.Class klass)

Get an object attribute whose type is assignable to the given type.

Parameters:

klass - a supertype of the desired attribute type

Returns:

the attribute value, or null if none

Throws:

MultipleValuesException - if there is more than one attribute assignable to the given type

get

public java.lang.String get(java.lang.String key)

Get the string value matching the given key. If the key was defined with no value, return the empty string.

Parameters:

key - the desired attribute's key

Returns:

the value for the given key, or null if the key is not present in this bundle

Throws:

MultipleValuesException - if there is more than one value for the given key

has

public boolean has(java.lang.Class klass)

Return whether this bundle has any object attributes whose type is assignable to the given type.

Parameters:

klass - a supertype of the desired attribute type

Returns:

true if there is at least one object attribute whose type is assignable to the given type, false otherwise

has

public boolean has(java.lang.String key)

Return whether this bundle has any string attributes for the given key.

Parameters:

key - the desired attribute key

Returns:

true if there is at least one string attribute for the given key, false otherwise

includingInherited

public Bundle includingInherited()

Return a composite bundle that includes all attributes inherited from supertypes by this element. All elements contained in this bundle will also be included in the returned bundle. //TODO: explain attribute inheritance rules

Returns:

a bundle that includes all inherited attributes for this element

Throws:

java.lang.UnsupportedOperationException - if unable to obtain inherited attributes for any reason

iterator

public java.util.Iterator iterator()

An iterator over all the attributes in this bundle, in declaration order. This iterator also provides the only way to selectively remove attributes from a bundle, though this functionality may not be supported by any given implementation or for specific bundles.

Returns:

a new iterator over all attributes in this bundle

iterator

public java.util.Iterator iterator(java.lang.Class klass)

Get an iterator over all object attributes whose type is assignable to the given type.

Parameters:

klass - a supertype of the desired attribute type

Returns:

the array of attribute values, or an empty array if none

iterator

public java.util.Iterator iterator(java.lang.String key)

Get an iterator over the values of all the simple attributes with the given key.

Parameters:

key - the desired attributes' key

Returns:

the array of attribute values, or an empty array if none

size

public int size()

Return the number of attributes in this bundle.

Returns:

the number of attributes in this bundle

toArray

public java.lang.Object[] toArray()

Return a new array with all the attributes from this bundle.

Returns:

an array of the attributes in this bundle; changing it will not change the bundle's contents