sk.baka.xml.gene
Interface ICoordinator

All Known Implementing Classes:

LaTeXCoordinator

public interface ICoordinator

Coordinates the plugins in order to produce required output. One for the output class, such as XHTML, PDF etc. Each coordinator instance may be used to perform the export multiple times, however it is configured only once.

Call flow

1. First the getConfigurator() function is called. If it returns non-null value then it is fully configured (see the configurator interface). If the export process is cancelled then dispose() is called and the process fails.
2. Next, the exporter graph needs to be built. getGraphBuilder() is called to determine the configured graph builder (coordinator should fill the forbidden and preferred sets appropriately). If the function returns non-null result then the exporter API computes graph, allows user to select a path in graph if needed and finally converts it into the TransformGraph instance. In this case, getTransformationGraph() method is not called.
3. If getGraphBuilder() returns null then API assumes that coordinator knows how to transform the document and it calls getTransformationGraph() to obtain the graph descriptor. If null is returned then coordinator is discarded and export fails.
4. Next, startExport(File) is called and the export begins. During the export, multiple calls to alterContext(IExporter, ExportContext, NamespacePath), requestResult(String), offerObject(String) and partialResultEvent(DocumentFragment, NamespacePath, Source, String, CoordinatorInputKey) may occur.
5. Finally, finishExport() is called. This repeats until the coordinator is no longer needed. Then the coordinator is disposed using the dispose() method.

General rules

If the exporter emits SAX events then the startDocument() and endDocument() events may not be emitted. The coordinator must be able to cope with these events. It can be done by calling startDocument() before the export, endDocument() after the export and suppressing each startDocument() and endDocument() emitted by the exporter.

If the root namespace of the document is not amongst possible root namespaces but is supported (for example, SVG document being exported to PDF - FO namespace is expected as the root namespace) then the coordinator should be able to provide some default content that shall wrap the document.

Each exporter is able to process only a nametree - it cannot process multi-namespaced document. However, it may produce multiple namespaces and process them. This may result in multiple fo:root elements, for example. Coordinator should be able to process such documents: for example it may: ignore fo:root element, but process each fo:block element contained in this fo:root element.

Author:

Martin Vysny

Method Summary

void	alterContext(IExporter exporter, ExportContext context, NamespacePath path) Called by GENE core anytime during the export process.
void	dispose() Disposes of this coordinator.
void	finishExport() Finalizes the export of the document.
IConfigurator	getConfigurator() Configures the coordinator for exporting a particular document.
ExportGraphBuilder	getGraphBuilder() Called after the configure() method.
CoordinatorInfo	getInfo() Returns the coordinator info instance that describes this coordinator.
TransformGraph	getTransformationGraph() Called only if getGraphBuilder() returned null.
Object	offerObject(String namespace) When the coordinator accepts the ObjectSource but wants to provide an object as a result to the exporter E (for example it wants E to draw something in a certain instance of Graphics), then return non-null value.
Source	partialResultEvent(DocumentFragment processed, NamespacePath path, Source source, String sourceNamespace, CoordinatorInputKey key) Using this method the coordinator is queried if it wants to modify the final result of one exporter pipe.
StreamResult	requestResult(String fileName) May be used when exporter wishes to write additional files as its output (an image that is referenced by XML produced by the exporter for example).
Result	startExport(File systemId) Initiates the export itself.

Method Detail

getConfigurator

IConfigurator getConfigurator()

Configures the coordinator for exporting a particular document. This includes querying the user for some coordinator-specific information, like output encoding, the style of produced document etc.

Returns:

a configurator instance or null if the coordinator does not need to be configured.

getGraphBuilder

ExportGraphBuilder getGraphBuilder()

Called after the configure() method. Returns configured instance of the graph builder.

Returns:

configured graph builder instance. May be null - in such case the getTransformationChain() is used to determine the exporter graph.

getTransformationGraph

TransformGraph getTransformationGraph()

Called only if getGraphBuilder() returned null. Describes the exporter graph directly. Returns non-empty map that maps each namespace present in the document to a TransformationInfo instance describing exporter chain exporting the namespace.

Returns:

object describing the exporter connections. If null then the exporting process fails.

startExport

Result startExport(File systemId)
                   throws ExportException,
                          IOException

Initiates the export itself. Coordinator must return a result where exporters results are written.

