|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |
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.
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.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.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.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.finishExport()
is called. This repeats until the
coordinator is no longer needed. Then the coordinator is disposed using the
dispose()
method.
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.
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 |
---|
IConfigurator configure()
null
if the coordinator
does not need to be configured.ExportGraphBuilder getGraphBuilder()
configure()
method. Returns configured
instance of the graph builder.
null
-
in such case the getTransformationChain()
is used to
determine the exporter graph.TransformGraph getTransformationGraph()
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.
null
then the exporting process fails.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!
namespace
- the namespace of the fragment that this coordinator may
receive.
null
if coordinator does not accept fragments with given
namespace.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.
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.
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.
ExportException
- if something goes wrong
IOException
- if i/o error occurs.Source partialResultEvent(DocumentFragment processed, NamespacePath path, Source source, String sourceNamespace, CoordinatorInputKey key) throws ExportException, IOException
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.
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.
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.
ExportException
- if error occurs during the source processing
IOException
- if error occurs during reading the source.void finishExport() throws ExportException, IOException
ExportException
- if something goes wrong
IOException
- if i/o error occurs.OutputStream requestResult(String fileName) throws IOException
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.
null
.
IOException
- if i/o error occurs.void dispose()
ExportHelper getHelper()
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.
namespace
- the namespace that communicates using the Object
source/result kind.
null
.
ExportException
- if something goes wrongvoid 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.
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
.
|
||||||||||
PREV CLASS NEXT CLASS | FRAMES NO FRAMES | |||||||||
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD |