Package com.snowtide.pdf

Interface Document

    • Field Summary

      Fields 
      Modifier and Type Field Description
      static String ATTR_AUTHOR
      Document attribute key used to retrieve a String indicating who created a PDF document.
      static String ATTR_CREATION_DATE
      Document attribute key used to retrieve a String indicating the date and time that a PDF document was created.
      static String ATTR_CREATOR
      Document attribute key used to retrieve a String indicating the name of the application that created the original document from which the PDF was generated.
      static String ATTR_KEYWORDS
      Document attribute key used to retrieve a String containing keywords associated with a PDF document.
      static String ATTR_MOD_DATE
      Document attribute key used to retrieve a String indicating the date and time that a PDF document was last modified.
      static String ATTR_PRODUCER
      Document attribute key used to retrieve a String indicating the name of the application that generated a PDF document.
      static String ATTR_SUBJECT
      Document attribute key used to retrieve a String indicating the subject of a PDF document.
      static String ATTR_TITLE
      Document attribute key used to retrieve a String indicating the title of a PDF document.
      static String ATTR_TRAPPED
      Document attribute key used to retrieve an indicator as to whether a PDF document includes trapping information (trapping is a method for correcting printing errors in high-quality printing environments).
      static String ATTR_USES_GRAPH_FONTS
      Some PDF files use fonts that are image-based -- instead of their encodings mapping character codes to standard Unicode characters, they map character codes to images of characters.

    • Field Detail

      • ATTR_CREATOR

        static final String ATTR_CREATOR
        Document attribute key used to retrieve a String indicating the name of the application that created the original document from which the PDF was generated.
        See Also:
        getAttribute(String), Constant Field Values

      • ATTR_TRAPPED

        static final String ATTR_TRAPPED
        Document attribute key used to retrieve an indicator as to whether a PDF document includes trapping information (trapping is a method for correcting printing errors in high-quality printing environments). This key maps to a String, the valid values of which are 'False' and 'Unknown'.
        See Also:
        getAttribute(String), Constant Field Values

      • ATTR_USES_GRAPH_FONTS

        static final String ATTR_USES_GRAPH_FONTS

        Some PDF files use fonts that are image-based -- instead of their encodings mapping character codes to standard Unicode characters, they map character codes to images of characters. This makes it possible for these kinds of fonts (typically referred to as Type3 fonts) to, for example, map the character code 32 to the image of a letter 'g' instead of the standard space character.

        PDFxStream can derive the Unicode encoding of Type3 fonts in many cases, and will do so automatically if possible. Otherwise, content that uses a Type3 font for which no proper encoding can be derived will be skipped, and a document attribute with this key will be set and mapped to a Boolean object with a value of true.

        See Also:
        getAttribute(String), Constant Field Values

    • Method Detail

      • getPdfFileSize

        long getPdfFileSize()
        Returns the size of the PDF file being read, in bytes.
        Since:
        v1.3

      • getPageCnt

        int getPageCnt()
        Returns the number of pages in the PDF document.

      • getPage

        Page getPage​(int n)
      throws IOException
        Reads and returns a single page. Page numbers are zero-indexed; they do not necessarily correspond with any reader-visible page number.
        Parameters:
        n - the number of the page to retrieve.
        Throws:
        IOException - if an error occurs while preparing the Page for use
        Since:
        v1.3

      • getPages

        List<Page> getPages()
        Returns a list of pages from this Document, which are loaded lazily when accessed via the returned list.
        Since:
        v3.0

      • getName

        String getName()
        Returns the name of the PDF that this Document is reading; this will be either the name of the PDF file that is being read, or the pdfName String that was provided if this Document was opened using one of the com.snowtide.PDF.open() methods that accepts an InputStream or ByteBuffer, e.g. PDF.open(java.io.InputStream, String)

        Nearly all of the logging messages generated by PDFxStream include the relevant Document's name, making them easier to interpret in a multithreaded production environment.

      • getPDFFile

        File getPDFFile()
        Returns a reference to the file that this Document is processing. This reference may be null if the Document instance is not reading from a File or InputStream.

      • getFormData

        Form getFormData()
          throws IOException
        Loads the form data contained in the current document, and returns a Form object that represents that data. If the current PDF contains no forms, this function returns null. The Form instance that is returned by this function is guaranteed to be an AcroForm.

        This function MUST NOT be called after this Document is closed.

        Throws:
        IOException - if an error occurs loading the form data

      • getAllEmbeddedFiles

        List<EmbeddedFile> getAllEmbeddedFiles()
                                throws IOException
        Returns a list of all of the embedded files available in the source PDF. This method includes all files associated with annotations as well; if you only want those embedded files that are associated with the source document itself (and not annotations), use getEmbeddedFiles().
        Throws:
        IOException - if reading the embedded file metadata fails
        Since:
        3.0.0
        See Also:
        getEmbeddedFiles()

      • getBookmarks

        Bookmark getBookmarks()
               throws IOException
        If the current PDF document contains a bookmark tree, this function will return its root node. If the document contains no bookmarks, this function will return null.

        An exception will be thrown if this function is called after this Document instance is closed.

        Throws:
        IOException - if an error occurs reading the bookmark tree
        Since:
        v1.3.5
        See Also:
        Bookmark

      • getAnnotations

        List<Annotation> getAnnotations​(int page)
                         throws IOException
        Returns a List of all annotations found on the page indicated by the given page number; each object will be an instance of a class that implements the Annotation interface.

        This function will never return null; if a page contains no annotations, an empty list will be returned. The returned list is guaranteed to offer efficient random access to its elements.

        Throws:
        IOException - if an error occurs retrieving the annotation data
        Since:
        v1.3.5
        See Also:
        Annotation

      • getAllAnnotations

        List<Annotation> getAllAnnotations()
                            throws IOException
        Returns a list containing all of the Annotations contained in the current PDF document. The returned list is guaranteed to offer efficient random access to its elements.
        Throws:
        IOException - if an error occurs retrieving the annotation data
        Since:
        v1.3.5

      • getAllAnnotations

        int getAllAnnotations​(List tgt)
               throws IOException
        Adds to the given List all of the Annotations contained in the current PDF document.
        Returns:
        the number of annotations added to the list
        Throws:
        IOException - if an error occurs retrieving the annotation data
        Since:
        v1.3.5
        See Also:
        Annotation

      • getPDFVersion

        PDFVersion getPDFVersion()
                  throws IOException

        Returns the PDFVersion instance that corresponds with the version of the PDF file specification to which current PDF file adheres. PDF specification version numbers correspond directly with particular versions of Adobe Acrobat:

        • v1.0 - Acrobat 1
        • v1.1 - Acrobat 2
        • v1.2 - Acrobat 3
        • v1.3 - Acrobat 4
        • v1.4 - Acrobat 5
        • v1.5 - Acrobat 6
        • v1.6 - Acrobat 7
        • v1.7 - Acrobat 8+

        This method may not be called after the Document is closed.

        Throws:
        IOException - if an error occurs in determining what the PDF file's version is
        Since:
        v1.3

      • getEncryptionInfo

        EncryptionInfo getEncryptionInfo()
        Returns an EncryptionInfo object, which provides access to some of the parameters used for the current PDF document's encryption.

        If the current PDF document is not encrypted, this method will return null.

        Since:
        v1.3

      • getXmlMetadata

        byte[] getXmlMetadata()
               throws IOException

        Returns the XML metadata available from this Document, or null if no XML metadata is available.

        Note: This method must be called before the Document is closed, and it should not be called while text is being actively read out of it. (Supporting such concurrency would require synchronization that would negatively impact performance.) Therefore, the best times to call this method are:

        • just after opening the Document but before reading text out of it
        • after all text has been read out of the Document, but before it is closed

        PDFxStream does not control the content returned by this method -- it just provides access to the data that is already stored in a PDF document. The schema of the the returned XML data is defined by Adobe, and is called the Extensible Metadata Platform (XMP). More information about XMP can be found on Adobe's website

        Throws:
        IOException - if this Document has already been closed, or if an error occurs retrieving the XML metadata.
        Since:
        v1.2

      • getAttribute

        Object getAttribute​(String attrName)
             throws IOException
        Returns the value of the specified document-level metadata attribute.

        All of the standard attribute names are defined in constants in this class, and are all prefixed with 'ATTR_'. A few notes should be kept in mind when accessing attribute values:

        • It is typical for only a subset of the possible attributes to be defined in a PDF document. Any attributes that are undefined will return a null value when their name is provided to this method.
        • Many more attributes are used in the real world than are formally specified by the PDF specification. It is entirely up to the PDF generator what attributes are to be outputted for a particular document, so some documents may contain attributes whose names are not canonicalized in the 'ATTR_' constants in this class. You can use the getAttributeKeys() method to get a Set of the names of all available attributes.
        • Most attribute values are Strings, but it is possible for attribute values to be Integers, Booleans, etc. The documentation associated with each attribute name constant in this class specifies what type may be expected when retrieving each particular attribute value. Any attributes specified as dates are returned from this method as String instances; these can be passed through parseDateString(String) to get a Date object.

        Note: the attributes available through this method are retrieved from the "classic" document /Info entry. The document metadata in an XML format (which typically contains the same set of metadata attributes that are available through this method) may be obtained via the getXmlMetadata() method.

        Parameters:
        attrName - the name of the attribute to be retrieved
        Returns:
        the value of the attribute with the given name defined in the PDF document being read, or null if no attribute is available with the given name. The type of this object depends upon which attribute is being retrieved, and is noted in the documentation of the attribute name constants held by this class.
        Throws:
        IOException - if an error occurs while retrieving the PDF document's metadata
        See Also:
        getXmlMetadata() for access to the XML-formatted document metadata

      • getAttributeKeys

        Set<String> getAttributeKeys()
                      throws IOException
        Returns a Set containing the keys of all available document metadata attributes.
        Throws:
        IOException - if an error occurs while retrieving the PDF document's metadata

      • getAttributeMap

        Map<String,​Object> getAttributeMap()
                                  throws IOException
        Returns a Map containing a copy of all keys and values of all available document metadata attributes.
        Throws:
        IOException - if an error occurs while retrieving the PDF document's metadata