info.bioinfweb.jphyloio

## Class AbstractEventWriter<P extends WriterStreamDataProvider<? extends AbstractEventWriter<P>>>

- java.lang.Object
- - info.bioinfweb.jphyloio.AbstractEventWriter<P>

- All Implemented Interfaces:
    JPhyloIOEventWriter, JPhyloIOFormatSpecificObject
  Direct Known Subclasses:
    AbstractTextEventWriter, AbstractXMLEventWriter

      public abstract class AbstractEventWriter<P extends WriterStreamDataProvider<? extends AbstractEventWriter<P>>>
      extends java.lang.Object
      implements JPhyloIOEventWriter

  Implements shared functionality for JPhyloIO event writers.
  Author:
    Ben Stöver

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `AbstractEventWriter.NoEditUniqueLabelHandler`
    `static interface` | `AbstractEventWriter.UniqueLabelHandler`

  - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static java.lang.String` | `EDITED_LABEL_SEPARATOR`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `AbstractEventWriter()`

  - ### Method Summary

    All Methods Static Methods Instance Methods Abstract Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected P` | `createStreamDataProvider()` This method is called in the constructor of `AbstractEventWriter` to initialize the stream data provider that will be returned by `getStreamDataProvider()`.
    `static java.lang.String` | `createUniqueLabel(ReadWriteParameterMap parameters, AbstractEventWriter.UniqueLabelHandler handler, LabeledIDEvent event)`
    `static java.lang.String` | `createUniqueLabel(ReadWriteParameterMap parameters, AbstractEventWriter.UniqueLabelHandler handler, java.lang.String label1, java.lang.String id1, java.lang.String label2, java.lang.String id2)`
    `static java.lang.String` | `createUniqueLabel(ReadWriteParameterMap parameters, LabeledIDEvent event)`
    `static java.lang.String` | `createUniqueLinkedOTULabel(ReadWriteParameterMap parameters, AbstractEventWriter.UniqueLabelHandler handler, LinkedLabeledIDEvent event, OTUListDataAdapter otuList, boolean otuFirst)`
    `protected void` | `decreaseIndention()`
    `static long` | `determineMaxSequenceLength(MatrixDataAdapter matrix, ReadWriteParameterMap parameters)` Calculates the maximum sequence length in matrix with unequal lengths.
    `protected abstract void` | `doWriteDocument(DocumentDataAdapter document, java.io.Writer writer, ReadWriteParameterMap parameters)`
    `protected void` | `extendSequence(MatrixDataAdapter matrix, ReadWriteParameterMap parameters, java.lang.String sequenceID, long targetLength, java.lang.String extensionToken, JPhyloIOEventReceiver receiver)`
    `protected java.lang.String` | `getFileStartInfo(ReadWriteParameterMap parameters)`
    `protected java.lang.String` | `getIndention()`
    `static java.lang.String` | `getLabeledIDName(LabeledIDEvent event)` Returns a name for the specified event.
    `static java.lang.String` | `getLinkedOTUNameOTUFirst(LinkedLabeledIDEvent linkedOTUEvent, OTUListDataAdapter otuList, ReadWriteParameterMap parameters)` Determines the name (label) to be used for the specified event when writing its data to a file.
    `static java.lang.String` | `getLinkedOTUNameOwnFirst(LinkedLabeledIDEvent linkedOTUEvent, OTUListDataAdapter otuList, ReadWriteParameterMap parameters)` Determines the name (label) to be used for the specified event when writing its data to a file.
    `static OTUListDataAdapter` | `getReferencedOTUList(DocumentDataAdapter document, ElementDataAdapter<LinkedLabeledIDEvent> source, ReadWriteParameterMap parameters)` Returns the OTU list found in `document` which is referenced by the specified event.
    `P` | `getStreamDataProvider()`
    `protected void` | `increaseIndention()`
    `static void` | `logIngnoredOTULists(DocumentDataAdapter document, ApplicationLogger logger, ReadWriteParameterMap parameters, java.lang.String formatName, java.lang.String labeledElements)` Outputs a warning message, if the specified document data adapter provides one or more OTU lists.
    `void` | `writeDocument(DocumentDataAdapter document, java.io.File file, ReadWriteParameterMap parameters)` Writes the data provided by the data adapter to a document in the according format of the implementing class.
    `void` | `writeDocument(DocumentDataAdapter document, java.io.OutputStream stream, ReadWriteParameterMap parameters)` Writes the data provided by the data adapter to a document in the according format of the implementing class.
    `void` | `writeDocument(DocumentDataAdapter document, java.io.Writer writer, ReadWriteParameterMap parameters)` Writes the data provided by the data adapter to a document in the according format of the implementing class.
    `static void` | `writeLineBreak(java.io.Writer writer, ReadWriteParameterMap parameters)` Writes the line separator, as it is specified in the parameter map or the line separator of the current operating system, if the map contains no according entry.
    `protected void` | `writeLineStart(java.io.Writer writer, java.lang.String text)`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

    - ### Methods inherited from interface info.bioinfweb.jphyloio.JPhyloIOFormatSpecificObject

      `getFormatID`

