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	addStyleSheet(String cssPath) Add a CSS style sheet that will be applied to each document.
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, String pdfPath) Convert an XML or HTML file 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	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	setHTML(boolean html) Specify whether documents should be parsed as HTML or XML/XHTML.
void	setLog(String logfile) Specify a file that Prince should use to log error/warning 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.

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.

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.

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.

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.

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.

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 disabled 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

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