ITT.WAFr.Utilities
Class PdfFile

java.lang.Object
  ITT.WAFr.Utilities.PdfFile

public final class PdfFile

extends Object

The PdfFile class represents a stream in Adobe's Portable Document Format (PDF).

This class can be used to generate an output stream in PDF from any input stream representing a well-formed HTML document.

The input source of the PDF document can be a URL object, String representing the address of a Web page, or any valid InputStream object.

Do not use buffered streams, as the PdfFile class will buffer both the input and output streams automatically.

In addition, a base URL object, or String representing a base location, can be passed to enable relative links for resources within the source HTML. Local file system URLs (file:///) are permitted as well.

The Create() method will interpret and rendered the input HTML source within a virtual browser at an auto-adjusting or specified explicit width. See the BrowserWidth(double,int) method description for details. Upon rendering, the resulting PDF page will be scaled to fit within the default or specified document size, taking the default or set document margins into account.

The Create() method should be called last following all parameter setting methods. Once called, subsequent calls to the Create() method will throw an exception and calls to all other methods will be ignored. A valid OutputStream object, representing a destination file or any other sub class, must be passed. Again, this stream should not be buffered.

Upon success or failure, the output stream, and any applicable input stream, will be closed automatically.

Nested Class Summary

class	PdfFile.BrowserWidthException This exception is thrown when the virtual browser render pixel width is not specified as a positive integer.
class	PdfFile.DocumentSizeException This exception is thrown when the specified document width or height, upon subtracting margins, is less than zero (0) units.
class	PdfFile.MarginsException This exception is thrown when the specified document margins are less than zero (0) units.
class	PdfFile.PageExhaustedException This exception is thrown when the specified HTML input source has already been processed and resources have been released.
class	PdfFile.ParsingException This exception is thrown when the specified HTML input source could not be successfully parsed.
static interface	PdfFile.PdfDocumentSize The PdfDocumentSize interface contains the well-known standard document sizes.
class	PdfFile.TimeoutException This exception is thrown when the specified HTML input source does not process in the timeout period allotted.
class	PdfFile.UrlException This exception is thrown when a specified Internet address fails to convert to a valid URL.

Field Summary

static boolean	AcrobatFonts Field representing if the PDF document supports embedded Adobe Acrobat fonts only.
static int	Centimeters Field representing measurement in units of centimeters.
static int	cm Field representing measurement in units of cm or centimeters.
static boolean	CustomFonts Field representing if the PDF document supports custom fonts local to the viewer.
static int	FitToPage Field representing if the virtual browser render width should adjust to fit entire Web page width.
static int	in Field representing measurement in units of in or inches.
static int	Inches Field representing measurement in units of inches.
static boolean	Landscape Field representing a page orientation of landscape.
static int	Millimeters Field representing measurement in units of millimeters.
static int	mm Field representing measurement in units of mm or millimeters.
static int	Pixels Field representing measurement in units of pixels.
static boolean	Portrait Field representing a page orientation of portrait.
static int	px Field representing measurement in units of px or pixels.

Constructor Summary

PdfFile()
Constructs a new PdfFile object.

Method Summary

void	BrowserWidth(double fWidth, int iUnits) Sets the virtual browser render width for the source HTML using the specified width and unit of measure.
void	BrowserWidth(int iWidth) Sets the virtual browser render width for the source HTML to the specified number of pixels.
void	Create(InputStream oInput, OutputStream oOutput) Creates an output stream representing a PDF document for the HTML page passed as an input stream.
void	Create(InputStream oInput, OutputStream oOutput, String sUrl) Creates an output stream representing a PDF document for the HTML page passed as an input stream with a base URL of the specified string.
void	Create(InputStream oInput, OutputStream oOutput, URL oUrl) Creates an output stream representing a PDF document for the HTML page passed as an input stream with specified base URL.
void	Create(String sUrl, OutputStream oOutput) Creates an output stream representing a PDF document for the HTML page at the string specifying a URL location.
void	Create(URL oUrl, OutputStream oOutput) Creates an output stream representing a PDF document for the HTML page at the specifed URL.
void	DocumentMargins(double fTop, double fLeft, double fBottom, double fRight, int iUnits) Sets the output PDF document margins to the parameters in a specified unit of measure.
void	DocumentMargins(Insets oInsets) Sets the output PDF document margins to the pixel insets specified.
void	DocumentMargins(Insets oInsets, int iUnits) Sets the output PDF document margins to the insets specified in any unit of measure.
void	DocumentMargins(int iTop, int iLeft, int iBottom, int iRight) Sets the output PDF document margins to the pixel insets specified.
void	DocumentSize(Dimension oDimensions) Sets the output PDF document size to the dimension in pixels.
void	DocumentSize(Dimension oDimensions, int iUnits) Sets the output PDF document size to the dimension specified in any unit of measure.
void	DocumentSize(double fWidth, double fHeight, int iUnits) Sets the output PDF document size to the width and height in the specified unit of measure.
void	DocumentSize(int iWidth, int iHeight) Sets the output PDF document size to the specified width and height in pixels.
void	FontSupport(boolean bFontSupport) Sets the indicator enabling the PDF to attempt use of all custom fonts used within the source HTML.
void	ImageSplitting(boolean bAllow) Sets the parameter indicating if the PDF document will split images at page breaks.
void	PageOrientation(boolean bOrientation) Sets the page orientation of the PDF document.
void	TextSplitting(boolean bAllow) Sets the parameter indicating if the PDF document will divide text characters vertically at page breaks.
void	Timeout(int iSeconds) Sets the timeout in seconds for the Create() method's input source HTML processing.

Methods inherited from class java.lang.Object

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

Field Detail

AcrobatFonts

public static final boolean AcrobatFonts

Field representing if the PDF document supports embedded Adobe Acrobat fonts only.

See Also:

Constant Field Values

Centimeters

public static final int Centimeters

Field representing measurement in units of centimeters.

See Also:

Constant Field Values

cm

public static final int cm

Field representing measurement in units of cm or centimeters.

See Also:

Constant Field Values

CustomFonts

public static final boolean CustomFonts

Field representing if the PDF document supports custom fonts local to the viewer.

See Also:

Constant Field Values

FitToPage

public static final int FitToPage

Field representing if the virtual browser render width should adjust to fit entire Web page width.

See Also:

Constant Field Values

in

public static final int in

Field representing measurement in units of in or inches.

See Also:

Constant Field Values

Inches

public static final int Inches

Field representing measurement in units of inches.

See Also:

Constant Field Values

Landscape

public static final boolean Landscape

Field representing a page orientation of landscape.

See Also:

Constant Field Values

Millimeters

public static final int Millimeters

Field representing measurement in units of millimeters.

See Also:

Constant Field Values

mm

public static final int mm

Field representing measurement in units of mm or millimeters.

See Also:

Constant Field Values

Pixels

public static final int Pixels

Field representing measurement in units of pixels.

See Also:

Constant Field Values

Portrait

public static final boolean Portrait

Field representing a page orientation of portrait.

See Also:

Constant Field Values

px

public static final int px

Field representing measurement in units of px or pixels.

See Also:

Constant Field Values

Constructor Detail

PdfFile

public PdfFile()

Constructs a new PdfFile object.

Method Detail

BrowserWidth

public void BrowserWidth(double fWidth,
                         int iUnits)

Sets the virtual browser render width for the source HTML using the specified width and unit of measure.

The PdfFile class must first interpret the input source HTML as does any Web browser. And like other browsers, you can decide the width. In a Web browser you simply resize the physical window. This method will simulate sizing of a physical Web browser window.

The behavior is exactly that of any Web browser. If the render width entered is greater than the layout of the source HTML, white space on one or both sides will be visible. If the width is less than the width of the HTML input, the rendered PDF will be cropped, as if viewing in a Web browser window too narrow to accommodate a Web page.

Any decimal numeric value can be specified for the width in either Inches, Centimeters, Millimeters, or Pixels.

Use the field value of FitToPage to dynamically set the width of the virtual browser to the required width of the input HTML source. This setting ignores the unit of measure.

FitToPage is the default value.

Parameters:

fWidth - a double specifying the width in which the virtual browser will render.

iUnits - a field value representing a unit of measure.

See Also:

BrowserWidth(int)

BrowserWidth

public void BrowserWidth(int iWidth)

Sets the virtual browser render width for the source HTML to the specified number of pixels.

See the BrowserWidth(double,int) method for description.

Parameters:

iWidth - an integer specifying the number of pixels in which the virtual browser will render.

See Also:

BrowserWidth(double,int)

Create

public void Create(InputStream oInput,
                   OutputStream oOutput)
            throws IOException,
                   PdfFile.UrlException,
                   PdfFile.BrowserWidthException,
                   PdfFile.MarginsException,
                   PdfFile.DocumentSizeException,
                   PdfFile.ParsingException,
                   PdfFile.TimeoutException,
                   PdfFile.PageExhaustedException

Creates an output stream representing a PDF document for the HTML page passed as an input stream.

This method does not support a base URL for relative linked resources. All resources must contain absolute paths to properly render.

The specified input and output stream should not be buffered as the PdfFile class handles buffering internally.

This method will close both the input and output streams regardless of success.

Parameters:

oInput - an input stream containing the HTML source to be converted.

oOutput - the destination output stream.

Throws:

IOException - if the output stream can not be written to.

PdfFile.UrlException - if the specified URL is not valid.

PdfFile.BrowserWidthException - if the virtual browser width is invalid.

PdfFile.MarginsException - if the document margins are invalid.

PdfFile.DocumentSizeException - if the document size is invalid.

PdfFile.ParsingException - if the HTML source fails to parse.

PdfFile.TimeoutException - if the HTML source fails to render in the specified timeout period.

PdfFile.PageExhaustedException - if the PDF document has already been rendered.

Create

public void Create(InputStream oInput,
                   OutputStream oOutput,
                   String sUrl)
            throws IOException,
                   PdfFile.UrlException,
                   PdfFile.BrowserWidthException,
                   PdfFile.MarginsException,
                   PdfFile.DocumentSizeException,
                   PdfFile.ParsingException,
                   PdfFile.TimeoutException,
                   PdfFile.PageExhaustedException

Creates an output stream representing a PDF document for the HTML page passed as an input stream with a base URL of the specified string.

The specified input and output stream should not be buffered as the PdfFile class handles buffering internally.

This method will close both the input and output streams regardless of success.

Parameters:

oInput - an input stream containing the HTML source to be converted.

oOutput - the destination output stream.

sUrl - representing the the base URL to be used for relative linked resources.

Throws:

IOException - if the output stream can not be written to.

PdfFile.UrlException - if the specified URL is not valid.

PdfFile.BrowserWidthException - if the virtual browser width is invalid.

PdfFile.MarginsException - if the document margins are invalid.

PdfFile.DocumentSizeException - if the document size is invalid.

PdfFile.ParsingException - if the HTML source fails to parse.

PdfFile.TimeoutException - if the HTML source fails to render in the specified timeout period.

PdfFile.PageExhaustedException - if the PDF document has already been rendered.

Create

public void Create(InputStream oInput,
                   OutputStream oOutput,
                   URL oUrl)
            throws IOException,
                   PdfFile.UrlException,
                   PdfFile.BrowserWidthException,
                   PdfFile.MarginsException,
                   PdfFile.DocumentSizeException,
                   PdfFile.ParsingException,
                   PdfFile.TimeoutException,
                   PdfFile.PageExhaustedException

Creates an output stream representing a PDF document for the HTML page passed as an input stream with specified base URL.

The specified input and output stream should not be buffered as the PdfFile class handles buffering internally.

This method will close both the input and output streams regardless of success.

Parameters:

oInput - an input stream containing the HTML source to be converted.

oOutput - the destination output stream.

oUrl - a URL specifying the base URL to be used for relative linked resources.

Throws:

IOException - if the output stream can not be written to.

PdfFile.UrlException - if the specified URL is not valid.

PdfFile.BrowserWidthException - if the virtual browser width is invalid.

PdfFile.MarginsException - if the document margins are invalid.

PdfFile.DocumentSizeException - if the document size is invalid.

PdfFile.ParsingException - if the HTML source fails to parse.

PdfFile.TimeoutException - if the HTML source fails to render in the specified timeout period.

PdfFile.PageExhaustedException - if the PDF document has already been rendered.

Create

public void Create(String sUrl,
                   OutputStream oOutput)
            throws IOException,
                   PdfFile.UrlException,
                   PdfFile.BrowserWidthException,
                   PdfFile.MarginsException,
                   PdfFile.DocumentSizeException,
                   PdfFile.ParsingException,
                   PdfFile.TimeoutException,
                   PdfFile.PageExhaustedException

Creates an output stream representing a PDF document for the HTML page at the string specifying a URL location.

The specified output stream should not be buffered as the PdfFile class handles buffering internally.

This method will close the output stream regardless of success.

Parameters:

sUrl - a string representing the URL of the HTML input source.

oOutput - the destination output stream.

Throws:

IOException - if the output stream can not be written to.

PdfFile.UrlException - if the specified URL is not valid.

PdfFile.BrowserWidthException - if the virtual browser width is invalid.

PdfFile.MarginsException - if the document margins are invalid.

PdfFile.DocumentSizeException - if the document size is invalid.

PdfFile.ParsingException - if the HTML source fails to parse.

PdfFile.TimeoutException - if the HTML source fails to render in the specified timeout period.

PdfFile.PageExhaustedException - if the PDF document has already been rendered.

Create

public void Create(URL oUrl,
                   OutputStream oOutput)
            throws IOException,
                   PdfFile.UrlException,
                   PdfFile.BrowserWidthException,
                   PdfFile.MarginsException,
                   PdfFile.DocumentSizeException,
                   PdfFile.ParsingException,
                   PdfFile.TimeoutException,
                   PdfFile.PageExhaustedException

Creates an output stream representing a PDF document for the HTML page at the specifed URL.

The specified output stream should not be buffered as the PdfFile class handles buffering internally.

This method will close the output stream regardless of success.

Parameters:

oUrl - a URL specifying the HTML input source.

oOutput - the destination output stream.

Throws:

IOException - if the output stream can not be written to.

PdfFile.UrlException - if the specified URL is not valid.

PdfFile.BrowserWidthException - if the virtual browser width is invalid.

PdfFile.MarginsException - if the document margins are invalid.

PdfFile.DocumentSizeException - if the document size is invalid.

PdfFile.ParsingException - if the HTML source fails to parse.

PdfFile.TimeoutException - if the HTML source fails to render in the specified timeout period.

PdfFile.PageExhaustedException - if the PDF document has already been rendered.

DocumentMargins

public void DocumentMargins(double fTop,
                            double fLeft,
                            double fBottom,
                            double fRight,
                            int iUnits)

Sets the output PDF document margins to the parameters in a specified unit of measure.

Any decimal numeric value can be specified for the individual margins in either Inches, Centimeters, Millimeters, or Pixels.

The default margins are:

Top: .50 inches
Left: .25 inches
Bottom: .25 inches
Right: .25 inches

Parameters:

fTop - a double representing the top margin of the output PDF.

fLeft - a double representing the left margin of the output PDF.

fBottom - a double representing the bottom margin of the output PDF.

fRight - a double representing the right margin of the output PDF.

iUnits - a field value representing a unit of measure.

See Also:

DocumentMargins(Insets), DocumentMargins(int,int,int,int)

DocumentMargins

public void DocumentMargins(Insets oInsets)

Sets the output PDF document margins to the pixel insets specified.

Parameters:

oInsets - an Insets object representing the top, left, bottom, and right margins of the output PDF in pixels.

See Also:

DocumentMargins(double,double,double,double,int), DocumentMargins(int,int,int,int)

DocumentMargins

public void DocumentMargins(Insets oInsets,
                            int iUnits)

Sets the output PDF document margins to the insets specified in any unit of measure.

An Insets object representing the top, left, bottom, and right margins in either Inches, Centimeters, Millimeters, or Pixels can be specified as the document margins.

Parameters:

oInsets - an Insets object representing the top, left, bottom, and right margins of the output PDF.

iUnits - a field value representing a unit of measure.

See Also:

DocumentMargins(double,double,double,double,int), DocumentMargins(int,int,int,int)

DocumentMargins

public void DocumentMargins(int iTop,
                            int iLeft,
                            int iBottom,
                            int iRight)

Sets the output PDF document margins to the pixel insets specified.

Parameters:

iTop - an integer representing the top margin of the output PDF in pixels.

iLeft - an integer representing the left margin of the output PDF in pixels.

iBottom - an integer representing the bottom margin of the output PDF in pixels.

iRight - an integer representing the right margin of the output PDF in pixels.

See Also:

DocumentMargins(double,double,double,double,int), DocumentMargins(Insets)

DocumentSize

public void DocumentSize(Dimension oDimensions)

Sets the output PDF document size to the dimension in pixels.

This method is most convenient for using the standard pre-defined field value document sizes from the PdfFile.PdfDocumentSize interface, although any pixel dimension can be specified.

The default value is the field PdfFile.PdfDocumentSize.Letter, which is 8.5 x 11 inches.

Parameters:

oDimensions - a Dimension object representing the pixel width and height of the output PDF.

DocumentSize

public void DocumentSize(Dimension oDimensions,
                         int iUnits)

Sets the output PDF document size to the dimension specified in any unit of measure.

A Dimension object representing the width and height in either Inches, Centimeters, Millimeters, or Pixels can be specified as the document size.

Parameters:

oDimensions - a Dimension object representing the width and height of the output PDF.

iUnits - a field value representing a unit of measure.

See Also:

DocumentSize(Dimension)

DocumentSize

public void DocumentSize(double fWidth,
                         double fHeight,
                         int iUnits)

Sets the output PDF document size to the width and height in the specified unit of measure.

Any decimal numeric value can be specified for the width and height in either Inches, Centimeters, Millimeters, or Pixels.

Parameters:

fWidth - a double representing the width of the output PDF.

fHeight - a double representing the height of the output PDF.

iUnits - a field value representing a unit of measure.

See Also:

DocumentSize(Dimension)

DocumentSize

public void DocumentSize(int iWidth,
                         int iHeight)

Sets the output PDF document size to the specified width and height in pixels.

Parameters:

iWidth - an integer representing the pixel width of the output PDF.

iHeight - an integer representing the pixel height of the output PDF.

See Also:

DocumentSize(Dimension)

FontSupport

public void FontSupport(boolean bFontSupport)

Sets the indicator enabling the PDF to attempt use of all custom fonts used within the source HTML.

NOTE: If this parameter is set to the field value of CustomFonts, Adobe Acrobat Reader will popup an informational dialog box specifying that any custom font being used does not contain a valid BBox. This is because the PdfFile class cannot generate dynamic font descriptors for fonts within the HTML source document. It is recommended that this method not be used.

To prevent this dialog, use the field value AcrobatFonts which substitutes all fonts to one of the 14 embedded Adobe Acrobat fonts.

The field value AcrobatFonts is the default setting.

Parameters:

bFontSupport - AcrobatFonts for embedded fonts only, CustomFonts for any utilized fonts.

ImageSplitting

public void ImageSplitting(boolean bAllow)

Sets the parameter indicating if the PDF document will split images at page breaks.

A setting of true will allow images to be split and span pages.

If the image is greater in height than the page height, the image will split regardless of this setting.

This setting is the true by default.

Parameters:

bAllow - true to enable, false to prohibit image splitting.

PageOrientation

public void PageOrientation(boolean bOrientation)

Sets the page orientation of the PDF document.

This setting is the field value of Portrait by default.

Parameters:

bOrientation - a field value of Portrait or Landscape.

TextSplitting

public void TextSplitting(boolean bAllow)

Sets the parameter indicating if the PDF document will divide text characters vertically at page breaks.

A setting of true will allow text characters to be split and span pages.

This setting is the false by default.

Parameters:

bAllow - true to enable, false to prohibit text splitting.

Timeout

public void Timeout(int iSeconds)

Sets the timeout in seconds for the Create() method's input source HTML processing.

A setting of zero (0) or less will result in no timeout, or process until completion.

The default is 60 seconds.

Parameters:

iSeconds - an integer specifying the timeout in seconds.