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

    All Methods Static Methods Instance Methods Concrete Methods Deprecated 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 `PDFFilter`s 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()`
    `boolean` | `isMergeFormFieldsEnabled()`
    `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.
    `<T extends PDFObject> T` | `registerTrailerObject(T obj)` Registers a `PDFObject` in this PDF document at end.
    `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` | `setMergeFormFieldsEnabled(boolean mergeFormFieldsEnabled)`
    `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 `PDFFilter`s 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)

    - #### 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

    - #### 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)

    - #### isMergeFormFieldsEnabled

          public boolean isMergeFormFieldsEnabled()

    - #### setMergeFormFieldsEnabled

          public void setMergeFormFieldsEnabled(boolean mergeFormFieldsEnabled)

    - #### isLinearizationEnabled

          public boolean isLinearizationEnabled()

    - #### setLinearizationEnabled

          public void setLinearizationEnabled(boolean b)

    - #### isFormXObjectEnabled

          public boolean isFormXObjectEnabled()

    - #### setFormXObjectEnabled

          public void setFormXObjectEnabled(boolean b)

Copyright © 2023 Apache Software Foundation. All rights reserved.