Docmosis API 4.5.0

com.docmosis.document.converter
Class ConversionInstruction

java.lang.Object
  extended bycom.docmosis.document.converter.ConversionInstruction
All Implemented Interfaces:
Serializable
Direct Known Subclasses:
ExtendedConversionInstruction

public class ConversionInstruction
extends Object
implements Serializable

This class is used to specify various settings for a document to be rendered. Control features include:

  1. specifying output formats
  2. any one-off or overriding renderers to be applied
  3. if producing multiple formats, the name for the files within the zip result

See Also:
Serialized Form

Nested Class Summary
static class ConversionInstruction.OfficeEngineProperties
          Properties specifically for the underlying office engine
 
Field Summary
static int PDF_INITIAL_VIEW_DEFAULT
          default view with neither outlines or thumbnails
static int PDF_INITIAL_VIEW_OUTLINE
          initial view with outline pane visible
static int PDF_INITIAL_VIEW_THUMBNAIL
          initial view with thumbnail pane visible
 
Constructor Summary
ConversionInstruction()
          Create a blank conversion instruction.
ConversionInstruction(ConversionInstruction other)
          Create a standalone copy of the given conversion instruction.
 
Method Summary
 boolean cleanupDataProvider()
          Determine if the DataProvider should be cleaned up at the end of the render process.
 boolean compressSingleDocument()
          Determine whether to compress (zip) the resulting document if only a single format is being used.
 boolean equals(Object obj)
           
 ConversionFormat[] getConversionFormats()
          Get the conversion formats specified by this instruction.
 Map getConversionProperties(ConversionFormat format)
           
 String getConverterGroupName()
          Get the name of the Converter Group to use to render the document.
 String getOutputFileName()
           
 String getOutputFileNameWithFormats()
          Determine the default output file name that will be produced based on: outputFileName conversionFormats compressSingleDocument The effect is to ensure the default outputName has the correct extension based on what will be generated (".zip" for multiple files or compressing single format, otherwise the extension for the type).
 RendererRegistry getRendererRegistry()
          Get the collection of renderers registry that have been set into this instruction.
 int hashCode()
           
 boolean includesFormat(ConversionFormat format)
          Determine if the specified format is included in the conversion formats currently set in this instruction.
 boolean isCompressingSingleDocument()
          Determine if a single resulting document should be automatically zipped to create a smaller file.
 boolean isConvertOnly()
          Determine if this instruction is flagged as "convert only" meaning extra processing (such as updating TOC and counting pages) is not done.
 boolean producesZippedDocument()
          Determines if this instruction produces a zipped result.
 ConversionInstruction setCleanupDataProvider(boolean cleanupDataProvider)
          Specify whether the data provider should be cleaned up at the end of the render process.
 ConversionInstruction setCompressingSingleDocument(boolean compressingSingleDocument)
          Specify whether a single resulting document should be automatically zipped to create a smaller file.
 ConversionInstruction setConversionFormats(ConversionFormat[] conversionFormats)
          Specify the conversion formats for the returned result.
 ConversionInstruction setConverterGroupName(String converterGroupName)
          Specify the name of the converter pool group to which this task is to be assigned.
 ConversionInstruction setConvertOnly(boolean convertOnly)
          Specify this instruction is flagged as "convert only" meaning extra processing (such as updating TOC and counting pages) is not done.
 ConversionInstruction setOutputFileName(String outputFileName)
          Specify the filename for output.
 ConversionInstruction setPdfArchiveMode(boolean archiveMode)
          Set whether to use PDF archive mode or not.
 ConversionInstruction setPdfDisplayTitle(boolean title)
          Set whether to display the document title (if available) in the PDF window title bar.
 ConversionInstruction setPdfEmbedStandardFonts(boolean embed)
          Specifies whether to embed the 14 standard PDF fonts or not.
 ConversionInstruction setPdfHideViewerMenubar(boolean hide)
          Specifies whether to hide the PDF viewer menubar when the document is active.
 ConversionInstruction setPdfHideViewerToolbar(boolean hide)
          Specifies whether to hide the PDF viewer toolbar when the document is active.
 ConversionInstruction setPdfHideViewerWindowControls(boolean hide)
          Specifies whether to hide the PDF viewer controls when the document is active.
 ConversionInstruction setPdfImageCompressionQuality(int quality)
          Specifies quality of the JPG export.
 ConversionInstruction setPdfInitialView(int view)
          Specifies how the PDF document should be displayed when opened.
 ConversionInstruction setPdfLosslessConversion(boolean lossless)
          Specifies if graphics are exported to PDF using a lossless compression eg.
 ConversionInstruction setPdfMagnification(int magnification, int zoom)
          Set the magnification and zoom.
 ConversionInstruction setPdfOpenInFullScreen(boolean fullScreen)
          Set whether to open the PDF in fullscreen mode or not.
 ConversionInstruction setPdfPasswordProtect(String password)
          Set a password to read-protect a PDF document.
 ConversionInstruction setPdfTagged(boolean tagged)
          Specify whether the PDF should be tagged.
 ConversionInstruction setPdfWatermark(String text)
          Set whether to use a watermark or not.
 ConversionInstruction setRenderer(Class forClass, FieldRenderer renderer)
          Set a renderer against the given Class for use with this instruction.
 ConversionInstruction setRenderer(String name, FieldRenderer renderer)
          Set a renderer with the given name for use with this instruction.
 ConversionInstruction setWordPasswordProtect(String password)
          Set an encrypted password to protect a Word document.
 
