org.apache.fop.pdf

Class PDFDocument

java.lang.Object

org.apache.fop.pdf.PDFDocument

public class PDFDocument
extends Object

Class representing a PDF document. The document is built up by calling various methods and then finally output to given filehandle using output method. A PDF document consists of a series of numbered objects preceded by a header and followed by an xref table and trailer. The xref table allows for quick access to objects by listing their character positions within the document. For this reason the PDF document must keep track of the character position of each object. The document also keeps direct track of the /Root, /Info and /Resources objects. Modified by Mark Lillywhite, mark-fop@inomial.com. The changes involve: ability to output pages one-at-a-time in a streaming fashion (rather than storing them all for output at the end); ability to write the /Pages object after writing the rest of the document; ability to write to a stream and flush the object list; enhanced trailer output; cleanups.

Field Summary

Fields

Modifier and Type	Field and Description
static String	ENCODING the encoding to use when converting strings to PDF commands
protected int	gStateObjectCount
protected List<Long>	indirectObjectOffsets the character position of each object
protected int	objectcount the counter for object numbering
protected List<PDFObject>	objects the objects themselves
protected boolean	outputStarted
protected List<PDFPage>	pageObjs
protected long	position the current character position
protected List<PDFStructElem>	structureTreeElements
protected List<PDFObject>	trailerObjects List of objects to write in the trailer

Constructor Summary

Constructors

Constructor and Description
PDFDocument(String prod) Creates an empty PDF document.
PDFDocument(String prod, VersionController versionController) Creates an empty PDF document.

Method Summary

Methods

