This class allows to free the memory taken by already processed pages when handling big PDF files. It provides three alternative approaches for this, each of which has its own advantages and most suitable use cases: .unsafeFlushDeep(int), .releaseDeep(int), .appendModeFlush(int).

Each approach is designed to be most suitable for specific modes of document processing. There are four document processing modes: reading, writing, stamping and append mode.

Reading mode: The PdfDocument instance is initialized using only PdfReader by PdfDocument.PdfDocument(PdfReader) constructor.

Writing mode: The PdfDocument instance is initialized using only PdfWriter by PdfDocument.PdfDocument(PdfWriter) constructor.

Stamping mode: The PdfDocument instance is initialized using both PdfReader and PdfWriter by PdfDocument.PdfDocument(PdfReader, PdfWriter) constructor. If the optional third StampingProperties argument is passed, its StampingProperties.useAppendMode() method shall NOT be called.
This mode allows to update the existing document by completely recreating it. The complete document will be rewritten by the end of PdfDocument.close() call.

Append mode: The PdfDocument instance is initialized using both PdfReader and PdfWriter by PdfDocument.PdfDocument(PdfReader, PdfWriter, StampingProperties) constructor. The third StampingProperties argument shall have StampingProperties.useAppendMode() method called.
This mode preserves the document intact with all its data, but adds additional data at the end of the file, which "overrides" and introduces amends to the original document. In this mode it's not required to rewrite the complete document which can be highly beneficial for big PDF documents handling.

The PageFlushingHelper class operates with two concepts of PDF objects states: flushed and released objects.

Flushed object is the one which is finalized and has been completely written to the output stream. This frees its memory but makes it impossible to modify it or read data from it. Whenever there is an attempt to modify or to fetch flushed object inner contents an exception will be thrown. Flushing is only possible for objects in the writing and stamping modes, also its possible to flush modified objects in append mode.

Released object is the one which has not been modified and has been "detached" from the PdfDocument, making it possible to remove it from memory during the GC, even if the document is not closed yet. All released object instances become read-only and any modifications will not be reflected in the resultant document. Read-only instances should be considered as copies of the original objects. Released objects can be re-read, however after re-reading new object instances are created. Releasing is only possible for not modified objects in reading, stamping and append modes. It's important to remember though, that during PdfDocument.close() in stamping mode all released objects will be re-read.

The PageFlushingHelper class doesn't work with PdfADocument instances.

Flushes to the output stream modified objects that can belong only to the given page, which makes this method "safe" compared to the .unsafeFlushDeep(int). Flushed object frees the memory, but it's impossible to modify such objects or read data from them. This method releases all other page structure objects that are not modified.

This method is mainly designed for the append mode. It is similar to the PdfPage.flush(), but it additionally releases all page objects that were not flushed. This method is ideal for small amendments of pages, but it makes more sense to use PdfPage.flush() for newly created or heavily modified pages.
This method will throw an exception for documents opened in reading mode (see PageFlushingHelper for more details on modes). It is also not advised to be used in stamping mode: even though it will indeed release the objects and free the memory, the released objects will definitely be re-read again on document closing, which would affect performance.

When using this method in append mode (or in stamping mode), be careful not to try to modify the object instances obtained before this method call! See PageFlushingHelper for details on released and flushed objects state.

This method shall be used only when it's known that the page and its inner structures processing is finished. This includes reading data from pages, page modification and page handling via addons/utilities. @param pageNum the page number which low level objects structure is to be flushed or released from memory.

Releases memory taken by all not modified objects belonging to the given page, including the page dictionary itself. This affects only the objects that are read from the existing input PDF.

This method is mainly designed for reading mode and also can be used in append mode (see PageFlushingHelper for more details on modes). In append mode modified objects will be kept in memory. The page and all its inner structure objects can be re-read again.

This method will not have any effect in the writing mode. It is also not advised to be used in stamping mode: even though it will indeed release the objects, they will be definitely re-read again on document closing, which would affect performance.

When using this method in append mode (or in stamping mode), be careful not to try to modify the object instances obtained before the releasing! See PageFlushingHelper for details on released objects state.

This method shall be used only when it's known that the page and its inner structures processing is finished. This includes reading data from pages, page modification and page handling via addons/utilities. @param pageNum the page number which low level objects structure is to be released from memory.

Flushes to the output stream all objects belonging to the given page. This frees the memory taken by those objects, but makes it impossible to modify them or read data from them.

This method is mainly designed for writing and stamping modes. It will throw an exception for documents opened in reading mode (see PageFlushingHelper for more details on modes). This method can also be used for append mode if new pages are added or existing pages are heavily modified and .appendModeFlush(int) is not enough.

This method is highly effective in freeing the memory and works properly for the vast majority of documents and use cases, however it can potentially cause failures. If document handling fails with exception after using this method, one should re-process the document with a "safe flushing" alternative (see PdfPage.flush() or consider using append mode and .appendModeFlush(int) method).

