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.biojavax.ontology;
023
024import java.util.Set;
025
026import org.biojava.ontology.Ontology;
027import org.biojava.ontology.Term;
028import org.biojava.utils.ChangeType;
029import org.biojava.utils.ChangeVetoException;
030import org.biojava.utils.Changeable;
031
032/**
033 * An Ontology that can be compared to another.
034 * @author Richard Holland
035 * @see ComparableTerm
036 * @see ComparableTriple
037 * @since 1.5
038 */
039public interface ComparableOntology extends Ontology,Comparable,Changeable {
040    
041    public static final ChangeType TERM = new ChangeType(
042            "This ontology's terms have changed",
043            "org.biojavax.ontology.ComparableOntology",
044            "TERM"
045            );
046    public static final ChangeType TRIPLE = new ChangeType(
047            "This ontology's triples have changed",
048            "org.biojavax.ontology.ComparableOntology",
049            "TRIPLE"
050            );
051    public static final ChangeType DESCRIPTION = new ChangeType(
052            "This ontology's description has changed",
053            "org.biojavax.ontology.ComparableOntology",
054            "DESCRIPTION"
055            );
056    
057    /**
058     * Sets a human-readable description of this ontology.
059     * @param description the description.
060     * @throws ChangeVetoException in case of problems.
061     */
062    public void setDescription(String description) throws ChangeVetoException;
063    
064    /**
065     * Return a human-readable description of this ontology.
066     * @return the description.
067     */
068    public String getDescription();
069    
070    /**
071     * Clears out all the terms and populates the ontology with the contents
072     * of the set passed. The terms should be ComparableTerms.
073     * @param terms a set of Term objects this ontology should have.
074     * @throws ChangeVetoException if any of them are unacceptable.
075     * @see ComparableTerm
076     */
077    public void setTermSet(Set terms) throws ChangeVetoException;
078    
079    /**
080     * Returns the set of terms in this ontology.
081     * @return a set of ComparableTerm objects.
082     * @see ComparableTerm
083     */
084    public Set getTermSet();
085    
086    /**
087     * Clears out all the triples and populates the ontology with the contents
088     * of the set passed.
089     * @param triples the set of ComparableTriple objects this ontology should have.
090     * @throws ChangeVetoException if any of them are unacceptable.
091     * @see ComparableTriple
092     */
093    public void setTripleSet(Set triples) throws ChangeVetoException;
094    
095    /**
096     * Returns the set of triples in this ontology.
097     * @return the set of ComparableTriple objects.
098     */
099    public Set getTripleSet();
100    
101    /**
102     * Looks for a term with the given name and returns it. If it couldn't be found,
103     * then it creates it, adds it to the ontology, then returns it.
104     * @param name the name of the term to look for.
105     * @return the ComparableTerm representing that name.
106     */
107    public ComparableTerm getOrCreateTerm(String name);
108    
109    /**
110     * Looks for a triple with the given subject object and predicate and returns it. 
111     * If it couldn't be found, then it creates it, adds it to the ontology,
112     * then returns it.
113     * @param subject the subject of the triple eg apple
114     * @param object the object of the triple eg fruit
115     * @param predicate the relationship of the triple eg is_a
116     * @return the ComparableTriple representing the object subject and predicate.
117     */
118    public ComparableTriple getOrCreateTriple(Term subject, Term object, Term predicate);
119    /**
120     * Looks for a term with the same name as the given term and returns it.
121     * If it couldn't be found, then it creates it, adds it to the ontology,
122     * then returns it.
123     * @param term the term to look for.
124     * @return the ComparableTerm representing that term in this ontology.
125     */
126    public ComparableTerm getOrImportTerm(Term term);
127}
128