com.tensegrity.generic.attribute
Interface AttributeCollectionVisitor

All Known Implementing Classes:

XMLVisitor

public interface AttributeCollectionVisitor

This interface defines a visitor for an AttributeCollection, which has a number of callback methods that get invoked during its traversal. Implementing this interface provides a mechanism to output arbitrary formats of an AttributeCollection and its nested collections. The visitor pattern offers a generic way to implement all kinds of operations that involve traversing parts or all of an AttributeCollection. This may include things like printing out an xml-dump, converting to strings, streaming out for serialization, finding attributes based on patterns or to ensure there are no cycles when adding new attributes to an existing hierarchy.

An implementing AttributeCollectionVisitor class should understand its invocation order.

• At the beginning of a traversal, the method beginVisit() is called.
• At the end of a traversal, the method endVisit() is called.
• Before an Attribute is visited, the method acceptFilter() is called, giving the visitor a chance to exclude it from the traversal. If the Attribute accepts, the method enterAttribute() is subsequently called.
• After an Attribute is visited, the method leaveAttribute() is called.
• Before an AttributeCollection is visited, the method enterAttributeCollection() is called.
• After an AttributeCollection is visited, the method leaveAttributeCollection() is called.
• Whenever something goes wrong or unexpectedly, a VisitException is thrown and the traversal stops.

Please note that excluding an Attribute by returning false from the acceptFilter() method will exclude entire subtrees from the traversal.

Version:

$Id: AttributeCollectionVisitor.java,v 1.12 2005/03/03 16:25:14 KevinCVS Exp $

Author:

S. Rutz

Method Summary

boolean	acceptFilter(Attribute attribute, int level, java.lang.String path) This method allows fine grained control of what subtrees in the hierarchy are visited by means of the return value of this method.
void	beginVisit() This method is invoked before the traversal of an AttributeCollection hierarchy actually begins.
void	endVisit() This method is invoked after an AtributeCollection traversal has ended.
void	enterAttribute(Attribute attribute, int level, java.lang.String path) This method is invoked during traversal of an AtributeCollection hierarchy each time an attribute is encountered and entered.
void	enterAttributeCollection(AttributeCollection attributeSet, int level, java.lang.String path) This method is invoked during traversal of an AtributeCollection hierarchy each time a nested AtributeCollection is encountered and entered.
void	leaveAttribute(Attribute attribute, int level, java.lang.String path) This method is invoked during traversal of an AtributeCollection hierarchy each time after an attribute was visited.
void	leaveAttributeCollection(AttributeCollection attributeSet, int level, java.lang.String path) This method is invoked during traversal of an AtributeCollection hierarchy each time after an AtributeCollection was visited.

Method Detail

beginVisit

public void beginVisit()
                throws VisitException

This method is invoked before the traversal of an AttributeCollection hierarchy actually begins. Initialization can be done here.

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

endVisit

public void endVisit()
              throws VisitException

This method is invoked after an AtributeCollection traversal has ended. Cleanup work can be done here.

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

enterAttribute

public void enterAttribute(Attribute attribute,
                           int level,
                           java.lang.String path)
                    throws VisitException

This method is invoked during traversal of an AtributeCollection hierarchy each time an attribute is encountered and entered. This method is invoked before nested AtributeCollection instances are visited.

Parameters:

attribute - the current Attribute of the traversal.

level - the nesting level of the traversal.

path - the current path of the traversal so far, excluding the current attribute. The full path to the current attribute thus is path + AttributeCollection.SEPARATOR + attribute.getName();

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

leaveAttribute

public void leaveAttribute(Attribute attribute,
                           int level,
                           java.lang.String path)
                    throws VisitException

This method is invoked during traversal of an AtributeCollection hierarchy each time after an attribute was visited. This method is invoked after a nested AtributeCollection has been visited.

Parameters:

attribute - the current Attribute of the traversal

level - the nesting level of the traversal

path - the current path of the traversal so far, excluding the current attribute. The full path to the current attribute thus is path + AttributeCollection.SEPARATOR + attribute.getName();

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

enterAttributeCollection

public void enterAttributeCollection(AttributeCollection attributeSet,
                                     int level,
                                     java.lang.String path)
                              throws VisitException

This method is invoked during traversal of an AtributeCollection hierarchy each time a nested AtributeCollection is encountered and entered. This method is invoked before nested attributes are visited.

Parameters:

attributeSet - the current AtributeCollection of the traversal.

level - the nesting level of the traversal.

path - the current path of the traversal so far.

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

leaveAttributeCollection

public void leaveAttributeCollection(AttributeCollection attributeSet,
                                     int level,
                                     java.lang.String path)
                              throws VisitException

This method is invoked during traversal of an AtributeCollection hierarchy each time after an AtributeCollection was visited. This method is invoked after nested attributes were visited.

Parameters:

attributeSet - the current AtributeCollection of the traversal.

level - the nesting level of the traversal.

path - the current path of the traversal so far.

Throws:

VisitException - thrown if the visitor implementation wants to signal an error to the caller. This exception must not be declared in an implementation implementing this interface.

Find more information in the class documentation

acceptFilter

public boolean acceptFilter(Attribute attribute,
                            int level,
                            java.lang.String path)

This method allows fine grained control of what subtrees in the hierarchy are visited by means of the return value of this method. If this method returns false for a particular Attribute then the Attribute and all potentially nested AtributeCollection objects are excluded from the traversal. If no filter should be used, then this method is implemented with just one statement returning true. Then the visiting process behaves like no filter is set at all. This method is a convenience method to limit and cutoff the search depending on a certain attribute's name or value, the nesting of the search so far or on the contents of the current access-path.

Parameters:

attribute - the current Attribute of the traversal

level - the nesting level of the traversal.

path - the current path of the traversal so far, excluding the current Attribute.

Returns:

false if to exclude this attribute and nested AtributeCollection objects from the traversal. true if the traversal shall continue as is. The full path to the current Attribute thus is path + AttributeCollection.SEPARATOR + attribute.getName();

Find more information in the class documentation