Modifier and Type	Method and Description
void	addDestination(PDFDestination destination) Adds a destination to the document.
PDFFormXObject	addFormXObject(PDFResourceContext res, PDFStream cont, PDFReference formres, String key) Add a form XObject to the PDF document.
PDFImageXObject	addImage(PDFResourceContext res, PDFImage img) Add an image to the PDF document.
void	addObject(PDFObject obj) Adds a PDFObject to this document.
void	addTrailerObject(PDFObject obj) Add trailer object.
void	applyEncryption(AbstractPDFStream stream) Apply the encryption filter to a PDFStream if encryption is enabled.
void	assignObjectNumber(PDFObject obj) Assigns the PDFObject an object number, and sets the parent of the PDFObject to this document.
void	enableAccessibility(boolean enableAccessibility)
static byte[]	encode(String text) Converts text to a byte array for writing to a PDF file.
protected PDFDestination	findDestination(PDFDestination compare) Finds a named destination.
protected PDFFileSpec	findFileSpec(PDFFileSpec compare) Finds a file spec.
protected PDFFont	findFont(String fontname) Finds a font.
protected PDFFunction	findFunction(PDFFunction compare) Looks through the registered functions to see if one that is equal to a reference object exists
protected PDFGoTo	findGoTo(PDFGoTo compare) Finds a goto.
protected PDFGoToRemote	findGoToRemote(PDFGoToRemote compare) Finds a goto remote.
protected PDFGState	findGState(PDFGState wanted, PDFGState current) Looks for an existing GState to use
protected PDFLaunch	findLaunch(PDFLaunch compare) Finds a launch.
protected PDFLink	findLink(PDFLink compare) Finds a link.
protected PDFPattern	findPattern(PDFPattern compare) Find a previous pattern.
protected PDFShading	findShading(PDFShading compare) Looks through the registered shadings to see if one that is equal to a reference object exists
static void	flushTextBuffer(StringBuilder textBuffer, OutputStream out) Flushes the given text buffer to an output stream with the right encoding and resets the text buffer.
int	getColorSpace() Returns the color space.
List<PDFDestination>	getDestinationList() Gets the list of named destinations.
PDFEncryption	getEncryption() Returns the active Encryption object.
PDFFactory	getFactory() Returns the factory for PDF objects.
Map<String,List<String>>	getFilterMap() Returns the PDFFilters map used for filters in this document.
Map<String,PDFFont>	getFontMap() Returns the font map for this document.
PDFImageXObject	getImage(String key) Deprecated. Use getXObject instead (so forms are treated in the same way)
PDFInfo	getInfo() Get the PDFInfo object for this document.
PDFOutline	getOutlineRoot() Get the root Outlines object.
PDFPages	getPages() Returns the PDFPages object associated with the root object.
PDFDeviceColorSpace	getPDFColorSpace() Returns the PDF color space object.
Version	getPDFVersion() Returns the current PDF version.
String	getPDFVersionString()
PDFProfile	getProfile()
PDFResources	getResources() Get the /Resources object for the document
PDFRoot	getRoot() Get the PDFRoot object for this document.
List<PDFStructElem>	getStructureTreeElements() Get the Structural Tree Collection for this document
PDFXObject	getXObject(String key) Get an XObject from the image map.
boolean	hasDestinations() Gets whether the document has named destinations.
boolean	isEncryptionActive() Indicates whether encryption is active for this PDF or not.
boolean	isFormXObjectEnabled()
boolean	isLinearizationEnabled()
boolean	isMergeFontsEnabled()
PDFStructTreeRoot	makeStructTreeRoot(PDFParentTree parentTree) Creates and returns a StructTreeRoot object.
void	output(OutputStream stream) Writes out the entire document
void	outputHeader(OutputStream stream) Write the PDF header.
static int	outputIndirectObject(PDFObject object, OutputStream stream) Outputs the given object, wrapped by obj/endobj, to the given stream.
void	outputTrailer(OutputStream stream) Write the trailer
PDFObject	registerObject(PDFObject obj) Registers a PDFObject in this PDF document.
void	registerStructureElement(PDFStructElem structElem) Adds the given element to the structure tree.
void	registerStructureElement(PDFStructElem structElem, StandardStructureAttributes.Table.Scope scope) Assigns the given scope to the given element and adds it to the structure tree.
PDFReference	resolveExtensionReference(String id)
void	setColorSpace(int theColorspace) Set the color space.
void	setCreationDate(Date date) Sets the creation date of the document.
void	setCreator(String creator) Sets the creator of the document.
void	setEncryption(PDFEncryptionParams params) Enables PDF encryption.
void	setFilterMap(Map<String,List<String>> map) Sets the filter map to use for filters in this document.
void	setFormXObjectEnabled(boolean b)
void	setLinearizationEnabled(boolean b)
void	setMergeFontsEnabled(boolean mergeFontsEnabled)
void	setPDFVersion(Version version) Sets the PDF version of this document.
void	setProducer(String producer) Sets the producer of the document.
protected int	streamIndirectObject(PDFObject o, OutputStream stream)
protected void	writeTrailer(OutputStream stream, int first, int last, int size, long mainOffset, long startxref)

Methods inherited from class java.lang.Object

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

Field Detail

ENCODING

public static final String ENCODING

the encoding to use when converting strings to PDF commands

See Also:

Constant Field Values

objectcount

protected int objectcount

the counter for object numbering

position

protected long position

the current character position

indirectObjectOffsets

protected List<Long> indirectObjectOffsets

the character position of each object

structureTreeElements

protected List<PDFStructElem> structureTreeElements

trailerObjects

protected List<PDFObject> trailerObjects

List of objects to write in the trailer

objects

protected List<PDFObject> objects

the objects themselves

gStateObjectCount

protected int gStateObjectCount

pageObjs

protected List<PDFPage> pageObjs

outputStarted

protected boolean outputStarted

Constructor Detail

PDFDocument

public PDFDocument(String prod)

Creates an empty PDF document. The constructor creates a /Root and /Pages object to track the document but does not write these objects until the trailer is written. Note that the object ID of the pages object is determined now, and the xref table is updated later. This allows Pages to refer to their Parent before we write it out.

