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.orDocRef
019 */
020
021package org.biojavax;
022import java.util.List;
023
024import org.biojava.utils.ChangeType;
025import org.biojava.utils.ChangeVetoException;
026import org.biojava.utils.Changeable;
027
028
029/**
030 * Represents a documentary reference. Relates to the reference table 
031 * in BioSQL.
032 * @author Mark Schreiber
033 * @author Richard Holland
034 * @see RankedDocRef
035 * @since 1.5
036 */
037public interface DocRef extends Comparable,Changeable {
038    
039    public static final ChangeType CROSSREF = new ChangeType(
040            "This reference's crossref has changed",
041            "org.biojavax.DocRef",
042            "CROSSREF"
043            );
044    public static final ChangeType REMARK = new ChangeType(
045            "This reference's remark has changed",
046            "org.biojavax.DocRef",
047            "REMARK"
048            );
049    
050    /**
051     * The document reference may refer to an object in another database. If so,
052     * this method will return that reference.
053     * @return Value of property crossref.
054     */
055    public CrossRef getCrossref();
056    
057    /**
058     * The document reference may refer to an object in another database. Use this
059     * method to set that reference. Null will unset it.
060     * @param crossref New value of property crossref.
061     * @throws ChangeVetoException in case of objections.
062     */
063    public void setCrossref(CrossRef crossref) throws ChangeVetoException;
064    
065    /**
066     * Returns a textual description of the document reference. This field is 
067     * immutable so should be set using the constructor of the implementing class.
068     * @return Value of property location.
069     */
070    public String getLocation();
071    
072    /**
073     * Returns the title of the document reference.
074     * @return Value of property title.
075     */
076    public String getTitle();
077    
078    /**
079     * Returns the authors of the document reference. 
080     * It will usually be in the form "Jones H., Bloggs J et al" or similar -
081     * a human-readable text value. Editors will have (ed.) appended, 
082     * consortiums will have (consortium) appended.
083     * @return Value of property authors.
084     */
085    public String getAuthors();
086    
087    /**
088     * Returns the authors of the document reference as a set of DocRefAuthor
089     * implementation instances. This field is immutable so should be set using 
090     * the constructor of the implementing class.
091     * @return The set of authors.
092     */
093    public List<DocRefAuthor> getAuthorList();
094    
095    /**
096     * Returns a CRC64 checksum of this document reference, allowing for easy
097     * comparisons with other document references.
098     * @return Value of property CRC.
099     */
100    public String getCRC();
101    
102    /**
103     * If remarks have been made about this document reference, this method
104     * will return them.
105     * @return Value of property Remark.
106     */
107    public String getRemark();
108    
109    /**
110     * Set the remarks for this document reference using this method. Remarks
111     * can be anything, it is derived from the equivalent field in the GenBank
112     * format.
113     * @param Remark New value of property Remark.
114     * @throws ChangeVetoException in case of objections.
115     */
116    public void setRemark(String Remark) throws ChangeVetoException;
117    
118}