com.pd4ml

Class PD4ML

java.lang.Object

com.pd4ml.PD4ML

public class PD4ML
extends Object

Constructor Summary

Constructors

Constructor and Description
PD4ML() PD4ML Constructor Creates and initializes an instance of the converter
PD4ML(int loglevel) PD4ML Constructor Creates and initializes an instance of the converter
PD4ML(String license) PD4ML Constructor Creates and initializes an instance of the converter
PD4ML(String license, int loglevel) PD4ML Constructor Creates and initializes an instance of the converter

Method Summary

Modifier and Type	Method and Description
void	addCustomResourceProvider(String customProviderClassName) add custom resource loader for non-standard or customized transport protocols
void	addCustomTagHandler(String customTagName, CustomTag implementation) adds a proprietary HTML tag implementation
void	addDocumentActionHandler(String actionType, String javaScript) method defines JavaScript action handler for generated document.
void	addMetadata(String key, String value, boolean hide) The method defines custom properties for PDF document meta data.
void	addStyle(String stylesheet, boolean overrideDocumentStyles) Apply additional stylesheet to the document
void	addStyle(URL stylesheet, boolean overrideDocumentStyles) Apply additional stylesheet to the document
void	adjustHtmlWidth(boolean adjust) sets htmlWidth to the most right margin of the HTML block content.
void	applyKerning(boolean enable) Forces PD4ML to align font glyphs to each other according to the font kerning hints (if available).
boolean	applyLicense(String license) applies license code.
void	asyncResourceLoader(int threadPoolSize) enables asynchronous resource loading (graphics, attachments etc) if thread pool size is not equal 0.
String	dump(int mode) debug/diagnostics method
void	embedTTFs(boolean embed, boolean allGlyphs)
void	enableHyperlinks(boolean enable) enables converting of HTML to PDF hyperlinks.
void	enableLigatures(boolean enable) Forces PD4ML to load TTF/OTF glyph susbstitution tables, to apply ligature replacements and to build compound glyphs.
void	fitPageVertically(int align) forces PD4ML to downscale entire HTML layout to fit a single PDF page vertically.
void	generateBookmarksFromAnchors(boolean enable)
void	generateBookmarksFromHeadings(boolean enable)
void	generateForms(boolean enable, String useTtfFont) forces PD4ML to convert HTML forms into PDF forms (Acroforms).
void	generateForms(boolean enable, String useTtfFont, String formFontCharRange) forces PD4ML to convert HTML forms into PDF forms (Acroforms).
void	generateMulticolumn(int columns, int span, boolean millimeters) switches PD4ML into multicolumn mode.
Object	getCache()
String	getDocumentTitle()
short	getFitPageVertically()
int	getHeight(int width) calculates document height for given document width.
Object	getLastRenderInfo(String key) returns statistics for the last render() call
PageMargins	getPageMargins(int pageNum, boolean imageGeneration) Returns page margins object for a specified page number.
PageSize	getPageSize(int pageNum) Returns page dimensions object for a specified page number.
static String	getVersion() returns current version number
static Date	getVersionBuildDate()
void	injectHtml(String htmlSnippet, boolean prependBodyContent) Injects a portion of HTML to the source
boolean	isDemoMode()
boolean	isPro()
void	merge(PdfDocument pdf, int fromPage, int toPage, boolean append) Merges conversion result with an already existing PDF document
void	monitorProgressWith(ProgressListener listener) conversion progress callback support
void	outputRange(String description)
void	overrideDocumentEncoding(String encoding) sets default encoding for URL-addressed HTML documents
static int	predictPageHeight(PageMargins pageMargins, PageSize pageSize, int userSpace) predicts page height for given conversion parameters
static float	predictScale(PageMargins pageMargins, PageSize pageSize, int userSpace) predicts document HTML-to-PDF mapping scale for given conversion parameters
void	protectPhysicalUnitDimensions(boolean keepPhysicalUnitDimensions) makes PD4ML to output PDF objects respecting dimensions/font sizes given in "in", "pt", "cm" etc.
void	readHTML(InputStream isr) converts input data to PDF
void	readHTML(InputStream isr, URL base) converts input data to PDF.
void	readHTML(InputStream isr, URL base, String encoding) converts input data to PDF
void	readHTML(URL url) input data referred by URL to PDF
void	readHTML(URL url, String encoding) input data referred by URL to PDF
BufferedImage[]	renderAsImages() renders document in RAM as a set of images, represent document pages
File	renderAsImages(File dir, String fileNamePrefix, String format) renders document as a set of image files, represent document pages
byte[][]	renderAsImages(String format) renders document in RAM as a set of images, represent document pages
void	setAuthorName(String name) sets an author name for the document
void	setCache(Object fontCache)
void	setCookie(String name, String value) makes PD4ML to add a cookie with given name and value to each URL connection request
void	setDocumentTitle(String title) forces to override HTML title
void	setDynamicData(Map<String,String> map)
void	setHtmlWidth(int width) defines desired HTML page width in screen pixels.
void	setHttpOptions(String proxy, String basicAuthentication) specifies HTTP options
void	setInitialPageNumber(int initialPageNumber) sets page number counter to given value.
void	setLogLevel(int level) enables an output of log/diagnostics messages.
void	setPageBackground(String htmlCode) defines HTML code to be rendered under each page content
void	setPageBackground(String htmlCode, String scope) defines HTML code to be rendered under each page content
void	setPageFooter(String htmlCode, int heightPx) defines HTML code to be rendered as page footer(s).
void	setPageFooter(String htmlCode, int heightPx, String scope) defines HTML code to be rendered as page footer(s).
void	setPageHeader(String htmlCode, int heightPx) defines HTML code to be rendered as page header(s).
void	setPageHeader(String htmlCode, int heightPx, String scope) defines HTML code to be rendered as page header(s).
void	setPageMargins(PageMargins margins) defines page margins for all document pages
void	setPageMargins(PageMargins margins, String scope) defines page margins for specified range(s) of pages
void	setPageSize(PageSize d) defines page size for all document pages.
void	setPageSize(PageSize d, String scope) defines page size for specified range(s) of pages
void	setParam(String key, String value) Sets parsing/rendering parameters
void	setPermissions(String password, int permissions) forces the resulting document to be encrypted with the given password
void	setRenderingHints(Map hints) Replaces the values of all preferences for the image rendering algorithms with the specified hints.
void	setSessionID(String sessionID) the method informs PD4ML about current session ID (in web application environments).
void	setWatermark(String htmlCode, float left, float top, float opacity, float angle, float scale, boolean screen, boolean print, String scope) defines page watermark.
void	terminate() Terminates conversion process and cleans the font cache
void	testTermination()
static float	translateToPt(float mm) converts from millimeters to points
void	useHttpRequest(javax.servlet.http.HttpServletRequest httpRequest, javax.servlet.http.HttpServletResponse httpResponse) method allows to inform PD4ML about actual HTTP request context (if any).
void	useTTF(String pathToFontDirs) enables TTF font embedding subsystem.
void	useTTF(String pathToFontDirs, boolean generateFontMappingFileIfMissing)
void	useTTF(String pathToFontDirs, String fontFileNameFilter) registers font directory and forces to index fonts, whose names match the filter patterns (for example, "arial,courier").
void	writePDF(OutputStream os) renders and writes parsed HTML as PDF document
void	writePDF(OutputStream os, String pdfFormat)
void	writeRTF(OutputStream os, boolean convertImagesToWMF)

