org.biojava.bio
Interface Annotation

All Superinterfaces:
Changeable
All Known Implementing Classes:
AbstractAnnotation, MergeAnnotation, OverlayAnnotation

public interface Annotation
extends Changeable

Arbitrary annotation associated with one or more objects.

Biological information often does not fit design patterns very well, and can be a jumble of facts and relationships. Annotation objects provide a standard way for you to store this mess as a property of an object.

Annotations may contain keys that have Annotations as values. In this way, annotations can be shared among multiple Annotatable objects, and you can represent semi-structured data.

It is perfectly possible to wrap up almost any tree-like or flat data structure as Annotation.

Author:
Matthew Pocock, Thomas Down
For general use:
Other than when using the constructor, you should be able to interact with nearly all Annotation implementations via this API.

Field Summary
static Annotation EMPTY_ANNOTATION
           A really useful empty and immutable annotation object.
static ChangeType PROPERTY
          This type symbolizes that one or more properties have changed.
 
Method Summary
 java.util.Map asMap()
          Return a map that contains the same key/values as this Annotation.
 boolean containsProperty(java.lang.Object key)
          Returns whether there the property is defined.
 java.lang.Object getProperty(java.lang.Object key)
           Retrieve the value of a property by key.
 java.util.Set keys()
          Get a set of key objects.
 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 interface org.biojava.utils.Changeable
addChangeListener, addChangeListener, isUnchanging, removeChangeListener, removeChangeListener
 

Field Detail

PROPERTY

public static final ChangeType PROPERTY
This type symbolizes that one or more properties have changed.


EMPTY_ANNOTATION

public static final Annotation EMPTY_ANNOTATION

A really useful empty and immutable annotation object.

For general use:
Use this instead of null when you really don't want an object or an implementation to have annotation even though it should implement Annotatable.
For developers:
Be careful when stooring Annotation arguments to constructors. It is possible that you have been passed EMPTY_ANNOTATION but that code later on will access this object believing it to be mutable. For example, the SeqIO factory code clones some Annotations passed in on Feature.Template instances
Method Detail

getProperty

public java.lang.Object getProperty(java.lang.Object key)
                             throws java.util.NoSuchElementException

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.

Parameters:
key - the key of the property to retrieve
Returns:
the object associated with that key
Throws:
java.util.NoSuchElementException - if there is no property with the key
For general use:
Normal raw access to the property. For cleverer access, use methods in AnnotationType.

setProperty

public void setProperty(java.lang.Object key,
                        java.lang.Object value)
                 throws java.lang.IllegalArgumentException,
                        ChangeVetoException

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.

Parameters:
key - the key object
value - the new value for this key
Throws:
java.lang.IllegalArgumentException - if the property key is not legal
ChangeVetoException - if this annotation object can't be changed, or if the change was vetoed
For general use:
Normal raw access to the property. For cleverer access, use methods in AnnotationType.

removeProperty

public void removeProperty(java.lang.Object key)
                    throws java.util.NoSuchElementException,
                           ChangeVetoException
Delete a property

Parameters:
key - the key object
Throws:
java.util.NoSuchElementException - if the property doesn't exist
ChangeVetoException - if the change is vetoed
Since:
1.3
For general use:
Normal raw access to the property. For cleverer access, use methods in AnnotationType.

containsProperty

public boolean containsProperty(java.lang.Object key)
Returns whether there the property is defined.

Parameters:
key - the key Object to search for
Returns:
true if this Annotation knows about the key, false otherwise
For general use:
Normal raw access to the property. For cleverer access, use methods in AnnotationType.

keys

public java.util.Set keys()
Get a set of key objects.

Returns:
a Set of key objects

asMap

public java.util.Map asMap()
Return a map that contains the same key/values as this Annotation.

If the annotation changes, the map may not reflect this. The Map may be unmodifiable.

Returns:
a Map