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.biojava.bio.seq;
023
024import org.biojava.bio.Annotatable;
025import org.biojava.bio.symbol.SymbolList;
026
027/**
028 * <p>
029 * A biological sequence.
030 * </p>
031 *
032 * <h2>Instantiation</h2>
033 *
034 * <pre>
035 * Sequence myDNA = DNATools.createDNASequence("ATTATTCGTG", "mySeq");
036 * Sequence myFasta = SeqIOTools.readFastaProtein("mySeq.fa");
037 * Sequence myGenbank = SeqIOTools.readGenbank("mySeq.gb");
038 * </pre>
039 *
040 * <h2>Common operations</h2>
041 *
042 * <pre>
043 * System.out.println("Length: " + myGenbank.length());
044 * System.out.println("Features: " + myGenbank.countFeatures());
045 * for(Iterator fi = myGenbank.features(); fi.hasNext(); ) {
046 *   Feature f = (Feature) fi.next();
047 *   System.out.println(f.getType() + "\t" + f.getLocation());
048 * }
049 *
050 * // create a new feature on a sequence
051 * StrandedFeature.Template ft = new StrandedFeature.Template();
052 * ft.type = "span";
053 * ft.location = new RangeLocation(230, 450);
054 * ft.source = "hand_made";
055 * ft.strand = StrandedFeature.NEGATIVE;
056 *
057 * StrandedFeature newSpan = (StrandedFeature) mySeq.createFeature(ft);
058 * </pre>
059 *
060 * <h2>Description</h2>
061 *
062 * <p>
063 * This interface is a symbol list, so it contains symbols. It is annotatable
064 * so that you can add annotation to it, and it is a FeatureHolder so that you
065 * can add information about specific regions.
066 * </p>
067 *
068 * <p>
069 * It is expected that there may be several implementations of this interface,
070 * each of which may be fairly heavy-weight. It takes the SymbolList interface
071 * that is nice mathematically, and turns it into a biologically useful object.
072 * </p>
073 * The {@link org.biojavax.bio.seq.RichSequence RichSequence} interface
074 * offers considerably more functionality and better persitence to BioSQL than
075 * it's super interface Sequence. We would recommend using it wherever possible.
076 * 
077 * @see org.biojavax.bio.seq.RichSequence
078 * @author Matthew Pocock
079 * @author Thomas Down
080 */
081
082public interface Sequence extends SymbolList, FeatureHolder, Annotatable {
083  /**
084   * A <a href="http://www.rfc-editor.org/rfc/rfc2396.txt">Uniform
085   * Resource Identifier</a> (URI) which identifies the sequence
086   * represented by this object.  For sequences in well-known
087   * database, this may be a URN, e.g.
088   *
089   * <pre>
090   * urn:sequence/embl:AL121903
091   * </pre>
092   *
093   * It may also be a URL identifying a specific resource, either
094   * locally or over the network
095   *
096   * <pre>
097   * file:///home/thomas/myseq.fa|seq22
098   * http://www.mysequences.net/chr22.seq
099   * </pre>
100   *
101   * @return the URI as a String
102   */
103  String getURN();
104  
105  /**
106   * The name of this sequence.
107   * <p>
108   * The name may contain spaces or odd characters.
109   *
110   * @return the name as a String
111   */
112  String getName();
113}