Methods inherited from class java.lang.Object

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

Constructor Detail

PD4ML

public PD4ML()

PD4ML Constructor Creates and initializes an instance of the converter

PD4ML

public PD4ML(String license,
             int loglevel)

PD4ML Constructor Creates and initializes an instance of the converter

Parameters:

loglevel - bitmask to control logging verbosity

license - license string or license file URI

PD4ML

public PD4ML(int loglevel)

PD4ML Constructor Creates and initializes an instance of the converter

Parameters:

loglevel - bitmask to control logging verbosity

PD4ML

public PD4ML(String license)

PD4ML Constructor Creates and initializes an instance of the converter

Parameters:

license - license string or license file URI

Method Detail

applyLicense

public boolean applyLicense(String license)

applies license code. The method should be called before initiation of PDF, RTF or image output. The method is implicitly called by PD4ML(String) If the method is not invoked, the software runs in demo mode: its output is watermarked and supplied with an ad footer. An applying of evalution license removes the watermarks but the footer message remains. An applying of a commercial license removes both watermark and footer in permitted output modes.

Parameters:

license - license string or license file URI

Returns:

true if the license is valid

See Also:

PD4ML(String)

isDemoMode

public final boolean isDemoMode()

Returns:

true if the library is used in demo mode

Since:

