## org.biojava.bio
Class OverlayAnnotation

    java.lang.Object
      org.biojava.utils.AbstractChangeable
          org.biojava.bio.OverlayAnnotation

All Implemented Interfaces:
  Serializable, Annotation, Changeable

    public class OverlayAnnotation

extends AbstractChangeable
implements Annotation, 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
`Map` `asMap()` Return a `Map` view onto this annotation.
`boolean` `containsProperty(Object key)` Returns whether there the property is defined.
`protected ChangeSupport` `getChangeSupport(ChangeType changeType)` Called to retrieve the ChangeSupport for this object.
`protected Map` `getOverlay()` Get the map used for the overlay.
`Object` `getProperty(Object key)` Retrieve the value of a property by key.
`Set` `keys()` Return a `Set` containing all key objects visible in this annotation.
`void` `removeProperty(Object key)` Delete a property.
`void` `setProperty(Object key, 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 Map getOverlay()

  Get the map used for the overlay. Modifying this modifies the Annotation.

  Returns:
    the overlay Map

### setProperty

    public void setProperty(Object key,
                            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(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 Object getProperty(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(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 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 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