Package com.pdftools.toolbox.pdf

Class FileReference

java.lang.Object

com.pdftools.toolbox.internal.NativeBase

com.pdftools.toolbox.internal.NativeObject

com.pdftools.toolbox.pdf.FileReference

public class FileReference
extends NativeObject

Description of a file

A file description is used for embedded files.

Method Summary

Modifier and Type	Method	Description
static FileReference	copy(Document targetDocument, FileReference fileReference)	Copy a file reference object
static FileReference	create(Document targetDocument, Stream data, java.lang.String name, java.lang.String mediaType, java.lang.String description, java.time.OffsetDateTime modificationDate)	Create a new file reference object
java.lang.String	getAssociationRelationship()	The file's association relationship (Getter)
Stream	getData()	The file's stream (Getter)
java.lang.String	getDescription()	The file's description (Getter)
java.lang.String	getMediaType()	The file's MIME type (Getter)
java.time.OffsetDateTime	getModificationDate()	The file's date of last modification (Getter)
java.lang.String	getName()	The file name (Getter)
void	setAssociationRelationship(java.lang.String value)	The file's association relationship (Setter)

Methods inherited from class com.pdftools.toolbox.internal.NativeObject

equals, hashCode

Methods inherited from class java.lang.Object

getClass, notify, notifyAll, toString, wait, wait, wait

Method Detail

create

public static FileReference create(Document targetDocument,
                                   Stream data,
                                   java.lang.String name,
                                   java.lang.String mediaType,
                                   java.lang.String description,
                                   java.time.OffsetDateTime modificationDate)
                            throws java.io.IOException,
                                   ConformanceException

Create a new file reference object

The newly created file reference object belongs to the document but is not (yet) used as an embedded file. The object can be added to the list of embedded files or to the list of associated files.

Parameters:

targetDocument - the output document with which the returned object is associated

data - A stream of the file to be added. Read access is required.

name - The name to be used for the embedded file. This name is presented to the user when viewing the list of embedded files.

mediaType - The mime type of the embedded file. Default: "application/octet-stream". Common values other than the default are "application/pdf", "application/xml", or "application/msword".

description - The description of the embedded file. This is presented to the user when viewing the list of embedded files.

modificationDate - The modify date of the file. Default: current time.

Returns:

the newly created file reference object

Throws:

java.lang.IllegalArgumentException - if the targetDocument argument has already been closed

java.lang.IllegalArgumentException - if the targetDocument argument is read-only

java.lang.IllegalArgumentException - if the name argument is an empty string

ConformanceException - if the document's conformance is PDF/A-1

ConformanceException - if the document's conformance is PDF/A-2 and the given data contains a file other than PDF/A-1 or PDF/A-2

java.io.IOException - Error reading from the stream.

java.lang.IllegalArgumentException - if targetDocument is null

java.lang.IllegalArgumentException - if data is null

java.lang.IllegalArgumentException - if name is null

copy

public static FileReference copy(Document targetDocument,
                                 FileReference fileReference)
                          throws java.io.IOException,
                                 ConformanceException

Copy a file reference object

Copy a file reference object from an input document to the given targetDocument. The returned object is associated with the given target document but not yet part of it.

Parameters:

targetDocument - the output document with which the returned object is associated

fileReference - a file reference object of a different document

Returns:

the copied file reference, associated with the current document

Throws:

java.lang.IllegalArgumentException - if the targetDocument argument has already been closed

java.lang.IllegalArgumentException - if the targetDocument argument is read-only

java.lang.IllegalArgumentException - if the fileReference argument is not associated with an input document

java.lang.IllegalArgumentException - if the fileReference object has already been closed

ConformanceException - if the document's conformance is PDF/A-1

ConformanceException - if the document's conformance is PDF/A-2 and the fileReference object contains an embedded file other than PDF/A-1 or PDF/A-2

java.io.IOException - Error reading from the input stream or writing to the output stream

java.lang.IllegalArgumentException - if targetDocument is null

java.lang.IllegalArgumentException - if fileReference is null

getAssociationRelationship

public java.lang.String getAssociationRelationship()

The file's association relationship (Getter)

This property is null if the file is not associated with any object. When associating a file reference with an object such as the document or a page, then this property defines the relationship between the file and the object. Typical values are:

• "Source": used if this file is the original source material for the associated content.
• "Data": used if this file represents information used to derive a visual presentation such as for a table or a graph.
• "Alternative": used if this file is an alternative representation of content, for example audio.
• "Supplement": used if this file represents a supplemental representation of the original source or data that may be more easily consumable (e.g., a MathML version of an equation).
• "EncryptedPayload": used if this file is an encrypted payload document that should be displayed to the user if the PDF processor has the cryptographic filter needed to decrypt the document.
• "FormData": used if this file is the data associated with form fields of this PDF.
• "Schema": used if this file is a schema definition for the associated object.
• "Unspecified": used when the relationship is not known.

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

setAssociationRelationship

public void setAssociationRelationship(java.lang.String value)

The file's association relationship (Setter)

This property is null if the file is not associated with any object. When associating a file reference with an object such as the document or a page, then this property defines the relationship between the file and the object. Typical values are:

• "Source": used if this file is the original source material for the associated content.
• "Data": used if this file represents information used to derive a visual presentation such as for a table or a graph.
• "Alternative": used if this file is an alternative representation of content, for example audio.
• "Supplement": used if this file represents a supplemental representation of the original source or data that may be more easily consumable (e.g., a MathML version of an equation).
• "EncryptedPayload": used if this file is an encrypted payload document that should be displayed to the user if the PDF processor has the cryptographic filter needed to decrypt the document.
• "FormData": used if this file is the data associated with form fields of this PDF.
• "Schema": used if this file is a schema definition for the associated object.
• "Unspecified": used when the relationship is not known.

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

java.lang.UnsupportedOperationException - the document is read-only

getDescription

public java.lang.String getDescription()

The file's description (Getter)

For embedded files, this is the description of the file presented to the user in the list of embedded files.

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

getMediaType

public java.lang.String getMediaType()

The file's MIME type (Getter)

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

getModificationDate

public java.time.OffsetDateTime getModificationDate()

The file's date of last modification (Getter)

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

getName

public java.lang.String getName()

The file name (Getter)

For embedded files, this is the name presented to the user in a the list of embedded files.

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed

getData

public Stream getData()

The file's stream (Getter)

Throws:

java.lang.IllegalStateException - if the object or the owning document has already been closed