Package 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 Detail

      • ENCODING

        public static final java.lang.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

      • log

        private org.apache.commons.logging.Log log
        the logger instance

      • position

        protected long position
        the current character position

      • indirectObjectOffsets

        protected java.util.List<java.lang.Long> indirectObjectOffsets
        the character position of each object

      • structureTreeElements

        protected java.util.List<PDFStructElem> structureTreeElements

      • trailerObjects

        protected java.util.List<PDFObject> trailerObjects
        List of objects to write in the trailer

      • objects

        protected java.util.List<PDFObject> objects
        the objects themselves

      • versionController

        private VersionController versionController
        Controls the PDF version of this document

      • pdfProfile

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

      • root

        private PDFRoot root
        the /Root object

      • outlineRoot

        private PDFOutline outlineRoot
        The root outline object

      • pages

        private PDFPages pages
        The /Pages object (mark-fop@inomial.com)

      • info

        private PDFInfo info
        the /Info object

      • resources

        private PDFResources resources
        the /Resources object

      • encryption

        private PDFEncryption encryption
        the document's encryption, if it exists

      • patternCount

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

      • shadingCount

        private int shadingCount
        the counter for Shading name numbering

      • xObjectCount

        private int xObjectCount
        the counter for XObject numbering

      • gStateObjectCount

        protected int gStateObjectCount

      • xObjectsMap

        private java.util.Map<java.lang.String,​PDFXObject> xObjectsMap

      • xObjectsMapFast

        private org.apache.xmlgraphics.image.loader.util.SoftMapCache xObjectsMapFast

      • fontMap

        private java.util.Map<java.lang.String,​PDFFont> fontMap

      • filterMap

        private java.util.Map<java.lang.String,​java.util.List<java.lang.String>> filterMap

      • gstates

        private java.util.List<PDFGState> gstates

      • functions

        private java.util.List<PDFFunction> functions

      • shadings

        private java.util.List<PDFShading> shadings

      • patterns

        private java.util.List<PDFPattern> patterns

      • links

        private java.util.List<PDFLink> links

      • filespecs

        private java.util.List<PDFFileSpec> filespecs

      • gotos

        private java.util.List<PDFGoTo> gotos

      • launches

        private java.util.List<PDFLaunch> launches

      • pageObjs

        protected java.util.List<PDFPage> pageObjs

      • layers

        private java.util.List<PDFLayer> layers

      • navigators

        private java.util.List<PDFNavigator> navigators

      • accessibilityEnabled

        private boolean accessibilityEnabled

      • staticRegionsPerPageForAccessibility

        private boolean staticRegionsPerPageForAccessibility

      • mergeFontsEnabled

        private boolean mergeFontsEnabled

      • mergeFormFieldsEnabled

        private boolean mergeFormFieldsEnabled

      • linearizationEnabled

        private boolean linearizationEnabled

      • formXObjectEnabled

        private boolean formXObjectEnabled

      • outputStarted

        protected boolean outputStarted

      • objectStreamsEnabled

        private boolean objectStreamsEnabled

    • Constructor Detail

      • PDFDocument

        public PDFDocument​(java.lang.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​(java.lang.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:
        java.lang.IllegalStateException - if the version of this PDF is not allowed to change.

      • getPDFVersionString

        public java.lang.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​(java.lang.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​(java.lang.StringBuilder textBuffer,
                                   java.io.OutputStream out)
                            throws java.io.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:
        java.io.IOException - if an I/O error occurs while writing to the output stream

      • setProducer

        public void setProducer​(java.lang.String producer)
        Sets the producer of the document.
        Parameters:
        producer - string indicating application producing the PDF

      • setCreationDate

        public void setCreationDate​(java.util.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​(java.lang.String creator)
        Sets the creator of the document.
        Parameters:
        creator - string indicating application creating the document

      • setFilterMap

        public void setFilterMap​(java.util.Map<java.lang.String,​java.util.List<java.lang.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 java.util.Map<java.lang.String,​java.util.List<java.lang.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 java.util.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)

      • registerTrailerObject

        public <T extends PDFObject> T registerTrailerObject​(T obj)
        Registers a PDFObject in this PDF document at end. 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

      • findPDFObject

        private java.lang.Object findPDFObject​(java.util.List<? extends PDFObject> list,
                                       PDFObject compare)

      • 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​(java.lang.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 java.util.Map<java.lang.String,​PDFFont> getFontMap()
        Returns the font map for this document.
        Returns:
        the map of fonts used in this document

      • getImage

        @Deprecated
public PDFImageXObject getImage​(java.lang.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​(java.lang.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

      • putXObject

        private void putXObject​(java.lang.String key,
                        PDFXObject pdfxObject)

      • toHashCode

        private java.lang.String toHashCode​(java.lang.String key)

      • addDestination

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

      • getDestinationList

        public java.util.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,
                                     java.lang.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)

      • setStaticRegionsPerPageForAccessibility

        public void setStaticRegionsPerPageForAccessibility​(boolean staticRegionsPerPageForAccessibility)

      • isStaticRegionsPerPageForAccessibility

        public boolean isStaticRegionsPerPageForAccessibility()

      • resolveExtensionReference

        public PDFReference resolveExtensionReference​(java.lang.String id)

      • output

        public void output​(java.io.OutputStream stream)
            throws java.io.IOException
        Writes out the entire document
        Parameters:
        stream - the OutputStream to output the document to
        Throws:
        java.io.IOException - if there is an exception writing to the output stream

      • addToObjectStream

        private void addToObjectStream​(CompressedObject object)

      • writeTrailer

        protected void writeTrailer​(java.io.OutputStream stream,
                            int first,
                            int last,
                            int size,
                            long mainOffset,
                            long startxref)
                     throws java.io.IOException
        Throws:
        java.io.IOException

      • streamIndirectObject

        protected int streamIndirectObject​(PDFObject o,
                                   java.io.OutputStream stream)
                            throws java.io.IOException
        Throws:
        java.io.IOException

      • streamIndirectObjects

        private void streamIndirectObjects​(java.util.Collection<? extends PDFObject> objects,
                                   java.io.OutputStream stream)
                            throws java.io.IOException
        Throws:
        java.io.IOException

      • recordObjectOffset

        private void recordObjectOffset​(PDFObject object)

      • outputIndirectObject

        public static int outputIndirectObject​(PDFObject object,
                                       java.io.OutputStream stream)
                                throws java.io.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:
        java.lang.IllegalArgumentException - if the object is not an indirect object
        java.io.IOException

      • outputHeader

        public void outputHeader​(java.io.OutputStream stream)
                  throws java.io.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:
        java.io.IOException - if there is an exception writing to the output stream

      • outputTrailer

        public void outputTrailer​(java.io.OutputStream stream)
                   throws java.io.IOException
        Write the trailer
        Parameters:
        stream - the OutputStream to write the trailer to
        Throws:
        java.io.IOException - if there is an exception writing to the output stream

      • createDestinations

        private void createDestinations()

      • outputTrailerObjectsAndXref

        private void outputTrailerObjectsAndXref​(java.io.OutputStream stream)
                                  throws java.io.IOException
        Throws:
        java.io.IOException

      • useObjectStreams

        private boolean useObjectStreams()

      • createTrailerDictionary

        private TrailerDictionary createTrailerDictionary​(boolean addRoot)

      • isMergeFontsEnabled

        public boolean isMergeFontsEnabled()

      • setMergeFontsEnabled

        public void setMergeFontsEnabled​(boolean mergeFontsEnabled)

      • isMergeFormFieldsEnabled

        public boolean isMergeFormFieldsEnabled()

      • setMergeFormFieldsEnabled

        public void setMergeFormFieldsEnabled​(boolean mergeFormFieldsEnabled)

      • getCurrentFileSize

        long getCurrentFileSize()

      • isLinearizationEnabled

        public boolean isLinearizationEnabled()

      • setLinearizationEnabled

        public void setLinearizationEnabled​(boolean b)

      • isFormXObjectEnabled

        public boolean isFormXObjectEnabled()

      • setFormXObjectEnabled

        public void setFormXObjectEnabled​(boolean b)

      • setObjectStreamsEnabled

        public void setObjectStreamsEnabled​(boolean b)

      • getObjectCount

        public int getObjectCount()