Docmosis API 4.5.0

com.docmosis.document
Class RenderRequest

java.lang.Object
  extended bycom.docmosis.document.RenderRequest

public class RenderRequest
extends Object

This class provides a way way of building the set of parameters for a render request, including less commonly used parameters. For typical render calls, the DocumentProcessor class has methods that can be called without needing to use this class at all. The same request object can be re used making the changes required for each render.

 
   // Simple Example
   // build request
   RenderRequest rr = new RenderRequest();
   rr.setTemplateFile(new File("myTemplate.doc"));
   rr.setOutputFile(new File("myResult.pdf"));
   DataProviderBuilder dpb = new DataProviderBuilder();
   //...add data here...
   rr.setDataProvider(dpb.getDataProvider());
  
   // now render
   DocumentProcessor.renderDoc(rr);
 
 
 
   // Higher Performance Example
   // Assumes template ("myTemplate.doc") has already been registered
   // build request
   RenderRequest rr = new RenderRequest();
   rr.setTemplateIdentifier(new TemplateIdentifier("myTemplate.doc"));
   ConversionInstruction ci = new ConversionInstruction();
   ci.setOutputFileName("myResult") ;
   ci.setConversionFormats(new ConversionFormat[] { 
 		 ConversionFormat.FORMAT_PDF,
   		 ConversionFormat.FORMAT_WORD
   });
   rr.setConversionInstruction(ci);
   rr.setOutputFile(new File("myResult.zip"));
   DataProviderBuilder dpb = new DataProviderBuilder();
   //...add data here...
   rr.setDataProvider(dpb.getDataProvider());
   
   // now render
   DocumentProcessor.renderDoc(rr);
 
 

See Also:
DocumentProcessor, ConversionInstruction

Constructor Summary
RenderRequest()
           
 
Method Summary
 ConversionInstruction getConversionInstruction()
          Get the conversion instruction to use for this request.
 DataProvider getDataProvider()
          Get the data provider to use
 ImageScalingDefault getImageScalingDefault()
          Get the default image scaling if specified, otherwise the system default is returned.
 ImageSupplier getImageSupplier()
           
 File getOutputFile()
          Get the output file specified.
 OutputStream getOutputStream()
          Determine where to stream the result.
 Boolean getPopulationErrorsFatal()
          Determine if population errors are fatal
 Boolean getProcessStylesInText()
          Determine whether text data will be parsed for html-like styling.
 boolean getRemoveTemplateAfterUse()
          Determine if "remove template after use" is specified.
 File getTemplateFile()
          Get the template file specified
 TemplateIdentifier getTemplateIdentifier()
          Get the specified template identifier indicating the template to use.
 TemplateStore getTemplateStore()
          Get the template store.
 NamedInputStream getTemplateStream()
          Get the template stream setting.
 RenderRequest setConversionInstruction(ConversionInstruction conversionInstruction)
          Set the conversion instruction to use for this request.
 RenderRequest setDataProvider(DataProvider dataProvider)
          Set the data to use for the render
 RenderRequest setImageScalingDefault(ImageScalingDefault imageScalingDefault)
          Set the default image scaling method (eg fit or stretch) to use when inserting images into the template.
 RenderRequest setImageSupplier(ImageSupplier imageSupplier)
          Set the image supplier to use for sourcing images for population.
 RenderRequest setOutputFile(File outputFile)
          Set the file to write the result to.
 RenderRequest setOutputStream(OutputStream streamTo)
          Specify where to stream the result.
 RenderRequest setPopulationErrorsFatal(Boolean populationErrorsFatal)
          Specify whether population errors should be fatal.
 RenderRequest setProcessStylesInText(Boolean processTextStyles)
          Specify whether text data should be parsed for HTML-like data.
 RenderRequest setRemoveTemplateAfterUse(boolean remove)
          Specify whether or not the template should be removed from the TemplateStore (the local cache) after being used for rendering.
 RenderRequest setTemplateFile(File templateFile)
          Specify the template to use by a direct reference to the source template file.
 RenderRequest setTemplateIdentifier(TemplateIdentifier templateIdentifier)
          Set the template to use.
 RenderRequest setTemplateStore(TemplateStore templateStore)
          Set the template store to use.
 RenderRequest setTemplateStream(InputStream templateStream, String name, boolean removeAfterUse)
          Specify that the template is to be obtained by reading the given InputStream.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

RenderRequest

public RenderRequest()
Method Detail

