Package com.pd4ml.pdf.cos

Class COSDocument

  • All Implemented Interfaces:
    java.io.Closeable, java.lang.AutoCloseable
    public class COSDocument
extends java.lang.Object
implements java.io.Closeable
    The in-memory representation of a whole PDF file's COS layer: the table of indirect objects keyed by COSObjectKey, and the trailer dictionary that names the document's root ("Catalog") and other special objects.

    A document can either be built up programmatically (see setObject(com.pd4ml.pdf.cos.COSObjectKey, com.pd4ml.pdf.cos.COSBase)) or produced by COSParser from the bytes of an actual PDF file. Either way, this is also the natural starting point for COSPathEvaluator queries.

    Thread-safety: the object table is safe for concurrent setObject(com.pd4ml.pdf.cos.COSObjectKey, com.pd4ml.pdf.cos.COSBase) calls from multiple threads (e.g. COSObjectImporter cloning several distinct source objects into one shared target document in parallel) -- it is a synchronized map, not a plain LinkedHashMap, specifically to avoid silently losing entries under concurrent put(). Insertion order is still preserved for callers that iterate getObjects()/getObjectKeys() without their own explicit sort. As with any synchronized-collection wrapper, a caller that iterates one of those views while another thread is still writing needs its own external synchronization on the returned document instance; the normal "build fully, then read" usage pattern (all writes happen-before the read, e.g. via thread join/executor completion) needs none. Other mutable fields here (trailer, version, etc.) are plain, unsynchronized fields -- this class is meant to be built up by one thread (or several threads only through setObject) and then safely published/read, not mutated concurrently in general.

    • Constructor Detail

      • COSDocument

        public COSDocument()

    • Method Detail

      • getVersion

        public float getVersion()

      • setVersion

        public void setVersion​(float version)

      • isEncrypted

        public boolean isEncrypted()
        True if this document's trailer names an /Encrypt dictionary (regardless of whether the password supplied to the parser actually worked -- see getEncryptionError() to tell those apart). Strings and streams are decrypted in place as the document is parsed, so once this returns true with no encryption error, every other accessor in this API already returns plaintext and there is nothing further to do.

      • setEncrypted

        public void setEncrypted​(boolean encrypted)

      • getEncryptionError

        public COSSecurityException getEncryptionError()
        Non-null when this document is encrypted but the password given to COSParser could not be authenticated as either the user or the owner password -- in that case, strings and streams throughout the document are still in their encrypted form.

      • getCatalog

        public COSDictionary getCatalog()
        The document catalog, i.e. trailer/Root, or null if the trailer has no (resolvable) Root entry.

      • setObject

        public void setObject​(COSObjectKey key,
                      COSBase value)
        Registers/overwrites the object stored under key. Used both by the parser (as it reads "n g obj ... endobj" bodies) and by in-memory document construction.

      • getObject

        public COSBase getObject​(COSObjectKey key)
        Looks up an already-registered object. Parsers that support lazy / on-demand parsing should override or wrap this class so a cache miss triggers parsing the object at its recorded file offset; this base implementation assumes eager loading (which is what COSParser.parse() does).

      • hasObject

        public boolean hasObject​(COSObjectKey key)

      • removeObject

        public void removeObject​(COSObjectKey key)
        Deregisters the object stored under key, if any. Used by callers that build up a document incrementally and then discard objects that turned out unreachable from the trailer's /Root (e.g. com.pd4ml.pdf.merge's post-clone reachability sweep, which drops structure-tree clones dragged in transitively via a /Pg reference to a page that wasn't actually selected).

      • getObjectKeys

        public java.util.Collection<COSObjectKey> getObjectKeys()

      • getObjects

        public java.util.Collection<COSBase> getObjects()

      • size

        public int size()

      • getHighestObjectNumber

        public long getHighestObjectNumber()
        Allocates the next free object number, for building new indirect objects programmatically.

      • createNewIndirectObject

        public COSObject createNewIndirectObject​(COSBase value)

      • setSourceToClose

        public void setSourceToClose​(java.io.Closeable source)
        Wires up a resource (e.g. the open file/stream the parser is reading from) that should be released when this document is closed.

      • close

        public void close()
           throws java.io.IOException
        Specified by:
        close in interface java.lang.AutoCloseable
        Specified by:
        close in interface java.io.Closeable
        Throws:
        java.io.IOException