Coordinator is responsible to convert exporter's output (in the partialResultEvent() method) to Source instance compatible with the result object returned by this method. Failure to do so results in an ExportException during the export. Some kinds of sources can be converted automatically; for reference please see SourceEnum's convert method.

Parameters:

systemId - system-dependent identifier of the primary output file. Absolute system-dependent path with filename, suitable to be passed to File object. Here the primary result (PDF file, HTML file, whatever) will be stored. Coordinator may create additional directories and files whenever needed (for example png/jpg images referenced by the primary html file etc).

Returns:

result where the final exporter product is written. A final product of exporters is stored here; all emp:mark elements are replaced by transformation results. DOM source is given as a DOM node containing the whole document, SAX source gives result on-the-fly.

Throws:

ExportException - if something goes wrong

IOException - if i/o error occurs.

partialResultEvent

Source partialResultEvent(DocumentFragment processed,
                          NamespacePath path,
                          Source source,
                          String sourceNamespace,
                          CoordinatorInputKey key)
                          throws ExportException,
                                 IOException

Using this method the coordinator is queried if it wants to modify the final result of one exporter pipe. If yes then non-null value must be returned - this Source object shall be used as a replacement of the result. The source parameter (or the result of the method if non-null) is then stored into memory. When all exporters finish, these stored pieces are put together and finally transmitted to the coordinator again using the export() call.

Parameters:

processed - this document fragment is being processed and the Result holds part (or whole) result of the fragment processing.

path - the namespace path to the parent product.

source - contains the result of a nametree processing. If the systemId is not null then it is a system-dependent local filesystem path to a file that holds the content of this result. Warning: instance of SAXSource is a live instance - if you call parse on the XMLReader instance then it reads the whole result. If this result is not stored and returned in a Source then it is lost. You may convert it to the DOMSource, make necessary adjustments and then convert back to the SAXSource and return. You may also construct new XMLReader (reading from the old source and making adjustments on-the-fly) and return it.

sourceNamespace - the namespace of the source.

key - uniquely identifies the pipe from exporter to the coordinator.

Returns:

If null then returned source is put into the 'big picture' as-is. If not null then the content of the source is ignored and the returned Source instance is used instead.

Throws:

ExportException - if error occurs during the source processing

IOException - if error occurs during reading the source.

finishExport

void finishExport()
                  throws ExportException,
                         IOException

Finalizes the export of the document. It should finish writing all files, close all opened streams and files.

Throws:

ExportException - if something goes wrong

IOException - if i/o error occurs.

requestResult

StreamResult requestResult(String fileName)
                           throws IOException

May be used when exporter wishes to write additional files as its output (an image that is referenced by XML produced by the exporter for example). It is caller's responsibility to close opened stream.

The coordinator should create a good-looking directory structure when the exported format contains images visible on the filesystem. For example, XHTML exporter should put all files into the exportedFileName-images directory. If exporting format embeds the images (PDF, TIFF) then the coordinator may just create a temp file and return an outputstream to it.

Parameters:

fileName - the name of the file being created. The coordinator may ignore the filename if it is not part of the result file (for example when a PNG image is embedded in result PDF file). Coordinator may change the filename if a file with this name already exists. If null or empty string, coordinator may generate any name.

Returns:

non-null result containing non-null opened output stream and null writer. The Result.getSystemId() must contain filename relative to the location of the document being exported.

Throws:

IOException - if i/o error occurs.

dispose

void dispose()

Disposes of this coordinator.

offerObject

Object offerObject(String namespace)
                   throws ExportException

When the coordinator accepts the ObjectSource but wants to provide an object as a result to the exporter E (for example it wants E to draw something in 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.

Parameters:

namespace - the namespace that communicates using the Object source/result kind.

Returns:

the object instance, or null.

Throws:

ExportException - if something goes wrong

alterContext

void alterContext(IExporter exporter,
                  ExportContext context,
                  NamespacePath path)

Called by GENE core anytime during the export process. By modifying given context values the coordinator may force the GENE engine to report another context to an exporter.

If you don't want to override GENE default behaviour just use an empty implementation.

Parameters:

exporter - this exporter is about to be executed with given context object. Never null. The coordinator must NOT call the IExporter.export(Source, Result, ExportContext) method.

context - current context object. Never null.

path - current namespace path. It must NOT be altered. Never null.

getInfo

CoordinatorInfo getInfo()

Returns the coordinator info instance that describes this coordinator.

Returns:

the info instance, must not be null.