com.tensegrity.generic.attribute
Interface AttributeCollection

All Superinterfaces:

java.lang.Cloneable, Restrictable

All Known Subinterfaces:

AttributeList, AttributeSet

public interface AttributeCollection

extends Restrictable, java.lang.Cloneable

An Attribute without a parent context is probably not a very good design idea. After all, known attributes usually reside in the context of a parent Class construct. Our Attribute pattern implementation, therefore, provides a generic parent container, represented by the AttributeCollection interface.

You will most likely need an object that implements a derived interface, such as AttributeList or AttributeSet. This can be done by means of an AttributeFactory, which will hide the particular implementation classes from client code.

Version:

$Id: AttributeCollection.java,v 1.46 2005/10/20 10:52:01 KevinCVS Exp $

Author:

M. Kegel, S. Rutz

Field Summary

static java.lang.String

SEPARATOR Path separator for AttributeSet hierarchies.

Method Summary

void	add(Attribute attribute) Adds the given Attribute to the collection.
void	clear() Clears the entire AttributeCollection.
java.lang.Object	clone() Clones / Deep-copies this AttributeCollection.
void	delete(java.lang.String name) Deletes any Attribute with the given name from the collection.
int	depth() Returns the maximum depth of this hierarchy.
java.util.Iterator	find(java.lang.String path) This method allows callers to retrieve attributes that are nested in an AttributeCollection to any arbitrary depth.
void	findAndDelete_nothrow(java.lang.String path) Deletes the Attribute at the give location collection.
void	findAndDelete(java.lang.String path) Deletes the Attribute at the given location from the collection.
java.util.Iterator	findAndFlatten(java.lang.String path) This method assembles attributes that match the path into a list of flat ones.
java.util.Iterator	findAndRemove_nothrow(java.lang.String path) Removes the Attribute with the given path from the AttributeCollection.
java.util.Iterator	findAndRemove(java.lang.String path) Removes the Attribute with the given path from the collection.
java.util.Iterator	findNoThrow(java.lang.String path) Same as the plain find() method, with the difference that no exception is thrown in case nothing is found or in case the search path is invalid.
void	freeze() Freezes the collection by making all attributes immutable and prohibiting the further addition of new ones.
AttributeTypeSet	getTypeSet() Returns all AttributeType objects of each Attribute in this set as a AttributeTypeSet.
AttributeTypeSet	getTypeTree() Returns the AttributeType‘s of each attribute in this set as a AttributeTypeSet.
java.util.Iterator	iterator() Returns an Iterator for all attributes in this collection.
AttributeCollection	merge(AttributeCollection other) This method creates a new AttributeCollection reflecting a merge of the given collection with this collection.
int	size() Returns the number of elements in this collection.
void	unfreeze() Releases the collection freeze state.
void	visit(AttributeCollectionVisitor visitor) Visits this collection of Attribute objects and all nested collections, then invokes visit(Attribute) from the given AttributeCollectionVisitor on all Attribute objects.

Methods inherited from interface com.tensegrity.generic.constraint.Restrictable

getConstraint, setConstraint

Field Detail

SEPARATOR

public static final java.lang.String SEPARATOR

Path separator for AttributeSet hierarchies. The separator must not be part of an attribute's name. Must always be of length 1.

See Also:

Constant Field Values

Method Detail

freeze

public void freeze()

Freezes the collection by making all attributes immutable and prohibiting the further addition of new ones.

unfreeze

public void unfreeze()

Releases the collection freeze state. This means all attributes are set to their previous immutable or mutable state and adding of further attributes to the set is again permitted.

size

public int size()

Returns the number of elements in this collection. Please note that this does not include any elements in potentially nested instances of AttributeCollection. This method will only return the number of Attribute objects that are directly contained by this instance.

Returns:

number of elements in the set.

Find more information in the class documentation

clear

public void clear()

Clears the entire AttributeCollection.

depth

public int depth()

Returns the maximum depth of this hierarchy. This means if there is one nested AttributeSet then the depth is 1, if there is another level of nesting then the depth is 2 and so on.

Returns:

the maximum depth of this hierarchy.

add

public void add(Attribute attribute)
         throws IllegalAttributeException,
                ConstraintViolationException

Adds the given Attribute to the collection.
It is not allowed to build cyclic hierarchies using an AttributeCollection. That means it is not allowed to assign an AttributeCollection to the value of an Attribute and add the Attribute directly or indirectly to the original AttributeCollection. It is the responsibility of the user to make sure such cycles are not accidently built.

Parameters:

attribute - the attribute to add. It is not allowed to add null as an attribute, doing so will result in a IllegalAttributeException.

Throws:

IllegalAttributeException - if the given Attribute is invalid. The exception might as well be thrown in case the AttributeCollection implementation can not deal with the particular attribute implementation that is attempted to be added. A null attribute or an attribute with its key being null is considered to be in an illegal state and will cause the exception to be thrown. The exception is thrown also if the AttributeCollection is frozen. Attempting to add a an Attribute to a frozen collection is forbidden and thus will generate the exception until an unfreeze operation is performed.

ConstraintViolationException - if the attribute does not conform to the constraints of this attribute set.

See Also:

freeze(), unfreeze()

Find more information in the class documentation

delete

public void delete(java.lang.String name)

Deletes any Attribute with the given name from the collection. Nested Attributecollection instances are not searched.

Parameters:

name - the name of the Attribute to be removed.

Find more information in the class documentation

getTypeSet

public AttributeTypeSet getTypeSet()

Returns all AttributeType objects of each Attribute in this set as a AttributeTypeSet.

