## org.biojavax.bio.seq.io
Interface RichSequenceFormat

All Superinterfaces:
  SequenceFormat

All Known Implementing Classes:
  EMBLFormat, EMBLxmlFormat, FastaFormat, GenbankFormat, INSDseqFormat, RichSequenceFormat.BasicFormat, RichSequenceFormat.HeaderlessFormat, UniProtFormat, UniProtXMLFormat

    public interface RichSequenceFormat

extends SequenceFormat

Allows a file format to be read/written as RichSequences.

Since:
  1.5
Author:
  Richard Holland

Nested Class Summary
`static class` `RichSequenceFormat.BasicFormat` Provides a basic format with simple things like line-widths precoded.
`static class` `RichSequenceFormat.HeaderlessFormat` Provides the basic implementation required for simple header/footer-less files such as Genbank.

Method Summary
`void` `beginWriting()` Informs the writer that we want to start writing.
`boolean` `canRead(BufferedInputStream stream)` Check to see if a given stream is in our format.
`boolean` `canRead(File file)` Check to see if a given file is in our format.
`void` `finishWriting()` Informs the writer that are done writing.
`boolean` `getElideComments()` Is the format going to emit events when comments data or remarks from bibliographic references are read?
`boolean` `getElideFeatures()` Is the format going to emit events when feature data is read?
`boolean` `getElideReferences()` Is the format going to emit events when bibliographic reference data is read?
`boolean` `getElideSymbols()` Is the format going to emit events when sequence data is read?
`int` `getLineWidth()` Retrive the current line width.
`PrintStream` `getPrintStream()` Gets the print stream currently being written to.
`SymbolTokenization` `guessSymbolTokenization(BufferedInputStream stream)` On the assumption that the stream is readable by this format (not checked), attempt to guess which symbol tokenization we should use to read it.
`SymbolTokenization` `guessSymbolTokenization(File file)` On the assumption that the file is readable by this format (not checked), attempt to guess which symbol tokenization we should use to read it.
`boolean` `readRichSequence(BufferedReader reader, SymbolTokenization symParser, RichSeqIOListener listener, Namespace ns)` Reads a sequence from the given buffered reader using the given tokenizer to parse sequence symbols.
`void` `setElideComments(boolean elideComments)` Use this method to toggle reading of comments data.
`void` `setElideFeatures(boolean elideFeatures)` Use this method to toggle reading of feature data.
`void` `setElideReferences(boolean elideReferences)` Use this method to toggle reading of bibliographic reference data.
`void` `setElideSymbols(boolean elideSymbols)` Use this method to toggle reading of sequence data.
`void` `setLineWidth(int width)` Set the line width.
`void` `setPrintStream(PrintStream os)` Sets the stream to write to.
`void` `writeSequence(Sequence seq, Namespace ns)` Writes a sequence out to the outputstream given by beginWriting() using the default format of the implementing class.

Methods inherited from interface org.biojava.bio.seq.io.SequenceFormat
`getDefaultFormat, readSequence, writeSequence, writeSequence`

Method Detail

### canRead

    boolean canRead(File file)
                    throws IOException

  Check to see if a given file is in our format. Some formats may be able to determine this by filename, whilst others may have to open the file and read it to see what format it is in.

  Parameters:
    `file` - the `File` to check.
  Returns:
    true if the file is readable by this format, false if not.
  Throws:
    `IOException` - in case the file is inaccessible.

### guessSymbolTokenization

    SymbolTokenization guessSymbolTokenization(File file)
                                               throws IOException

  On the assumption that the file is readable by this format (not checked), attempt to guess which symbol tokenization we should use to read it. For formats that only accept one tokenization, just return it without checking the file. For formats that accept multiple tokenizations, its up to you how you do it.

  Parameters:
    `file` - the `File` object to guess the format of.
  Returns:
    a `SymbolTokenization` to read the file with.
  Throws:
    `IOException` - if the file is unrecognisable or inaccessible.

### canRead

    boolean canRead(BufferedInputStream stream)
                    throws IOException

  Check to see if a given stream is in our format.

  Parameters:
    `stream` - the `BufferedInputStream` to check.
  Returns:
    true if the stream is readable by this format, false if not.
  Throws:
    `IOException` - in case the stream is inaccessible.