Parameters:

prod - the name of the producer of this pdf document

PDFDocument

public PDFDocument(String prod,
           VersionController versionController)

Creates an empty PDF document. The constructor creates a /Root and /Pages object to track the document but does not write these objects until the trailer is written. Note that the object ID of the pages object is determined now, and the xref table is updated later. This allows Pages to refer to their Parent before we write it out.

Parameters:

prod - the name of the producer of this pdf document

versionController - the version controller of this PDF document

Method Detail

getPDFVersion

public Version getPDFVersion()

Returns the current PDF version.

Returns:

returns the PDF version

setPDFVersion

public void setPDFVersion(Version version)

Sets the PDF version of this document.

Parameters:

version - the PDF version

Throws:

IllegalStateException - if the version of this PDF is not allowed to change.

getPDFVersionString

public String getPDFVersionString()

Returns:

the String representing the current PDF version

getProfile

public PDFProfile getProfile()

Returns:

the PDF profile currently active.

getFactory

public PDFFactory getFactory()

Returns the factory for PDF objects.

Returns:

the PDFFactory object

encode

public static byte[] encode(String text)

Converts text to a byte array for writing to a PDF file.

Parameters:

text - text to convert/encode

Returns:

the resulting byte array

flushTextBuffer

public static void flushTextBuffer(StringBuilder textBuffer,
                   OutputStream out)
                            throws IOException

Flushes the given text buffer to an output stream with the right encoding and resets the text buffer. This is used to efficiently switch between outputting text and binary content.

Parameters:

textBuffer - the text buffer

out - the output stream to flush the text content to

Throws:

IOException - if an I/O error occurs while writing to the output stream

setProducer

public void setProducer(String producer)

Sets the producer of the document.

Parameters:

producer - string indicating application producing the PDF

setCreationDate

public void setCreationDate(Date date)

Sets the creation date of the document.

Parameters:

date - Date to be stored as creation date in the PDF.

setCreator

public void setCreator(String creator)

Sets the creator of the document.

Parameters:

creator - string indicating application creating the document

setFilterMap

public void setFilterMap(Map<String,List<String>> map)

Sets the filter map to use for filters in this document.

Parameters:

map - the map of filter lists for each stream type

getFilterMap

public Map<String,List<String>> getFilterMap()

Returns the PDFFilters map used for filters in this document.

Returns:

the map of filters being used

getPages

public PDFPages getPages()

Returns the PDFPages object associated with the root object.

Returns:

the PDFPages object

getRoot

public PDFRoot getRoot()

Get the PDFRoot object for this document.

Returns:

the PDFRoot object

getStructureTreeElements

public List<PDFStructElem> getStructureTreeElements()

Get the Structural Tree Collection for this document

Returns:

makeStructTreeRoot

public PDFStructTreeRoot makeStructTreeRoot(PDFParentTree parentTree)

Creates and returns a StructTreeRoot object.

Parameters:

parentTree - the value of the ParenTree entry

Returns:

the structure tree root

registerStructureElement

public void registerStructureElement(PDFStructElem structElem)

Adds the given element to the structure tree.

registerStructureElement

public void registerStructureElement(PDFStructElem structElem,
                            StandardStructureAttributes.Table.Scope scope)

Assigns the given scope to the given element and adds it to the structure tree. The scope may not be added if it's not compatible with this document's PDF version.

getInfo

public PDFInfo getInfo()

Get the PDFInfo object for this document.

Returns:

the PDFInfo object

registerObject

public PDFObject registerObject(PDFObject obj)

Registers a PDFObject in this PDF document. The object is assigned a new object number.

Parameters:

obj - PDFObject to add

Returns:

the added PDFObject added (with its object number set)

assignObjectNumber

public void assignObjectNumber(PDFObject obj)

Assigns the PDFObject an object number, and sets the parent of the PDFObject to this document.

