com.princexml
Class Prince

Object
  com.princexml.Prince

public class Prince
extends Object

The main Prince class.

Constructor Summary

Prince(String exePath)
Constructor for Prince.

Prince(String exePath, PrinceEvents events)
Constructor for Prince.

Method Summary

void	addScript(String jsPath) Add a JavaScript script that will be executed before conversion.
void	addStyleSheet(String cssPath) Add a CSS style sheet that will be applied to each document.
void	clearScripts() Clear all of the JavaScript scripts.
void	clearStyleSheets() Clear all of the CSS style sheets.
boolean	convert(InputStream xmlInput, OutputStream pdfOutput) Convert an XML or HTML file to a PDF file.
boolean	convert(String xmlPath) Convert an XML or HTML file to a PDF file.
boolean	convert(String xmlPath, OutputStream pdfOutput) Convert an XML or HTML file to a PDF file.
boolean	convert(String xmlPath, String pdfPath) Convert an XML or HTML file to a PDF file.
boolean	convertMultiple(List xmlPaths, String pdfPath) Convert multiple XML or HTML files to a PDF file.
void	setBaseURL(String baseurl) Specify the base URL of the input document.
void	setCompress(boolean compress) Specify whether compression should be applied to the output PDF file.
void	setDebug(boolean debug) Enable logging of debug messages.
void	setEmbedFonts(boolean embedFonts) Specify whether fonts should be embedded in the output PDF file.
void	setEncrypt(boolean encrypt) Specify whether encryption should be applied to the output PDF file.
void	setEncryptInfo(int keyBits, String userPassword, String ownerPassword, boolean disallowPrint, boolean disallowModify, boolean disallowCopy, boolean disallowAnnotate) Set the parameters used for PDF encryption.
void	setFileRoot(String fileRoot) Specify the root directory for absolute filenames.
void	setHTML(boolean html) Specify whether documents should be parsed as HTML or XML/XHTML.
void	setHttpPassword(String password) Specify the password for HTTP basic authentication.
void	setHttpProxy(String proxy) Specify the URL for the HTTP proxy server, if needed.
void	setHttpUsername(String username) Specify the username for HTTP basic authentication.
void	setInputType(String inputType) Specify whether documents should be parsed as HTML or XML/XHTML.
void	setJavaScript(boolean javascript) Specify whether JavaScript scripts found in the document should be executed during document conversion.
void	setLog(String logfile) Specify a file that Prince should use to log error/warning messages.
void	setNetwork(boolean network) Specify whether network access is allowed for downloading HTTP resources.
void	setSubsetFonts(boolean subsetFonts) Specify whether embedded fonts should be subset to only include the glyphs that are actually used in the PDF file.
void	setVerbose(boolean verbose) Enable verbose logging of informative messages.
void	setXInclude(boolean xinclude) Specify whether XML Inclusions (XInclude) processing should be applied to input documents.

Methods inherited from class Object

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

Constructor Detail

Prince

public Prince(String exePath)

Constructor for Prince.

Parameters:

exePath - The path of the Prince executable. (For example, this may be C:\Program Files\Prince\engine\bin\prince.exe on Windows or /usr/bin/prince on Linux).

Prince

public Prince(String exePath,
              PrinceEvents events)

Constructor for Prince.

Parameters:

exePath - The path of the Prince executable. (For example, this may be C:\Program Files\Prince\engine\bin\prince.exe on Windows or /usr/bin/prince on Linux).

events - An instance of the PrinceEvents interface that will receive error/warning messages returned from Prince.

Method Detail

addStyleSheet

public void addStyleSheet(String cssPath)

Add a CSS style sheet that will be applied to each document.

Parameters:

cssPath - The filename of the CSS style sheet.

clearStyleSheets

public void clearStyleSheets()

Clear all of the CSS style sheets.

addScript

public void addScript(String jsPath)

Add a JavaScript script that will be executed before conversion.

Parameters:

jsPath - The filename of the JavaScript script.

clearScripts

public void clearScripts()

Clear all of the JavaScript scripts.

setHTML

