/*
 *                    BioJava development code
 *
 * This code may be freely distributed and modified under the
 * terms of the GNU Lesser General Public Licence.  This should
 * be distributed with the code.  If you do not have a copy,
 * see:
 *
 *      http://www.gnu.org/copyleft/lesser.html
 *
 * Copyright for this code is held jointly by the individual
 * authors.  These should be listed in @author doc comments.
 *
 * For more information on the BioJava project and its aims,
 * or to join the biojava-l mailing list, visit the home page
 * at:
 *
 *      http://www.biojava.org/
 *
 */

package org.biojava.nbio.ontology;

import org.biojava.nbio.ontology.utils.Annotatable;
import org.biojava.nbio.ontology.utils.Annotation;
import org.biojava.nbio.ontology.utils.SmallAnnotation;

import java.util.Arrays;
import java.util.Set;
import java.util.TreeSet;



/**
 * A term in an ontology.  This has an {@link org.biojava.nbio.Annotation Annotation}
 * which can be used for storing additional human-displayable information.  It
 * is strongly recommended that the Annotation is not used for any machine-readable
 * data -- this should be represented by relations in the ontology instead.
 *
 * <p>
 * Terms are things that represent things. They are the same sort of thing as a
 * Java object or a prolog atom. A sub-set of terms are themselves relations.
 * This means that they are used to describe associations between pairs of terms.
 * Since all terms can be described, it is possible (and indeed encouraged) to
 * describe relations. As a minimum, you should consider saying if they are
 * identity or partial order relations, or if they are transitive, reflexive,
 * symmetrical, anti-symmetrical or anything else you know about them. This gives
 * the inference engine some chance of working out what is going on.
 * </p>
 *
 * @author Thomas Down
 * @author Matthew Pocock
 * @since 1.4
 * @see org.biojavax.ontology.ComparableTerm
 */

public interface Term extends Annotatable {
        /**
         * ChangeType which indicates that this term's ontology has been
         * altered
         */


        /**
         * Return the name of this term.
         * @return the name of the term
         */

        public String getName();

        /**
         * Return a human-readable description of this term, or the empty string if
         * none is available.
         * @return the description of the term
         */

        public String getDescription();

        /** set the description of the term;
         *
         * @param description
         *
         */
        public void setDescription(String description);

        /**
         * Return the ontology in which this term exists.
         * @return the ontology
         */

        public Ontology getOntology();

        /**
         * Return the synonyms for this term.
         * @return the synonyms
         */

        public Object[] getSynonyms();

        /**
         * Add a synonym for this term.
         * @param synonym the synonym
         */

        public void addSynonym(Object synonym);

        /**
         * Remove a synonym for this term.
         * @param synonym
         */

        public void removeSynonym(Object synonym);

        /**
         * Simple in-memory implementation of an ontology term.
         * @see org.biojavax.ontology.SimpleComparableTerm
         * This can be used to implement Ontology.createTerm
         */

        public static class Impl
        extends AbstractTerm
        implements Term, java.io.Serializable {
                /**
                 *
                 */
                private static final long serialVersionUID = 6561668917514377417L;

                private final String name;

                private final Ontology ontology;
                private Annotation annotation;
                private Set<Object> synonyms;

                public Impl(Ontology ontology, String name) {
                        this(ontology,name,null,null);
                }

                public Impl(Ontology ontology, String name, String description) {
                        this(ontology,name,description,null);
                }

                public Impl(Ontology ontology, String name, String description, Object[] synonyms) {
                        if (name == null) {
                                throw new NullPointerException("Name must not be null");
                        }
                        // by AP - description can change from now on...
                        //if (description == null) {
                        //    throw new NullPointerException("Description must not be null");
                        //}
                        if (ontology == null) {
                                throw new NullPointerException("Ontology must not be null");
                        }

                        this.name = name;
                        this.description = description;
                        this.ontology = ontology;

                        this.synonyms = new TreeSet<Object>();
                        if (synonyms!=null) this.synonyms.addAll(Arrays.asList(synonyms));
                }

                @Override
                public void addSynonym(Object synonym) {
                        this.synonyms.add(synonym);
                }

                @Override
                public void removeSynonym(Object synonym) {
                        this.synonyms.remove(synonym);
                }

                @Override
                public Object[] getSynonyms() {
                        return this.synonyms.toArray();
                }

                @Override
                public String getName() {
                        return name;
                }

                public void setAnnotation(Annotation annotation) {
                        this.annotation = annotation;
                }

                public void setSynonyms(Set<Object> synonyms) {
                        this.synonyms = synonyms;
                }

                @Override
                public String getDescription() {
                        return description;
                }

                @Override
                public Ontology getOntology() {
                        return ontology;
                }

                @Override
                public String toString() {
                        return name;
                }

                @Override
                public Annotation getAnnotation() {
                        if (annotation == null) {
                                annotation = new SmallAnnotation();
                        }
                        return annotation;
                }

          @Override
        public int hashCode() {
                int value = 17;
                if(getName() != null)
                  value *= 31 * getName().hashCode();
                return 17 * value;
          }

          @Override
        public boolean equals(Object obj)
          {
                if(obj == this) return true;
                if(!(obj instanceof Term)) return false;

                Term that = (Term) obj;

                return this.getOntology() == that.getOntology() &&
                                this.getName() == that.getName();
          }
        }
}