org.apache.fop.pdf
Class PDFDocument

java.lang.Object
  extended by 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. Modified by lmckenzi@ca.ibm.com Sometimes IDs are created, but not validated. This tracks the difference. Image support modified from work of BoBoGi. Font support based on work by Takayuki Takeuchi.


Field Summary
protected  ColorSpace colorspace
          the colorspace (0=RGB, 1=CMYK)
static String ENCODING
          Encoding of the PDF
protected  PDFEncryption encryption
          the documents encryption, if exists
protected  IDReferences idReferences
          the documents idReferences
protected  PDFInfo info
          the /Info object
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 static String pdfVersion
          the version of PDF supported
protected  List pendingLinks
          the objects themselves
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  int xObjectCount
          the counter for XObject numbering
protected  List xObjects
          the XObjects
protected  Map xObjectsMap
          the XObjects Map.
protected  int xref
          character position of xref table
 
Constructor Summary
PDFDocument()
          creates an empty PDF document
 
Method Summary
 void addDestination(String destinationName, String internalDest)
          Make a destination object and add it
 int addImage(FopImage img)
           
 void addTrailerObject(PDFObject object)
           
 PDFPattern createGradient(boolean radial, ColorSpace theColorspace, List theColors, List theBounds, List theCoords)
           
 int getColorSpace()
           
 PDFOutline getOutlineRoot()
          Get the root Outlines object.
 PDFResources getResources()
          get the /Resources object for the document
 PDFAnnotList makeAnnotList()
          make an annotation list object
 PDFArray makeArray(int[] values)
          make an Array object (ex.
 PDFEncoding makeEncoding(String encodingName)
          make a /Encoding object
 PDFFont makeFont(String fontname, String basefont, String encoding, FontMetric metrics, FontDescriptor descriptor)
          make a Type1 /Font object
 PDFFontDescriptor makeFontDescriptor(FontDescriptor desc, byte subtype)
          make a /FontDescriptor object
 PDFFunction makeFunction(int theNumber, int theFunctionType, List theDomain, List theRange, StringBuffer theFunctionDataStream)
          make a postscript calculator function
 PDFFunction makeFunction(int theFunctionType, List theDomain, List theRange, List theSize, int theBitsPerSample, int theOrder, List theEncode, List theDecode, StringBuffer theFunctionDataStream, List theFilter)
          Make a Type 0 sampled function
 PDFFunction makeFunction(int theFunctionType, List theDomain, List theRange, List theCZero, List theCOne, double theInterpolationExponentN)
          make a type Exponential interpolation function (for shading usually)
 PDFFunction makeFunction(int theFunctionType, List theDomain, List theRange, List theFunctions, List theBounds, List theEncode)
          Make a Type 3 Stitching function
protected  PDFInfo makeInfo()
          make an /Info object
 PDFLink makeLink(Rectangle rect, String destination, int linkType)
          make a link object
 PDFLink makeLink(Rectangle rect, String page, String dest)
           
 PDFLink makeLinkCurrentPage(Rectangle rect, String dest)
           
 PDFOutline makeOutline(PDFOutline parent, String label, String destination)
          Make an outline object and add it to the given outline
 PDFPage makePage(PDFResources resources, PDFStream contents, int pagewidth, int pageheight, Page currentPage)
          make a /Page object
 PDFPages makePages()
          Make a /Pages object.
 PDFPattern makePattern(int thePatternType, PDFResources theResources, int thePaintType, int theTilingType, List theBBox, double theXStep, double theYStep, List theMatrix, List theXUID, StringBuffer thePatternDataStream)
          Make a tiling pattern
 PDFPattern makePattern(int thePatternType, PDFShading theShading, List theXUID, StringBuffer theExtGState, List theMatrix)
          Make a smooth shading pattern
 PDFICCStream makePDFICCStream()
           
 PDFResources makeResources()
          Make a /Resources object.
 PDFRoot makeRoot(PDFPages pages)
          Make a /Catalog (Root) object.
 PDFShading makeShading(int theShadingType, ColorSpace theColorSpace, List theBackground, List theBBox, boolean theAntiAlias, int theBitsPerCoordinate, int theBitsPerComponent, int theBitsPerFlag, List theDecode, PDFFunction theFunction)
          Make a free-form gouraud shaded triangle mesh, coons patch mesh, or tensor patch mesh shading object
 PDFShading makeShading(int theShadingType, ColorSpace theColorSpace, List theBackground, List theBBox, boolean theAntiAlias, int theBitsPerCoordinate, int theBitsPerComponent, List theDecode, int theVerticesPerRow, PDFFunction theFunction)
          make a Lattice-Form Gouraud mesh shading object
 PDFShading makeShading(int theShadingType, ColorSpace theColorSpace, List theBackground, List theBBox, boolean theAntiAlias, List theDomain, List theMatrix, PDFFunction theFunction)
          make a function based shading object
 PDFShading makeShading(int theShadingType, ColorSpace theColorSpace, List theBackground, List theBBox, boolean theAntiAlias, List theCoords, List theDomain, PDFFunction theFunction, List theExtend)
          Make an axial or radial shading object.
 PDFStream makeStream()
          make a stream object
 void output(OutputStream stream)
          write the entire document out
 void outputHeader(OutputStream stream)
          write the PDF header
 void outputTrailer(OutputStream stream)
          write the trailer
 void setColorSpace(int theColorspace)
           
 void setEncryption(String ownerPassword, String userPassword, boolean allowPrint, boolean allowCopyContent, boolean allowEditContent, boolean allowEditAnnotations)
          set the encryption object
 void setIDReferences(IDReferences idReferences)
           
 void setProducer(String producer)
          set the producer of the document
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

pdfVersion

protected static final String pdfVersion
the version of PDF supported

See Also:
Constant Field Values

position

protected int position
the current character position


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


xref

protected int xref
character position of xref table


root

protected PDFRoot root
the /Root object


info

protected PDFInfo info
the /Info object


resources

protected PDFResources resources
the /Resources object


idReferences

protected IDReferences idReferences
the documents idReferences


encryption

protected PDFEncryption encryption
the documents encryption, if exists


colorspace

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


patternCount

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


shadingCount

protected int shadingCount
the counter for Shading name numbering


xObjectCount

protected int xObjectCount
the counter for XObject numbering


xObjects

protected List xObjects
the XObjects


xObjectsMap

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


pendingLinks

protected List pendingLinks
the objects themselves


ENCODING

public static final String ENCODING
Encoding of the PDF

See Also:
Constant Field Values
Constructor Detail

PDFDocument

public PDFDocument()
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. This took me a long time to work out, and is so obvious now. Sigh. mark-fop@inomial.com. Maybe I should do a PDF course.

Method Detail

setProducer

public void setProducer(String producer)
set the producer of the document

Parameters:
producer - string indicating application producing the PDF

setEncryption

public void setEncryption(String ownerPassword,
                          String userPassword,
                          boolean allowPrint,
                          boolean allowCopyContent,
                          boolean allowEditContent,
                          boolean allowEditAnnotations)
set the encryption object

Parameters:
ownerPassword - The owner password for the pdf file
userPassword - The user password for the pdf file
allowPrint - Indicates whether the printing permission will be set
allowCopyContent - Indicates whether the content extracting permission will be set
allowEditContent - Indicates whether the edit content permission will be set
allowEditAnnotations - Indicates whether the edit annotations permission will be set

makeRoot

public PDFRoot makeRoot(PDFPages pages)
Make a /Catalog (Root) object. This object is written in the trailer.


makePages

public PDFPages makePages()
Make a /Pages object. This object is written in the trailer.


makeResources

public PDFResources makeResources()
Make a /Resources object. This object is written in the trailer.


makeInfo

protected PDFInfo makeInfo()
make an /Info object

Parameters:
producer - string indicating application producing the PDF
Returns:
the created /Info object

makeFunction

public PDFFunction makeFunction(int theFunctionType,
                                List theDomain,
                                List theRange,
                                List theSize,
                                int theBitsPerSample,
                                int theOrder,
                                List theEncode,
                                List theDecode,
                                StringBuffer theFunctionDataStream,
                                List theFilter)
Make a Type 0 sampled function

Parameters:
theDomain - List objects of Double objects. This is the domain of the function. See page 264 of the PDF 1.3 Spec.
theRange - List objects of Double objects. This is the Range of the function. See page 264 of the PDF 1.3 Spec.
theSize - A List object of Integer objects. This is the number of samples in each input dimension. I can't imagine there being more or less than two input dimensions, so maybe this should be an array of length 2. See page 265 of the PDF 1.3 Spec.
theBitsPerSample - An int specifying the number of bits user to represent each sample value. Limited to 1,2,4,8,12,16,24 or 32. See page 265 of the 1.3 PDF Spec.
theOrder - The order of interpolation between samples. Default is 1 (one). Limited to 1 (one) or 3, which means linear or cubic-spline interpolation. This attribute is optional. See page 265 in the PDF 1.3 spec.
theEncode - List objects of Double objects. This is the linear mapping of input values intop the domain of the function's sample table. Default is hard to represent in ascii, but basically [0 (Size0 1) 0 (Size1 1)...]. This attribute is optional. See page 265 in the PDF 1.3 spec.
theDecode - List objects of Double objects. This is a linear mapping of sample values into the range. The default is just the range. This attribute is optional. Read about it on page 265 of the PDF 1.3 spec.
theFunctionDataStream - The sample values that specify the function are provided in a stream. This is optional, but is almost always used. Page 265 of the PDF 1.3 spec has more.
theFilter - This is a List of String objects which are the various filters that have are to be applied to the stream to make sense of it. Order matters, so watch out. This is not documented in the Function section of the PDF 1.3 spec, it was deduced from samples that this is sometimes used, even if we may never use it in FOP. It is added for completeness sake.
theNumber - The object number of this PDF object.
theFunctionType - This is the type of function (0,2,3, or 4). It should be 0 as this is the constructor for sampled functions.

makeFunction

public PDFFunction makeFunction(int theFunctionType,
                                List theDomain,
                                List theRange,
                                List theCZero,
                                List theCOne,
                                double theInterpolationExponentN)
make a type Exponential interpolation function (for shading usually)

Parameters:
theDomain - List objects of Double objects. This is the domain of the function. See page 264 of the PDF 1.3 Spec.
theRange - List of Doubles that is the Range of the function. See page 264 of the PDF 1.3 Spec.
theCZero - This is a List of Double objects which defines the function result when x=0. This attribute is optional. It's described on page 268 of the PDF 1.3 spec.
theCOne - This is a List of Double objects which defines the function result when x=1. This attribute is optional. It's described on page 268 of the PDF 1.3 spec.
theInterpolationExponentN - This is the inerpolation exponent. This attribute is required. PDF Spec page 268
theFunctionType - The type of the function, which should be 2.

makeFunction

public PDFFunction makeFunction(int theFunctionType,
                                List theDomain,
                                List theRange,
                                List theFunctions,
                                List theBounds,
                                List theEncode)
Make a Type 3 Stitching function

Parameters:
theDomain - List objects of Double objects. This is the domain of the function. See page 264 of the PDF 1.3 Spec.
theRange - List objects of Double objects. This is the Range of the function. See page 264 of the PDF 1.3 Spec.
theFunctions - A List of the PDFFunction objects that the stitching function stitches. This attributed is required. It is described on page 269 of the PDF spec.
theBounds - This is a List of Doubles representing the numbers that, in conjunction with Domain define the intervals to which each function from the 'functions' object applies. It must be in order of increasing magnitude, and each must be within Domain. It basically sets how much of the gradient each function handles. This attributed is required. It's described on page 269 of the PDF 1.3 spec.
theEncode - List objects of Double objects. This is the linear mapping of input values intop the domain of the function's sample table. Default is hard to represent in ascii, but basically [0 (Size0 1) 0 (Size1 1)...]. This attribute is required. See page 270 in the PDF 1.3 spec.
theFunctionType - This is the function type. It should be 3, for a stitching function.

makeFunction

public PDFFunction makeFunction(int theNumber,
                                int theFunctionType,
                                List theDomain,
                                List theRange,
                                StringBuffer theFunctionDataStream)
make a postscript calculator function

Parameters:
theNumber -
theFunctionType -
theDomain -
theRange -
theFunctionDataStream -

makeShading

public PDFShading makeShading(int theShadingType,
                              ColorSpace theColorSpace,
                              List theBackground,
                              List theBBox,
                              boolean theAntiAlias,
                              List theDomain,
                              List theMatrix,
                              PDFFunction theFunction)
make a function based shading object

Parameters:
theShadingType - The type of shading object, which should be 1 for function based shading.
theColorSpace - The colorspace is 'DeviceRGB' or something similar.
theBackground - An array of color components appropriate to the colorspace key specifying a single color value. This key is used by the f operator buy ignored by the sh operator.
theBBox - List of double's representing a rectangle in the coordinate space that is current at the time of shading is imaged. Temporary clipping boundary.
theAntiAlias - Whether or not to anti-alias.
theDomain - Optional List of Doubles specifying the domain.
theMatrix - List of Doubles specifying the matrix. If it's a pattern, then the matrix maps it to pattern space. If it's a shading, then it maps it to current user space. It's optional, the default is the identity matrix
theFunction - The PDF Function that maps an (x,y) location to a color

makeShading

public PDFShading makeShading(int theShadingType,
                              ColorSpace theColorSpace,
                              List theBackground,
                              List theBBox,
                              boolean theAntiAlias,
                              List theCoords,
                              List theDomain,
                              PDFFunction theFunction,
                              List theExtend)
Make an axial or radial shading object.

Parameters:
theShadingType - 2 or 3 for axial or radial shading
theColorSpace - "DeviceRGB" or similar.
theBackground - theBackground An array of color components appropriate to the colorspace key specifying a single color value. This key is used by the f operator buy ignored by the sh operator.
theBBox - List of double's representing a rectangle in the coordinate space that is current at the time of shading is imaged. Temporary clipping boundary.
theAntiAlias - Default is false
theCoords - List of four (type 2) or 6 (type 3) Double
theDomain - List of Doubles specifying the domain
theFunction - the Stitching (PDFfunction type 3) function, even if it's stitching a single function
theExtend - List of Booleans of whether to extend teh start and end colors past the start and end points The default is [false, false]

makeShading

public PDFShading makeShading(int theShadingType,
                              ColorSpace theColorSpace,
                              List theBackground,
                              List theBBox,
                              boolean theAntiAlias,
                              int theBitsPerCoordinate,
                              int theBitsPerComponent,
                              int theBitsPerFlag,
                              List theDecode,
                              PDFFunction theFunction)
Make a free-form gouraud shaded triangle mesh, coons patch mesh, or tensor patch mesh shading object

Parameters:
theShadingType - 4, 6, or 7 depending on whether it's Free-form gouraud-shaded triangle meshes, coons patch meshes, or tensor product patch meshes, respectively.
theColorSpace - "DeviceRGB" or similar.
theBackground - theBackground An array of color components appropriate to the colorspace key specifying a single color value. This key is used by the f operator buy ignored by the sh operator.
theBBox - List of double's representing a rectangle in the coordinate space that is current at the time of shading is imaged. Temporary clipping boundary.
theAntiAlias - Default is false
theBitsPerCoordinate - 1,2,4,8,12,16,24 or 32.
theBitsPerComponent - 1,2,4,8,12, and 16
theBitsPerFlag - 2,4,8.
theDecode - List of Doubles see PDF 1.3 spec pages 303 to 312.
theFunction - the PDFFunction

makeShading

public PDFShading makeShading(int theShadingType,
                              ColorSpace theColorSpace,
                              List theBackground,
                              List theBBox,
                              boolean theAntiAlias,
                              int theBitsPerCoordinate,
                              int theBitsPerComponent,
                              List theDecode,
                              int theVerticesPerRow,
                              PDFFunction theFunction)
make a Lattice-Form Gouraud mesh shading object

Parameters:
theShadingType - 5 for lattice-Form Gouraud shaded-triangle mesh without spaces. "Shading1" or "Sh1" are good examples.
theColorSpace - "DeviceRGB" or similar.
theBackground - theBackground An array of color components appropriate to the colorspace key specifying a single color value. This key is used by the f operator buy ignored by the sh operator.
theBBox - List of double's representing a rectangle in the coordinate space that is current at the time of shading is imaged. Temporary clipping boundary.
theAntiAlias - Default is false
theBitsPerCoordinate - 1,2,4,8,12,16, 24, or 32
theBitsPerComponent - 1,2,4,8,12,24,32
theDecode - List of Doubles. See page 305 in PDF 1.3 spec.
theVerticesPerRow - number of vertices in each "row" of the lattice.
theFunction - The PDFFunction that's mapped on to this shape

makePattern

public PDFPattern makePattern(int thePatternType,
                              PDFResources theResources,
                              int thePaintType,
                              int theTilingType,
                              List theBBox,
                              double theXStep,
                              double theYStep,
                              List theMatrix,
                              List theXUID,
                              StringBuffer thePatternDataStream)
Make a tiling pattern

Parameters:
thePatternType - the type of pattern, which is 1 for tiling.
theResources - the resources associated with this pattern
thePaintType - 1 or 2, colored or uncolored.
theTilingType - 1, 2, or 3, constant spacing, no distortion, or faster tiling
theBBox - List of Doubles: The pattern cell bounding box
theXStep - horizontal spacing
theYStep - vertical spacing
theMatrix - Optional List of Doubles transformation matrix
theXUID - Optional List of Integers that uniquely identify the pattern
thePatternDataStream - The stream of pattern data to be tiled.

makePattern

public PDFPattern makePattern(int thePatternType,
                              PDFShading theShading,
                              List theXUID,
                              StringBuffer theExtGState,
                              List theMatrix)
Make a smooth shading pattern

Parameters:
thePatternType - the type of the pattern, which is 2, smooth shading
theShading - the PDF Shading object that comprises this pattern
theXUID - optional:the extended unique Identifier if used.
theExtGState - optional: the extended graphics state, if used.
theMatrix - Optional:List of Doubles that specify the matrix.

getColorSpace

public int getColorSpace()

setColorSpace

public void setColorSpace(int theColorspace)

createGradient

public PDFPattern createGradient(boolean radial,
                                 ColorSpace theColorspace,
                                 List theColors,
                                 List theBounds,
                                 List theCoords)

makeEncoding

public PDFEncoding makeEncoding(String encodingName)
make a /Encoding object

Parameters:
encodingName - character encoding scheme name
Returns:
the created /Encoding object

makePDFICCStream

public PDFICCStream makePDFICCStream()

makeFont

public PDFFont makeFont(String fontname,
                        String basefont,
                        String encoding,
                        FontMetric metrics,
                        FontDescriptor descriptor)
make a Type1 /Font object

Parameters:
fontname - internal name to use for this font (eg "F1")
basefont - name of the base font (eg "Helvetica")
encoding - character encoding scheme used by the font
metrics - additional information about the font
descriptor - additional information about the font
Returns:
the created /Font object

makeFontDescriptor

public PDFFontDescriptor makeFontDescriptor(FontDescriptor desc,
                                            byte subtype)
make a /FontDescriptor object


makeArray

public PDFArray makeArray(int[] values)
make an Array object (ex. Widths array for a font)


addImage

public int addImage(FopImage img)

makePage

public PDFPage makePage(PDFResources resources,
                        PDFStream contents,
                        int pagewidth,
                        int pageheight,
                        Page currentPage)
make a /Page object

Parameters:
resources - resources object to use
contents - stream object with content
pagewidth - width of the page in points
pageheight - height of the page in points
Returns:
the created /Page object

makeLink

public PDFLink makeLink(Rectangle rect,
                        String destination,
                        int linkType)
make a link object

Parameters:
rect - the clickable rectangle
destination - the destination file
linkType - the link type
Returns:
the PDFLink object created

addTrailerObject

public void addTrailerObject(PDFObject object)

makeLinkCurrentPage

public PDFLink makeLinkCurrentPage(Rectangle rect,
                                   String dest)

makeLink

public PDFLink makeLink(Rectangle rect,
                        String page,
                        String dest)

makeStream

public PDFStream makeStream()
make a stream object

Returns:
the stream object created

makeAnnotList

public PDFAnnotList makeAnnotList()
make an annotation list object

Returns:
the annotation list object created

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.


makeOutline

public PDFOutline makeOutline(PDFOutline parent,
                              String label,
                              String destination)
Make an outline object and add it to the given outline

Parameters:
parent - parent PDFOutline object
label - the title for the new outline object
action - the PDFAction to reference

getResources

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

Returns:
the /Resources object

output

public void output(OutputStream stream)
            throws IOException
write the entire document out

Parameters:
writer - the OutputStream to output the document to
Throws:
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

outputTrailer

public void outputTrailer(OutputStream stream)
                   throws IOException
write the trailer

Parameters:
stream - the OutputStream to write the trailer to
Throws:
IOException

setIDReferences

public void setIDReferences(IDReferences idReferences)

addDestination

public void addDestination(String destinationName,
                           String internalDest)
Make a destination object and add it

Parameters:
label - the title for the new destination object
dest - the destination name to reference


Copyright ? 1999-2003 Apache Software Foundation. All Rights Reserved.