jdsl.core.api
Interface Decorable

All Known Subinterfaces:
Edge, Face, Position, Vertex
All Known Implementing Classes:
HashtableDecorable

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 an attribute.

The decorations are based on the concept of key. The key 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 key for decoring more than one decorable object. For example, if we are decorating all the positions of a graph we can use just one key to retrieve the decoration on all positions.

Version:
$Id: Decorable.java,v 1.3 2000/01/12 03:21:28 mdh Exp $
Author:
Luca Vismara (lv), Andrew Schwerin (schwerin), Maurizio Pizzonia (map)

Method Summary
 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

public 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 key is invalid (i.e. wrong class)

get

public 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

public 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

public 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.