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.AlreadyExistsException;
027import org.biojava.ontology.Triple;
028import org.biojava.utils.ChangeType;
029import org.biojava.utils.ChangeVetoException;
030import org.biojava.utils.Changeable;
031
032/**
033 * Comparable triples, obviously. Allows them to have descriptors. 
034 * @author Richard Holland
035 * @since 1.5
036 */
037public interface ComparableTriple extends Triple,Comparable,Changeable {
038
039    public static final ChangeType DESCRIPTOR = new ChangeType(
040            "This triple's descriptors have changed",
041            "org.biojavax.ontology.ComparableTriple",
042            "DESCRIPTOR"
043            );
044    
045    /**
046     * Adds a descriptor. Must not be null.
047     * @param desc the descriptor to add.
048     * @throws ChangeVetoException in case of objections.
049     * @throws AlreadyExistsException if the descriptor already exists.
050     * @throws IllegalArgumentException if the descriptor is missing.
051     */
052    public void addDescriptor(ComparableTerm desc) throws AlreadyExistsException, IllegalArgumentException,ChangeVetoException;
053    
054    /**
055     * Removes a descriptor. Must not be null.
056     * @return True if it did it, false if the descriptor did not exist.
057     * @param desc the descriptor to remove.
058     * @throws ChangeVetoException in case of objections.
059     * @throws IllegalArgumentException if the descriptor is missing.
060     */
061    public boolean removeDescriptor(ComparableTerm desc) throws IllegalArgumentException,ChangeVetoException;
062     
063    /**
064     * Clears the current set of descriptors and replaces it with the content of 
065     * the set passed.
066     * @param descriptors the set of ComparableTerm descriptors to add.
067     * @throws ChangeVetoException in case of objections.
068     * @see ComparableTerm
069     */
070    public void setDescriptors(Set descriptors) throws ChangeVetoException;
071    
072    /**
073     * Returns all descriptors.
074     * @return a set of all ComparableTerm descriptors, possibly empty.
075     * @see ComparableTerm
076     */
077    public Set getDescriptors();
078    
079}