Methods inherited from class java.lang.Object
clone, finalize, getClass, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

PDF_INITIAL_VIEW_DEFAULT

public static final int PDF_INITIAL_VIEW_DEFAULT
default view with neither outlines or thumbnails

See Also:
Constant Field Values

PDF_INITIAL_VIEW_OUTLINE

public static final int PDF_INITIAL_VIEW_OUTLINE
initial view with outline pane visible

See Also:
Constant Field Values

PDF_INITIAL_VIEW_THUMBNAIL

public static final int PDF_INITIAL_VIEW_THUMBNAIL
initial view with thumbnail pane visible

See Also:
Constant Field Values
Constructor Detail

ConversionInstruction

public ConversionInstruction()
Create a blank conversion instruction.


ConversionInstruction

public ConversionInstruction(ConversionInstruction other)
Create a standalone copy of the given conversion instruction.

Parameters:
other - the instruction to copy
Method Detail

getOutputFileName

public String getOutputFileName()

getOutputFileNameWithFormats

public String getOutputFileNameWithFormats()
Determine the default output file name that will be produced based on:

setOutputFileName

public ConversionInstruction setOutputFileName(String outputFileName)
Specify the filename for output. Since a single render can produce an archive of documents, this setting is used to control the name of the files within the (zip) archive. It doesn't control the name of the final file being rendered since that is a parameter to the render methods of DocumentProcessor.

Parameters:
outputFileName - the name of the file
Returns:
this instruction to help with "command chaining".

isCompressingSingleDocument

public boolean isCompressingSingleDocument()
Determine if a single resulting document should be automatically zipped to create a smaller file. It is up to the caller to make sure that the filename used to render the document (passed to DocumentProcessor.render()) is suitable (typically this means that it should have a .zip extension).

Returns:
true if single resulting documents should be zipped.

getConversionFormats

public ConversionFormat[] getConversionFormats()
Get the conversion formats specified by this instruction. If multiple formats are specified, a single render call will produce a zip archive with multiple documents inside. If not formats are specified, then the output file name (if set) is used to determine the output format (if possible).

Returns:
the list of conversion formats.

setWordPasswordProtect

public ConversionInstruction setWordPasswordProtect(String password)
Set an encrypted password to protect a Word document.

Parameters:
password - the password to open the Word document; null removes any current passwords.
Returns:
this instruction to help with "command chaining".

setPdfPasswordProtect

public ConversionInstruction setPdfPasswordProtect(String password)
Set a password to read-protect a PDF document. This setting is ignored if archive mode is set to true because they are considered incompatible concepts.

Parameters:
password - the password to open the PDF document
Returns:
this instruction to help with "command chaining".

setPdfMagnification

public ConversionInstruction setPdfMagnification(int magnification,
                                                 int zoom)
                                          throws IllegalArgumentException
Set the magnification and zoom.

Parameters:
magnification - the magnification rule to use as follows: 0= Opens with default zoom magnification. 1= Opens magnified to fit the entire page within the window. 2= Opens magnified to fit the entire page width within the window. 3= Opens magnified to fit the entire width of its bounding box within the window (cuts out margins). 4= Opens with the zoom level specified in the zoom property. The default is 0.
zoom - only applicable if the magnification is 4. Zoom determines the percentage zoom level.
Returns:
this instruction to help with "command chaining".
Throws:
IllegalArgumentException

