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
022package org.biojava.ontology;
023
024import java.util.Arrays;
025import java.util.Set;
026import java.util.TreeSet;
027
028import org.biojava.bio.Annotatable;
029import org.biojava.bio.Annotation;
030import org.biojava.bio.SmallAnnotation;
031import org.biojava.utils.ChangeType;
032
033/**
034 * A term in an ontology.  This has an {@link org.biojava.bio.Annotation Annotation}
035 * which can be used for storing additional human-displayable information.  It
036 * is strongly recommended that the Annotation is not used for any machine-readable
037 * data -- this should be represented by relations in the ontology instead.
038 *
039 * <p>
040 * Terms are things that represent things. They are the same sort of thing as a
041 * Java object or a prolog atom. A sub-set of terms are themselves relations.
042 * This means that they are used to describe associations between pairs of terms.
043 * Since all terms can be described, it is possible (and indeed encouraged) to
044 * describe relations. As a minimum, you should consider saying if they are
045 * identity or partial order relations, or if they are transitive, reflexive,
046 * symmetrical, anti-symmetrical or anything else you know about them. This gives
047 * the inference engine some chance of working out what is going on.
048 * </p>
049 *
050 * @author Thomas Down
051 * @author Matthew Pocock
052 * @since 1.4
053 * @see org.biojavax.ontology.ComparableTerm
054 */
055
056public interface Term extends Annotatable {
057    /**
058     * ChangeType which indicates that this term's ontology has been
059     * altered
060     */
061
062    public static final ChangeType ONTOLOGY = new ChangeType(
063      "This term's ontology has been changed",
064      "org.biojava.ontology.Term",
065      "ONTOLOGY"
066    );
067
068    /**
069     * Return the name of this term.
070     * @return the name of the term
071     */
072
073    public String getName();
074
075    /**
076     * Return a human-readable description of this term, or the empty string if
077     * none is available.
078     * @return the description of the term
079     */
080
081    public String getDescription();
082    
083    /** set the description of the term;
084     * 
085     * @param description
086     * 
087     */
088    public void setDescription(String description);
089
090    /**
091     * Return the ontology in which this term exists.
092     * @return the ontology
093     */
094
095    public Ontology getOntology();
096
097    /**
098     * Return the synonyms for this term.
099     * @return the synonyms
100     */
101
102    public Object[] getSynonyms();
103
104    /**
105     * Add a synonym for this term.
106     * @param synonym the synonym
107     */
108
109    public void addSynonym(Object synonym);
110
111    /**
112     * Remove a synonym for this term.
113     * @param synonym 
114     */
115
116    public void removeSynonym(Object synonym);
117    
118    /**
119     * Simple in-memory implementation of an ontology term.
120     * @see org.biojavax.ontology.SimpleComparableTerm
121     * This can be used to implement Ontology.createTerm
122     */
123
124    public static class Impl
125    extends AbstractTerm
126    implements Term, java.io.Serializable {
127        /**
128                 * 
129                 */
130                private static final long serialVersionUID = 6561668917514377417L;
131
132                private final String name;
133        
134        private final Ontology ontology;
135        private Annotation annotation;
136        private Set<Object> synonyms;
137
138        public Impl(Ontology ontology, String name) {
139            this(ontology,name,null,null);
140        }
141        
142        public Impl(Ontology ontology, String name, String description) {
143            this(ontology,name,description,null);
144        }
145         
146        public Impl(Ontology ontology, String name, String description, Object[] synonyms) {
147            if (name == null) {
148                throw new NullPointerException("Name must not be null");
149            }
150            // by AP - description can change from now on...
151            //if (description == null) {
152            //    throw new NullPointerException("Description must not be null");
153            //}
154            if (ontology == null) {
155                throw new NullPointerException("Ontology must not be null");
156            }
157
158            this.name = name;
159            this.description = description;
160            this.ontology = ontology;
161
162            this.synonyms = new TreeSet<Object>();
163            if (synonyms!=null) this.synonyms.addAll(Arrays.asList(synonyms));
164        }
165
166        public void addSynonym(Object synonym) {
167            this.synonyms.add(synonym);
168        }
169        
170        public void removeSynonym(Object synonym) {
171            this.synonyms.remove(synonym);
172        }
173        
174        public Object[] getSynonyms() {
175            return this.synonyms.toArray();
176        }
177
178        public String getName() {
179            return name;
180        }                        
181
182                public void setAnnotation(Annotation annotation) {
183                        this.annotation = annotation;
184                }
185
186                public void setSynonyms(Set<Object> synonyms) {
187                        this.synonyms = synonyms;
188                }
189
190                public String getDescription() {
191            return description;
192        }
193
194        public Ontology getOntology() {
195            return ontology;
196        }
197
198        public String toString() {
199            return name;
200        }
201
202        public Annotation getAnnotation() {
203            if (annotation == null) {
204                annotation = new SmallAnnotation();
205            }
206            return annotation;
207        }
208
209      public int hashCode() {
210        int value = 17;
211        if(getName() != null)
212          value *= 31 * getName().hashCode();
213        return 17 * value;
214      }
215
216      public boolean equals(Object obj)
217      {
218        if(obj == this) return true;
219        if(!(obj instanceof Term)) return false;
220
221        Term that = (Term) obj;
222
223        return this.getOntology() == that.getOntology() &&
224                this.getName() == that.getName();
225      }
226    }
227}