com.docmosis.document
Class DocumentProcessor

java.lang.Object
  com.docmosis.document.DocumentProcessor

public class DocumentProcessor

extends Object

This class is the entry point for controlling the production of documents. Templates that have been previously registered with the configured TemplateStore can be merged with data to provide the resulting document(s). The process is fairly simple:

   1. register templates (only needs to be done once and whenever templates change)
   2. identify the template and the data source
   3. identify the output formats and destination
   4. call the renderDoc() method
 

Here is an example of use:

        // initialise from configuration specified by classpath
        SystemManager.initialise();

        try {
                TemplateStore store = TemplateStoreFactory.getStore();

                // Store a new template into the Template Store under the
                // name FirstTest.
                TemplateIdentifier templateId = StoreHelper.storeTemplate(
                        "FirstTest", new File(
                                "c:/docs/testDoc.doc"),
                        store);

                // the templateId can also be manually created (if you know 
                // the template is already registered) like this:
                // TemplateIdentifier templateId = new TemplateIdentifier("FirstTest");

                // create some data to push into the template
                DataProviderBuilder dpb = new DataProviderBuilder();
                dpb.add("Name", "Person Alpha");
                dpb.add("Addr", "10 The Pond, Froggsville");
                dpb.add("DOB", "16 Mar 2002");
                dpb.add("dateReported", "10/3/07");
                dpb.add("recordNumber", "1638.4");

                // create the instruction for processing. PDF and WORD format implies a zip archive 
                ConversionInstruction conversionInstruction = new ConversionInstruction();
                conversionInstruction.setConversionFormats(new ConversionFormat[] {
                        ConversionFormat.FORMAT_PDF,
                        ConversionFormat.FORMAT_WORD });

                // files inside the zip will use this as the basis for their name
                conversionInstruction.setOutputFileName("testResult");

                OutputStream out = null;
                try {

                                // Store output in this file (named zip because multiple formats will produce a zip file)
                    final String outName = "c:/docs/firstTest.zip";

                    try {
                        out = new FileOutputStream(outName);

                        // Render the document
                        DocumentProcessor. renderDoc(templateId, dpb.getDataProvider(), 
                                        conversionInstruction, out);
                    } finally {
                        FileUtilities.close(out);
                    }

                } finally {
                    FileUtilities.close(out);
                }
        } finally {
                // shtudown (would not do this for each document render, just at system shutdown)
                SystemManager.release();
        }

 

Constructor Summary

DocumentProcessor()

Method Summary

static boolean	hasOnlineConverters() Determine if there are any online converters in the default Converter Pool Group.
static boolean	hasOnlineConverters(String groupName) Determine if there are any online converters in the given Converter Pool Group.
static void	renderDoc(File template, File outputFile, DataProvider dp) Render the given template to the given output file with the given data.
static void	renderDoc(File template, OutputStream outputStream, ConversionFormat format, DataProvider dp) Render the given template to the given output stream with the given data.
static void	renderDoc(TemplateIdentifier templateId, DataProvider dp, ConversionInstruction instruction, OutputStream streamTo) Render the template specified by the given templateId with the given data according to the given instruction.
static void	setDefaultRenderer(Class forClass, FieldRenderer renderer) Set a "default" renderer against the given Class for system wide use.
static void	setDefaultRenderer(String name, FieldRenderer renderer) Set a "default" renderer against the given name for system wide use.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

DocumentProcessor

public DocumentProcessor()

Method Detail

renderDoc

public static void renderDoc(TemplateIdentifier templateId,
                             DataProvider dp,
                             ConversionInstruction instruction,
                             OutputStream streamTo)
                      throws IOException,
                             ProcessingException,
                             TemplateStoreException

Render the template specified by the given templateId with the given data according to the given instruction. The template identitified must have already been registered into the store or an exception will be thrown. This is the most performant call to rendering a template since it assumes the template is already registered in the template store.
The resulting document will be streamed to the given destination.
NOTE: This method will retry the render process under certain circumstances up to the limit specified by the property docmosis.render.maxRetries. This property defaults to 3. If a retry is performed a message is logged at INFO level indicating the retry is underway.
NOTE: At the completion of the render cleanup() will be called on the given DataProvider if it implements the Cleanable interface. This behaviour may be overridden by the ConversionInstruction but care must be taken if the data provider is providing image streams (which can only be read once).