Returns:

an AttributeTypeSet.

getTypeTree

public AttributeTypeSet getTypeTree()

Returns the AttributeType‘s of each attribute in this set as a AttributeTypeSet. Each subset is added to it‘s parent set as an AttributeType.

Returns:

an iterator for the attribute types.

iterator

public java.util.Iterator iterator()

Returns an Iterator for all attributes in this collection.

Returns:

an iterator for the attributes

find

public java.util.Iterator find(java.lang.String path)
                        throws VisitException

This method allows callers to retrieve attributes that are nested in an AttributeCollection to any arbitrary depth. For example, an AttributeCollection might look like this:

 set0 -+---- attr01
       |
       |---- attr02
       |
       |---- set1 -+---- attr11
                   |
                   |---- set2 -+---- attr21
                    
 

Finding Attribute attr21 in this Attribute hierarchy given a reference to the top-level AttributeCollection set0 is done by invoking set0.find("set0:set1:set2:attr21");
If you specify a path down the hierarchy that does not correspond to an existing AttributeCollection, a VisitException is thrown. This exception is also thrown if the path ends with a separator character or if the path components are not found during the search.

Parameters:

path - the path pattern to find in the set and nested sets.

Returns:

an Iterator linking to the found Attributes.

Throws:

VisitException - if the path is not valid or nothing was found.

See Also:

findNoThrow(String)

Find more information in the class documentation

findNoThrow

public java.util.Iterator findNoThrow(java.lang.String path)

Same as the plain find() method, with the difference that no exception is thrown in case nothing is found or in case the search path is invalid. The exception is silently ignored and an empty Iterator is returned.

Parameters:

path - the path pattern to find in the collection and nested collections.

Returns:

an Iterator containing the Attributes that were found.

See Also:

find(String)

Find more information in the class documentation

findAndRemove

public java.util.Iterator findAndRemove(java.lang.String path)
                                 throws VisitException

Removes the Attribute with the given path from the collection. An Iterator containing all removed Attribute objects is returned to the caller.

Parameters:

path - the pattern of the Attribute(s) to remove.

Returns:

an Iterator for all removed Attributes.

Throws:

VisitException - if the path is not valid or nothing was found.

See Also:

find(String)

Find more information in the class documentation

findAndRemove_nothrow

public java.util.Iterator findAndRemove_nothrow(java.lang.String path)

Removes the Attribute with the given path from the AttributeCollection. This method is analogous to the findAndRemove method, but no exceptions are thrown. In case the given path is illegal or nothing is found an empty Iterator is returned.

Parameters:

path - the path pattern of the Attribute(s) to remove.

Returns:

an Iterator for all the Attributes that were removed or an empty Iterator if nothing was removed.

See Also:

find(String), findAndRemove(String)

Find more information in the class documentation

findAndDelete

public void findAndDelete(java.lang.String path)
                   throws VisitException

Deletes the Attribute at the given location from the collection. This method recognizes paths the same way as the find method does.

Parameters:

path - the path pattern for the Attribute(s) to remove.

Throws:

VisitException - if the path is not valid or nothing was found.

Find more information in the class documentation

findAndDelete_nothrow

public void findAndDelete_nothrow(java.lang.String path)

Deletes the Attribute at the give location collection. This method recognizes paths the same way the find method does. This method is analogous to the findAndRemove method, but no exceptions are thrown.

Parameters:

path - the pattern for the Attributes to remove.

See Also:

findAndDelete(String)

Find more information in the class documentation

findAndFlatten

public java.util.Iterator findAndFlatten(java.lang.String path)
                                  throws VisitException,
                                         IllegalNameException,
                                         IllegalValueException,
                                         ConstraintViolationException,
                                         java.lang.CloneNotSupportedException,
                                         IllegalAttributeException

This method assembles attributes that match the path into a list of flat ones. The names are kept unique by replacing the directory separator with the character '.' .

Parameters:

path - the path of the attribute(s) to remove.

Returns:

an iterator for all the attributes that were found or an empty iterator if nothing was found.

Throws:

VisitException - thrown if an error occured.

IllegalNameException - thrown if an error occured.

IllegalValueException - thrown if an error occured.

ConstraintViolationException - thrown if an error occured.

java.lang.CloneNotSupportedException - thrown if an error occured.

IllegalAttributeException - thrown if an error occured.

visit

public void visit(AttributeCollectionVisitor visitor)
           throws VisitException

Visits this collection of Attribute objects and all nested collections, then invokes visit(Attribute) from the given AttributeCollectionVisitor on all Attribute objects.

Parameters:

visitor - the AttributeCollectionVisitor that visits the found Attributes.

Throws:

VisitException - thrown if the visitor got into to an exceptional state.

Find more information in the class documentation

clone

public java.lang.Object clone()
                       throws java.lang.CloneNotSupportedException

Clones / Deep-copies this AttributeCollection.

Returns:

a deep copy of this AttributeCollection.

Throws:

java.lang.CloneNotSupportedException - if invoking clone() method on some indwell object is not allowed or supported.

merge

public AttributeCollection merge(AttributeCollection other)
                          throws IllegalAttributeException,
                                 ConstraintViolationException

This method creates a new AttributeCollection reflecting a merge of the given collection with this collection. Each subclass of AttributeCollection regulates how a merge will be done. ! The given attribute collection other must not contain elements with the same name !

Parameters:

other - the other collection you want to merge with this collection.

Returns:

AttributeCollection the merged attribute collection.

Throws:

IllegalAttributeException - if an illegal attribute was found.

ConstraintViolationException - if a violation of constraints occurs.