org.biojava.bio
Class OverlayAnnotation

java.lang.Object
  extended by org.biojava.utils.AbstractChangeable
      extended by org.biojava.bio.OverlayAnnotation
All Implemented Interfaces:
java.io.Serializable, Annotation, Changeable

public class OverlayAnnotation
extends AbstractChangeable
implements Annotation, java.io.Serializable

Annotation implementation which allows new key-value pairs to be layered on top of an underlying Annotation. When getProperty is called, we first check for a value stored in the overlay. If this fails, the underlying Annotation is checked. Values passed to setProperty are always stored within the overlay.

Since:
1.1 In the case where you wish to wrap an underlying Annotation in a view that will allow it to be edited without altering the original object, but also reflect changes in the original object.
Author:
Thomas Down, Matthew Pocock, Greg Cox
See Also:
Serialized Form

Nested Class Summary
protected  class OverlayAnnotation.PropertyForwarder
          Forwards change events from the underlying Annotation to this one.
 
Field Summary
 
Fields inherited from interface org.biojava.bio.Annotation
EMPTY_ANNOTATION, PROPERTY
 
Constructor Summary
OverlayAnnotation(Annotation par)
          Construct an annotation which can overlay new key-value pairs onto an underlying annotation.
 
Method Summary
 java.util.Map asMap()
          Return a Map view onto this annotation.
 boolean containsProperty(java.lang.Object key)
          Returns whether there the property is defined.
protected  ChangeSupport getChangeSupport(ChangeType changeType)
          Called to retrieve the ChangeSupport for this object.
protected  java.util.Map getOverlay()
          Get the map used for the overlay.
 java.lang.Object getProperty(java.lang.Object key)
           Retrieve the value of a property by key.
 java.util.Set keys()
          Return a Set containing all key objects visible in this annotation.
 void removeProperty(java.lang.Object key)
          Delete a property.
 void setProperty(java.lang.Object key, java.lang.Object value)
           Set the value of a property.
 
Methods inherited from class org.biojava.utils.AbstractChangeable
addChangeListener, addChangeListener, generateChangeSupport, hasListeners, hasListeners, isUnchanging, removeChangeListener, removeChangeListener
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 
Methods inherited from interface org.biojava.utils.Changeable
addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener
 

Constructor Detail

OverlayAnnotation

public OverlayAnnotation(Annotation par)
Construct an annotation which can overlay new key-value pairs onto an underlying annotation.

Parameters:
par - The `parent' annotation, on which new key-value pairs can be layered.
Method Detail

getChangeSupport

protected ChangeSupport getChangeSupport(ChangeType changeType)
Description copied from class: AbstractChangeable
Called to retrieve the ChangeSupport for this object.

Your implementation of this method should have the following structure:

 ChangeSupport cs = super.getChangeSupport(ct);

 if(someForwarder == null && ct.isMatching(SomeInterface.SomeChangeType)) {
   someForwarder = new ChangeForwarder(...

   this.stateVariable.addChangeListener(someForwarder, VariableInterface.AChange);
 }

 return cs;
 
It is usual for the forwarding listeners (someForwarder in this example) to be transient and lazily instantiated. Be sure to register & unregister the forwarder in the code that does the ChangeEvent handling in setter methods.

Overrides:
getChangeSupport in class AbstractChangeable

getOverlay

protected java.util.Map getOverlay()
Get the map used for the overlay. Modifying this modifies the Annotation.

Returns:
the overlay Map

setProperty

public void setProperty(java.lang.Object key,
                        java.lang.Object value)
                 throws ChangeVetoException
Description copied from interface: Annotation

Set the value of a property.

This method throws an exception if either properties can not be added to this object, or that this particular property is immutable or illegal within the implementation.

Normal raw access to the property. For cleverer access, use methods in AnnotationType.

Specified by:
setProperty in interface Annotation
Parameters:
key - the key object
value - the new value for this key
Throws:
ChangeVetoException - if this annotation object can't be changed, or if the change was vetoed.

removeProperty

public void removeProperty(java.lang.Object key)
                    throws ChangeVetoException
Description copied from interface: Annotation
Delete a property. Normal raw access to the property. For cleverer access, use methods in AnnotationType.

Specified by:
removeProperty in interface Annotation
Parameters:
key - the key object
Throws:
ChangeVetoException - if the change is vetoed

getProperty

public java.lang.Object getProperty(java.lang.Object key)
Description copied from interface: Annotation

Retrieve the value of a property by key.

Unlike the Map collections, it will complain if the key does not exist. It will only return null if the key is defined and has value null.

Normal raw access to the property. For cleverer access, use methods in AnnotationType.

Specified by:
getProperty in interface Annotation
Parameters:
key - the key of the property to retrieve
Returns:
the object associated with that key

containsProperty

public boolean containsProperty(java.lang.Object key)
Description copied from interface: Annotation
Returns whether there the property is defined. Normal raw access to the property. For cleverer access, use methods in AnnotationType.

Specified by:
containsProperty in interface Annotation
Parameters:
key - the key Object to search for
Returns:
true if this Annotation knows about the key, false otherwise

keys

public java.util.Set keys()
Return a Set containing all key objects visible in this annotation. The Set is unmodifiable, but will dynamically reflect changes made to the annotation.

Specified by:
keys in interface Annotation
Returns:
the keys as a Set

asMap

public java.util.Map asMap()
Return a Map view onto this annotation. The returned Map is unmodifiable, but will dynamically reflect any changes made to this annotation.

Specified by:
asMap in interface Annotation
Returns:
a view of this Annotation as an immutable Map