Package com.pdftools.toolbox.pdf

Class Document

java.lang.Object

com.pdftools.toolbox.internal.NativeBase

com.pdftools.toolbox.internal.NativeObject

com.pdftools.toolbox.pdf.Document

All Implemented Interfaces:

java.lang.AutoCloseable

public class Document
extends NativeObject
implements java.lang.AutoCloseable

Method Summary

Modifier and Type	Method	Description
void	close()	Close the object
static Document	create(Stream stream, Conformance conformance, Encryption encryption)	Create a new PDF document.
static Document	createWithFdf(Stream pdfStream, Stream fdfStream, Conformance conformance, Encryption encryption)	Create a new PDF document and an associated FDF.
FileReferenceList	getAllEmbeddedFiles()	plain embedded, associated, and attached files (Getter)
FileReferenceList	getAssociatedFiles()	document-associated files (Getter)
Conformance	getConformance()	the claimed conformance of the document.
FieldNodeMap	getFormFields()	The form fields of the document (Getter)
boolean	getIsLinearized()	Whether the document is linearized.
Metadata	getMetadata()	the metadata of the document.
Destination	getOpenDestination()	The destination that is displayed when the document is opened.
OptionalContentGroupList	getOptionalContentGroups()	The optional content groups (layers) of the document.
OutlineItemList	getOutline()	The document outline, also known as "Bookmarks".
IccBasedColorSpace	getOutputIntent()	the output intent of the document.
PageList	getPages()	the pages of the document.
java.util.EnumSet<Permission>	getPermissions()	The permissions in force for this document.
FileReferenceList	getPlainEmbeddedFiles()	plain embedded files (Getter)
SignatureFieldList	getSignatureFields()	The signature fields of the document (Getter)
ViewerSettings	getViewerSettings()	The settings to use when opening the document in a viewer.
static Document	open(Stream stream, java.lang.String password)	Open a PDF document.
static Document	openWithFdf(Stream pdfStream, Stream fdfStream, java.lang.String password)	Open a PDF document together with an FDF file.
void	setMetadata(Metadata value)	the metadata of the document.
void	setOpenDestination(Destination value)	The destination that is displayed when the document is opened.
void	setOutputIntent(IccBasedColorSpace value)	the output intent of the document.
void	setViewerSettings(ViewerSettings value)	The settings to use when opening the document in a viewer.

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

open

public static Document open(Stream stream,
                            java.lang.String password)
                     throws java.io.IOException,
                            CorruptException,
                            PasswordException,
                            ConformanceException,
                            UnsupportedFeatureException

Open a PDF document.

Documents opened with this method are read-only and cannot be modified.

Parameters:

stream -

The stream where the PDF document is stored.

Read access is required.

password - the password to open the PDF document

Returns:

the newly created document instance

Throws:

PasswordException - if the file is encrypted and the password is not valid.

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

CorruptException - if the file is corrupt or not a PDF.

UnsupportedFeatureException - if the file is a PDF collection.

UnsupportedFeatureException - if the PDF contains unrendered XFA fields.

ConformanceException - if the document's conformance level is not supported

java.lang.IllegalArgumentException - if stream is null

openWithFdf

public static Document openWithFdf(Stream pdfStream,
                                   Stream fdfStream,
                                   java.lang.String password)
                            throws java.io.IOException,
                                   CorruptException,
                                   PasswordException,
                                   ConformanceException,
                                   UnsupportedFeatureException

Open a PDF document together with an FDF file.

Documents opened with this method are read-only and cannot be modified.

Parameters:

pdfStream -

The stream where the PDF document is stored.

Read access is required.

fdfStream -

The stream where the FDF file is stored.

Read access is required.

password - the password to open the PDF document

Returns:

the newly created document instance

Throws:

PasswordException - if the file is encrypted and the password is not valid.

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

CorruptException - if the file is corrupt or not a PDF.

UnsupportedFeatureException - if the file is a PDF collection.

UnsupportedFeatureException - if the PDF contains unrendered XFA fields.

ConformanceException - if the document's conformance level is not supported

java.lang.IllegalArgumentException - if pdfStream is null