- - ### Field Detail

    - #### EDITED_LABEL_SEPARATOR

          public static final java.lang.String EDITED_LABEL_SEPARATOR

      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### AbstractEventWriter

          public AbstractEventWriter()

  - ### Method Detail

    - #### createStreamDataProvider

          protected P createStreamDataProvider()

      This method is called in the constructor of `AbstractEventWriter` to initialize the stream data provider that will be returned by `getStreamDataProvider()`. Inheriting classes that use their own stream data provider implementation should overwrite this method.

      This default implementation creates a new instance of `WriterStreamDataProvider`.

      Returns:
        the stream data provider to be used with this instance

    - #### getStreamDataProvider

          public P getStreamDataProvider()

    - #### writeLineBreak

          public static void writeLineBreak(java.io.Writer writer,
                                            ReadWriteParameterMap parameters)
                                     throws java.io.IOException

      Writes the line separator, as it is specified in the parameter map or the line separator of the current operating system, if the map contains no according entry.
      Parameters:
        `writer` - the writer to write the line break to
        `parameters` - the parameter map possibly containing a line separator definition
      Throws:
        `java.io.IOException` - if an I/O error occurs while writing to the specified writer

    - #### logIngnoredOTULists

          public static void logIngnoredOTULists(DocumentDataAdapter document,
                                                 ApplicationLogger logger,
                                                 ReadWriteParameterMap parameters,
                                                 java.lang.String formatName,
                                                 java.lang.String labeledElements)

      Outputs a warning message, if the specified document data adapter provides one or more OTU lists.
      Parameters:
        `document` - the document data adapter to be checked for OTU lists
        `logger` - the logger to write the warning to
        `formatName` - the name of the format to which OTU lists cannot be written (will be included in the message)
        `labeledElements` - the name of data elements (e.g. sequences or nodes) that may reference the OTU lists (The warning message will use this name for a hint that the OTU lists may still be used to label this type of elements.)

    - #### getLabeledIDName

          public static java.lang.String getLabeledIDName(LabeledIDEvent event)

      Returns a name for the specified event.
      Parameters:
        `event` - the event to get the name of
      Returns:
        either the label of the event or its ID, if it does not carry a label

    - #### getLinkedOTUNameOwnFirst

          public static java.lang.String getLinkedOTUNameOwnFirst(LinkedLabeledIDEvent linkedOTUEvent,
                                                                  OTUListDataAdapter otuList,
                                                                  ReadWriteParameterMap parameters)

      Determines the name (label) to be used for the specified event when writing its data to a file. The name is tried to be set by the following properties in decreasing priority:
      1. the label of `linkedOTUEvent` if present
      2. the label of the linked OTU event, if any is linked and carries a label
      3. the ID of `linkedOTUEvent`
      Parameters:
        `linkedOTUEvent` - the event defining the name
        `otuList` - the data adapter providing the OTU data
      Returns:
        a string representing the specified event as described
      See Also:
        `#getLinkedOTUNameOTUFirst(LinkedLabeledIDEvent, OTUListDataAdapter)`

    - #### getLinkedOTUNameOTUFirst

          public static java.lang.String getLinkedOTUNameOTUFirst(LinkedLabeledIDEvent linkedOTUEvent,
                                                                  OTUListDataAdapter otuList,
                                                                  ReadWriteParameterMap parameters)

      Determines the name (label) to be used for the specified event when writing its data to a file. The name is tried to be set by the following properties in decreasing priority:
      1. the label of the linked OTU event, if any is linked and carries a label
      2. the ID of the linked OTU event, if any is linked
      3. the label of `linkedOTUEvent` if present
      4. the ID of `linkedOTUEvent`
      Parameters:
        `linkedOTUEvent` - the event defining the name
        `otuList` - the data adapter providing the OTU data
      Returns:
        a string representing the specified event as described
      See Also:
        `#getLinkedOTUNameOwnFirst(LinkedLabeledIDEvent, OTUListDataAdapter)`

    - #### getReferencedOTUList

          public static OTUListDataAdapter getReferencedOTUList(DocumentDataAdapter document,
                                                                ElementDataAdapter<LinkedLabeledIDEvent> source,
                                                                ReadWriteParameterMap parameters)

      Returns the OTU list found in `document` which is referenced by the specified event.
      Parameters:
        `document` - the document data adapter providing the OTU lists.
        `source` - the event referencing the OTU list
      Returns:
        the referenced list or `null`, if the specified event does not reference any OTU
      Throws:
        `java.lang.IllegalArgumentException` - if no OTU list with the specified ID is available in `document`

    - #### determineMaxSequenceLength

          public static long determineMaxSequenceLength(MatrixDataAdapter matrix,
                                                        ReadWriteParameterMap parameters)

      Calculates the maximum sequence length in matrix with unequal lengths. This method iterates over all sequences if `MatrixDataAdapter.getColumnCount(ReadWriteParameterMap)` returns -1, otherwise it will directly return the specified column count.
      Parameters:
        `matrix` - the matrix data adapter containing the sequences
      Returns:
        the maximal sequence length or -1, if the specified matrix data adapter does not declare any sequences

    - #### getIndention

          protected java.lang.String getIndention()

    - #### writeLineStart

          protected void writeLineStart(java.io.Writer writer,
                                        java.lang.String text)
                                 throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### increaseIndention

          protected void increaseIndention()

    - #### decreaseIndention

          protected void decreaseIndention()

    - #### createUniqueLabel

          public static java.lang.String createUniqueLabel(ReadWriteParameterMap parameters,
                                                           AbstractEventWriter.UniqueLabelHandler handler,
                                                           java.lang.String label1,
                                                           java.lang.String id1,
                                                           java.lang.String label2,
                                                           java.lang.String id2)

    - #### createUniqueLabel

          public static java.lang.String createUniqueLabel(ReadWriteParameterMap parameters,
                                                           AbstractEventWriter.UniqueLabelHandler handler,
                                                           LabeledIDEvent event)

    - #### createUniqueLabel

          public static java.lang.String createUniqueLabel(ReadWriteParameterMap parameters,
                                                           LabeledIDEvent event)

    - #### createUniqueLinkedOTULabel

          public static java.lang.String createUniqueLinkedOTULabel(ReadWriteParameterMap parameters,
                                                                    AbstractEventWriter.UniqueLabelHandler handler,
                                                                    LinkedLabeledIDEvent event,
                                                                    OTUListDataAdapter otuList,
                                                                    boolean otuFirst)

    - #### extendSequence

          protected void extendSequence(MatrixDataAdapter matrix,
                                        ReadWriteParameterMap parameters,
                                        java.lang.String sequenceID,
                                        long targetLength,
                                        java.lang.String extensionToken,
                                        JPhyloIOEventReceiver receiver)
                                 throws java.io.IOException

      Throws:
        `java.io.IOException`

    - #### getFileStartInfo

          protected java.lang.String getFileStartInfo(ReadWriteParameterMap parameters)

    - #### writeDocument

          public void writeDocument(DocumentDataAdapter document,
                                    java.io.File file,
                                    ReadWriteParameterMap parameters)
                             throws java.io.IOException

      Description copied from interface: `JPhyloIOEventWriter`
      Writes the data provided by the data adapter to a document in the according format of the implementing class.
      Specified by:
        `writeDocument` in interface `JPhyloIOEventWriter`
      Parameters:
        `document` - the adapter providing the data to be written
        `file` - the file to write the data to
        `parameters` - a map of parameters to exchange information with the writer implementation (Care should be taken, if a parameter map is reused for multiple calls, since the writer implementation may add or changes entries in the map.)
      Throws:
        `java.io.IOException`

    - #### writeDocument

          public void writeDocument(DocumentDataAdapter document,
                                    java.io.OutputStream stream,
                                    ReadWriteParameterMap parameters)
                             throws java.io.IOException

      Description copied from interface: `JPhyloIOEventWriter`
      Writes the data provided by the data adapter to a document in the according format of the implementing class.
      Specified by:
        `writeDocument` in interface `JPhyloIOEventWriter`
      Parameters:
        `document` - the adapter providing the data to be written
        `stream` - the stream to write the data to
        `parameters` - a map of parameters to exchange information with the writer implementation (Care should be taken, if a parameter map is reused for multiple calls, since the writer implementation may add or changes entries in the map.)
      Throws:
        `java.io.IOException`

    - #### writeDocument

          public void writeDocument(DocumentDataAdapter document,
                                    java.io.Writer writer,
                                    ReadWriteParameterMap parameters)
                             throws java.io.IOException

      Description copied from interface: `JPhyloIOEventWriter`
      Writes the data provided by the data adapter to a document in the according format of the implementing class.
      Specified by:
        `writeDocument` in interface `JPhyloIOEventWriter`
      Parameters:
        `document` - the adapter providing the data to be written
        `writer` - the writer to write the data to
        `parameters` - a map of parameters to exchange information with the writer implementation (Care should be taken, if a parameter map is reused for multiple calls, since the writer implementation may add or changes entries in the map.)
      Throws:
        `java.io.IOException`

    - #### doWriteDocument

          protected abstract void doWriteDocument(DocumentDataAdapter document,
                                                  java.io.Writer writer,
                                                  ReadWriteParameterMap parameters)
                                           throws java.io.IOException

      Throws:
        `java.io.IOException`