### guessSymbolTokenization

    SymbolTokenization guessSymbolTokenization(BufferedInputStream stream)
                                               throws IOException

  On the assumption that the stream is readable by this format (not checked), attempt to guess which symbol tokenization we should use to read it. For formats that only accept one tokenization, just return it without checking the stream. For formats that accept multiple tokenizations, its up to you how you do it.

  Parameters:
    `stream` - the `BufferedInputStream` object to guess the format of.
  Returns:
    a `SymbolTokenization` to read the stream with.
  Throws:
    `IOException` - if the stream is unrecognisable or inaccessible.

### setPrintStream

    void setPrintStream(PrintStream os)

  Sets the stream to write to.

  Parameters:
    `os` - the PrintStream to write to.
  Throws:
    `IOException` - if writing fails.

### getPrintStream

    PrintStream getPrintStream()

  Gets the print stream currently being written to.

  Returns:
    the current print stream.

### beginWriting

    void beginWriting()
                      throws IOException

  Informs the writer that we want to start writing. This will do any initialisation required, such as writing the opening tags of an XML file that groups sequences together.

  Throws:
    `IOException` - if writing fails.

### finishWriting

    void finishWriting()
                       throws IOException

  Informs the writer that are done writing. This will do any finalisation required, such as writing the closing tags of an XML file that groups sequences together.

  Throws:
    `IOException` - if writing fails.

### readRichSequence

    boolean readRichSequence(BufferedReader reader,
                             SymbolTokenization symParser,
                             RichSeqIOListener listener,
                             Namespace ns)
                             throws BioException,
                                    IllegalSymbolException,
                                    IOException

  Reads a sequence from the given buffered reader using the given tokenizer to parse sequence symbols. Events are passed to the listener, and the namespace used for sequences read is the one given. If the namespace is null, then the default namespace for the parser is used, which may depend on individual implementations of this interface.

  Parameters:
    `reader` - the input source
    `symParser` - the tokenizer which understands the sequence being read
    `listener` - the listener to send sequence events to
    `ns` - the namespace to read sequences into.
  Returns:
    true if there is more to read after this, false otherwise.
  Throws:
    `BioException` - in case of parsing errors.
    `IllegalSymbolException` - if the tokenizer couldn't understand one of the sequence symbols in the file.
    `IOException` - if there was a read error.

### writeSequence

    void writeSequence(Sequence seq,
                       Namespace ns)
                       throws IOException

  Writes a sequence out to the outputstream given by beginWriting() using the default format of the implementing class. If namespace is given, sequences will be written with that namespace, otherwise they will be written with the default namespace of the implementing class (which is usually the namespace of the sequence itself). If you pass this method a sequence which is not a RichSequence, it will attempt to convert it using RichSequence.Tools.enrich(). Obviously this is not going to guarantee a perfect conversion, so it's better if you just use RichSequences to start with!

  Parameters:
    `seq` - the sequence to write
    `ns` - the namespace to write it with
  Throws:
    `IOException` - in case it couldn't write something

### getLineWidth

    int getLineWidth()

  Retrive the current line width. Defaults to 80.

  Returns:
    the line width

### setLineWidth

    void setLineWidth(int width)

  Set the line width. When writing, the lines of sequence will never be longer than the line width. Defaults to 80.

  Parameters:
    `width` - the new line width

### setElideSymbols

    void setElideSymbols(boolean elideSymbols)

  Use this method to toggle reading of sequence data.

  Parameters:
    `elideSymbols` - set to true if you don't want the sequence data.

### getElideSymbols

    boolean getElideSymbols()

  Is the format going to emit events when sequence data is read?

  Returns:
    true if it is not otherwise false (false is default) .

### setElideFeatures

    void setElideFeatures(boolean elideFeatures)

  Use this method to toggle reading of feature data.

  Parameters:
    `elideFeatures` - set to true if you don't want the feature data.

### getElideFeatures

    boolean getElideFeatures()

  Is the format going to emit events when feature data is read?

  Returns:
    true if it is not otherwise false (false is default).

### setElideReferences

    void setElideReferences(boolean elideReferences)

  Use this method to toggle reading of bibliographic reference data.

  Parameters:
    `elideReferences` - set to true if you don't want the bibliographic reference data.

### getElideReferences

    boolean getElideReferences()

  Is the format going to emit events when bibliographic reference data is read?

  Returns:
    true if it is not otherwise false (false is default) .

### setElideComments

    void setElideComments(boolean elideComments)

  Use this method to toggle reading of comments data. Will also ignore remarks lines in bibliographic references.

  Parameters:
    `elideComments` - set to true if you don't want the comments data.

### getElideComments

    boolean getElideComments()

  Is the format going to emit events when comments data or remarks from bibliographic references are read?

  Returns:
    true if it is not otherwise false (false is default).