Parameters:

obj - PDFObject to assign a number to

addObject

public void addObject(PDFObject obj)

Adds a PDFObject to this document. The object MUST have an object number assigned.

Parameters:

obj - PDFObject to add

addTrailerObject

public void addTrailerObject(PDFObject obj)

Add trailer object. Adds an object to the list of trailer objects.

Parameters:

obj - the PDF object to add

applyEncryption

public void applyEncryption(AbstractPDFStream stream)

Apply the encryption filter to a PDFStream if encryption is enabled.

Parameters:

stream - PDFStream to encrypt

setEncryption

public void setEncryption(PDFEncryptionParams params)

Enables PDF encryption.

Parameters:

params - The encryption parameters for the pdf file

isEncryptionActive

public boolean isEncryptionActive()

Indicates whether encryption is active for this PDF or not.

Returns:

boolean True if encryption is active

getEncryption

public PDFEncryption getEncryption()

Returns the active Encryption object.

Returns:

the Encryption object

findFunction

protected PDFFunction findFunction(PDFFunction compare)

Looks through the registered functions to see if one that is equal to a reference object exists

Parameters:

compare - reference object

Returns:

the function if it was found, null otherwise

findShading

protected PDFShading findShading(PDFShading compare)

Looks through the registered shadings to see if one that is equal to a reference object exists

Parameters:

compare - reference object

Returns:

the shading if it was found, null otherwise

findPattern

protected PDFPattern findPattern(PDFPattern compare)

Find a previous pattern. The problem with this is for tiling patterns the pattern data stream is stored and may use up memory, usually this would only be a small amount of data.

Parameters:

compare - reference object

Returns:

the shading if it was found, null otherwise

findFont

protected PDFFont findFont(String fontname)

Finds a font.

Parameters:

fontname - name of the font

Returns:

PDFFont the requested font, null if it wasn't found

findDestination

protected PDFDestination findDestination(PDFDestination compare)

Finds a named destination.

Parameters:

compare - reference object to use as search template

Returns:

the link if found, null otherwise

findLink

protected PDFLink findLink(PDFLink compare)

Finds a link.

Parameters:

compare - reference object to use as search template

Returns:

the link if found, null otherwise

findFileSpec

protected PDFFileSpec findFileSpec(PDFFileSpec compare)

Finds a file spec.

Parameters:

compare - reference object to use as search template

Returns:

the file spec if found, null otherwise

findGoToRemote

protected PDFGoToRemote findGoToRemote(PDFGoToRemote compare)

Finds a goto remote.

Parameters:

compare - reference object to use as search template

Returns:

the goto remote if found, null otherwise

findGoTo

protected PDFGoTo findGoTo(PDFGoTo compare)

Finds a goto.

Parameters:

compare - reference object to use as search template

Returns:

the goto if found, null otherwise

findLaunch

protected PDFLaunch findLaunch(PDFLaunch compare)

Finds a launch.

Parameters:

compare - reference object to use as search template

Returns:

the launch if found, null otherwise

findGState

protected PDFGState findGState(PDFGState wanted,
                   PDFGState current)

Looks for an existing GState to use

Parameters:

wanted - requested features

current - currently active features

Returns:

the GState if found, null otherwise

getPDFColorSpace

public PDFDeviceColorSpace getPDFColorSpace()

Returns the PDF color space object.

Returns:

the color space

getColorSpace

public int getColorSpace()

Returns the color space.

Returns:

the color space

setColorSpace

public void setColorSpace(int theColorspace)

Set the color space. This is used when creating gradients.

Parameters:

theColorspace - the new color space

getFontMap

public Map<String,PDFFont> getFontMap()

Returns the font map for this document.

Returns:

the map of fonts used in this document

getImage

@Deprecated
public PDFImageXObject getImage(String key)

Deprecated. Use getXObject instead (so forms are treated in the same way)