setPdfArchiveMode

public ConversionInstruction setPdfArchiveMode(boolean archiveMode)
                                        throws IllegalArgumentException
Set whether to use PDF archive mode or not. Setting archive mode will use the PDF version of PDF/A-1. Note: PDF password protection, external hyperlinks etc are disabled archive mode is turned on.

Parameters:
archiveMode - true to use PDF archive mode; false otherwise. Default is false.
Returns:
this instruction to help with "command chaining".
Throws:
IllegalArgumentException

setPdfImageCompressionQuality

public ConversionInstruction setPdfImageCompressionQuality(int quality)
                                                    throws IllegalArgumentException
Specifies quality of the JPG export. A higher value results in higher quality and file.

Parameters:
quality - Minimum inclusive value: 1. Represents lowest value that can be used. The lower the value, the less good is the compression quality and the bigger is be the file size. Maximum inclusive value:100. Represents highest value that can be used. The higher the value, the better is the compression quality and the smaller is the file size. The default is 90.
Returns:
this instruction to help with "command chaining".
Throws:
IllegalArgumentException

setPdfInitialView

public ConversionInstruction setPdfInitialView(int view)
                                        throws IllegalArgumentException
Specifies how the PDF document should be displayed when opened.

Parameters:
view - PDF_INITIAL_VIEW_DEFAULT = Select the default viewer mode, neither outlines or thumb nails. PDF_INITIAL_VIEW_OUTLINE = The document is opened with outline pane opened. PDF_INITIAL_VIEW_THUMBNAIL = The document is opened with thumb nail pane opened. The default value is 0.
Returns:
this instruction to help with "command chaining".
Throws:
IllegalArgumentException - if an invalid view is provided

setPdfLosslessConversion

public ConversionInstruction setPdfLosslessConversion(boolean lossless)
Specifies if graphics are exported to PDF using a lossless compression eg. PNG or if they are compressed using the JPEG format.

Parameters:
lossless - true to use lossless compression; false to use normal compression; default is false; setting this property to true will override any calls to setPdfImageCompressionQuality().
Returns:
this instruction to help with "command chaining".

setPdfEmbedStandardFonts

public ConversionInstruction setPdfEmbedStandardFonts(boolean embed)
Specifies whether to embed the 14 standard PDF fonts or not.

Parameters:
embed - true to embed standard fonts; false to not do so; default is false.
Returns:
this instruction to help with "command chaining".

setPdfWatermark

public ConversionInstruction setPdfWatermark(String text)
Set whether to use a watermark or not. Note that the watermark is not currently customisable. It is currently dark red text turned 90 degrees clockwise.

Parameters:
text - the text of the watermark to use. Use null to set no watermark. Default is null.
Returns:
this instruction to help with "command chaining".

setPdfOpenInFullScreen

public ConversionInstruction setPdfOpenInFullScreen(boolean fullScreen)
Set whether to open the PDF in fullscreen mode or not.

Parameters:
fullScreen - true to open the PDF in full screen mode; false otherwise.
Returns:
this instruction to help with "command chaining".

setPdfDisplayTitle

public ConversionInstruction setPdfDisplayTitle(boolean title)
Set whether to display the document title (if available) in the PDF window title bar.

Parameters:
title - true to display the document title; false to just display the file name; default is to just display the file name.
Returns:
this instruction to help with "command chaining".

setPdfHideViewerMenubar

public ConversionInstruction setPdfHideViewerMenubar(boolean hide)
Specifies whether to hide the PDF viewer menubar when the document is active.

Parameters:
hide - true to hide the view menubar; default is false.
Returns:
this instruction to help with "command chaining".

setPdfHideViewerToolbar

public ConversionInstruction setPdfHideViewerToolbar(boolean hide)
Specifies whether to hide the PDF viewer toolbar when the document is active.

Parameters:
hide - true to hide the viewer toolbar ; default is false.
Returns:
this instruction to help with "command chaining".

setPdfHideViewerWindowControls

public ConversionInstruction setPdfHideViewerWindowControls(boolean hide)
Specifies whether to hide the PDF viewer controls when the document is active.

Parameters:
hide - true to hide the viewer controls; default is false.
Returns:
this instruction to help with "command chaining".

setPdfTagged

public ConversionInstruction setPdfTagged(boolean tagged)
Specify whether the PDF should be tagged. Tagged PDFs store further information in the PDF (such as image ALT text), which can help assistive / accessibility technologies to "read" the document for example

