scale.annot
Class Annotation

java.lang.Object
  scale.annot.Annotation

All Implemented Interfaces:

DisplayNode

Direct Known Subclasses:

AliasAnnote, PureFunctionAnnotation

public abstract class Annotation
extends java.lang.Object
implements DisplayNode

Annotations are a flexible mechanism for attaching information to certain class instances such as the nodes of a program representation graph.

$Id: Annotation.java,v 1.53 2007-08-27 18:37:27 burrill Exp $

Copyright 2008 by the Scale Compiler Group,
Department of Computer Science
University of Massachusetts,
Amherst MA. 01003, USA
All Rights Reserved.

An annotation should be used to specify information whose lack will not result in an invalid compilation. If the information is needed for validity, it should be represented as a member field of a class instead. It should not be possible to reach from the annotation instance to the object that is annotated .

The same annotation mechanism is used for both Clef and Score and all classes derived from the Root class.

Annotations are not an efficient (in either space or time) mechanism for representing a given piece of information, but are flexible enough to represent varied information.

Annotations represent varied information. Some information will be immutable, and so the annotation will not change (i.e., be deleted) over time. Other information is transitory and will need to be deleted, perhaps even en masse. The annotation handling mechanism has the following capabilities:

• Associates annotations with nodes of a program representation.
• Efficiently answers the question: Does a node have an annotation of a given type?
• Supports efficient removal of all annotations of a given type from the program representation.
• Annotations are unique.
• Allows nodes to have more than one instance of a single annotation type.
• Hides the implementation of annotations and their supporting structures enough to allow performance improvements later.
• Enables garbage collection of discarded annotation instances.

All annotations inherit from the abstract Annotation class. Each sub-class has a static method annotationKey that returns the key for that class of annotation. Each sub-class has a static create method that is called to attach the annotation of that type to a node. This annotation instance may be a new instance or it may be an already existing instance. The constructor method in every annoation sub-class is private in order to insure that the create method is always used.

The create method takes a minimum of three arguments.

1. The first argument is the node to which the new annotation will be attached. It is important to use the most restrictive class possible for the type of this argument as it is used by the AnnotationTool to determine the which annotations can be attached to which nodes.
2. The second argument specifies who created the annotation. Annotations carry an indication of where they were created. This is used for debugging and error checking. The creator is represented by a Creator object which is sub-classed to specify the type of creator. Some sample sub-classes are as follows:
   • CreatorSource
   • CreatorAnnotationTool
   • CreatorClef2score
   • CreatorclefBuilder
   • CreatorAliasAnalysis
   The creator field is immutable.
