nz.ac.waikato.jdsl.core.api
Interface Decorable

All Known Subinterfaces:

Edge, Position, Vertex

All Known Implementing Classes:

Edge.NONEEdge, HashtableDecorable, NodeBinaryTree.NBTNode, NodeBinaryTree.NBTSuperNode, NodeSequence.FNSNode, Vertex.NONEVertex

public interface Decorable

Decorability is the ability to attach extra pieces of information to an object. Although there are no restrictions on how long a decoration may remain attached to an object, the slow speed of most implementations prevent them from being useful for any sort of long-term storage. Their primary use is in labelling an object during the course of an algorithm so that the algorithm may return later in its execution in order to access the label.

Such temporary storage of information is useful in the form of decoration because it allows an algorithm to be written for an existing data structure without having to use secondary data structures and without having to modify the internal representation of the data structure.

This interface defines the methods that a decorable object must implement: those of getting, setting, destroying and checking for a decoration.

The decorations are based on the concept of attribute. The attribute identifies a decoration among all possible ones in a decorated object, and it has to be provided for accessing the decoration itself. Nothing prevents using the same attribute for decoring more than one decorable object. For example, if we are decorating all the positions of a graph we can use just one attribute to retrieve the decoration on all positions.

Version:

JDSL 2.1.1

Author:

Luca Vismara (lv), Andrew Schwerin (schwerin), Maurizio Pizzonia (map)

Method Summary

ObjectIterator	attributes() Returns an iterator over all the attributes attached to this decorable.
java.lang.Object	destroy(java.lang.Object attr) Removes the (attribute, value) entry associated with a certain attribute, attr, from the decorable object.
java.lang.Object	get(java.lang.Object attr) Returns the value in the (attribute, value) entry associated with a certain attribute, attr, in this decorable object.
boolean	has(java.lang.Object attr) Tests whether there is an (attribute, value) entry associated with a certain attribute in this decorable object.
void	set(java.lang.Object attr, java.lang.Object value) Sets the value in the (attribute, value) entry associated with a certain attribute in this decorable object.

Method Detail

set

void set(java.lang.Object attr,
         java.lang.Object value)
         throws InvalidAttributeException

Sets the value in the (attribute, value) entry associated with a certain attribute in this decorable object. Creates the attribute if it does not already exist in this decorable object.

Parameters:

attr - The attribute to set (and create if necessary)

value - the new value of the attribute in the decorable object

Throws:

InvalidAttributeException - if the attribute is invalid (i.e. wrong class)

get

java.lang.Object get(java.lang.Object attr)
                     throws InvalidAttributeException

Returns the value in the (attribute, value) entry associated with a certain attribute, attr, in this decorable object.

Parameters:

attr - The attribute of which to attempt to get the value

Returns:

The value associated with attribute

Throws:

InvalidAttributeException - if attr is not set or is otherwise invalid (i.e. wrong class)

destroy

java.lang.Object destroy(java.lang.Object attr)
                         throws InvalidAttributeException

Removes the (attribute, value) entry associated with a certain attribute, attr, from the decorable object.

Parameters:

attr - The attribute to destroy (eliminate)

Returns:

the value associated with destroyed attribute

Throws:

InvalidAttributeException - if the attribute is not set or is otherwise invalid (i.e. wrong class)

has

boolean has(java.lang.Object attr)
            throws InvalidAttributeException

Tests whether there is an (attribute, value) entry associated with a certain attribute in this decorable object.

Parameters:

attr - The attribute for which to check this decorable object

Throws:

InvalidAttributeException - if attribute is invalid for some reason

attributes

ObjectIterator attributes()

Returns an iterator over all the attributes attached to this decorable.

Returns:

an ObjectIterator over all the attributes attached to this decorable