sk.uniba.euromath.gene
Interface ICoordinator

All Known Implementing Classes:
LaTeXCoordinator, XHTMLCoordinator

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 configure() 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 finish(true) is called, followed by a call to dispose() method 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(URLDir, String, String) is called and the export begins. During the export, multiple calls to getSource(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)
           May be called anytime during the export process.
 IConfigurator configure()
          Configures the coordinator for exporting a particular document.
 void dispose()
          Disposes of this coordinator.
 void finishExport()
          Finalizes the export of the document.
 ExportGraphBuilder getGraphBuilder()
          Called after the configure() method.
 ExportHelper getHelper()
          Returns helper instance provided to the coordinator.
 EnumSet<SourceEnum> getSource(String namespace)
           Specifies the input types that the coordinator's partialResultEvent method is able to receive from exporters.
 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.
 OutputStream 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(URLDir root, String fileName, String systemId)
           Initiates the export itself.
 

Method Detail

configure

IConfigurator configure()
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.

getSource

EnumSet<SourceEnum> getSource(String namespace)

Specifies the input types that the coordinator's partialResultEvent method is able to receive from exporters. If it accepts multiple types then the output with highest priority is picked. ObjectSource has the highest priority, followed by SAX, DOM and Stream.

Warning: this method result must be consistent with result returned by the CoordinatorInfo object instance for this coordinator class!

Parameters:
namespace - the namespace of the fragment that this coordinator may receive.
Returns:
all source types that the coordinator accepts, or null if coordinator does not accept fragments with given namespace.

startExport

Result startExport(URLDir root,
                   String fileName,
                   String 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:
root - the directory where the file will be exported. 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).
fileName - the name of the primary file being exported.
systemId - system identifier of the primary output file, constructed from root and fileName parameters for convenience. A OS-dependent identifier, suitable to be passed to File object.
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

OutputStream 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.

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:
opened output stream, never null.
Throws:
IOException - if i/o error occurs.

dispose

void dispose()
Disposes of this coordinator. It should dispose its helper instance.


getHelper

ExportHelper getHelper()
Returns helper instance provided to the coordinator.

Returns:
helper instance given to the 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)

May be called 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.


Copyright 2003-2003-2006 null. All Rights Reserved.