v1.1.0

isPro

public final boolean isPro()

Returns:

true if it is Pro version of the library

Since:

v3.8.1

getVersion

public static String getVersion()

returns current version number

Returns:

version number formatted as a string

getVersionBuildDate

public static Date getVersionBuildDate()

Returns:

current version build date

merge

public void merge(PdfDocument pdf,
                  int fromPage,
                  int toPage,
                  boolean append)

Merges conversion result with an already existing PDF document

Parameters:

pdf - PDF document

fromPage - start page of the existing document (1 or greater)

toPage - end page of the existing document (-1 means all pages)

append - 'true' forces to append the existing PDF to the conversion result. Otherwise the existing document will lead the conversion result.

terminate

public void terminate()

Terminates conversion process and cleans the font cache

readHTML

public void readHTML(InputStream isr)
              throws InvokeException,
                     IOException

converts input data to PDF

Parameters:

isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag

Throws:

InvokeException - the input or output stream is null

IOException - input/output problems

readHTML

public void readHTML(InputStream isr,
                     URL base)
              throws InvokeException,
                     IOException

converts input data to PDF.

Parameters:

isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag

base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag

Throws:

InvokeException - the input or output stream is null

IOException - input/output problems

readHTML

public void readHTML(InputStream isr,
                     URL base,
                     String encoding)
              throws InvokeException,
                     IOException

converts input data to PDF

Parameters:

isr - input stream of formatted data. Determines encoding from BOM bytes or from HTML's meta tag

base - base URL to lookup referred resources like images or CSS. Can be specified in HTML body with <base href="..."> tag

encoding - content encoding. Value "default" corresponds to current OS encoding

Throws:

InvokeException - the input or output stream is null

IOException - input/output problems

readHTML

public void readHTML(URL url)
              throws InvokeException,
                     IOException

input data referred by URL to PDF

Parameters:

url - text representation of the input data URL

Throws:

MalformedURLException - invalid URL

InvokeException - the input or output stream is null

IOException - input/output problems

readHTML

public void readHTML(URL url,
                     String encoding)
              throws MalformedURLException,
                     InvokeException,
                     IOException

input data referred by URL to PDF

Parameters:

url - text representation of the input data URL

encoding - encoding name to override

Throws:

MalformedURLException - invalid URL

InvokeException - the input or output stream is null

IOException - input/output problems

setLogLevel

public void setLogLevel(int level)

enables an output of log/diagnostics messages.

Parameters:

level - log output verbosity level

useTTF

public void useTTF(String pathToFontDirs)
            throws FileNotFoundException

enables TTF font embedding subsystem. Available only in professional version of PD4ML.

Parameters:

pathToFontDirs - URL of a font directory or a path to pd4fonts.properties mapping file

The font directory should contain pd4fonts.properties mapping file. The file records have the following format:
font_name=file_name

• font_name - font name used in the source HTML.
• file_name - font file name (should exist in the font directory)

Example:

Book\ Antiqua=BKANT.TTF
To generate the file automatically you may use the command line call:
java -jar pd4ml.jar -configure.fonts <fontdir>
After the generation, please edit the file and remove manually all references to the fonts, that are not allowed to be redistributed. Contact your TTF fonts provider for the info.

In order to support J2EE deployments a PD4ML-specific protocol "java:" is supported to load font resources via ClassLoader.

Example: useTTF("java:myfonts");

In that case the runtime looks for a fonts folder named "/myfonts" in all JAR files available for the application class loaders. The content of the folder should correspond to the rules described above: pd4fonts.properties + *.ttf

Example: useTTF("java:");

The simplest case. The runtime looks for a JAR file which contains pd4fonts.properties + *.ttf in the root directory.

Throws:

FileNotFoundException - if pd4fonts.properties file is not found or the file refers to missing font files

useTTF

public void useTTF(String pathToFontDirs,
                   boolean generateFontMappingFileIfMissing)
            throws FileNotFoundException

Parameters:

pathToFontDirs - URI of TTF file directory

generateFontMappingFileIfMissing - forces to index available fonts (if they are not indexed yet). The indexing may be time/resource consuming. If true, make sure PD4ML has write permission to pathToFontDirs

