Package org.faceless.pdf2

Class EmbeddedFile

  • All Implemented Interfaces:
    Cloneable
    public final class EmbeddedFile
extends Object

    This class represents a file which may be embedded into a PDF document, either by using the AnnotationFile class, the getAssociatedFiles list on PDFPage or PDFAnnotation, by adding to the StructureTree, or (most typically) through the PDF.getEmbeddedFiles() map.

    Since 2.26 this class may represent a File or a Folder. Folders only make sense in the context of a PDF Portfolio, and that class has more detail on the structure. Attempting to use a folder EmbeddedFile in another context will result in an IllegalArgumentException. Folders return a List from getChildren(), and all EmbeddedFiles may have another EmbeddedFile returned from getParent().

    Since:
    2.6
    See Also:
    Portfolio, OutputProfile.getAssociatedFiles()

    • Constructor Detail

      • EmbeddedFile

        public EmbeddedFile​(File file)
             throws IOException
        Create a new EmbeddedFile object to embed the specified file.
        Parameters:
        file - the file to embed
        Throws:
        IOException

      • EmbeddedFile

        public EmbeddedFile​(File file,
                    String name)
             throws IOException
        Create a new EmbeddedFile object to embed the specified file.
        Parameters:
        file - the file to embed
        name - the name to give the file
        Throws:
        IOException
        Since:
        2.14.1

      • EmbeddedFile

        public EmbeddedFile​(InputStream in,
                    String name)
             throws IOException
        Set the content of this Embeddedfile to the specified InputStream. The InputStream is read completely but not closed.
        Parameters:
        in - the InputStream to read from - must not be null
        name - the filename - must not be null
        Throws:
        IOException

      • EmbeddedFile

        public EmbeddedFile​(PDF pdf,
                    String name)
             throws IOException
        Set the content of this EmbeddedFile to the specified PDF. The PDF is rendered to a stream, and from there treated as an ordinary file. The MIME-type, creation and modification date are all set with this constructor.
        Parameters:
        pdf - the PDF to store as an embedded file.
        name - the "filename" of the PDF to use when storing it internally.
        Throws:
        IOException
        Since:
        2.7.8

    • Method Detail

      • getOwners

        public Collection<Object> getOwners()

        Return the set of presumed "owners" of this EmbeddedFile - the object(s) the EmbeddedFile is associated with. This is populated when a full OutputProfile of the PDF is generated with the OutputProfiler class, and will otherwise be empty.

        The BFO API does not give full access to the PDF object model, and EmbeddedFiles can be associated with literally anything, including more than one object at a time. So in some cases the object returned will have no meaning, and may even be null if it cannot be determined. Where it is returned, in most cases it will be a PDF, PDFPage, PDFAnnotation, PDFImage or a Element accessible from the PDF.getStructureTree() method. All of these objects have methods for managing EmbeddedFiles directly. directly.

        Since:
        2.26
        See Also:
        XMP.getOwners(), OutputProfile.getAssociatedFiles()

      • createFolder

        public static EmbeddedFile createFolder​(String name)
        Create a new EmbeddedFile folder with the specified name
        Parameters:
        name - the name. The root folder typically has an empty name.
        Since:
        2.26

      • setName

        public void setName​(String name)
        Change the name on this file
        Parameters:
        name - the name, which must not be null
        Since:
        2.24.2

      • getName

        public String getName()
        Return the Filename of the file

      • setType

        public void setType​(String mimetype)
        Set the MIME type for this file attachment. This is optional but recommended, as it is not set automatically. Types on folders are ignored.
        Parameters:
        mimetype - the MIME type of the file

      • getType

        public String getType()
        Return the MIME type of this file attachment if specified, or null if not specified.

      • setDescription

        public void setDescription​(String desc)
        Set the optional description for this file.
        Parameters:
        desc - the description to use

      • setCreationDate

        public void setCreationDate​(Date date)

        Set the Creation Date of this file. Java has no way to detemine the creation date of a file (many operating systems don't have this concept), so this attribute is not set automatically.

        Call setCreationDate(Calendar) to set the date with timezone information.

        Parameters:
        date - the Creation Date of this file, which is assumed to be in the current timezone.

      • setCreationDate

        public void setCreationDate​(Calendar date)
        Set the Creation Date of this file. Java has no way to detemine the creation date of a file (many operating systems don't have this concept), so this attribute is not set automatically.
        Parameters:
        date - the Creation date of this file
        Since:
        2.26

      • getCreationDate

        public Date getCreationDate()
        Return the Creation Date of this file, or null if not specified. Call getCreationDateAsCalendar() to get timezone information.

      • getCreationDateAsCalendar

        public Calendar getCreationDateAsCalendar()
        Return the Creation Date of this file, or null if not specified.
        Since:
        2.26

      • setModDate

        public void setModDate​(Date date)

        Set the Last-modified Date of this file. When creating an EmbeddedFile from the EmbeddedFile(File) constructor, this value is initialised to the correct date.

        Call setModDate(Calendar) to set the date with timezone information.

        Parameters:
        date - the Last-Modified Date of this file, which is assumed to be in the current timezone.

      • setModDate

        public void setModDate​(Calendar date)

        Set the Last-modified Date of this file. When creating an EmbeddedFile from the EmbeddedFile(File) constructor, this value is initialised to the correct date.

        Parameters:
        date - the Last-modified Date of this file
        Since:
        2.26

      • getRelationship

        public String getRelationship()
        Get the "associated file relationship" field. This is an optional value in PDF 2.0 but is required in PDF/A-3 or later. Setting this on a Folder does nothing.
        Since:
        2.14.1

      • setRelationship

        public void setRelationship​(String name)
        Set the "associated file relationship" field, which defines the relationship between this file attachment and the PDF. This is an optional value in PDF 2.0 but required for PDF/A-3 or later. The value is normally one of "Source", "Data", "Alternative", "Supplement" or "Unspecified", but may be any value.
        Since:
        2.14.1

      • getModDate

        public Date getModDate()
        Return the Last-modified Date of this file, or null if not specified. Call getModDateAsCalendar() to get timezone information (preferred).

      • getModDateAsCalendar

        public Calendar getModDateAsCalendar()
        Return the Last-modified Date of this file, or null if not specified.
        Since:
        2.26

      • getSize

        public long getSize()
        Return the size of the attached file, or -1 if not specified or its a folder. A file always has a size of course, but that size isn't always stored in the PDF. If this method returns -1 there is no way to determine the size of the file without reading it.
        Returns:
        the stored file size.

      • getCompressedSize

        public long getCompressedSize()
        Return the compressed size of the attached file. Unlike getSize(), this property is inherent to the way the PDF stores the data, so is always known.

      • getData

        public InputStream getData()
        Return the attached file as an InputStream, or null if the file is not attached and is referenced by name only, or its a folder.

      • getPDF

        public PDF getPDF()
           throws IOException
        If this EmbeddedFile contains a PDF object, parse it and return it.
        Throws:
        IOException
        Since:
        2.24.3

      • hasPDF

        public boolean hasPDF()
        Return true if this EmbeddedFile has previously returned a PDF from getPDF(). This method is a simple comparison and returns immediately.
        Since:
        2.26

      • isValid

        public boolean isValid()

        Returns true if the file matches the stored checksum or if no checksum is specified. Note most files are stored compressed using the Flate algorithm, which is self-checksumming, so this method is a little redundant. However the MD5 checksum optionally stored with embedded files is much stronger, so we provide this method for completeness.

        Note that if no checksum is stored this method returns true, so although a false definitely indicates a corrupt file, a true doesn't guarantee that it isn't corrupt.

        Returns:
        true if the file is a folder, has no checksum, or has a checksum which matches the file.

      • getXMP

        public XMP getXMP()
        Return an XMP Metadata object representing any XML metadata associated with this object
        Returns:
        the XMP, which may be empty or invalid but will never be null
        Since:
        2.27.2

      • getAssociatedFiles

        public Collection<EmbeddedFile> getAssociatedFiles()
        Return the list of embedded files assocatiated with this file. The list is live and can be edited. The ability to associate files with an EmbeddedFile is new in PDF 2.0. In general, associating a file with another file is probably not something that should be done without a specific requirement.
        Since:
        2.27.2
        See Also:
        AnnotationFile

      • setPortfolioFolder

        public void setPortfolioFolder​(String foldername)
        Deprecated.
        see the Portfolio class for details on how to manager Portfolios since 2.26
        Set the name of the folder this EmbeddedFile should be stored in when the PDF is a Portfolio. Folders are only supported in Acrobat X and later, and the folder name must be set before the EmbeddedFile is added to the PDF.getEmbeddedFiles() map.
        Parameters:
        foldername - the folder name - subfolders are delimetered with the "/" character, eg /folder1/subfolder2
        Throws:
        IllegalStateException - if this is called after this object is added to the PDF
        Since:
        2.14.1

      • getPortfolioFolder

        public String getPortfolioFolder()
        Return the name of the folder. Since 2.26 this is formed by concatenating the chain of ancestors from getParent() with the "/" character. If no parent is set, this method returns "/"
        Since:
        2.14.1

      • putUserData

        public void putUserData​(String key,
                        Object value)
        Set a custom property on the PDF. The property will be saved with the file with the "BFOO_" prefix.
        Parameters:
        value - a CharSequence, Number, Date, Calendar, Boolean, byte[], or a List/Map of those values, or null to remove the property
        Since:
        2.24.2

      • getUserData

        public Object getUserData​(String key)
        Return a property previously set on the PDF with the putUserData() method
        Returns:
        a String, Boolean, Number, Calendar, byte[] or a Map/List of those values if found, or null if no such property exists.
        Since:
        2.24.2

      • getProperties

        public Map<String,​Object> getProperties()
        Return an editable map of general properties set on this EmbeddedFile. This is particularly useful with a PDF Portfolio, but can be used for any embedded file. Any key can be used except "Type", and values must be of type CharSequence, Number, Date or Calendar. Null keys or values are not allowed. The key names should match a Portfolio.FieldType entry set in the Portfolio.getSchema() map.
        Since:
        2.26
        See Also:
        Portfolio

      • isFolder

        public boolean isFolder()
        Return true if this EmbeddedFile represents a Folder, false if it represents a File.
        Since:
        2.26

      • getParent

        public EmbeddedFile getParent()
        If this EmbeddedFile is inside a Folder, return the parent folder, otherwise return null.
        Returns:
        the parent folder
        Since:
        2.26

      • getChildren

        public List<EmbeddedFile> getChildren()
        If this EmbeddedFile is a Folder, return a list of its children. The returned list is live and can be edited. Unlike normal lists, an item may only exist in it once, so care should be taken when editing it with an iterator. The returned list is linked, not sequential. It may not contain null values. Attempting to add an item that already has a parent will remove that item from that parent.
        Returns:
        a List of children if this is a Folder, or null if this is a File.
        Since:
        2.26

      • getSourcePDF

        public PDF getSourcePDF()
        Return the PDF that "owns" this EmbeddedFile - the PDF which most recently contained this object in its PDF.getEmbeddedFiles() map. If this is not set, this method returns null.
        Since:
        2.26.

      • toString

        public String toString()

      • putLiteral

        public void putLiteral​(String key,
                       String tokens)
        Put a literal token sequnce. For debugging
        Parameters:
        key - the key
        tokens - the token sequence, eg "true" or "/foo" or "[/Foo/Bar]". No refs, just direct objects.