The unsafety comes from the possibility of objects being shared between pages and the fact that object data cannot be read after the flushing. Whenever flushed object is attempted to be modified or its data is fetched the exception will be thrown (flushed object can be added to the other objects, though).

In stamping/append mode the issue occurs if some object is shared between two or more pages, and the first page is flushed, and later for processing of the second page this object is required to be read/modified. Normally only page resources (like images and fonts) are shared, which are often not required for page processing: for example for page stamping (e.g. adding watermarks, headers, etc) only new resources are added. Among examples of when the page resources are indeed required (and therefore the risk of this method causing failures being high) would be page contents parsing: text extraction, any general PdfCanvasProcessor class usage, usage of pdfSweep addon.

In writing mode this method normally will work without issues: by default iText creates page objects in such way that they are independent from each other. Again, the resources can be shared, but as mentioned above it's safe to add already flushed resources to the other pages because this doesn't require reading data from them.

For append mode only modified objects are flushed, all others are released and can be re-read later on.

This method shall be used only when it's known that the page and its inner structures processing is finished. This includes reading data from pages, page modification and page handling via addons/utilities. @param pageNum the page number which low level objects structure is to be flushed to the output stream.

{@code PdfDate} is the PDF date object.

PDF defines a standard date format. The PDF date format closely follows the format defined by the international standard ASN.1 (Abstract Syntax Notation One, defined in CCITT X.208 or ISO/IEC 8824). A date is a {@code PdfString} of the form:

{@code (D:YYYYMMDDHHmmSSOHH'mm') }

See also ISO-320001 7.9.4, "Dates". @see PdfString @see java.util.GregorianCalendar

Adds file associated with PDF document as a whole and identifies the relationship between them.

Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method is very similar to PdfDocument.addFileAttachment(String, PdfFileSpec). However, besides adding file description to Names tree, it adds file to array value of the AF key in the document catalog.

For associated files their associated file specification dictionaries shall include the AFRelationship key key @param description the file description @param fs file specification dictionary of associated file @see PdfDocument#addFileAttachment(String, PdfFileSpec)

Gets direct object and try to resolve indirects chain.

Note: If chain of references has length of more than 32, this method return 31st reference in chain.

Marks indirect reference as free in the document. This doesn't "remove" indirect objects from the document, it only ensures that corresponding xref entry is free and indirect object referred by this reference is no longer linked to it. Actual object still might be written to the resultant document (and would get a new corresponding indirect reference in this case) if it is still contained in some other object.

This method will not give any result if the corresponding indirect object or another object that contains a reference to this object is already flushed.

Note: in some cases, removing a link of indirect object to it's indirect reference while leaving the actual object in the document structure might lead to errors, because some objects are expected to always have such explicit link (e.g. Catalog object, page objects, etc).

Sets the 'modified' flag to the indirect object, the flag denotes that the object was modified since the document opening.

This flag is meaningful only if the PdfDocument is opened in append mode (see StampingProperties.useAppendMode()).

In append mode the whole document is preserved as is, and only changes to the document are appended to the end of the document file. Because of this, only modified objects need to be flushed and are allowed to be flushed (i.e. to be written). @return this PdfObject instance.

Adds file associated with PDF page and identifies the relationship between them.

Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method adds file to array value of the AF key in the page dictionary.

For associated files their associated file specification dictionaries shall include the AFRelationship key key @param fs file specification dictionary of associated file

Adds file associated with PDF page and identifies the relationship between them.

Associated files may be used in Pdf/A-3 and Pdf 2.0 documents. The method adds file to array value of the AF key in the page dictionary. If description is provided, it also will add file description to catalog Names tree.

For associated files their associated file specification dictionaries shall include the AFRelationship key key @param description the file description @param fs file specification dictionary of associated file

Flushes page dictionary, its content streams, annotations and thumb image.

If the page belongs to the document which is tagged, page flushing also triggers flushing of the tags, which are considered to belong to the page. The logic that defines if the given tag (structure element) belongs to the page is the following: if all the marked content references (dictionary or number references), that are the descendants of the given structure element, belong to the current page - the tag is considered to belong to the page. If tag has descendants from several pages - it is flushed, if all other pages except the current one are flushed.

Flushes page dictionary, its content streams, annotations and thumb image. If flushResourcesContentStreams is true, all content streams that are rendered on this page (like FormXObjects, annotation appearance streams, patterns) and also all images associated with this page will also be flushed.

For notes about tag structure flushing see PdfPage#flush() method.

If PdfADocument is used, flushing will be applied only if flushResourcesContentStreams is true.

Be careful with handling document in which some of the pages are flushed. Keep in mind that flushed objects are finalized and are completely written to the output stream. This frees their memory but makes it impossible to modify or read data from them. Whenever there is an attempt to modify or to fetch flushed object inner contents an exception will be thrown. Flushing is only possible for objects in the writing and stamping modes, also its possible to flush modified objects in append mode. @param flushResourcesContentStreams if true all content streams that are rendered on this page (like form xObjects, annotation appearance streams, patterns) and also all images associated with this page will be flushed.