Throws:

FileNotFoundException - font directory not found

See Also:

useTTF(String)

useTTF

public void useTTF(String pathToFontDirs,
                   String fontFileNameFilter)
            throws FileNotFoundException

registers font directory and forces to index fonts, whose names match the filter patterns (for example, "arial,courier").

Parameters:

pathToFontDirs - URI of TTF file directory,

fontFileNameFilter - a comma-separated list of font family names or name parts

Throws:

FileNotFoundException - font directory not found

See Also:

useTTF(String)

embedTTFs

public void embedTTFs(boolean embed,
                      boolean allGlyphs)

Parameters:

embed - if true forces PD4ML to include used font glyphs to the resulting PDF, otherwise it registers only font family names (expecting the TTFs present in the PDF reader environment)

allGlyphs - if true (and if param 'embed' is true) forces PD4ML to include all font glyphs to the resulting PDF

generateForms

public void generateForms(boolean enable,
                          String useTtfFont)

forces PD4ML to convert HTML forms into PDF forms (Acroforms). Note: The feature is at a very early stage now (v3.2.3).

Parameters:

useTtfFont - - UNICODE TTF font name to be used for form input. The name must appear in pd4fonts.properties or specified via @font-face CSS at-rule

enable - enables or disables the feature

Since:

v3.2.3 Pro

See Also:

useTTF(String)

generateForms

public void generateForms(boolean enable,
                          String useTtfFont,
                          String formFontCharRange)

forces PD4ML to convert HTML forms into PDF forms (Acroforms). Note: The feature is at a very early stage now (v3.2.3).

Parameters:

useTtfFont - - UNICODE TTF font name to be used for form input. The name must appear in pd4fonts.properties or specified via @font-face CSS at-rule

enable - enables or disables the feature

formFontCharRange - - specifies ranges of characters to be embedded to the resulting PDF to cover possible user input, e.g. "0-9a-zA-Z*.,:"

Since:

v4.0.2

See Also:

useTTF(String)

generateMulticolumn

public void generateMulticolumn(int columns,
                                int span,
                                boolean millimeters)

switches PD4ML into multicolumn mode. The mode in not compatible with adjustHtmlWidth() and fitPageVertically() calls.

Parameters:

columns - - number of columns per page

span - - space between the columns

millimeters - - if 'true' the gap is in millimeters, otherwise in points

useHttpRequest

public void useHttpRequest(javax.servlet.http.HttpServletRequest httpRequest,
                           javax.servlet.http.HttpServletResponse httpResponse)

method allows to inform PD4ML about actual HTTP request context (if any). HTTP request/response allows to get output of dynamic webapp resources.

Parameters:

httpRequest - actual HTTP request

httpResponse - actual HTTP response

addCustomResourceProvider

public void addCustomResourceProvider(String customProviderClassName)

add custom resource loader for non-standard or customized transport protocols

Parameters:

customProviderClassName - name of class, derived from CustomResourceProvider. The class implementation must be in the classpath

addCustomTagHandler

public void addCustomTagHandler(String customTagName,
                                CustomTag implementation)

adds a proprietary HTML tag implementation

Parameters:

customTagName - HTML tag name

implementation - an instance of implementation class

generateBookmarksFromHeadings

public void generateBookmarksFromHeadings(boolean enable)

Parameters:

enable - if set to true, PD4ML creates PDF bookmark tree structure derived from <H1>-<H6> structure.

See Also:

generateBookmarksFromAnchors(boolean)

generateBookmarksFromAnchors

public void generateBookmarksFromAnchors(boolean enable)

Parameters:

enable - if true, PD4ML creates PDF bookmarks from headings ( <a name="destination">Label</a> tags). If a label attribute is not defined, it uses destination string as visible label.

See Also:

generateBookmarksFromHeadings(boolean)

setSessionID

public void setSessionID(String sessionID)

the method informs PD4ML about current session ID (in web application environments). The session ID is implicitely added by PD4ML to resource references (CSS, image etc). The addition is done in the following form: "resource.jpg;jsessionid=<sessionID>?other_args". "jsessionid" reserved name can be overriden by a setting of "pd4ml.sessionid.varname" environment variable

Parameters:

sessionID - actual session ID

Since:

v3.0.0.b1

overrideDocumentEncoding