java.lang.IllegalArgumentException - if fdfStream is null

create

public static Document create(Stream stream,
                              Conformance conformance,
                              Encryption encryption)
                       throws java.io.IOException,
                              ConformanceException

Create a new PDF document.

Documents with created with this method are writable and can be modified.

Parameters:

stream -

The stream where the PDF document is stored.

Both, read and write access is required.

conformance -

The required conformance level of the PDF document. Adding pages or content from incompatible documents or using incompatible features will lead to a conformance error.

When using null, the conformance is determined automatically, based on the conformance of the input documents and the requirements of the used features.

Note that for PDF/A document it is highly recommended to set an output intent using setOutputIntent(com.pdftools.toolbox.pdf.content.IccBasedColorSpace).

encryption - the optional encryption parameters

Returns:

the newly created document instance

Throws:

java.io.IOException - Error writing to the stream.

ConformanceException - If the conformance level is lower than 1.7 and Unicode passwords are specified. In this context "a Unicode password" is essentially one containing characters that are not in the Windows ANSI encoding (Windows Code Page 1252).

java.lang.IllegalArgumentException - if stream is null

createWithFdf

public static Document createWithFdf(Stream pdfStream,
                                     Stream fdfStream,
                                     Conformance conformance,
                                     Encryption encryption)
                              throws java.io.IOException,
                                     ConformanceException

Create a new PDF document and an associated FDF.

Documents with created with this method are writable and can be modified. When creating a document with this method, all annotations.MarkupAnnotations - created or copied - are stored as an FDF file to the fdfStream. In the output PDF (pdfStream), only annotations that are not annotations.MarkupAnnotations are stored.

Parameters:

pdfStream -

The stream where the PDF document is stored.

Both, read and write access is required. The resulting PDF document contains no annotations.MarkupAnnotations.

fdfStream -

The stream where the document's annotations.MarkupAnnotations are stored in the FDF format.

Both, read and write access is required.

conformance -

The required conformance level of the PDF document. Adding pages or content from incompatible documents or using incompatible features will lead to a conformance error.

When using null, the conformance is determined automatically, based on the conformance of the input documents and the requirements of the used features.

Note that for PDF/A document it is highly recommended to set an output intent using setOutputIntent(com.pdftools.toolbox.pdf.content.IccBasedColorSpace).

encryption - the optional encryption parameters

Returns:

the newly created document instance

Throws:

java.io.IOException - Error writing to the pdfStream

ConformanceException - If the conformance level is lower than 1.7 and Unicode passwords are specified. In this context "a Unicode password" is essentially one containing characters that are not in the Windows ANSI encoding (Windows Code Page 1252).

java.lang.IllegalArgumentException - if pdfStream is null

java.lang.IllegalArgumentException - if fdfStream is null

getOptionalContentGroups

public OptionalContentGroupList getOptionalContentGroups()

The optional content groups (layers) of the document. (Getter)

Throws:

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

getConformance

public Conformance getConformance()

the claimed conformance of the document. (Getter)

This method only returns the claimed conformance level, the document is not validated.

Throws:

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

getMetadata

public Metadata getMetadata()

the metadata of the document. (Getter)

If the document is writable, the metadata object will be writable too and all changes to the metadata object are reflected in the document.

Throws:

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

setMetadata

public void setMetadata(Metadata value)

the metadata of the document. (Setter)

If the document is writable, the metadata object will be writable too and all changes to the metadata object are reflected in the document.

Throws:

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

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

java.lang.IllegalArgumentException - if the given Metadata object is null

java.lang.IllegalArgumentException - if the given Metadata object belongs to a different document

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

java.lang.IllegalArgumentException - if value is null

getPages

public PageList getPages()

the pages of the document. (Getter)

If the document is writable, it is possible to append new pages to the end of the list.

Throws:

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

getOutputIntent

public IccBasedColorSpace getOutputIntent()

the output intent of the document. (Getter)

The output intent specifies a color profile that characterizes the intended output device. It is used to render device colors on devices other than the intended output device.

Throws:

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

setOutputIntent

