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.symbol.Location;
025
026/**
027 * Feature which represents a component in an assembly (contig).
028 * This implies that a portion (possibly all) of the 
029 * associated componentSequence is included in this feature's
030 * parent sequence.
031 *
032 * <p>
033 * There are important invariants which apply to all ComponentFeatures.
034 * The Location returned by getLocation() must
035 * contain the same number of unique point locations as that
036 * returned by getComponentLocation().
037 * </p>
038 *
039 * <p>
040 * In BioJava 1.2, two extra properties were added to <code>ComponentFeature</code>
041 * to support the use of these features in environments were it it necessary to
042 * represent an assembly built from sequences which are not currently available.
043 * Widespread use of such sequences is not encouraged, but it is recognized that
044 * they are useful as intermediate objects for data integration applications.
045 * </p>
046 *
047 * @author Thomas Down
048 * @since 1.1
049 */
050
051public interface ComponentFeature extends StrandedFeature {
052    /**
053     * Get the sequence object which provides a component of this
054     * feature's parent sequence.
055     *
056     * @return A sequence.
057     */
058
059    public Sequence getComponentSequence();
060
061    /**
062     * Return a location which identifies a portion of the component
063     * sequence which is to be included in the assembly.
064     *
065     * @return A location within the component sequence.
066     */
067
068    public Location getComponentLocation();
069
070    /**
071     * Get the name of the component sequence.  In general, this
072     * should be equivalent to
073     * <code>getComponentSequence().getName()</code>.  However,
074     * it may still be defined for un-resolveable components.
075     *
076     * @since 1.2
077     */
078
079    public String getComponentSequenceName();
080
081    /**
082     * Determine if the sequence references by this ComponentFeature
083     * is available in this context.  If not, calls to getComponentSequence will
084     * fail, and getSymbols will return a non-informative 
085     * <code>SymbolList</code> (in a DNA context, a list of Ns).
086     *
087     * @since 1.2
088     */
089
090    public boolean isComponentResolvable();
091
092    /**
093     * Template for constructing a new ComponentFeature.
094     *
095     * <p>
096     * In BioJava 1.2, we add the <code>componentSequenceName</code>
097     * property.  In general, it is only necessary to specify
098     * <em>either</em> componentSequenceName or componentSequence
099     * </p>
100     */
101
102    public static class Template extends StrandedFeature.Template {
103        public String   componentSequenceName;
104        public Sequence componentSequence;
105        public Location componentLocation;
106    }
107}