public void overrideDocumentEncoding(String encoding)

sets default encoding for URL-addressed HTML documents

Parameters:

encoding - encoding name, matches Java encoding naming specifics (i.e. "ISO8859_1" instead of "ISO-8859-1")

Since:

v3.7.1

enableHyperlinks

public void enableHyperlinks(boolean enable)

enables converting of HTML to PDF hyperlinks.

Parameters:

enable - if false, PD4ML does not generate active hyperlinks in resulting PDF. Default is "true"

Since:

v1.2.0

setPageHeader

public void setPageHeader(String htmlCode,
                          int heightPx)
                   throws InvokeException

defines HTML code to be rendered as page header(s). Implicitly adds <pd4ml:page.header> to source HTML

Parameters:

htmlCode - header HTML code

heightPx - header height (in screen pixels)

Throws:

InvokeException - method called with invalid parameters

setPageHeader

public void setPageHeader(String htmlCode,
                          int heightPx,
                          String scope)
                   throws InvokeException

defines HTML code to be rendered as page header(s). Implicitly adds <pd4ml:page.header scope="..."> to source HTML

Parameters:

htmlCode - header HTML code

heightPx - header height (in screen pixels)

scope - scope of pages to apply the header

Throws:

InvokeException - method called with invalid parameters

setPageFooter

public void setPageFooter(String htmlCode,
                          int heightPx)
                   throws InvokeException

defines HTML code to be rendered as page footer(s). Implicitly adds <pd4ml:page.footer> to source HTML

Parameters:

htmlCode - footer HTML code

heightPx - footer height (in screen pixels)

Throws:

InvokeException - method called with invalid parameters

setPageFooter

public void setPageFooter(String htmlCode,
                          int heightPx,
                          String scope)
                   throws InvokeException

defines HTML code to be rendered as page footer(s). Implicitly adds <pd4ml:page.footer scope="..."> to source HTML

Parameters:

htmlCode - footer HTML code

heightPx - footer height (in screen pixels)

scope - scope of pages to apply the footer

Throws:

InvokeException - method called with invalid parameters

setWatermark

public void setWatermark(String htmlCode,
                         float left,
                         float top,
                         float opacity,
                         float angle,
                         float scale,
                         boolean screen,
                         boolean print,
                         String scope)

defines page watermark. The watermark content is rendered over the page content on all (or selected) pages.

Parameters:

htmlCode - watermark HTML code

left - horizintal position

top - vertical position

opacity - watermark opacity from 0 to 1

angle - rotate watermark layout to a given degree

scale - watermark content scale from 0 to 1

screen - if true, watermarks screen view

print - if true, watermarks printed output

scope - scope of pages to apply the watermark

setPageBackground

public void setPageBackground(String htmlCode)

defines HTML code to be rendered under each page content

Parameters:

htmlCode - background layout HTML code

setPageBackground

public void setPageBackground(String htmlCode,
                              String scope)

defines HTML code to be rendered under each page content

Parameters:

htmlCode - background layout HTML code

scope - scope of pages to apply the background

setPermissions

public void setPermissions(String password,
                           int permissions)

forces the resulting document to be encrypted with the given password

Parameters:

password - password. If is set to "empty", than no password assigned to document, only permissions.

permissions - an integer value according to PDF encryption specification

Since:

v1.1.0

setCookie

public void setCookie(String name,
                      String value)

makes PD4ML to add a cookie with given name and value to each URL connection request

Parameters:

name - cookie name

value - cookie value

Since:

v3.0.2

setHttpOptions

public void setHttpOptions(String proxy,
                           String basicAuthentication)

specifies HTTP options

Parameters:

proxy - null or HTTP proxy settings in "host:port" format

basicAuthentication - HTTP authentication pair in "login:password" format

addDocumentActionHandler

public void addDocumentActionHandler(String actionType,
                                     String javaScript)

method defines JavaScript action handler for generated document.

Parameters:

actionType - "OpenAction", "DC" (document close), "WS" (will save), "DS" (did save), "WP" (will print) or "DP" (did print)

javaScript - handler code

setPageSize

public void setPageSize(PageSize d,
                        String scope)

defines page size for specified range(s) of pages

Parameters:

d - page dimensions

scope - scope of pages to apply the size

setPageSize

public void setPageSize(PageSize d)
                 throws InvokeException

