info.bioinfweb.jphyloio.objecttranslation

## Interface ObjectTranslator<O>

- Type Parameters:
    `O` - the type of Java object this translator instance is able to handle
  All Known Implementing Classes:
    AbstractObjectTranslator, AbstractXMLObjectTranslator, Base64BinaryTranslator, BigDecimalTranslator, BigIntegerTranslator, BooleanTranslator, ByteTranslator, ColorTranslator, DateTimeTranslator, DateTranslator, DoubleTranslator, EnumTranslator, FloatTranslator, HexadecimalColorTranslator, HexBinaryTranslator, IllegalArgumentExceptionSimpleValueTranslator, IntegerTranslator, ListTranslator, LongTranslator, NumericValueTranslator, PhyloXMLColorTranslator, QNameTranslator, ShortTranslator, SimpleValueTranslator, StringTranslator, TimeTranslator, URITranslator

      public interface ObjectTranslator<O>

  Classes implementing this interface are able to convert between Java Objects and their text or XML representation.

  Instances of implementations can be obtained using `ObjectTranslatorFactory`, which also allows to register custom implementations (e.g. provided in application code). Instances of `JPhyloIOEventReader` and `JPhyloIOEventWriter` make use of object translators to read and write literal metadata objects. The factory to be used can be specified using the parameter `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`.

  Since:
    0.0.0
  Author:
    Ben Stöver
  See Also:
    `ObjectTranslatorFactory`, `ReadWriteParameterNames.KEY_OBJECT_TRANSLATOR_FACTORY`

- - ### Method Summary

    All Methods Instance Methods Abstract Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.lang.Class<O>` | `getObjectClass()` Returns the Java class of object instances created by this translator.
    `boolean` | `hasStringRepresentation()` Determines whether the objects handled by this instance have a simple string representation or need a more complex XML representation.
    `java.lang.String` | `javaToRepresentation(java.lang.Object object, WriterStreamDataProvider<?> streamDataProvider)` Converts the specified Java object to its string representation.
    `O` | `readXMLRepresentation(javax.xml.stream.XMLEventReader reader, ReaderStreamDataProvider<?> streamDataProvider)` Tries to create a new instance of the handled object type from the data provided by the specified XML reader.
    `O` | `representationToJava(java.lang.String representation, ReaderStreamDataProvider<?> streamDataProvider)` Converts the specified string representation to a new instance of the according Java object.
    `void` | `writeXMLRepresentation(javax.xml.stream.XMLStreamWriter writer, java.lang.Object object, WriterStreamDataProvider<?> streamDataProvider)` Writes the XML representation of the specified object into the specified XML writer.

- - ### Method Detail

    - #### getObjectClass

          java.lang.Class<O> getObjectClass()

      Returns the Java class of object instances created by this translator.

      Note that `javaToRepresentation(Object, WriterStreamDataProvider)` and `writeXMLRepresentation(XMLStreamWriter, Object, WriterStreamDataProvider)` may also accept instances of other classes. This is independent from the return value here.

      Returns:
        the class of the handled objects

    - #### hasStringRepresentation

          boolean hasStringRepresentation()

      Determines whether the objects handled by this instance have a simple string representation or need a more complex XML representation.

      Instances that return `false here` will throw an `UnsupportedOperationException`, if `javaToRepresentation(Object, WriterStreamDataProvider)` is called.

      Returns:
        `true` if handled objects have a simple string representation or `false` if XML is necessary to represent the handled objects

    - #### javaToRepresentation

          java.lang.String javaToRepresentation(java.lang.Object object,
                                                WriterStreamDataProvider<?> streamDataProvider)
                                         throws java.lang.UnsupportedOperationException,
                                                java.lang.ClassCastException

      Converts the specified Java object to its string representation.
      Parameters:
        `object` - the object to be translated
        `streamDataProvider` - TODO
      Returns:
        the string representation of the object
      Throws:
        `java.lang.UnsupportedOperationException` - if objects handled by this instance can only be represented as XML
        `java.lang.ClassCastException` - if the specified object is not an instance of the supported class or does not implement the supported interface
      See Also:
        `hasStringRepresentation()`

    - #### writeXMLRepresentation

          void writeXMLRepresentation(javax.xml.stream.XMLStreamWriter writer,
                                      java.lang.Object object,
                                      WriterStreamDataProvider<?> streamDataProvider)
                               throws java.io.IOException,
                                      javax.xml.stream.XMLStreamException,
                                      java.lang.ClassCastException

      Writes the XML representation of the specified object into the specified XML writer.
      Parameters:
        `writer` - the writer to be used to write the XML representation
        `object` - the object to be converted
        `streamDataProvider` - TODO
      Throws:
        `java.io.IOException` - if an I/O error occurs while trying to write to the specified writer
        `javax.xml.stream.XMLStreamException` - if an XML stream exception occurs while trying to write to the specified writer
        `java.lang.ClassCastException`

    - #### representationToJava

          O representationToJava(java.lang.String representation,
                                 ReaderStreamDataProvider<?> streamDataProvider)
                          throws InvalidObjectSourceDataException,
                                 java.lang.UnsupportedOperationException

      Converts the specified string representation to a new instance of the according Java object.

      If `#getClass()` returns an interface for this instance, the concrete class of the returned object may depend on the representation.

      Parameters:
        `representation` - the string representation of the object to be created
        `streamDataProvider` - the stream data provider of the calling reader (Maybe `null`. Some translators will use it to gain additional status information required for translating, e.g. prefix to namespace mapping for creating QNames.)
      Returns:
        the new object
      Throws:
        `java.lang.UnsupportedOperationException` - if objects handled by this instance can only be represented as XML
        `InvalidObjectSourceDataException` - if the specified string representation cannot be parsed to a supported object

    - #### readXMLRepresentation

          O readXMLRepresentation(javax.xml.stream.XMLEventReader reader,
                                  ReaderStreamDataProvider<?> streamDataProvider)
                           throws java.io.IOException,
                                  javax.xml.stream.XMLStreamException,
                                  InvalidObjectSourceDataException

      Tries to create a new instance of the handled object type from the data provided by the specified XML reader.

      This method will start reading from the current position of the reader and read only as far as necessary to collect all data for the new object. Therefore the reader should be positioned before the start tag, that represents the object and will read until the according end tag was consumed. If the supported objects have a simple string representation, the reader should be positioned in front of the according characters.

      If this

      Parameters:
        `reader` - the XML reader providing the data to create a new object
        `streamDataProvider` - TODO
      Returns:
        the new object
      Throws:
        `java.io.IOException` - if an I/O error occurs while trying to read from the specified reader
        `javax.xml.stream.XMLStreamException` - if an XML stream exception occurs while trying to read from the specified reader
        `InvalidObjectSourceDataException` - if an unexpected XML event was encountered or an XML event has unexpected contents