001/*
002 *                    BioJava development code
003 *
004 * This code may be freely distributed and modified under the
005 * terms of the GNU Lesser General Public Licence.  This should
006 * be distributed with the code.  If you do not have a copy,
007 * see:
008 *
009 *      http://www.gnu.org/copyleft/lesser.html
010 *
011 * Copyright for this code is held jointly by the individual
012 * authors.  These should be listed in @author doc comments.
013 *
014 * For more information on the BioJava project and its aims,
015 * or to join the biojava-l mailing list, visit the home page
016 * at:
017 *
018 *      http://www.biojava.org/
019 *
020 */
021
022
023package org.biojava.nbio.ontology.utils;
024
025import java.util.Map;
026import java.util.NoSuchElementException;
027import java.util.Set;
028
029
030/**
031 * <p>
032 * Arbitrary annotation associated with one or more objects.
033 * </p>
034 *
035 * <p>
036 * Biological information often does not fit design patterns very well, and can
037 * be a jumble of facts and relationships. Annotation objects provide a standard
038 * way for you to store this mess as a property of an object.
039 * </p>
040 *
041 * <p>
042 * Annotations may contain keys that have Annotations as values. In this way,
043 * annotations can be shared among multiple Annotatable objects, and you can
044 * represent semi-structured data.
045 * </p>
046 *
047 * <p>
048 * It is perfectly possible to wrap up almost any tree-like or flat data
049 * structure as Annotation.
050 * </p>
051 * Other than when using the constructor, you should be able to
052 * interact with nearly all Annotation implementations via this API.
053 *
054 * @author Matthew Pocock
055 * @author Thomas Down
056 * @see org.biojavax.RichAnnotation
057 *
058 *
059 * @since 1.0
060 */
061public interface Annotation  {
062
063
064        /**
065         * <p>
066         * Retrieve the value of a property by key.
067         * </p>
068         *
069         * <p>
070         * Unlike the Map collections, it will complain if the key does not exist. It
071         * will only return null if the key is defined and has value null.
072         * </p> Normal raw access to the property. For cleverer access, use
073         * methods in AnnotationType.
074         *
075         * @param key  the key of the property to retrieve
076         * @return  the object associated with that key
077         * @throws NoSuchElementException if there is no property with the key
078         *
079         *
080         */
081        Object getProperty(Object key) throws NoSuchElementException;
082
083        /**
084         * <p>
085         * Set the value of a property.
086         * </p>
087         *
088         * <p>
089         * This method throws an exception if either properties can not be
090         * added to this object, or that this particular property is immutable or
091         * illegal within the implementation.
092         * </p> Normal raw access to the property. For cleverer access, use
093         * methods in AnnotationType.
094         *
095         * @param key the key object
096         * @param value the new value for this key
097         * @throws IllegalArgumentException if the property <code>key</code> is not
098         *         legal
099         * @throws ChangeVetoException if this annotation object can't be changed, or
100         *         if the change was vetoed.
101         */
102        void setProperty(Object key, Object value)
103                        throws IllegalArgumentException;
104
105        /**
106         * Delete a property. Normal raw access to the property. For cleverer access, use
107         * methods in AnnotationType.
108         *
109         * @param key the key object
110         * @throws NoSuchElementException if the property doesn't exist
111         * @throws ChangeVetoException if the change is vetoed
112         * @since 1.3
113         *
114         */
115
116        public void removeProperty(Object key)
117                        throws NoSuchElementException;
118
119        /**
120         * Returns whether there the property is defined. Normal raw access to the property. For cleverer access, use
121         * methods in AnnotationType.
122         *
123         * @param key the key Object to search for
124         * @return true if this Annotation knows about the key, false otherwise
125         */
126        boolean containsProperty(Object key);
127
128        /**
129         * Get a set of key objects.
130         *
131         * @return  a Set of key objects
132         */
133        Set keys();
134
135        /**
136         * Return a map that contains the same key/values as this Annotation.
137         * <p>
138         * If the annotation changes, the map may not reflect this.  The Map
139         * may be unmodifiable.
140         *
141         * @return a Map
142         */
143        Map asMap();
144
145        /**
146         * <p>
147         * A really useful empty and immutable annotation object.
148         * </p>
149         *
150         * Be careful when stooring Annotation arguments to
151         *  constructors. It is possible that you have been passed EMPTY_ANNOTATION but
152         * that code later on will access this object believing it to be
153         * mutable. For example, the SeqIO factory code clones some
154         * Annotations passed in on Feature.Template instances
155         *
156         * Use this instead of null when you really don't want an object or
157         * an implementation to have annotation even though it should implement
158         * Annotatable.
159         */
160        static final Annotation EMPTY_ANNOTATION = new EmptyAnnotation();
161}
162