Gets compression level of this PdfStream. For more details @see java com. util itextpdf. zip io. Deflater source.DeflaterOutputStream. @return compression level.

Sets compression level of this PdfStream. For more details @see java com. util itextpdf. zip io. Deflater source.DeflaterOutputStream. @param compressionLevel the compression level (0 = best speed, 9 = best compression, -1 is default)

A {@code PdfString}-class is the PDF-equivalent of a JAVA-{@code String}-object.

A string is a sequence of characters delimited by parenthesis. If a string is too long to be conveniently placed on a single line, it may be split across multiple lines by using the backslash character (\) at the end of a line to indicate that the string continues on the following line. Within a string, the backslash character is used as an escape to specify unbalanced parenthesis, non-printing ASCII characters, and the backslash character itself. Use of the \ddd escape sequence is the preferred way to represent characters outside the printable ASCII character set.
This object is described in the 'Portable Document Format Reference Manual version 1.7' section 3.2.3 (page 53-56). @see PdfObject

Marks this string object as not encrypted in the encrypted document.

If it's marked so, it will be considered as already in plaintext and decryption will not be performed for it. In order to have effect, this method shall be called before .getValue() and .getValueBytes() methods.

NOTE: this method is only needed in a very specific cases of encrypted documents. E.g. digital signature dictionary /Contents entry shall not be encrypted. Also this method isn't meaningful in non-encrypted documents.

PdfTextArray defines an array with displacements and PdfString-objects.

A PdfTextArray is used with the operator TJ in PdfCanvas. The first object in this array has to be a PdfString; see reference manual version 1.3 section 8.7.5, pages 346-347. OR see reference manual version 1.6 section 5.3.2, pages 378-379. To emit a more efficient array, we consolidate repeated numbers or strings into single array entries. For example: "add( 50 ); add( -50 );" will REMOVE the combined zero from the array.

Flushes all modified objects which have not been flushed yet. Used in case incremental updates. @param forbiddenToFlush a Set of references that are forbidden to be flushed automatically.

Flushes all objects which have not been flushed yet. @param forbiddenToFlush a Set of references that are forbidden to be flushed automatically.

Gets default compression level for @see PdfStream. For more details @see java com. util itextpdf. zip io. Deflater source.DeflaterOutputStream. @return compression level.

Sets default compression level for @see PdfStream. For more details @see java com. util itextpdf. zip io. Deflater source.DeflaterOutputStream. @param compressionLevel compression level.

Sets the certificate encryption options for the document. An array of one or more public certificates must be provided together with an array of the same size for the permissions for each certificate. The open permissions for the document can be EncryptionConstants.ALLOW_PRINTING, EncryptionConstants.ALLOW_MODIFY_CONTENTS, EncryptionConstants.ALLOW_COPY, EncryptionConstants.ALLOW_MODIFY_ANNOTATIONS, EncryptionConstants.ALLOW_FILL_IN, EncryptionConstants.ALLOW_SCREENREADERS, EncryptionConstants.ALLOW_ASSEMBLY and EncryptionConstants.ALLOW_DEGRADED_PRINTING. The permissions can be combined by ORing them. @param certs the public certificates to be used for the encryption @param permissions the user permissions for each of the certificates @param encryptionAlgorithm the type of encryption. It can be one of EncryptionConstants.STANDARD_ENCRYPTION_40, EncryptionConstants.STANDARD_ENCRYPTION_128, EncryptionConstants.ENCRYPTION_AES_128 or EncryptionConstants.ENCRYPTION_AES_256. Optionally EncryptionConstants.DO_NOT_ENCRYPT_METADATA can be ORed to output the metadata in cleartext @return this {@code WriterProperties} instance

Sets the encryption options for the document. The userPassword and the ownerPassword can be null or have zero length. In this case the ownerPassword is replaced by a random string. The open permissions for the document can be EncryptionConstants.ALLOW_PRINTING, EncryptionConstants.ALLOW_MODIFY_CONTENTS, EncryptionConstants.ALLOW_COPY, EncryptionConstants.ALLOW_MODIFY_ANNOTATIONS, EncryptionConstants.ALLOW_FILL_IN, EncryptionConstants.ALLOW_SCREENREADERS, EncryptionConstants.ALLOW_ASSEMBLY and EncryptionConstants.ALLOW_DEGRADED_PRINTING. The permissions can be combined by ORing them. @param userPassword the user password. Can be null or empty @param ownerPassword the owner password. Can be null or empty @param permissions the user permissions @param encryptionAlgorithm the type of encryption. It can be one of EncryptionConstants.STANDARD_ENCRYPTION_40, EncryptionConstants.STANDARD_ENCRYPTION_128, EncryptionConstants.ENCRYPTION_AES_128 or EncryptionConstants.ENCRYPTION_AES_256. Optionally EncryptionConstants.DO_NOT_ENCRYPT_METADATA can be ORed to output the metadata in cleartext @return this {@code WriterProperties} instance