getImageSupplier

public ImageSupplier getImageSupplier()

setImageSupplier

public RenderRequest setImageSupplier(ImageSupplier imageSupplier)
Set the image supplier to use for sourcing images for population.

Parameters:
imageSupplier -
Returns:
this instance to allow method-chaining for convenience
See Also:
ImageSupplier

getImageScalingDefault

public ImageScalingDefault getImageScalingDefault()
Get the default image scaling if specified, otherwise the system default is returned.

Returns:
the specified scaling otherwise the system default

setImageScalingDefault

public RenderRequest setImageScalingDefault(ImageScalingDefault imageScalingDefault)
Set the default image scaling method (eg fit or stretch) to use when inserting images into the template. This setting will be used for images where the template is using the bm_ or img_ naming scheme. Templates can specify the scaling method overriding this setting.

Parameters:
imageScalingDefault - the setting to use by default
Returns:
this instance to allow method-chaining for convenience
See Also:
ImageScalingDefault

getTemplateStore

public TemplateStore getTemplateStore()
Get the template store. This will return the default system template store if none has been specified

Returns:
the specified store if any, otherwise the default

setTemplateStore

public RenderRequest setTemplateStore(TemplateStore templateStore)
Set the template store to use. If not specified, the default store will be utilised.

Parameters:
templateStore - the store to use for this request

getConversionInstruction

public ConversionInstruction getConversionInstruction()
Get the conversion instruction to use for this request.

Returns:
null if no conversion information is determined

setConversionInstruction

public RenderRequest setConversionInstruction(ConversionInstruction conversionInstruction)
Set the conversion instruction to use for this request. The conversion instruction allows setting of a raft of conversion-specific settings. Note: If the conversion instruction specifies an output name, it will override the file name derived from this requests setOutputFile() method.

Parameters:
conversionInstruction - the instruction
Returns:
this instance to allow method-chaining for convenience
See Also:
ConversionInstruction

getTemplateIdentifier

public TemplateIdentifier getTemplateIdentifier()
Get the specified template identifier indicating the template to use.

Returns:
null if not specified

setTemplateIdentifier

public RenderRequest setTemplateIdentifier(TemplateIdentifier templateIdentifier)
Set the template to use. The template must have previously been registered in the store using the template monitor (settings in the docmosis.properties file) or the calling the DropStoreHelper. Calling this method overrides any previous calls to setTemplateFile() and setTemplateStream(). TemplateIdentifiers can optionally have a "context" which is a path-structure, allowing the templates to be organised.
 
    // template without any context
    TemplateIdentifier tid = new TemplateIdentifier("myTemplate.doc");
    
    // template with a context
    TemplateIdentifier tid = new TemplateIdentifier("myTemplate.doc", "/projects/projectA");
    or
    TemplateIdentifier tid = TemplateIdentifier.fromPath("/projects/projectA/myTemplate.doc");
    
 
 

Parameters:
templateIdentifier - the template
Returns:
this instance for convenience
See Also:
setTemplateFile(File), setTemplateStream(InputStream, String, boolean)

setTemplateFile

public RenderRequest setTemplateFile(File templateFile)
Specify the template to use by a direct reference to the source template file. This is convenient since there is no need to register the template with the TemplateStore separately. Calling this method overrides any previous calls to setTemplateIdentifier() and setTemplateStream(). The file will be loaded and analysed as required before rendering hence there is an overhead to calling this method. The file is also loaded into the "root" of the template store so it has no context.

Parameters:
templateFile -
See Also:
setTemplateIdentifier(TemplateIdentifier), setTemplateStream(InputStream, String, boolean)

setTemplateStream

public RenderRequest setTemplateStream(InputStream templateStream,
                                       String name,
                                       boolean removeAfterUse)
Specify that the template is to be obtained by reading the given InputStream. At render time, the template stream will be read, loaded into the TemplateStore with the given name and then used for the render. The template loaded into the TemplateStore will then be optionally removed from the store depending on the removeAfterUse parameter. The name parameter is used to identify the template in the TemplateStore during the render process. Things to note about the name are:
 1. The name may be null, in which case a temporary unique name will be used
 2. The name may include a "context" path, for example ("temporary/template1.doc")
    or ("dynamic/templates/template1433").
 3. If the name correlates with a template that already exists, that template will
    be overwritten.
 
This method does not close the given InputStream, it is expected the caller will close it. Calling this method overrides any previous calls to setTemplateIdentifier(), setTemplateFile() and setRemoveTemplateAfterUse().

