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.io;
023
024import java.io.PrintStream;
025
026import org.biojava.bio.seq.Feature;
027import org.biojava.bio.seq.StrandedFeature;
028import org.biojava.bio.symbol.Location;
029
030/**
031 * Objects implementing the <code>SeqFileFormer</code> interface are
032 * responsible for the detailed formatting of sequence data prior to
033 * writing to a <code>PrintStream</code>. Some file formats, such as
034 * Fasta, are very simple and don't require a
035 * <code>SeqFileFormer</code>.
036 *
037 * @author Keith James
038 * @since 1.2
039 * @deprecated Use org.biojavax.bio.seq.io framework instead
040 */
041public interface SeqFileFormer extends SeqIOListener
042{
043    /**
044     * <code>getPrintStream</code> returns the
045     * <code>PrintStream</code> to which an instance will write the
046     * formatted data. If this has not been set, an implementation
047     * should default to System.out.
048     *
049     * @return the <code>PrintStream</code> which will be written to.
050     */
051    public PrintStream getPrintStream();
052
053    /**
054     * <code>setPrintStream</code> informs an instance which
055     * <code>PrintStream</code> to use.
056     *
057     * @param stream a <code>PrintStream</code> to write to.
058     */
059    public void setPrintStream(PrintStream stream);
060
061    /**
062     * <code>formatLocation</code> creates a String representation of
063     * a <code>Location</code>. The strand may not be relevant for all
064     * formats (e.g. it is relevant for Genbank and EMBL, but not for
065     * SwissProt). In such cases the implementation may accept a
066     * strand of 'unknown', '0' or '.'. A <code>StringBuffer</code> is
067     * used to allow avoidance of expensive <code>String</code>
068     * manipulations on (potentially very large numbers of) locations.
069     *
070     * @param sb a <code>StringBuffer</code> to append the location
071     * to.
072     * @param loc a <code>Location</code> to format.
073     * @param strand a <code>StrandedFeature.Strand</code> indicating
074     * any relevant strandedness.
075     *
076     * @return a <code>StringBuffer</code> with the location appended.
077     */
078    public StringBuffer formatLocation(StringBuffer           sb,
079                                       Location               loc,
080                                       StrandedFeature.Strand strand);
081
082    /**
083     * Formats the location of a feature.  This version is required when
084     * formatting remote locations, since the location field of a remote
085     * feature is the projection of that feature on the sequence.  When a
086     * distinction is made between 'order' and 'join' this method will likely
087     * be extended for that also.
088     *
089     * @param theFeature The feature with the location to format
090     * @return String The formatted location
091     */
092    public String formatLocation(Feature theFeature);
093}