public void setOutputIntent(IccBasedColorSpace value)

the output intent of the document. (Setter)

The output intent specifies a color profile that characterizes the intended output device. It is used to render device colors on devices other than the intended output device.

Throws:

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

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

java.lang.UnsupportedOperationException - if an output intent has been set already

java.lang.IllegalArgumentException - if the given content.IccBasedColorSpace object is null

java.lang.IllegalArgumentException - if the given content.IccBasedColorSpace object has already been closed

java.lang.IllegalArgumentException - if the given content.IccBasedColorSpace object> is associated with a different document

getFormFields

public FieldNodeMap getFormFields()
                           throws CorruptException

The form fields of the document (Getter)

This list contains all AcroForm form fields that belong to this document. Adding to this list results in an error:

• IllegalState if the list has already been closed
• UnsupportedOperation if the document is read-only
• IllegalArgument
  • if the given form field node is null
  • if the given form field node has already been closed
  • if the given form field node does not belong to the same document as the list
  • if the given form field node has already been added to a form field node list
  • if the given form field node's identifier equals an identifier of one of the form field nodes in this list

This list does not support removing elements or setting elements or clearing.

Throws:

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

CorruptException - if the document contains corrupt form fields

getSignatureFields

public SignatureFieldList getSignatureFields()

The signature fields of the document (Getter)

Signature fields are a special kind of form fields, that can contain digital signatures.

Throws:

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

getPlainEmbeddedFiles

public FileReferenceList getPlainEmbeddedFiles()

plain embedded files (Getter)

This list contains plain embedded files, i.e., files that are embedded in this document without having a specific association (getAssociatedFiles()), and without being contained in any annotations.FileAttachment.

If the document is writable, then it is possible to append new file references to the list. Every file reference object can occur at most once in this list.

For PDF/A-3 documents, appending to this list results in a Conformance error.

Throws:

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

getAssociatedFiles

public FileReferenceList getAssociatedFiles()

document-associated files (Getter)

This list contains associated files, whose associated object is the document.

If the document is writable, then it is possible to append new file references to the list. Every file reference object can occur at most once in this list.

Appending to this list results in a Conformance error if the document's conformance is neither PDF/A-3 nor can be upgraded to PDF 2.0.

Throws:

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

getAllEmbeddedFiles

public FileReferenceList getAllEmbeddedFiles()

plain embedded, associated, and attached files (Getter)

This read-only list contains the union of all plain embedded files, associated files, and files contained in file attachment annotations. This is the list of files contained in a PDF as presented in a PDF viewer.

This list does not support appending.

Throws:

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

getOutline

public OutlineItemList getOutline()

The document outline, also known as "Bookmarks".

Throws:

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

getOpenDestination

public Destination getOpenDestination()

The destination that is displayed when the document is opened.

Throws:

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

setOpenDestination

public void setOpenDestination(Destination value)

The destination that is displayed when the document is opened.

Throws:

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

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

java.lang.IllegalArgumentException - if the destination is associated with a different document

java.lang.IllegalArgumentException - if the destination has already been closed

getPermissions

public java.util.EnumSet<Permission> getPermissions()

The permissions in force for this document. This property is null if the document is not encrypted.

Throws:

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

getViewerSettings

public ViewerSettings getViewerSettings()

The settings to use when opening the document in a viewer.

Throws:

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

setViewerSettings

public void setViewerSettings(ViewerSettings value)

The settings to use when opening the document in a viewer.

Throws:

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

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

java.lang.IllegalArgumentException - if viewer settings are associated with a different document

java.lang.IllegalArgumentException - if value is null

getIsLinearized

public boolean getIsLinearized()

Whether the document is linearized.

Linearization is also known as "Fast Web View" and is a way of optimizing PDFs so they can be streamed into a client application. This helps online documents open almost instantly, without having to wait for a large document to completely download.

Throws:

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

close

public void close()
           throws ToolboxException,
                  java.io.IOException

Close the object

Release all native resources associated with the object.

Specified by:

close in interface java.lang.AutoCloseable

Throws:

ToolboxException - only explicitly stated in a superclass

java.io.IOException