Package org.openpdf.renderer

Class PDFObject

java.lang.Object
org.openpdf.renderer.PDFObject
public class PDFObject extends Object
a class encapsulating all the possibilities of content for an object in a PDF file.

A PDF object can be a simple type, like a Boolean, a Number, a String, or the Null value. It can also be a NAME, which looks like a string, but is a special type in PDF files, like "/Name".

A PDF object can also be complex types, including Array; Dictionary; Stream, which is a Dictionary plus an array of bytes; or Indirect, which is a reference to some other PDF object. Indirect references will always be dereferenced by the time any data is returned from one of the methods in this class.

  • Field Details

    • INDIRECT

      public static final int INDIRECT
      an indirect reference
      See Also:

    • BOOLEAN

      public static final int BOOLEAN
      a Boolean
      See Also:

    • NUMBER

      public static final int NUMBER
      a Number, represented as a double
      See Also:

    • STRING

      public static final int STRING
      a String
      See Also:

    • NAME

      public static final int NAME
      a special string, seen in PDF files as /Name
      See Also:

    • ARRAY

      public static final int ARRAY
      an array of PDFObjects
      See Also:

    • DICTIONARY

      public static final int DICTIONARY
      a Hashmap that maps String names to PDFObjects
      See Also:

    • STREAM

      public static final int STREAM
      a Stream: a Hashmap with a byte array
      See Also:

    • NULL

      public static final int NULL
      the NULL object (there is only one)
      See Also:

    • KEYWORD

      public static final int KEYWORD
      a special PDF bare word, like R, obj, true, false, etc
      See Also:

    • OBJ_NUM_EMBEDDED

      public static final int OBJ_NUM_EMBEDDED
      When a value of objNum or objGen, indicates that the object is not top-level, and is embedded in another object
      See Also:

    • OBJ_NUM_TRAILER

      public static final int OBJ_NUM_TRAILER
      When a value of objNum or objGen, indicates that the object is not top-level, and is embedded directly in the trailer.
      See Also:

    • nullObj

      public static final PDFObject nullObj
      the NULL PDFObject

    • type

      private int type
      the type of this object

    • value

      private Object value
      the value of this object. It can be a wide number of things, defined by type

    • stream

      private ByteBuffer stream
      the encoded stream, if this is a STREAM object

    • decodedStream

      private SoftReference decodedStream
      a cached version of the decoded stream

    • decodedStreamFilterLimits

      private Set<String> decodedStreamFilterLimits
      The filter limits used to generate the cached decoded stream

    • owner

      private final PDFFile owner
      the PDFFile from which this object came, used for dereferences

    • cache

      private SoftReference cache
      a cache of translated data. This data can be garbage collected at any time, after which it will have to be rebuilt.

    • objNum

      private int objNum
      See Also:

    • objGen

      private int objGen
      See Also:

  • Constructor Details

    • PDFObject

      public PDFObject(PDFFile owner, int type, Object value)
      create a new simple PDFObject with a type and a value
      Parameters:
      owner - the PDFFile in which this object resides, used for dereferencing. This may be null.
      type - the type of object
      value - the value. For DICTIONARY, this is a HashMap. for ARRAY it's an ArrayList. For NUMBER, it's a Double. for BOOLEAN, it's Boolean.TRUE or Boolean.FALSE. For everything else, it's a String.

    • PDFObject

      public PDFObject(Object obj) throws PDFParseException
      create a new PDFObject that is the closest match to a given Java object. Possibilities include Double, String, PDFObject[], HashMap, Boolean, or PDFParser.Tok, which should be "true" or "false" to turn into a BOOLEAN.
      Parameters:
      obj - the sample Java object to convert to a PDFObject.
      Throws:
      PDFParseException - if the object isn't one of the above examples, and can't be turned into a PDFObject.

    • PDFObject

      public PDFObject(PDFFile owner, PDFXref xref)
      create a new PDFObject based on a PDFXref
      Parameters:
      owner - the PDFFile from which the PDFXref was drawn
      xref - the PDFXref to turn into a PDFObject

  • Method Details

    • getDictRefAsString

      public String getDictRefAsString(String name) throws IOException
      Convenient method to get a dictionary value as String
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsBoolean

      public Boolean getDictRefAsBoolean(String name) throws IOException
      Convenient method to get a dictionary value as String
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsInt

      public Integer getDictRefAsInt(String name) throws IOException
      Convenient method to get a dictionary value as Integer
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsIntArray

      public int[] getDictRefAsIntArray(String name) throws IOException
      Convenient method to get a dictionary value as int[]
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsFloatArray

      public float[] getDictRefAsFloatArray(String name) throws IOException
      Convenient method to get a dictionary value as float[]
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsFloat

      public Float getDictRefAsFloat(String name) throws IOException
      Convenient method to get a dictionary value as Float
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getDictRefAsDouble

      public Double getDictRefAsDouble(String name) throws IOException
      Convenient method to get a dictionary value as Double
      Parameters:
      name - of the dictionary value
      Returns:
      the value or null if no entry exists with that name
      Throws:
      IOException

    • getType

      public int getType() throws IOException
      get the type of this object. The object will be dereferenced, so INDIRECT will never be returned.
      Returns:
      the type of the object
      Throws:
      IOException

    • setStream

      public void setStream(ByteBuffer data)
      set the stream of this object. It should have been a DICTIONARY before the call.
      Parameters:
      data - the data, as a ByteBuffer.

    • getCache

      public Object getCache() throws IOException
      get the value in the cache. May become null at any time.
      Returns:
      the cached value, or null if the value has been garbage collected.
      Throws:
      IOException

    • setCache

      public void setCache(Object obj) throws IOException
      set the cached value. The object may be garbage collected if no other reference exists to it.
      Parameters:
      obj - the object to be cached
      Throws:
      IOException

    • getStream

      public byte[] getStream(Set<String> filterLimits) throws IOException
      Throws:
      IOException

    • getStream

      public byte[] getStream() throws IOException
      get the stream from this object. Will return null if this object isn't a STREAM.
      Returns:
      the stream, or null, if this isn't a STREAM.
      Throws:
      IOException

    • getStreamBuffer

      public ByteBuffer getStreamBuffer() throws IOException
      get the stream from this object as a byte buffer. Will return null if this object isn't a STREAM.
      Returns:
      the buffer, or null, if this isn't a STREAM.
      Throws:
      IOException

    • getStreamBuffer

      public ByteBuffer getStreamBuffer(Set<String> filterLimits) throws IOException
      get the stream from this object as a byte buffer. Will return null if this object isn't a STREAM.
      Returns:
      the buffer, or null, if this isn't a STREAM.
      Throws:
      IOException

    • decodeStream

      private ByteBuffer decodeStream(Set<String> filterLimits) throws IOException
      Get the decoded stream value
      Throws:
      IOException

    • getIntValue

      public int getIntValue() throws IOException
      get the value as an int. Will return 0 if this object isn't a NUMBER.
      Throws:
      IOException

    • getFloatValue

      public float getFloatValue() throws IOException
      get the value as a float. Will return 0 if this object isn't a NUMBER
      Throws:
      IOException

    • getDoubleValue

      public double getDoubleValue() throws IOException
      get the value as a double. Will return 0 if this object isn't a NUMBER.
      Throws:
      IOException

    • getStringValue

      public String getStringValue() throws IOException
      get the value as a String. Will return null if the object isn't a STRING, NAME, or KEYWORD. This method will NOT convert a NUMBER to a String. If the string is actually a text string (i.e., may be encoded in UTF16-BE or PdfDocEncoding), then one should use getTextStringValue() or use one of the PDFStringUtil methods on the result from this method. The string value represents exactly the sequence of 8 bit characters present in the file, decrypted and decoded as appropriate, into a string containing only 8 bit character values - that is, each char will be between 0 and 255.
      Throws:
      IOException

    • getTextStringValue

      public String getTextStringValue() throws IOException
      Get the value as a text string; i.e., a string encoded in UTF-16BE or PDFDocEncoding. Simple latin alpha-numeric characters are preserved in both these encodings.
      Returns:
      the text string value
      Throws:
      IOException

    • getArray

      public PDFObject[] getArray() throws IOException
      get the value as a PDFObject[]. If this object is an ARRAY, will return the array. Otherwise, will return an array of one element with this object as the element.
      Throws:
      IOException

    • getBooleanValue

      public boolean getBooleanValue() throws IOException
      get the value as a boolean. Will return false if this object is not a BOOLEAN
      Throws:
      IOException

    • getAt

      public PDFObject getAt(int idx) throws IOException
      if this object is an ARRAY, get the PDFObject at some position in the array. If this is not an ARRAY, returns null.
      Throws:
      IOException

    • getDictKeys

      public Iterator getDictKeys() throws IOException
      get an Iterator over all the keys in the dictionary. If this object is not a DICTIONARY or a STREAM, returns an Iterator over the empty list.
      Throws:
      IOException

    • getDictionary

      public HashMap<String,PDFObject> getDictionary() throws IOException
      get the dictionary as a HashMap. If this isn't a DICTIONARY or a STREAM, returns null
      Throws:
      IOException

    • getDictRef

      public PDFObject getDictRef(String key) throws IOException
      get the value associated with a particular key in the dictionary. If this isn't a DICTIONARY or a STREAM, or there is no such key, returns null.
      Throws:
      IOException

    • isDictType

      public boolean isDictType(String match) throws IOException
      returns true only if this object is a DICTIONARY or a STREAM, and the "Type" entry in the dictionary matches a given value.
      Parameters:
      match - the expected value for the "Type" key in the dictionary
      Returns:
      whether the dictionary is of the expected type
      Throws:
      IOException

    • getDecrypter

      public PDFDecrypter getDecrypter()

    • setObjectId

      public void setObjectId(int objNum, int objGen)
      Set the object identifiers
      Parameters:
      objNum - the object number
      objGen - the object generation number

    • getObjNum

      public int getObjNum()
      Get the object number of this object; a negative value indicates that the object is not numbered, as it's not a top-level object: if the value is OBJ_NUM_EMBEDDED, it is because it's embedded within another object. If the value is OBJ_NUM_TRAILER, it's because it's an object from the trailer.
      Returns:
      the object number, if positive

    • getObjGen

      public int getObjGen()
      Get the object generation number of this object; a negative value indicates that the object is not numbered, as it's not a top-level object: if the value is OBJ_NUM_EMBEDDED, it is because it's embedded within another object. If the value is OBJ_NUM_TRAILER, it's because it's an object from the trailer.
      Returns:
      the object generation number, if positive

    • toString

      public String toString()
      return a representation of this PDFObject as a String. Does NOT dereference anything: this is the only method that allows you to distinguish an INDIRECT PDFObject.
      Overrides:
      toString in class Object

    • dereference

      public PDFObject dereference() throws IOException
      Make sure that this object is dereferenced. Use the cache of an indirect object to cache the dereferenced value, if possible.
      Throws:
      IOException

    • isIndirect

      public boolean isIndirect()
      Identify whether the object is currently an indirect/cross-reference
      Returns:
      whether currently indirect

    • equals

      public boolean equals(Object o)
      Test whether two PDFObject are equal. Objects are equal IFF they are the same reference OR they are both indirect objects with the same id and generation number in their xref
      Overrides:
      equals in class Object

    • getRoot

      public PDFObject getRoot()
      Returns the root of this object.
      Returns: