org.apache.fop.pdf

## Class PDFObject

- java.lang.Object
- - org.apache.fop.pdf.PDFObject

- All Implemented Interfaces:
    PDFWritable
  Direct Known Subclasses:
    AbstractPDFStream, PDFAction, PDFAnnotList, PDFArray, PDFCharProcs, PDFCIDFont, PDFCIDSystemInfo, PDFDestination, PDFDictionary, PDFEncryptionJCE, PDFFunction, PDFGState, PDFICCBasedColorSpace, PDFInfo, PDFLink, PDFName, PDFNumber, PDFNumsArray, PDFOutline, PDFOutputIntent, PDFPages, PDFPathPaint, PDFShading, PDFText

      public abstract class PDFObject
      extends Object
      implements PDFWritable

  generic PDF object. A PDF Document is essentially a collection of these objects. A PDF Object has a number and a generation (although the generation will always be 0 in new documents).

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static org.apache.commons.logging.Log` | `log` logger for all PDFObjects (and descendants)

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `PDFObject()` Default constructor.
    `PDFObject(PDFObject parent)` Constructor for direct objects.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected boolean` | `contentEquals(PDFObject o)` Check if the other PDFObject has the same content as the current object.
    `static byte[]` | `encode(String text)` Converts text to a byte array for writing to a PDF file.
    `protected void` | `encodeBinaryToHexString(byte[] data, OutputStream out)` Encodes binary data as hexadecimal string object.
    `protected byte[]` | `encodeString(String string)` Encodes a String (3.2.3 in PDF 1.4 specs)
    `protected byte[]` | `encodeText(String text)` Encodes a Text String (3.8.1 in PDF 1.4 specs)
    `protected void` | `formatObject(Object obj, OutputStream out, StringBuilder textBuffer)` Formats an object for serialization to PDF.
    `void` | `getChildren(Set<PDFObject> children)`
    `PDFDocument` | `getDocument()` Returns the parent PDFDocument if assigned.
    `PDFDocument` | `getDocumentSafely()` Returns the parent PDFDocument, but unlike `getDocument()` it throws an informative Exception if the parent document is unavailable instead of having a NullPointerException somewhere without a message.
    `int` | `getGeneration()` Returns this object's generation.
    `String` | `getObjectID()` Returns the PDF representation of the Object ID.
    `PDFObjectNumber` | `getObjectNumber()` Returns the object's number.
    `PDFObject` | `getParent()` Returns this objects's parent.
    `boolean` | `hasObjectNumber()` Indicates whether this PDFObject has already been assigned an object number.
    `PDFReference` | `makeReference()` Creates and returns a reference to this object.
    `int` | `output(OutputStream stream)` Write the PDF represention of this object
    `void` | `outputInline(OutputStream out, StringBuilder textBuffer)` Writes a "direct object" (inline object) representation to the stream.
    `String` | `referencePDF()` Returns the PDF representation of a reference to this object.
    `void` | `setDocument(PDFDocument doc)` Sets the parent PDFDocument.
    `void` | `setObjectNumber(int objectNumber)`
    `void` | `setObjectNumber(PDFDocument document)` Sets the object number
    `void` | `setObjectNumber(PDFObjectNumber objectNumber)`
    `void` | `setParent(PDFObject parent)` Sets the direct parent object.
    `protected byte[]` | `toPDF()` Encodes the object as a byte array for output to a PDF file.
    `protected String` | `toPDFString()` This method returns a String representation of the PDF object.

    - ### Methods inherited from class java.lang.Object

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

