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 *
057 *
058 * @since 1.0
059 */
060public interface Annotation  {
061
062
063        /**
064         * <p>
065         * Retrieve the value of a property by key.
066         * </p>
067         *
068         * <p>
069         * Unlike the Map collections, it will complain if the key does not exist. It
070         * will only return null if the key is defined and has value null.
071         * </p> Normal raw access to the property. For cleverer access, use
072         * methods in AnnotationType.
073         *
074         * @param key  the key of the property to retrieve
075         * @return  the object associated with that key
076         * @throws NoSuchElementException if there is no property with the key
077         *
078         *
079         */
080        Object getProperty(Object key);
081
082        /**
083         * <p>
084         * Set the value of a property.
085         * </p>
086         *
087         * <p>
088         * This method throws an exception if either properties can not be
089         * added to this object, or that this particular property is immutable or
090         * illegal within the implementation.
091         * </p> Normal raw access to the property. For cleverer access, use
092         * methods in AnnotationType.
093         *
094         * @param key the key object
095         * @param value the new value for this key
096         * @throws IllegalArgumentException if the property <code>key</code> is not
097         *         legal
098         */
099        void setProperty(Object key, Object value)
100        ;
101
102        /**
103         * Delete a property. Normal raw access to the property. For cleverer access, use
104         * methods in AnnotationType.
105         *
106         * @param key the key object
107         * @throws NoSuchElementException if the property doesn't exist
108         * @since 1.3
109         *
110         */
111
112        public void removeProperty(Object key)
113        ;
114
115        /**
116         * Returns whether there the property is defined. Normal raw access to the property. For cleverer access, use
117         * methods in AnnotationType.
118         *
119         * @param key the key Object to search for
120         * @return true if this Annotation knows about the key, false otherwise
121         */
122        boolean containsProperty(Object key);
123
124        /**
125         * Get a set of key objects.
126         *
127         * @return  a Set of key objects
128         */
129        Set keys();
130
131        /**
132         * Return a map that contains the same key/values as this Annotation.
133         * <p>
134         * If the annotation changes, the map may not reflect this.  The Map
135         * may be unmodifiable.
136         *
137         * @return a Map
138         */
139        Map asMap();
140
141        /**
142         * <p>
143         * A really useful empty and immutable annotation object.
144         * </p>
145         *
146         * Be careful when storing Annotation arguments to
147         *  constructors. It is possible that you have been passed EMPTY_ANNOTATION but
148         * that code later on will access this object believing it to be
149         * mutable. For example, the SeqIO factory code clones some
150         * Annotations passed in on Feature.Template instances
151         *
152         * Use this instead of null when you really don't want an object or
153         * an implementation to have annotation even though it should implement
154         * Annotatable.
155         */
156        static final Annotation EMPTY_ANNOTATION = new EmptyAnnotation();
157}
158