defines page size for all document pages. A set of predefined page format constants is available in the PD4Constants interface.
To get "Landscape" page orientation invoke rotate() method of PageSize

Parameters:

d - page PageSize

Throws:

InvokeException - when the specified page format is null or does not fit to already defined page insets

getPageSize

public PageSize getPageSize(int pageNum)

Returns page dimensions object for a specified page number. The result depends on default page format, page formats specified with setPageSize() calls as well as page formats defined in-line in CSS (page at-rule) or in HTML (<pd4ml:page.break> tag attribute).

Parameters:

pageNum - One-based indexed page number (the leading page is #1)

Returns:

page dimensions object

setPageMargins

public void setPageMargins(PageMargins margins)

defines page margins for all document pages

Parameters:

margins - page margins

setPageMargins

public void setPageMargins(PageMargins margins,
                           String scope)

defines page margins for specified range(s) of pages

Parameters:

margins - page margins

scope - scope of pages to apply the margins

getPageMargins

public PageMargins getPageMargins(int pageNum,
                                  boolean imageGeneration)

Returns page margins object for a specified page number. The result depends on default page margins, page margins specified with setPageMargins() calls as well as page formats defined in-line in CSS (page at-rule).

Parameters:

pageNum - One-based indexed page number (the leading page is #1)

imageGeneration - selects default margin settings. By imageGeneration=true by default there is no margins.

Returns:

page margins object

setHtmlWidth

public void setHtmlWidth(int width)
                  throws InvokeException

defines desired HTML page width in screen pixels. Virtually it can be seen as a web browser window horizontal resize.
In the resulting PDF the HTML width is mapped to the paper page width (minus insets). There is no way to specify HTML page height. The height in screen pixels is set automatically depending on the width and the paper page proportions.

Parameters:

width - HTML width in screen pixels

Throws:

InvokeException - when the width is not a positive value great that 0.

adjustHtmlWidth

public void adjustHtmlWidth(boolean adjust)

sets htmlWidth to the most right margin of the HTML block content. Calling the method would force PD4ML to build HTML layout with htmlWidth set by setHtmlWidth(int), to determine the most right edge of rendered content and to use the value for PDF mapping. Notes:

• The method takes no effect for multi-URL PD4ML call: render(URL[],OutputStream)
• In order to use the method efficiently, it is important to call setHtmlWidth(int) with a parameter value, which is greater than the expected right edge offset.
• If the source document has HTML objects, whose width is set to 100%, than the method call is meaningless.
• As long as htmlWidth affects HTML-to-PDF scale factor, usage of the method causes inconstancy of font/object sizes in the resulting PDF from document to document.

Parameters:

adjust - enables the adjustments

Since:

3.0.2

fitPageVertically

public void fitPageVertically(int align)

forces PD4ML to downscale entire HTML layout to fit a single PDF page vertically.

Parameters:

align - content alignment

See Also:

Constants.LEFT_ALIGN, Constants.CENTER_ALIGN, Constants.RIGHT_ALIGN

getFitPageVertically

public short getFitPageVertically()

Returns:

content alignment if fitPageVertically mode is on

setAuthorName

public final void setAuthorName(String name)

sets an author name for the document

Parameters:

name - author's name

Since:

v1.0.5

setDocumentTitle

public final void setDocumentTitle(String title)

forces to override HTML title

Parameters:

title - document title

Since:

v1.0.5

setInitialPageNumber

public void setInitialPageNumber(int initialPageNumber)

sets page number counter to given value. Impacts page numbering in document headers and footers.

Parameters:

initialPageNumber - page number of the first generated page

addStyle

public final void addStyle(URL stylesheet,
                           boolean overrideDocumentStyles)
                    throws InvokeException

Apply additional stylesheet to the document

Parameters:

stylesheet - of css stylesheet

overrideDocumentStyles - if true, applies the stylesheet after styles defined in the document header.

Throws:

InvokeException - too many styles added

Since:

v3.1.0 Pro

addStyle

public final void addStyle(String stylesheet,
                           boolean overrideDocumentStyles)
                    throws InvokeException

Apply additional stylesheet to the document

Parameters:

stylesheet - stylesheet content

overrideDocumentStyles - if true, applies the stylesheet after styles defined in the document header.

Throws:

InvokeException - too many styles added

Since:

v3.1.0 Pro

injectHtml

public void injectHtml(String htmlSnippet,
                       boolean prependBodyContent)

Injects a portion of HTML to the source

Parameters:

htmlSnippet - HTML code

prependBodyContent - if true, the HTML injected after opening <body> tag, otherwise right before closing </body> tag.

testTermination

public void testTermination()
                     throws ForcedTerminationException

Throws:

ForcedTerminationException - if terminated

getHeight

public int getHeight(int width)
              throws IOException

calculates document height for given document width. The method implicitly renders the page layout in idle mode. The call can be time/resource consuming for big documents.

Parameters:

width - desired withs in screen pixels

Returns:

calculated document height

Throws:

IOException - general IO exception

getDocumentTitle

public String getDocumentTitle()
                        throws InvokeException

Returns:

HTML document title

Throws:

InvokeException - if readHTML() is not invoked before

writePDF

public void writePDF(OutputStream os)
              throws IOException

renders and writes parsed HTML as PDF document

Parameters:

os - output stream to write PDF document bytes

Throws:

IOException - general IO exception

writePDF

public void writePDF(OutputStream os,
                     String pdfFormat)
              throws IOException

Parameters:

pdfFormat - Forces PD4ML to output either a regular PDF or a PDF format compliant with PDF/A specification. PDF/A specification requires all used fonts to be embedded to the resulting document. So the method call cannot guarantee the resulting doc is PDF/A, for example, if TTF embedding is disabled or not configured. To make sure a resulting document matches PDF/A requirements, request the last rendering status.

os - output stream to write generated PDF bytes

Throws:

IOException - general IO exception

See Also:

Constants.PD4ML_PDFA_STATUS, getLastRenderInfo(String)

writeRTF

public void writeRTF(OutputStream os,
                     boolean convertImagesToWMF)
              throws IOException

Parameters:

os - output stream to write generated RTF document bytes

convertImagesToWMF - converts images to bulky WMF format for compatibility with restricted RTF viewers

Throws:

IOException - general IO exception

setRenderingHints

public void setRenderingHints(Map hints)

Replaces the values of all preferences for the image rendering algorithms with the specified hints. The existing values for all rendering hints are discarded and the new set of known hints and values are initialized from the specified Map object. Hint categories include controls for rendering quality and overall time/quality trade-off in the rendering process. Refer to the java.awt.RenderingHints class for definitions of some common keys and values.

Parameters:

hints - the image rendering hints to be set

See Also:

RenderingHints

renderAsImages

public File renderAsImages(File dir,
                           String fileNamePrefix,
                           String format)
                    throws IOException

renders document as a set of image files, represent document pages

Parameters:

dir - target directory

fileNamePrefix - file name prefix for image files. The prefix is followed by page number and file extension, corresponds the requested image type.

format - image format

Returns:

first page image file

Throws:

IOException - general IO exception

See Also:

Constants.PNG24, Constants.PNG8, Constants.MULTIPAGE_TIFF, Constants.MULTIPAGE_TIFF_COMPRESSED, Constants.TIFF, Constants.TIFF_COMPRESSED

renderAsImages

public byte[][] renderAsImages(String format)
                        throws IOException

renders document in RAM as a set of images, represent document pages

Parameters:

format - image format

Returns:

a two-dimensional array of images

Throws:

IOException - general IO exception

See Also:

Constants.PNG24, Constants.PNG8, Constants.MULTIPAGE_TIFF, Constants.MULTIPAGE_TIFF_COMPRESSED, Constants.TIFF, Constants.TIFF_COMPRESSED

renderAsImages

public BufferedImage[] renderAsImages()
                               throws IOException

renders document in RAM as a set of images, represent document pages

Returns:

an array of buffered image objects

Throws:

IOException - general IO exception

dump

public String dump(int mode)
            throws IOException

debug/diagnostics method

Parameters:

mode - dump verbosity flags

Returns:

dump or parsed/normalized HTML structure

Throws:

IOException - general IO exception

protectPhysicalUnitDimensions

public void protectPhysicalUnitDimensions(boolean keepPhysicalUnitDimensions)

makes PD4ML to output PDF objects respecting dimensions/font sizes given in "in", "pt", "cm" etc. Use the method carefully: as long as it triggered, there is no single HTML-to-PDF scale factor for all HTML objects. The resulting PDF layout may appear visually corrupted. If the method is not triggered, all sizes given in physical measurement units are converted to their screen pixel equivalents (using 72dpi) before HTML layout. The method call can not be combined with adjustHtmlWidth() and fitPageVertically() calls, which affect HTML-to-PDF scale factor their own way.

Parameters:

keepPhysicalUnitDimensions - enable if true

Since:

v3.0.4, v4.0.9

translateToPt

public static final float translateToPt(float mm)

converts from millimeters to points

Parameters:

mm - value in millimeters

Returns:

converted value

predictScale

public static final float predictScale(PageMargins pageMargins,
                                       PageSize pageSize,
                                       int userSpace)

predicts document HTML-to-PDF mapping scale for given conversion parameters

Parameters:

pageMargins - page margins

pageSize - page size

userSpace - HTML width in screen pixels

Returns:

computed scale factor

predictPageHeight

public static final int predictPageHeight(PageMargins pageMargins,
                                          PageSize pageSize,
                                          int userSpace)

predicts page height for given conversion parameters

Parameters:

pageMargins - page margins

pageSize - page size

userSpace - HTML width in screen pixels

Returns:

computed page height in screen pixels

setDynamicData

public void setDynamicData(Map<String,String> map)

Parameters:

map - a set of key/value (String/String) pairs to dynamically substitute placeholders in HTML template (like "$[key]"). Key names "page", "total" and "title" are reserved for PDF headers and footers.

setParam

public void setParam(String key,
                     String value)

Sets parsing/rendering parameters

Parameters:

key - parameter name

value - parameter value

getLastRenderInfo

public Object getLastRenderInfo(String key)
                         throws ForcedTerminationException

returns statistics for the last render() call

Parameters:

key - - one of the currently supported keys: "pd4ml.document.height.px", "pd4ml.right.edge.px" or "pd4ml.total.pages".

Returns:

Long object (for the currently implemented keys; other types expected in the future)

Throws:

ForcedTerminationException - if terminate() invoked before

Since:

3.5.1

See Also:

Constants.PD4ML_DOCUMENT_HEIGHT_PX, Constants.PD4ML_RIGHT_EDGE_PX, Constants.PD4ML_TOTAL_PAGES

outputRange

public void outputRange(String description)

Parameters:

description - a string with output rules. Currently allows to limit a scope of generated pages. Examples: "2+" - skip the first page, "1-2" - output only the first and the second pages, "even" or "odd" - it is obvious. The rules may be combined: "3-7,odd"

Since:

v3.5.5

monitorProgressWith

public void monitorProgressWith(ProgressListener listener)

conversion progress callback support

Parameters:

listener - receiver of progress update messages

addMetadata

public void addMetadata(String key,
                        String value,
                        boolean hide)

The method defines custom properties for PDF document meta data. The method takes effect only with PD4ML DMS and PD4ML UA license types.

Parameters:

key - a unique name, which must not be one of the standard property names Title, Author, Subject, Keywords, Creator, Producer, CreationDate, ModDate and Trapped

value - data itself

hide - makes the metadata not appear in the PDF document properties dialog of Acroread

applyKerning

public void applyKerning(boolean enable)

Forces PD4ML to align font glyphs to each other according to the font kerning hints (if available). The API call takes effect only by PDF generation.

Parameters:

enable - - enables the feature

enableLigatures

public void enableLigatures(boolean enable)

Forces PD4ML to load TTF/OTF glyph susbstitution tables, to apply ligature replacements and to build compound glyphs. The feature requires pd4ml_fonttool.jar

Parameters:

enable - - enables the feature

getCache

public Object getCache()

Returns:

cache object to be reused by new PD4ML instances. The cache object is not reentrant, so a single instance cannot be used from multiple threads.

See Also:

setCache(Object)

setCache

public void setCache(Object fontCache)

Parameters:

fontCache - cache object returned by other PD4ML instance

See Also:

getCache()

asyncResourceLoader

public void asyncResourceLoader(int threadPoolSize)

enables asynchronous resource loading (graphics, attachments etc) if thread pool size is not equal 0. By default the asynchronous loader is disabled. As the loader spawns new threads, usage of it is discouraged in Java EE environment.

Parameters:

threadPoolSize - loader thread pool size. If the value is negative, it it does not limit the pool size: creates new threads as needed, but will reuse previously constructed threads when they are available.