- - ### Field Detail

    - #### log

          protected static final org.apache.commons.logging.Log log

      logger for all PDFObjects (and descendants)

  - ### Constructor Detail

    - #### PDFObject

          public PDFObject()

      Default constructor.

    - #### PDFObject

          public PDFObject(PDFObject parent)

      Constructor for direct objects.
      Parameters:
        `parent` - the containing PDFObject instance

  - ### Method Detail

    - #### getObjectNumber

          public PDFObjectNumber getObjectNumber()

      Returns the object's number.
      Returns:
        the PDF Object number

    - #### hasObjectNumber

          public boolean hasObjectNumber()

      Indicates whether this PDFObject has already been assigned an object number.
      Returns:
        True if it has an object number

    - #### setObjectNumber

          public void setObjectNumber(PDFDocument document)

      Sets the object number

    - #### setObjectNumber

          public void setObjectNumber(PDFObjectNumber objectNumber)

    - #### setObjectNumber

          public void setObjectNumber(int objectNumber)

    - #### getGeneration

          public int getGeneration()

      Returns this object's generation.
      Returns:
        the PDF Object generation

    - #### getDocument

          public final PDFDocument getDocument()

      Returns the parent PDFDocument if assigned.
      Returns:
        the parent PDFDocument (May be null if the parent PDFDocument has not been assigned)

    - #### getDocumentSafely

          public final PDFDocument getDocumentSafely()

      Returns the parent PDFDocument, but unlike `getDocument()` it throws an informative Exception if the parent document is unavailable instead of having a NullPointerException somewhere without a message.
      Returns:
        the parent PDFDocument

    - #### setDocument

          public void setDocument(PDFDocument doc)

      Sets the parent PDFDocument.
      Parameters:
        `doc` - the PDFDocument.

    - #### getParent

          public PDFObject getParent()

      Returns this objects's parent. The parent is null if it is a "direct object".
      Returns:
        the parent or null if there's no parent (or it hasn't been set)

    - #### setParent

          public void setParent(PDFObject parent)

      Sets the direct parent object.
      Parameters:
        `parent` - the direct parent

    - #### getObjectID

          public String getObjectID()

      Returns the PDF representation of the Object ID.
      Returns:
        the Object ID

    - #### referencePDF

          public String referencePDF()

      Returns the PDF representation of a reference to this object.
      Returns:
        the reference string

    - #### makeReference

          public PDFReference makeReference()

      Creates and returns a reference to this object.
      Returns:
        the object reference

    - #### output

          public int output(OutputStream stream)
                     throws IOException

      Write the PDF represention of this object
      Parameters:
        `stream` - the stream to write the PDF to
      Returns:
        the number of bytes written
      Throws:
        `IOException` - if there is an error writing to the stream

    - #### outputInline

          public void outputInline(OutputStream out,
                                   StringBuilder textBuffer)
                            throws IOException

      Writes a "direct object" (inline object) representation to the stream. A text buffer is given for optimized encoding of text content.

      IMPORTANT: If you need to write out binary output, call `PDFDocument.flushTextBuffer(StringBuilder, OutputStream)` before writing any content to the `OutputStream`!

      Specified by:
        `outputInline` in interface `PDFWritable`
      Parameters:
        `out` - the OutputStream (for binary content)
        `textBuffer` - the text buffer for text content
      Throws:
        `IOException` - if an I/O error occurs

    - #### toPDF

          protected byte[] toPDF()

      Encodes the object as a byte array for output to a PDF file.
      Returns:
        PDF string

    - #### toPDFString

          protected String toPDFString()

      This method returns a String representation of the PDF object. The result is normally converted/encoded to a byte array by toPDF(). Only use this method to implement the serialization if the object can be fully represented as text. If the PDF representation of the object contains binary content use toPDF() or output(OutputStream) instead. This applies to any object potentially containing a string object because string object are encrypted and therefore need to be binary.
      Returns:
        String the String representation

    - #### encode

          public static final 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

    - #### encodeText

          protected byte[] encodeText(String text)

      Encodes a Text String (3.8.1 in PDF 1.4 specs)
      Parameters:
        `text` - the text to encode
      Returns:
        byte[] the encoded text

    - #### encodeString

          protected byte[] encodeString(String string)

      Encodes a String (3.2.3 in PDF 1.4 specs)
      Parameters:
        `string` - the string to encode
      Returns:
        byte[] the encoded string

    - #### encodeBinaryToHexString

          protected void encodeBinaryToHexString(byte[] data,
                                                 OutputStream out)
                                          throws IOException

      Encodes binary data as hexadecimal string object.
      Parameters:
        `data` - the binary data
        `out` - the OutputStream to write the encoded object to
      Throws:
        `IOException` - if an I/O error occurs

    - #### formatObject

          protected void formatObject(Object obj,
                                      OutputStream out,
                                      StringBuilder textBuffer)
                               throws IOException

      Formats an object for serialization to PDF.

      IMPORTANT: If you need to write out binary output, call `PDFDocument.flushTextBuffer(StringBuilder, OutputStream)` before writing any content to the `OutputStream`!

      Parameters:
        `obj` - the object
        `out` - the OutputStream to write to
        `textBuffer` - a text buffer for text output
      Throws:
        `IOException` - If an I/O error occurs

    - #### contentEquals

          protected boolean contentEquals(PDFObject o)

      Check if the other PDFObject has the same content as the current object.

      Note: This function has a contract which is less binding than `Object.equals(Object)`. Whereas equals would require all values to be identical, this method is not required to check everything. In the case of PDFObjects, this means that the overriding function does not have to check for `getObjectID()`.

      Parameters:
        `o` - object to compare to.
      Returns:
        true if the other object has the same content.

    - #### getChildren

          public void getChildren(Set<PDFObject> children)

Copyright © 2023 Apache Software Foundation. All rights reserved.