public void setHTML(boolean html)

Specify whether documents should be parsed as HTML or XML/XHTML. By default, all documents will be parsed as XML/XHTML, unless they have a filename extension of ".html" or ".htm" and appear to contain HTML rather than XML or XHTML. This method provides a way to override this autodetection and insist that all documents should be parsed as HTML.

This is also necessary if a HTML document is passed to Prince from an InputStream, as this has no filename and hence Prince will not check the extension and will always treat it as XML/XHTML unless this method has been called.

Parameters:

html - True if all documents should be treated as HTML, false otherwise.

setInputType

public void setInputType(String inputType)

Specify whether documents should be parsed as HTML or XML/XHTML. By default, all documents will be parsed as XML/XHTML, unless they have a filename extension of ".html" or ".htm" and appear to contain HTML rather than XML or XHTML. This method provides a way to override this autodetection and insist that all documents should be parsed as HTML or XML.

This is also necessary if a HTML document is passed to Prince from an InputStream, as this has no filename and hence Prince will not check the extension and will always treat it as XML/XHTML unless this method has been called.

Parameters:

inputType - "auto", "html", or "xml"

setLog

public void setLog(String logfile)

Specify a file that Prince should use to log error/warning messages. If this method if not called or if null is specified as the filename then Prince will not write to any log. This method does not affect the operation of the PrinceEvents interface, which will also receive error/warning messages from Prince.

Parameters:

logfile - The filename that Prince should use to log error/warning messages, or null to disable logging.

setVerbose

public void setVerbose(boolean verbose)

Enable verbose logging of informative messages.

Parameters:

verbose - True to enable verbose logging.

setDebug

public void setDebug(boolean debug)

Enable logging of debug messages.

Parameters:

debug - True to enable debug logging.

setBaseURL

public void setBaseURL(String baseurl)

Specify the base URL of the input document. This can be used to override the path of the input document, which is convenient when processing local copies of a document from a website. It is also helpful for specifying a base URL for documents that are provided via an InputStream, as these documents have no natural base URL.

Parameters:

baseurl - The base URL or path of the input document.

setFileRoot

public void setFileRoot(String fileRoot)

Specify the root directory for absolute filenames. This can be used when converting a local file that uses absolute paths to refer to web resources. For example, /images/logo.jpg can be rewritten to /usr/share/images/logo.jpg by specifying "/usr/share" as the root.

Parameters:

fileRoot - The path to prepend to absolute filenames.

setJavaScript

public void setJavaScript(boolean javascript)

Specify whether JavaScript scripts found in the document should be executed during document conversion. Scripts will not be executed by default unless explicitly enabled.

Parameters:

javascript - True to enable JavaScript script execution.

setXInclude

public void setXInclude(boolean xinclude)

Specify whether XML Inclusions (XInclude) processing should be applied to input documents. XInclude processing will be performed by default unless explicitly disabled.

Parameters:

xinclude - False to disable XInclude processing.

setNetwork

public void setNetwork(boolean network)

Specify whether network access is allowed for downloading HTTP resources. Network access is allowed by default unless explicitly disabled.

Parameters:

network - False to disable network access.

setHttpUsername

public void setHttpUsername(String username)

Specify the username for HTTP basic authentication.

Parameters:

username - The username for HTTP basic authentication.

setHttpPassword

public void setHttpPassword(String password)

Specify the password for HTTP basic authentication.

Parameters:

password - The password for HTTP basic authentication.

setHttpProxy

public void setHttpProxy(String proxy)

Specify the URL for the HTTP proxy server, if needed.

Parameters:

proxy - The URL for the HTTP proxy server.

setEmbedFonts

public void setEmbedFonts(boolean embedFonts)

Specify whether fonts should be embedded in the output PDF file. Fonts will be embedded by default unless explicitly disabled.

Parameters:

embedFonts - False to disable PDF font embedding.

setSubsetFonts

public void setSubsetFonts(boolean subsetFonts)

Specify whether embedded fonts should be subset to only include the glyphs that are actually used in the PDF file. Embedded fonts will be subset by default unless this is explicitly disabled.

