org.apache.fop.pdf

Class PDFDocument


public class PDFDocument
extends java.lang.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

static String
ENCODING
the encoding to use when converting strings to PDF commandos.
static int
PDF_VERSION_1_3
Integer constant to represent PDF 1.3
static int
PDF_VERSION_1_4
Integer constant to represent PDF 1.4
protected PDFDeviceColorSpace
colorspace
the colorspace (0=RGB, 1=CMYK)
protected List
destinations
List of Destinations.
protected PDFEncryption
encryption
the documents encryption, if exists
protected List
filespecs
List of FileSpecs.
protected Map
filterMap
The filter map.
protected Map
fontMap
the Font Map.
protected List
functions
List of functions.
protected List
gotoremotes
List of GoToRemotes.
protected List
gotos
List of GoTos.
protected List
gstates
List of PDFGState objects.
protected PDFInfo
info
the /Info object
protected List
links
List of Links.
protected List
location
the character position of each object
protected int
objectcount
the counter for object numbering
protected List
objects
the objects themselves
protected int
patternCount
the counter for Pattern name numbering (e.g.
protected List
patterns
List of patterns.
protected PDFProfile
pdfProfile
Indicates which PDF profiles are active (PDF/A, PDF/X etc.)
protected int
pdfVersion
Indicates what PDF version is active
protected int
position
the current character position
protected PDFResources
resources
the /Resources object
protected PDFRoot
root
the /Root object
protected int
shadingCount
the counter for Shading name numbering
protected List
shadings
List of shadings.
protected int
xObjectCount
the counter for XObject numbering
protected Map
xObjectsMap
the XObjects Map.
protected int
xref
character position of xref table

Constructor Summary

PDFDocument(String prod)
Creates an empty PDF document.

Method Summary

void
addDestination(PDFDestination destination)
Adds a destination to the document.
PDFFormXObject
addFormXObject(PDFResourceContext res, PDFStream cont, PDFResources formres, String key)
Add a form XObject to the PDF document.
PDFXObject
addImage(PDFResourceContext res, PDFImage img)
Add an image to the PDF document.
void
addObject(PDFObject obj)
Adds an 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 a object number and sets the parent of the PDFObject to this PDFDocument.
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 PDFGState
findGState(PDFGState wanted, PDFGState current)
Looks for an existing GState to use
protected PDFGoTo
findGoTo(PDFGoTo compare)
Finds a goto.
protected PDFGoToRemote
findGoToRemote(PDFGoToRemote compare)
Finds a goto remote.
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
int
getColorSpace()
Get the color space.
List
getDestinationList()
Gets the list of named destinations.
PDFDests
getDests()
Gets the PDFDests object (which represents the /Dests entry).
PDFEncryption
getEncryption()
Returns the active Encryption object.
PDFFactory
getFactory()
Returns the factory for PDF objects.
Map
getFilterMap()
Get the filter map used for filters in this document.
Map
getFontMap()
Get the font map for this document.
protected String
getIDEntry()
PDFXObject
getImage(String key)
Get an image from the image map.
PDFInfo
getInfo()
Get the pdf info object for this document.
PDFOutline
getOutlineRoot()
Get the root Outlines object.
PDFDeviceColorSpace
getPDFColorSpace()
Get the PDF color space object.
int
getPDFVersion()
String
getPDFVersionString()
PDFPages
getPages()
Returns the PDFPages object associated with the root object.
PDFProfile
getProfile()
PDFResources
getResources()
get the /Resources object for the document
PDFRoot
getRoot()
Get the PDF root object.
boolean
hasDestinations()
Gets whether the document has named destinations.
boolean
isEncodingOnTheFly()
Indicates whether stream encoding on-the-fly is enabled.
boolean
isEncryptionActive()
Indicates whether encryption is active for this PDF or not.
void
output(OutputStream stream)
write the entire document out
void
outputHeader(OutputStream stream)
Write the PDF header.
void
outputTrailer(OutputStream stream)
write the trailer
PDFObject
registerObject(PDFObject obj)
Registers a PDFObject in this PDF document.
protected InputStream
resolveURI(String uri)
Resolve a URI.
void
setColorSpace(int theColorspace)
Set the color space.
void
setCreationDate(Date date)
Set the creation date of the document.
void
setCreator(String creator)
Set the creator of the document.
void
setEncryption(PDFEncryptionParams params)
Enables PDF encryption.
void
setFilterMap(Map map)
Set the filter map to use for filters in this document.
void
setProducer(String producer)
set the producer of the document

Field Details

ENCODING

public static final String ENCODING
the encoding to use when converting strings to PDF commandos.

PDF_VERSION_1_3

public static final int PDF_VERSION_1_3
Integer constant to represent PDF 1.3
Field Value:
3

PDF_VERSION_1_4

public static final int PDF_VERSION_1_4
Integer constant to represent PDF 1.4
Field Value:
4

colorspace

protected PDFDeviceColorSpace colorspace
the colorspace (0=RGB, 1=CMYK)

destinations

protected List destinations
List of Destinations.

encryption

protected PDFEncryption encryption
the documents encryption, if exists

filespecs

protected List filespecs
List of FileSpecs.

filterMap

protected Map filterMap
The filter map.

fontMap

protected Map fontMap
the Font Map.

functions

protected List functions
List of functions.

gotoremotes

protected List gotoremotes
List of GoToRemotes.

gotos

protected List gotos
List of GoTos.

gstates

protected List gstates
List of PDFGState objects.

info

protected PDFInfo info
the /Info object

links

protected List links
List of Links.

location

protected List location
the character position of each object

objectcount

protected int objectcount
the counter for object numbering

objects

protected List objects
the objects themselves

patternCount

protected int patternCount
the counter for Pattern name numbering (e.g. 'Pattern1')

patterns

protected List patterns
List of patterns.

pdfProfile

protected PDFProfile pdfProfile
Indicates which PDF profiles are active (PDF/A, PDF/X etc.)

pdfVersion

protected int pdfVersion
Indicates what PDF version is active

position

protected int position
the current character position

resources

protected PDFResources resources
the /Resources object

root

protected PDFRoot root
the /Root object

shadingCount

protected int shadingCount
the counter for Shading name numbering

shadings

protected List shadings
List of shadings.

xObjectCount

protected int xObjectCount
the counter for XObject numbering

xObjectsMap

protected Map xObjectsMap
the XObjects Map. Should be modified (works only for image subtype)

xref

protected int xref
character position of xref table

Constructor Details

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

Method Details

addDestination

public void addDestination(PDFDestination destination)
Adds a destination to the document.
Parameters:
destination - the destination object

addFormXObject

public PDFFormXObject addFormXObject(PDFResourceContext res,
                                     PDFStream cont,
                                     PDFResources 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 - the PDF Resources for the Form XObject data
key - the key for the object
Returns:
the PDF Form XObject that references the PDF data

addImage

public PDFXObject 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

addObject

public void addObject(PDFObject obj)
Adds an PDFObject to this document. The object must have a 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

assignObjectNumber

public void assignObjectNumber(PDFObject obj)
Assigns the PDFObject a object number and sets the parent of the PDFObject to this PDFDocument.
Parameters:
obj - PDFObject to assign a number to

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:
byte[] the resulting byte array

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

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

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

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

findGState

protected PDFGState findGState(PDFGState wanted,
                               PDFGState current)
Looks for an existing GState to use
Parameters:
wanted - requested features
current - currently active features
Returns:
PDFGState the GState 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

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

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

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

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

getColorSpace

public int getColorSpace()
Get the color space.
Returns:
the color space

getDestinationList

public List getDestinationList()
Gets the list of named destinations.
Returns:
the list of named destinations.

getDests

public PDFDests getDests()
Gets the PDFDests object (which represents the /Dests entry).
Returns:
the PDFDests object (which represents the /Dests entry).

getEncryption

public PDFEncryption getEncryption()
Returns the active Encryption object.
Returns:
the Encryption object

getFactory

public PDFFactory getFactory()
Returns the factory for PDF objects.
Returns:
PDFFactory the factory

getFilterMap

public Map getFilterMap()
Get the filter map used for filters in this document.
Returns:
the map of filters being used

getFontMap

public Map getFontMap()
Get the font map for this document.
Returns:
the map of fonts used in this document

getIDEntry

protected String getIDEntry()
Returns:
the "ID" entry for the file trailer

getImage

public PDFXObject getImage(String key)
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

getInfo

public PDFInfo getInfo()
Get the pdf info object for this document.
Returns:
the PDF Info object for this document

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

getPDFColorSpace

public PDFDeviceColorSpace getPDFColorSpace()
Get the PDF color space object.
Returns:
the color space

getPDFVersion

public int getPDFVersion()
Returns:
the integer representing the active PDF version (one of PDFDocument.PDF_VERSION_*)

getPDFVersionString

public String getPDFVersionString()
Returns:
the String representing the active PDF version

getPages

public PDFPages getPages()
Returns the PDFPages object associated with the root object.
Returns:
the PDFPages object

getProfile

public PDFProfile getProfile()
Returns:
the PDF profile currently active.

getResources

public PDFResources getResources()
get the /Resources object for the document
Returns:
the /Resources object

getRoot

public PDFRoot getRoot()
Get the PDF root object.
Returns:
the PDFRoot object

hasDestinations

public boolean hasDestinations()
Gets whether the document has named destinations.
Returns:
whether the document has named destinations.

isEncodingOnTheFly

public boolean isEncodingOnTheFly()
Indicates whether stream encoding on-the-fly is enabled. If enabled stream can be serialized without the need for a buffer to merely calculate the stream length.
Returns:
boolean true if on-the-fly encoding is enabled

isEncryptionActive

public boolean isEncryptionActive()
Indicates whether encryption is active for this PDF or not.
Returns:
boolean True if encryption is active

output

public void output(OutputStream stream)
            throws IOException
write the entire document out
Parameters:
stream - the OutputStream to output the document to

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

outputTrailer

public void outputTrailer(OutputStream stream)
            throws IOException
write the trailer
Parameters:
stream - the OutputStream to write the trailer to

registerObject

public PDFObject registerObject(PDFObject obj)
Registers a PDFObject in this PDF document. The PDF is assigned a new object number.
Parameters:
obj - PDFObject to add
Returns:
PDFObject the PDFObject added (its object number set)

resolveURI

protected InputStream resolveURI(String uri)
            throws java.io.FileNotFoundException
Resolve a URI.
Parameters:
uri - the uri to resolve
Returns:
the InputStream from the URI.

setColorSpace

public void setColorSpace(int theColorspace)
Set the color space. This is used when creating gradients.
Parameters:
theColorspace - the new color space

setCreationDate

public void setCreationDate(Date date)
Set the creation date of the document.
Parameters:
date - Date to be stored as creation date in the PDF.

setCreator

public void setCreator(String creator)
Set the creator of the document.
Parameters:
creator - string indicating application creating the document

setEncryption

public void setEncryption(PDFEncryptionParams params)
Enables PDF encryption.
Parameters:
params - The encryption parameters for the pdf file

setFilterMap

public void setFilterMap(Map map)
Set the filter map to use for filters in this document.
Parameters:
map - the map of filter lists for each stream type

setProducer

public void setProducer(String producer)
set the producer of the document
Parameters:
producer - string indicating application producing the PDF

Copyright 1999-2007 The Apache Software Foundation. All Rights Reserved.