Parameters:
templateStream - the source of the template
name - the name of the template to use. May be null (in which case removeAfterUse will be assumed to be true) and may contain a "context" path (see above description)
removeAfterUse - if set to true, the template will be removed from the TemplateStore after the render is complete.
See Also:
setTemplateIdentifier(TemplateIdentifier), setTemplateFile(File), setRemoveTemplateAfterUse(boolean)

getTemplateStream

public NamedInputStream getTemplateStream()
Get the template stream setting.

Returns:
null if not set.

setRemoveTemplateAfterUse

public RenderRequest setRemoveTemplateAfterUse(boolean remove)
Specify whether or not the template should be removed from the TemplateStore (the local cache) after being used for rendering. This is useful when you know the template being used is temporary and there is no value in having it cached.

Parameters:
remove - the flag indicating cache removal
Returns:
this instance for convenience

getRemoveTemplateAfterUse

public boolean getRemoveTemplateAfterUse()
Determine if "remove template after use" is specified.

Returns:
true if so.

getTemplateFile

public File getTemplateFile()
Get the template file specified

Returns:
null if not specified

getDataProvider

public DataProvider getDataProvider()
Get the data provider to use

Returns:
the data provider

setDataProvider

public RenderRequest setDataProvider(DataProvider dataProvider)
Set the data to use for the render

Parameters:
dataProvider - the data
Returns:
this instance to allow method-chaining for convenience

getPopulationErrorsFatal

public Boolean getPopulationErrorsFatal()
Determine if population errors are fatal

Returns:
null if not set (meaning system default applies)

setPopulationErrorsFatal

public RenderRequest setPopulationErrorsFatal(Boolean populationErrorsFatal)
Specify whether population errors should be fatal. Fatal means the document will not be produced - instead an Exception will be thrown ("production mode"). A setting of false is akin to "development mode" meaning Docmosis will do it's best to render the document and indicate within the document where the errors are.

Setting populationErrorsFatal to null will enable system-default behaviour to apply. System default behaviour can be set using the property docmosis.populator.error.fatal to true or false.

Parameters:
populationErrorsFatal - if null the system default behaviour will take effect
Returns:
this instance

getProcessStylesInText

public Boolean getProcessStylesInText()
Determine whether text data will be parsed for html-like styling.

Returns:
null if the system default applies

setProcessStylesInText

public RenderRequest setProcessStylesInText(Boolean processTextStyles)
Specify whether text data should be parsed for HTML-like data. This allows font style changes within a paragraph. Text can contain <b>, <i> and <u> html tags to indicate portions of the data should be styled and this setting decides whether the engine treats this mark-up as special or as plain text. Currently supported styles are: For example, given some data:
  This is <b>bold</b> text.
the word "bold" will be rendered in bold if this setting is true.

Setting processStringStyles to null will enable system-default behaviour to apply. System default behaviour can be set using the property docmosis.populator.field.markup.process to true or false.

Parameters:
processTextStyles - if null, the system default behaviour will take effect
Returns:
this instance

getOutputStream

public OutputStream getOutputStream()
Determine where to stream the result.

Returns:
null if not set

setOutputStream

public RenderRequest setOutputStream(OutputStream streamTo)
Specify where to stream the result. Calling this method overrides any previous call to setOutputFile(). Setting the output stream requires you to also set the Conversion Instruction to allow the output format(s) to be determined.

Parameters:
streamTo -
See Also:
setOutputFile(File), setConversionInstruction(ConversionInstruction)

getOutputFile

public File getOutputFile()
Get the output file specified.

Returns:
null if not set

setOutputFile

public RenderRequest setOutputFile(File outputFile)
Set the file to write the result to. This provides a convenient short hand way of specifying both the destination and the format of the result. For example
 
    File out = new File("output/result.pdf");
    renderRequest.setOutputFile(out);
 
 
specifies both the output format (PDF - inferred from the file name) and where the result should be written. Calling this method overrides any previous call to setStreamTo(). If setConversionInstruction has been called() any settings it holds for conversion formats and output name will override the format and name of this method.

Parameters:
outputFile -
Returns:
this instance to allow method-chaining for convenience
See Also:
setOutputStream(OutputStream), setConversionInstruction(ConversionInstruction)

Docmosis API 4.5.0

Copyright © 2014 Docmosis Pty Ltd. All Rights Reserved.