Parameters:

subsetFonts - False to disable subsetting of embedded fonts.

setCompress

public void setCompress(boolean compress)

Specify whether compression should be applied to the output PDF file. Compression will be applied by default unless explicitly disabled.

Parameters:

compress - False to disable PDF compression.

setEncrypt

public void setEncrypt(boolean encrypt)

Specify whether encryption should be applied to the output PDF file. Encryption will not be applied by default unless explicitly enabled.

Parameters:

encrypt - True to enable PDF encryption.

setEncryptInfo

public void setEncryptInfo(int keyBits,
                           String userPassword,
                           String ownerPassword,
                           boolean disallowPrint,
                           boolean disallowModify,
                           boolean disallowCopy,
                           boolean disallowAnnotate)

Set the parameters used for PDF encryption. Calling this method will also enable PDF encryption, equivalent to calling setEncrypt(true).

Parameters:

keyBits - The size of the encryption key in bits (must be 40 or 128).

userPassword - The user password for the encrypted PDF file.

ownerPassword - The owner password for the encrypted PDF file.

disallowPrint - True to disallow printing of the encrypted PDF file.

disallowModify - True to disallow modification of the encrypted PDF file.

disallowCopy - True to disallow copying from the encrypted PDF file.

disallowAnnotate - True to disallow annotation of the encrypted PDF file.

Throws:

IllegalArgumentException - if keyBits is not 40 or 128.

convert

public boolean convert(String xmlPath)
                throws IOException

Convert an XML or HTML file to a PDF file. The name of the output PDF file will be the same as the name of the input file but with an extension of ".pdf".

Parameters:

xmlPath - The filename of the input XML or HTML document.

Returns:

True if a PDF file was generated successfully.

Throws:

IOException

convert

public boolean convert(String xmlPath,
                       String pdfPath)
                throws IOException

Convert an XML or HTML file to a PDF file.

Parameters:

xmlPath - The filename of the input XML or HTML document.

pdfPath - The filename of the output PDF file.

Returns:

True if a PDF file was generated successfully.

Throws:

IOException

convertMultiple

public boolean convertMultiple(List xmlPaths,
                               String pdfPath)
                        throws IOException

Convert multiple XML or HTML files to a PDF file.

Parameters:

xmlPaths - The filenames of the input XML or HTML documents.

pdfPath - The filename of the output PDF file.

Returns:

True if a PDF file was generated successfully.

Throws:

IOException

convert

public boolean convert(String xmlPath,
                       OutputStream pdfOutput)
                throws IOException

Convert an XML or HTML file to a PDF file. This method is useful for servlets as it allows Prince to write the PDF output directly to the OutputStream of the servlet response.

Note that no error/warning messages will be returned via the PrinceEvents interface when calling this method. This is due to a limitation of Prince that will be fixed in a future release. In the meantime, we recommend the use of the setLog() method to specify a log file that can be used to view error/warning messages from Prince.

Parameters:

xmlPath - The filename of the input XML or HTML document.

pdfOutput - The OutputStream to which Prince will write the PDF output.

Returns:

True if a PDF file was generated successfully.

Throws:

IOException

convert

public boolean convert(InputStream xmlInput,
                       OutputStream pdfOutput)
                throws IOException

Convert an XML or HTML file to a PDF file. This method is useful for servlets as it allows Prince to write the PDF output directly to the OutputStream of the servlet response.

Note that it may be helpful to specify a base URL or path for the input document using the setBaseURL() method. This allows relative URLs and paths in the document (eg. for images) to be resolved correctly.

Note that no error/warning messages will be returned via the PrinceEvents interface when calling this method. This is due to a limitation of Prince that will be fixed in a future release. In the meantime, we recommend the use of the setLog() method to specify a log file that can be used to view error/warning messages from Prince.

Parameters:

xmlInput - The InputStream from which Prince will read the XML or HTML document.

pdfOutput - The OutputStream to which Prince will write the PDF output.

Returns:

True if a PDF file was generated successfully.

Throws:

IOException