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.bio;
023
024import java.util.Set;
025
026import org.biojava.utils.ChangeType;
027import org.biojava.utils.ChangeVetoException;
028import org.biojava.utils.Changeable;
029import org.biojavax.Comment;
030import org.biojavax.Namespace;
031import org.biojavax.RankedCrossRefable;
032import org.biojavax.RankedDocRef;
033import org.biojavax.RichAnnotatable;
034import org.biojavax.bio.taxa.NCBITaxon;
035
036/**
037 * This class relates to the bioentry table in BioSQL. It holds everything you need
038 * to define a non-sequence bearing bioentry.
039 * @author Mark Schreiber
040 * @author Richard Holland
041 * @see BioEntryRelationship
042 * @since 1.5
043 */
044public interface BioEntry extends RichAnnotatable,RankedCrossRefable,Comparable,Changeable {
045    
046    public static final ChangeType IDENTIFIER = new ChangeType(
047            "This bioentry's identifier has changed",
048            "org.biojavax.bio.BioEntry",
049            "IDENTIFIER"
050            );
051    public static final ChangeType DESCRIPTION = new ChangeType(
052            "This bioentry's description has changed",
053            "org.biojavax.bio.BioEntry",
054            "DESCRIPTION"
055            );
056    public static final ChangeType DIVISION = new ChangeType(
057            "This bioentry's division has changed",
058            "org.biojavax.bio.BioEntry",
059            "DIVISION"
060            );
061    public static final ChangeType TAXON = new ChangeType(
062            "This bioentry's taxon has changed",
063            "org.biojavax.bio.BioEntry",
064            "TAXON"
065            );
066    public static final ChangeType SEQVERSION = new ChangeType(
067            "This bioentry's sequence version has changed",
068            "org.biojavax.bio.BioEntry",
069            "SEQVERSION"
070            );
071    public static final ChangeType RANKEDCROSSREF = new ChangeType(
072            "This bioentry's ranked crossrefs changed",
073            "org.biojavax.bio.BioEntry",
074            "RANKEDCROSSREF"
075            );
076    public static final ChangeType RANKEDDOCREF = new ChangeType(
077            "This bioentry's ranked docrefs changed",
078            "org.biojavax.bio.BioEntry",
079            "RANKEDDOCREF"
080            );
081    public static final ChangeType COMMENT = new ChangeType(
082            "This bioentry's comments changed",
083            "org.biojavax.bio.BioEntry",
084            "COMMENT"
085            );
086    public static final ChangeType RELATIONS = new ChangeType(
087            "This bioentry's relations have changed",
088            "org.biojavax.bio.BioEntry",
089            "RELATIONS"
090            );
091    
092    /**
093     * Returns the namespace of this bioentry. The namespace is supposed
094     * to be an immutable property set by the constructor.
095     * @return the namespace of this bioentry.
096     */
097    public Namespace getNamespace();
098    
099    /**
100     * Returns the name of this bioentry. The name is supposed
101     * to be an immutable property set by the constructor.
102     * @return Value of property name.
103     */
104    public String getName();
105    
106    /**
107     * Returns the accession of this bioentry. The accession is supposed
108     * to be an immutable property set by the constructor.
109     * @return Value of property accession.
110     */
111    public String getAccession();
112    
113    /**
114     * Returns the identifier of this bioentry.
115     * @return Value of property identifier.
116     */
117    public String getIdentifier();
118    
119    /**
120     * Sets the identifier of this bioentry. Null is allowable.
121     * @param identifier New value of property identifier.
122     * @throws ChangeVetoException in case of objections.
123     */
124    public void setIdentifier(String identifier) throws ChangeVetoException;
125    
126    /**
127     * Returns the division of this bioentry. Division relates to a division
128     * of the parent namespace.
129     * @return Value of property division.
130     */
131    public String getDivision();
132    
133    /**
134     * Sets the division of this bioentry. Null is allowable.
135     * @param division New value of property division.
136     * @throws ChangeVetoException in case of objections.
137     */
138    public void setDivision(String division) throws ChangeVetoException;
139    
140    /**
141     * Returns a description of this sequence.
142     * @return Value of property description.
143     */
144    public String getDescription();
145    
146    /**
147     * Sets the description for this bioentry.
148     * @param description New value of property description.
149     * @throws ChangeVetoException in case of objections.
150     */
151    public void setDescription(String description) throws ChangeVetoException;
152    
153    /**
154     * Gets the version of this bioentry. Bioentries with no versions return 0.
155     * The version is supposed to be immutable and set only by the constructor.
156     * @return Value of property version.
157     */
158    public int getVersion();
159    
160    /**
161     * Gets the taxon associated with this bioentry. It may be null.
162     * @return Value of property taxon.
163     */
164    public NCBITaxon getTaxon();
165    
166    /**
167     * Sets the taxon for this bioentry. It may be null, in which case the
168     * taxon is unset.
169     * @param taxon New value of property taxon.
170     * @throws ChangeVetoException in case of objections.
171     */
172    public void setTaxon(NCBITaxon taxon) throws ChangeVetoException;
173    
174    /**
175     * Returns a set of all bioentrydocrefs associated with this bioentry. This
176     * set is not mutable. If no docrefs are associated, you will get back an
177     * empty set.
178     * @return a set of RankedDocRef objects.
179     * @see RankedDocRef
180     */
181    public Set<RankedDocRef> getRankedDocRefs();
182    
183    /**
184     * Returns a set of all comments associated with this bioentry. This
185     * set is not mutable. If no comments are associated, you will get back an
186     * empty set.
187     * @return a set of Comment objects.
188     * @see Comment
189     */
190    public Set<Comment> getComments();
191    
192    /**
193     * Returns a set of all relationships associated with this bioentry. This
194     * set is not mutable. If no relationships are associated, you will get back an
195     * empty set.
196     * @return a set of BioEntryRelationship objects.
197     * @see BioEntryRelationship
198     */
199    public Set<BioEntryRelationship> getRelationships();
200    
201    /**
202     * Adds a ranked docref instance to this bioentry. Must not be null.
203     * @param docref the item to add.
204     * @throws ChangeVetoException if it doesn't want to add it.
205     */
206    public void addRankedDocRef(RankedDocRef docref) throws ChangeVetoException;
207    
208    /**
209     * Removes a ranked docref instance from this bioentry. If it was not found,
210     * nothing happens.
211     * @param docref the item to remove.
212     * @throws ChangeVetoException if it doesn't want to remove it.
213     */
214    public void removeRankedDocRef(RankedDocRef docref) throws ChangeVetoException;
215    
216    /**
217     * Adds a comment instance to this bioentry. Must not be null.
218     * @param comment the item to add.
219     * @throws ChangeVetoException if it doesn't want to add it.
220     */
221    public void addComment(Comment comment) throws ChangeVetoException;
222    
223    /**
224     * Removes a comment instance from this bioentry. If it wasn't present, it
225     * nothing will happen.
226     * @param comment the item to remove.
227     * @throws ChangeVetoException if it doesn't want to remove it.
228     */
229    public void removeComment(Comment comment) throws ChangeVetoException;
230    
231    /**
232     * Adds a relation instance to this bioentry. It must not be null.
233     * @param relation the item to add.
234     * @throws ChangeVetoException if it doesn't want to add it.
235     */
236    public void addRelationship(BioEntryRelationship relation) throws ChangeVetoException;
237    
238    /**
239     * Removes a relation instance from this bioentry. If it wasn't present,
240     * nothing will happen.
241     * @param relation the item to remove.
242     * @throws ChangeVetoException if it doesn't want to remove it.
243     */
244    public void removeRelationship(BioEntryRelationship relation) throws ChangeVetoException;
245}
246
247
248