3. The third argument specifies the belief in this annotation. Annotations retain a measure of belief in the accuracy of the annotation. Annotations maintain separate values for the user's belief and the system's (i.e., Scale's) belief, and an indication of how to combine the beliefs into a single value. The representation of belief is intended to support two situations:
   1. Verification of annotations
   2. Overriding of annotations (usually by the user)
   For example, an annotation which is known to be absolutely true presumably would not have to be verified. Also, if a user wants to disable an annotation that the system created, the system's belief may still be used to issue warnings.

Since Scale is not a truth system, it is not overly sophisticated in the use of belief values. If the combined belief value suggests any level of truth, the annotation should be treated as true (except by annotation verification components).

See Also:

Support, Creator

Field Summary

static java.lang.String[]

knownAnnotations This is a list of all the annotations classes known by the Scale system.

Constructor Summary

protected

Annotation(Creator creator, Support support) Create an annotation.

Method Summary

void	addNode(AnnotationInterface n) Associates a node with this annotation.
static java.util.Enumeration<Annotation>	allAnnotations(AnnotationInterface n) Return an enumeration of all annotations in the annotation container.
static java.util.Enumeration<Annotation>	allMatchingAnnotations(java.lang.Object akey, AnnotationInterface n) Return an enumeration of all annotations with the specified key in the annotation container.
static java.lang.Object	annotationKey() All sub-classes should define annotationKey() to return a unique object for the key.
java.lang.String	annotationName() For display and debugging.
boolean	equals(java.lang.Object o) Return true if both annotations have the same key, creator, support, etc.
abstract boolean	equivalent(Annotation a) Return true if the annotations are equivalent.
static Annotation	getAnnotation(java.lang.Object akey, AnnotationInterface n) Returns a single instance of the annotation with the given key from the annotation container.
Creator	getCreator() Return the creator of the annotation.
DColor	getDisplayColorHint() Return a String specifying the color to use for coloring this node in a graphical display.
java.lang.String	getDisplayLabel() Return a String suitable for labeling this node in a graphical display.
java.lang.String	getDisplayName() Return a unique name suitable for display.
DShape	getDisplayShapeHint() Return a String specifying a shape to use when drawing this node in a graphical display.
abstract java.lang.Object	getKey() Return the key for this annotation class.
int	getNodeID() Return the node label.
Support	getSupport() Return the support of the annotation.
static boolean	hasAnnotation(java.lang.Object akey, AnnotationInterface n) Test if the indicated annotation kind is in the container.
static boolean	hasEqualAnnotation(Annotation a, AnnotationInterface n) Test if the equivalent annotation is in the container.
int	hashCode()
abstract boolean	isUnique() Returns a flag indicating if a node is permitted to have multiple instances of this annotation type.
static void	removeAllAnnotationTables() Remove all annotations from static lookup tables.
void	removeNode(AnnotationInterface n) Removes an association of a node with this annotation.
static void	removeNode(AnnotationInterface n, java.lang.Object key) Removes an association of a node with all annotations having this key.
boolean	sameSupport(Creator c, Support sup) Return true if the annotation has this creator and this support.
java.lang.String	toString() Return a string representation of the annotation.
static java.lang.String	toStringAnnotations(AnnotationInterface n) Convert the container of annotations to a string representation.
java.lang.String	toStringClass() Convert the class name of this node to a string representation.
abstract java.lang.String	toStringSpecial() Return a string representation of the additioanl internal state of the annotation.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

knownAnnotations

public static final java.lang.String[] knownAnnotations

This is a list of all the annotations classes known by the Scale system.

Constructor Detail

Annotation

protected Annotation(Creator creator,
                     Support support)

Create an annotation. This constructor should only be called by a sub-class constructor.

Parameters:

creator - indication of what Scale component created this annotation

support - the support for this annotation

See Also:

Creator, Support

Method Detail

annotationKey

public static java.lang.Object annotationKey()

All sub-classes should define annotationKey() to return a unique object for the key. There is no key for the abstract class Annotation. Currently, this object is the string representing the full class name.

getKey

public abstract java.lang.Object getKey()

Return the key for this annotation class. Since

    this.annotationKey()
 

returns the wrong key when used in a parent class method, each sub-class must implement a method to return its key.

   public Object getKey()
   {
     return ThisClass.annotationKey();
   }
 

annotationName

public final java.lang.String annotationName()

For display and debugging.

addNode

public final void addNode(AnnotationInterface n)

Associates a node with this annotation. The caller of this method must always use the method as

    na = annotation.addNode(this, na);
 

Parameters:

n - node being added

removeNode

public static final void removeNode(AnnotationInterface n,
                                    java.lang.Object key)
                             throws NoSuchElementException

Removes an association of a node with all annotations having this key.

Parameters:

n - node being disassociated

key - is the annotation key

Throws:

NoSuchElementException - tried to delete a node which is not associated with this annotation.

removeNode

public final void removeNode(AnnotationInterface n)
                      throws NoSuchElementException

Removes an association of a node with this annotation.

Parameters:

n - node being disassociated

Throws:

NoSuchElementException - tried to delete a node which is not associated with this annotation.

getSupport

public final Support getSupport()

Return the support of the annotation.

getCreator

public final Creator getCreator()

Return the creator of the annotation.

isUnique

public abstract boolean isUnique()

Returns a flag indicating if a node is permitted to have multiple instances of this annotation type.

Returns:

true when a node may not have multiple instances of this annotation type

equivalent

public abstract boolean equivalent(Annotation a)

Return true if the annotations are equivalent. Note - the Creator and the Support are not used in equivalence testing.

Parameters:

a - the other annotation

equals

public final boolean equals(java.lang.Object o)

Return true if both annotations have the same key, creator, support, etc.

Overrides:

equals in class java.lang.Object

Parameters:

o - the other annotation

hashCode

public int hashCode()

Overrides:

hashCode in class java.lang.Object

sameSupport

public final boolean sameSupport(Creator c,
                                 Support sup)

Return true if the annotation has this creator and this support.

toStringClass

public final java.lang.String toStringClass()

Convert the class name of this node to a string representation.

toString

public final java.lang.String toString()

Return a string representation of the annotation.

Overrides:

toString in class java.lang.Object

toStringSpecial

public abstract java.lang.String toStringSpecial()

Return a string representation of the additioanl internal state of the annotation.

getAnnotation

public static final Annotation getAnnotation(java.lang.Object akey,
                                             AnnotationInterface n)

Returns a single instance of the annotation with the given key from the annotation container. This method may return null.

Parameters:

akey - the annotation key

n - is the node with annotations

Returns:

an arbitrary annotation of the indicated kind or null

hasAnnotation

public static final boolean hasAnnotation(java.lang.Object akey,
                                          AnnotationInterface n)

Test if the indicated annotation kind is in the container.

Parameters:

akey - the annotation key

n - is the node with annotations

Returns:

true if the indicated kind of annotation is in the annoation container

hasEqualAnnotation

public static final boolean hasEqualAnnotation(Annotation a,
                                               AnnotationInterface n)

Test if the equivalent annotation is in the container. Note - the Creator and Support are not used in equivalence testing.

Parameters:

a - is the annotation

n - is the node with annotations

Returns:

true if an equivalent annotation is in the annoation container

allAnnotations

public static final java.util.Enumeration<Annotation> allAnnotations(AnnotationInterface n)

Return an enumeration of all annotations in the annotation container.

Parameters:

n - is the node with annotations

Returns:

an enumeration of all the annotations in the annotation container

allMatchingAnnotations

public static final java.util.Enumeration<Annotation> allMatchingAnnotations(java.lang.Object akey,
                                                                             AnnotationInterface n)

Return an enumeration of all annotations with the specified key in the annotation container.

Parameters:

akey - the annotation key

n - is the node with annotations

Returns:

an enumeration of all the annotations of the indicated kind in the annotation container

toStringAnnotations

public static final java.lang.String toStringAnnotations(AnnotationInterface n)

Convert the container of annotations to a string representation.

Parameters:

n - is the node with annotations

getNodeID

public int getNodeID()

Return the node label.

getDisplayName

public java.lang.String getDisplayName()

Return a unique name suitable for display.

Specified by:

getDisplayName in interface DisplayNode

getDisplayLabel

public java.lang.String getDisplayLabel()

Return a String suitable for labeling this node in a graphical display.

Specified by:

getDisplayLabel in interface DisplayNode

getDisplayColorHint

public DColor getDisplayColorHint()

Return a String specifying the color to use for coloring this node in a graphical display.

Specified by:

getDisplayColorHint in interface DisplayNode

See Also:

DColor

getDisplayShapeHint

public DShape getDisplayShapeHint()

Return a String specifying a shape to use when drawing this node in a graphical display.

Specified by:

getDisplayShapeHint in interface DisplayNode

See Also:

DShape

removeAllAnnotationTables

public static void removeAllAnnotationTables()

Remove all annotations from static lookup tables.