Get an image from the image map.

Parameters:

key - the image key to look for

Returns:

the image or PDFXObject for the key if found

getXObject

public PDFXObject getXObject(String key)

Get an XObject from the image map.

Parameters:

key - the XObject key to look for

Returns:

the PDFXObject for the key if found

addDestination

public void addDestination(PDFDestination destination)

Adds a destination to the document.

Parameters:

destination - the destination object

getDestinationList

public List<PDFDestination> getDestinationList()

Gets the list of named destinations.

Returns:

the list of named destinations.

hasDestinations

public boolean hasDestinations()

Gets whether the document has named destinations.

Returns:

whether the document has named destinations.

addImage

public PDFImageXObject addImage(PDFResourceContext res,
                       PDFImage img)

Add an image to the PDF document. This adds an image to the PDF objects. If an image with the same key already exists it will return the old PDFXObject.

Parameters:

res - the PDF resource context to add to, may be null

img - the PDF image to add

Returns:

the PDF XObject that references the PDF image data

addFormXObject

public PDFFormXObject addFormXObject(PDFResourceContext res,
                            PDFStream cont,
                            PDFReference formres,
                            String key)

Add a form XObject to the PDF document. This adds a Form XObject to the PDF objects. If a Form XObject with the same key already exists it will return the old PDFFormXObject.

Parameters:

res - the PDF resource context to add to, may be null

cont - the PDF Stream contents of the Form XObject

formres - a reference to the PDF Resources for the Form XObject data

key - the key for the object

Returns:

the PDF Form XObject that references the PDF data

getOutlineRoot

public PDFOutline getOutlineRoot()

Get the root Outlines object. This method does not write the outline to the PDF document, it simply creates a reference for later.

Returns:

the PDF Outline root object

getResources

public PDFResources getResources()

Get the /Resources object for the document

Returns:

the /Resources object

enableAccessibility

public void enableAccessibility(boolean enableAccessibility)

resolveExtensionReference

public PDFReference resolveExtensionReference(String id)

output

public void output(OutputStream stream)
            throws IOException

Writes out the entire document

Parameters:

stream - the OutputStream to output the document to

Throws:

IOException - if there is an exception writing to the output stream

writeTrailer

protected void writeTrailer(OutputStream stream,
                int first,
                int last,
                int size,
                long mainOffset,
                long startxref)
                     throws IOException

Throws:

IOException

streamIndirectObject

protected int streamIndirectObject(PDFObject o,
                       OutputStream stream)
                            throws IOException

Throws:

IOException

outputIndirectObject

public static int outputIndirectObject(PDFObject object,
                       OutputStream stream)
                                throws IOException

Outputs the given object, wrapped by obj/endobj, to the given stream.

Parameters:

object - an indirect object, as described in Section 3.2.9 of the PDF 1.5 Reference.

stream - the stream to which the object must be output

Throws:

IllegalArgumentException - if the object is not an indirect object

IOException

outputHeader

public void outputHeader(OutputStream stream)
                  throws IOException

Write the PDF header. This method must be called prior to formatting and outputting AreaTrees.

Parameters:

stream - the OutputStream to write the header to

Throws:

IOException - if there is an exception writing to the output stream

outputTrailer

public void outputTrailer(OutputStream stream)
                   throws IOException

Write the trailer

Parameters:

stream - the OutputStream to write the trailer to

Throws:

IOException - if there is an exception writing to the output stream

isMergeFontsEnabled

public boolean isMergeFontsEnabled()

setMergeFontsEnabled

public void setMergeFontsEnabled(boolean mergeFontsEnabled)

isLinearizationEnabled

public boolean isLinearizationEnabled()

setLinearizationEnabled

public void setLinearizationEnabled(boolean b)

isFormXObjectEnabled

public boolean isFormXObjectEnabled()

setFormXObjectEnabled

public void setFormXObjectEnabled(boolean b)