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

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