Parameters:

templateId - the identifier of the template to render

dp - the DataProvider containing the data

instruction - the ConversionInstruction controlling aspects of the render

streamTo - the destination stream for the resulting document(s)

Throws:

IOException - if an IO problem occurs

ProcessingException - if a problem occurs processing the template

TemplateStoreException - if the template cannot be found or the template store has a problem.

See Also:

ConversionInstruction, TemplateIdentifier, DataProvider, Cleanable

renderDoc

public static void renderDoc(File template,
                             File outputFile,
                             DataProvider dp)
                      throws IOException,
                             ProcessingException,
                             TemplateStoreException,
                             ConversionException,
                             NoConvertersRunningException

Render the given template to the given output file with the given data. The format of the output is determined by the extension of the output file. The template will be registered into the template store on the caller's behalf automatically using the template name and placing it in the root of the store. This call is a little less efficient than render(TemplateIdentifier...) since it must first check if the template needs to be [re-]registered. If the template does need to be re-registered it will take about twice as long as otherwise. The mechanism this method uses to determine if the template has changed is simply the last modified timestamp of the file against the timestamp of the template in the store.

Parameters:

template - the template file to use

outputFile - the location to place the output

dp - the data to populate with

Throws:

IOException - if an IO problem occurs

ProcessingException - if a general processing problem occurs.

TemplateStoreException - if there is a problem with the store configuration

ConversionException - if the template or document cannot be processed

NoConvertersRunningException - if the system has not initialized correctly.

renderDoc

public static void renderDoc(File template,
                             OutputStream outputStream,
                             ConversionFormat format,
                             DataProvider dp)
                      throws IOException,
                             ProcessingException,
                             TemplateStoreException,
                             ConversionException,
                             NoConvertersRunningException

Render the given template to the given output stream with the given data. The template will be registered into the template store on the caller's behalf automatically using the template name and placing it in the root of the store. This call is a little less efficient than render(TemplateIdentifier...) since it must first check if the template needs to be [re-]registered. If the template does need to be re-registered it will take about twice as long as otherwise. The mechanism this method uses to determine if the template has changed is simply the last modified timestamp of the file against the timestamp of the template in the store. The outputStream is not closed by this method (since it is not the creator of the stream).

Parameters:

template - the template file to use

outputStream - the stream to which the resulting document will be sent

format - the format in which to render the resulting document

dp - the data to populate with

Throws:

IOException - if an IO problem occurs

ProcessingException - if a general processing problem occurs.

TemplateStoreException - if there is a problem with the store configuration

ConversionException - if the template or document cannot be processed

NoConvertersRunningException - if the system has not initialized correctly.

hasOnlineConverters

public static boolean hasOnlineConverters()
                                   throws ConverterPoolException

Determine if there are any online converters in the default Converter Pool Group. This means that (contention allowing) a document can be rendered right away.

Returns:

true if there are online converters.

Throws:

ConverterPoolException - if the ConverterPool isn't initialized or the group cannot be found.

hasOnlineConverters

public static boolean hasOnlineConverters(String groupName)
                                   throws ConverterPoolException

Determine if there are any online converters in the given Converter Pool Group. This means that (contention allowing) a document can be rendered right away.

Parameters:

groupName - the name of the group to query or null for the default group

Returns:

true if there are online converters.

Throws:

ConverterPoolException - if the ConverterPool isn't initialized or the group cannot be found.

setDefaultRenderer

public static void setDefaultRenderer(String name,
                                      FieldRenderer renderer)

Set a "default" renderer against the given name for system wide use. For all document production that occurs after this call, any template that refers to a renderer by the given name will have the given renderer applied unless an overriding renderer has been specified in the ConversionInstruction.

Parameters:

name - the name against which the renderer is associated

renderer - the renderer

setDefaultRenderer

public static void setDefaultRenderer(Class forClass,
                                      FieldRenderer renderer)

Set a "default" renderer against the given Class for system wide use. For all document production that occurs after this call, any template field that is populated with data of the given class will have the given renderer applied automatically, unless overriding renderer has been specified in the ConversionInstruction.

Parameters:

forClass - the Class against which the renderer is associated

renderer - the renderer