sk.uniba.euromath.gene
Interface IExporter

All Known Implementing Classes:

ExporterAdapter, ImageToPngExporter, XsltExporterBase

public interface IExporter

Exports (transforms) the document from single namespace to a result. All exporters are generally thread-unsafe. One exporter may be used repeatedly to transform same kind of nametree.

All document fragment provided to methods of this interface have the following properties:

• There are no entity reference nodes - all references are resolved
• There are no CDATA nodes - all are converted to Text nodes and merged together

Each exporter should override toString() method and provide a short description of itself, for debugging purposes etc.

Author:

Martin Vysny

Method Summary

void	export(Source source, Result result, ExportContext context) Exports (transforms) the document from a single namespace and writes it to the result.
ExporterInfo	getInfo() Returns information about the exporter.
Map<String,Object>	getProperties() Properties that drives the export process.
Object	offerObject() When the exporter accepts the ObjectSource but wants to provide an object as a result to the exporter E (for example it wants E to draw something on a certain instance of Graphics), then return non-null value.

Method Detail

getProperties

Map<String,Object> getProperties()

Properties that drives the export process. Currently there are no properties defined, you may use this facility to introduce your own.

Returns:

map of properties. If some required properties are missing then the exporter may fail during the export, with the appropriate error message.

export

void export(Source source,
            Result result,
            ExportContext context)
            throws ExportException,
                   IOException

Exports (transforms) the document from a single namespace and writes it to the result.

If the result is text or binary data and the result is instance of DOMResult or SAXResult then the result must contain one text/cdata node with the result.

If needed then Coordinator may communicate with the Exporter directly via the ObjectResult class, however the plugin may throw an exception when it does not support such return style. You can use this result style to render images in the memory and give it to the renderer (the Coordinator) directly, for example when rendering images to the PDF-FOP result type.

If result does not specify the encoding then UTF-8 should be used as default encoding. If the encoding is not supported by the result file format then any valid encoding can be used. However, Coordinator is strongly encouraged to provide the encoding whenever appropriate. If the need of encoding can be avoided then use the appropriate means to avoid it. For example if the result is DOM, SAX or if StreamResult has non- null writer.

If some required properties are missing or they have incorrect values then UnsupportedOperation exception should be thrown with appropriate error message.

If object is offered as a source then the exporter must be able to free any resources associated with the object (for example it must call dispose() on java.awt.Graphics.

Both source and result must not be closed after the export is done.

Parameters:

source - the source of the transformation. identifier may be null or it may identify the datasource - previous exporter, source document etc. SAXSource: reader is never null, input source is almost always null. DOMSource: node is never null. StreamSource: at least one of StreamSource.getInputStream() and StreamSource.getReader() is not null. If they are both non-null you must select one and use it exclusively - you cannot use read from both. ObjectSource: No assumptions can be made on the value of object - this protocol is user-specific.

result - the result of the transformation. identifier may be null or you may set it to identify this exporter. SAXResult: content handler is never null, lexical handler is not used and is null. node is never null, next sibling is not used and is null. StreamResult: at least one of output stream and writer is not null. If they are both non-null you must select one and use it exclusively - you cannot write to both. ObjectResult: No assumptions can be made on the value of object - this protocol is user-specific.

context - the export context.

Throws:

UnsupportedOperationException - if some properties are missing or incorrect.

IllegalArgumentException - if the source is from another document as the one provided by the init call.

ExportException - if something goes wrong in the process of transformation - an unrecoverable error. All non-fatal errors and warnings should be logged using the helper's log.

IOException - if i/o error occurs.

getInfo

ExporterInfo getInfo()

Returns information about the exporter.

Returns:

info object. Must be equal with the info object returned by the exporter factory.

offerObject

Object offerObject()

When the exporter accepts the ObjectSource but wants to provide an object as a result to the exporter E (for example it wants E to draw something on a certain instance of Graphics), then return non-null value. If this functionality is not needed then just return null - if E requires some object then it can create any object as long as it is instance of class that this exporter expects.

The consumer (the one that receives the object, i.e. this) is responsible for freeing the object if necessary (at the end of the export method), even if this function returned null.

If you want producer (the one that creates the object) to create custom instances then provide a factory object. This trick is used with http://www.uniba.sk/euromath/holder/java.awt.Graphics holder - a factory is returned that is able to produce java.awt.Graphics instances.

Returns:

the object instance, or null.