Parameters:
tagged - if true, the PDF will be tagged.
Returns:
this instruction to help with "command chaining".

getConversionProperties

public Map getConversionProperties(ConversionFormat format)

compressSingleDocument

public boolean compressSingleDocument()
Determine whether to compress (zip) the resulting document if only a single format is being used.

Returns:
true if the document should be compressed

setCompressingSingleDocument

public ConversionInstruction setCompressingSingleDocument(boolean compressingSingleDocument)
Specify whether a single resulting document should be automatically zipped to create a smaller file. It is up to the caller to make sure that the filename used to render the document (passed to DocumentProcessor.render()) is suitable (typically this means that it should have a .zip extension). Note: if you are generating HTML output (only) in a call to Docmosis and the resulting document has images, you need this flag set to true and the resulting zip file will also include the HTML images required for viewing it correctly.

Parameters:
compressingSingleDocument - if true, single documents will be zipped.
Returns:
this instruction to help with "command chaining".

setConversionFormats

public ConversionInstruction setConversionFormats(ConversionFormat[] conversionFormats)
Specify the conversion formats for the returned result. If multiple formats are specified, a single render call will produce a zip archive with multiple documents inside. Each internal file will be named according to setOutputFileName().

Parameters:
conversionFormats - the array of formats desired
Returns:
this instruction to help with "command chaining".

getConverterGroupName

public String getConverterGroupName()
Get the name of the Converter Group to use to render the document. This only applies if multiple groups of converters are being used in a large-scale system.

Returns:
the group name to use.

setConverterGroupName

public ConversionInstruction setConverterGroupName(String converterGroupName)
Specify the name of the converter pool group to which this task is to be assigned. This optional setting is helpful when groups of converters have been configured and different tasks can be managed by different groups. If no group name has been set for this instruction the default group is used.

Parameters:
converterGroupName - the name of the group.
Returns:
this instruction to help with "command chaining".

cleanupDataProvider

public boolean cleanupDataProvider()
Determine if the DataProvider should be cleaned up at the end of the render process. This is particularly useful where dataproviders are holding image streams or file handles.

Returns:
true if the dataprovider should be cleaned up.

setCleanupDataProvider

public ConversionInstruction setCleanupDataProvider(boolean cleanupDataProvider)
Specify whether the data provider should be cleaned up at the end of the render process. The default is true.

Parameters:
cleanupDataProvider - set to false to disable auto cleanup
Returns:
this instruction to help with "command chaining".

isConvertOnly

public boolean isConvertOnly()
Determine if this instruction is flagged as "convert only" meaning extra processing (such as updating TOC and counting pages) is not done.

Returns:
true if flagged as convert only

setConvertOnly

public ConversionInstruction setConvertOnly(boolean convertOnly)
Specify this instruction is flagged as "convert only" meaning extra processing (such as updating TOC and counting pages) is not done.

Parameters:
convertOnly - if true, minimised processing will occur
Returns:
this instruction to help with "command chaining".

setRenderer

public ConversionInstruction setRenderer(String name,
                                         FieldRenderer renderer)
Set a renderer with the given name for use with this instruction. Setting a renderer here overrides any default renderer associated with the same name.

Parameters:
name - the name against which the renderer is associated
renderer - the renderer
Returns:
this instruction to help with "command chaining".

setRenderer

public ConversionInstruction setRenderer(Class forClass,
                                         FieldRenderer renderer)
Set a renderer against the given Class for use with this instruction. Setting a renderer here overrides any default renderer associated with the same Class.

Parameters:
forClass - the Class against which the renderer is associated
renderer - the renderer
Returns:
this instruction to help with "command chaining".

getRendererRegistry

public RendererRegistry getRendererRegistry()
Get the collection of renderers registry that have been set into this instruction.

Returns:
null if no renderers have been set.

includesFormat

public boolean includesFormat(ConversionFormat format)
Determine if the specified format is included in the conversion formats currently set in this instruction.

Parameters:
format - the format to test
Returns:
true if set

producesZippedDocument

public boolean producesZippedDocument()
Determines if this instruction produces a zipped result. This is true if there are multiple formats specified, or compressSingleDocument is set.

Returns:
whether or not the result will be zipped

hashCode

public int hashCode()

equals

public boolean equals(Object obj)

Docmosis API 4.5.0

Copyright © 2014 Docmosis Pty Ltd. All Rights Reserved.