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 a simple example of use:

                // one off initialise - just done at application launch (or first
                // render)
                SystemManager.initialise();

                try {
                        DataProviderBuilder dpb = new DataProviderBuilder();
                        dpb.add("name", "James");
                        dpb.add("state", "CA");
                        DocumentProcessor.renderDoc(new File("myTemplate.doc"), new File(
                                        "myResult.pdf"), dpb.getDataProvider());
                } finally {
                        // shutdown (would not do this for each document render, just at
                        // system shutdown)
                        SystemManager.release();
                }
 

Here is a longer example:

        // 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 {
                // shutdown (would not do this for each document render, just at system shutdown)
                SystemManager.release();
        }

 

Constructor Summary

DocumentProcessor()

Method Summary

static int	getOnlineConverterCount() Get the number of converters online for the default converter pool group.
static int	getOnlineConverterCount(String groupName) Get the number of converters online for the named converter pool group.
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 DocumentRenderResult	renderDoc(File template, File outputFile, DataProvider dp) Render the given template to the given output file with the given data.
static DocumentRenderResult	renderDoc(File template, File outputFile, DataProvider dp, boolean cleanupDataProvider) Render the given template to the given output file with the given data.
static DocumentRenderResult	renderDoc(File template, OutputStream outputStream, ConversionFormat format, DataProvider dp) Render the given template to the given output stream with the given data.
static DocumentRenderResult	renderDoc(File template, OutputStream outputStream, ConversionFormat format, DataProvider dp, boolean cleanupDataProvider) Render the given template to the given output stream with the given data.
static DocumentRenderResult	renderDoc(RenderRequest request) Execute a render using the given render request.
static DocumentRenderResult	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 DocumentRenderResult 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 identified 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. Error handling is based on the default configured behaviour which is to attempt to render errors into the generated document (to assist debugging and development) rather than throw exceptions. There is another render method which allows this behaviour to be specified. The default configured template store will be used to retrieve templates. The default settings are used to decide how to scale image in templates that are set to use the default scaling interpretation (eg stretch to fit or preserve aspect ratio).
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)

Returns:

a DocumentRenderResult with some information about the document

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, ImageScalingDefault

renderDoc

public static DocumentRenderResult renderDoc(RenderRequest request)
                                      throws IOException,
                                             ProcessingException,
                                             TemplateStoreException,
                                             ConversionException,
                                             NoConvertersRunningException

Execute a render using the given render request. The request specifies all the required information for the render.

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.

ConversionException - if there is a problem with converting the document

NoConvertersRunningException - if there are no operational converters

See Also:

RenderRequest

renderDoc

public static DocumentRenderResult 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. The DataProvider will automatically be cleaned up (meaning all data is removed) after this call. The default configured template store will be used to retrieve templates.

Parameters:

template - the template file to use

outputFile - the location to place the output

dp - the data to populate with

Returns:

a DocumentRenderResult with some information about the document

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 initialised correctly.

renderDoc

public static DocumentRenderResult renderDoc(File template,
                                             File outputFile,
                                             DataProvider dp,
                                             boolean cleanupDataProvider)
                                      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. If cleanupDataProvider is set to false the DataProvider will not be cleaned up after the render and the same data can be used multiple times to render a document (rather than creating it each time). It is then the caller's responsibility to cleanup the data provider when ready using code like this:

  if (dp instanceof Cleanable) {
    ((Cleanable)dp).cleanup();
  }
 

The default configured template store will be used to retrieve templates.

Parameters:

template - the template file to use

outputFile - the location to place the output

dp - the data to populate with

cleanupDataProvider - if false, the DataProvider will not be cleaned up allowing the same data to be used to make multiple calls.

Returns:

a DocumentRenderResult with some information about the document

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 initialised correctly.

renderDoc

public static DocumentRenderResult 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). The DataProvider will automatically be cleaned up (meaning all data is removed) after this call. The default configured template store will be used to retrieve templates.

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

Returns:

a DocumentRenderResult with some information about the document

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 initialised correctly.

renderDoc

public static DocumentRenderResult renderDoc(File template,
                                             OutputStream outputStream,
                                             ConversionFormat format,
                                             DataProvider dp,
                                             boolean cleanupDataProvider)
                                      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). If cleanupDataProvider is set to false the DataProvider will not be cleaned up after the render and the same data can be used multiple times to render a document (rather than creating it each time). It is then the caller's responsibility to cleanup the data provider when ready using code like this:

  if (dp instanceof Cleanable) {
    ((Cleanable)dp).cleanup();
  }
 

The default configured template store will be used to retrieve templates.

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

cleanupDataProvider - if false, the DataProvider will not be cleaned up allowing the same data to be used to make multiple calls.

Returns:

a DocumentRenderResult with some information about the document

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

getOnlineConverterCount

public static int getOnlineConverterCount()
                                   throws ConverterPoolException

Get the number of converters online for the default converter pool group. This indicates the degree of parallel document production available at this point in time.

Returns:

-1 if the system has not been initialised

Throws:

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

getOnlineConverterCount

public static int getOnlineConverterCount(String groupName)
                                   throws ConverterPoolException

Get the number of converters online for the named converter pool group. This indicates the degree of parallel document production available at this point in time.

Returns:

-1 if the system has not been initialised

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