com.lowagie.text.pdf

Class PdfStamper

public class PdfStamper extends Object implements PdfViewerPreferences, PdfEncryptionSettings

Applies extra content to the pages of a PDF document. This extra content can be all the objects allowed in PdfContentByte including pages from other Pdfs. The original PDF will keep all the interactive elements including bookmarks, links and form fields.

It is also possible to change the field values and to flatten them. New fields can be added but not flattened.

Author: Paulo Soares (psoares@consiste.pt)

Field Summary
booleanhasSignature
HashMapmoreInfo
PdfSignatureAppearancesigApp
protected PdfStamperImpstamper
The writer
Constructor Summary
PdfStamper(PdfReader reader, OutputStream os)
Starts the process of adding extra content to an existing PDF document.
PdfStamper(PdfReader reader, OutputStream os, char pdfVersion)
Starts the process of adding extra content to an existing PDF document.
PdfStamper(PdfReader reader, OutputStream os, char pdfVersion, boolean append)
Starts the process of adding extra content to an existing PDF document, possibly as a new revision.
Method Summary
voidaddAnnotation(PdfAnnotation annot, int page)
Adds an annotation of form field in a specific page.
voidaddComments(FdfReader fdf)
Adds the comments present in an FDF file.
voidaddFileAttachment(String description, byte[] fileStore, String file, String fileDisplay)
Adds a file attachment at the document level.
voidaddFileAttachment(String description, PdfFileSpecification fs)
Adds a file attachment at the document level.
voidaddJavaScript(String js)
Adds a JavaScript action at the document level.
voidaddViewerPreference(PdfName key, PdfObject value)
Adds a viewer preference
voidclose()
Closes the document.
static PdfStampercreateSignature(PdfReader reader, OutputStream os, char pdfVersion, File tempFile, boolean append)
Applies a digital signature to a document, possibly as a new revision, making possible multiple signatures.
static PdfStampercreateSignature(PdfReader reader, OutputStream os, char pdfVersion)
Applies a digital signature to a document.
static PdfStampercreateSignature(PdfReader reader, OutputStream os, char pdfVersion, File tempFile)
Applies a digital signature to a document.
AcroFieldsgetAcroFields()
Gets the AcroFields object that allows to get and set field values and to merge FDF forms.
PdfImportedPagegetImportedPage(PdfReader reader, int pageNumber)
Gets a page from other PDF document.
HashMapgetMoreInfo()
Gets the optional String map to add or change values in the info dictionary.
PdfContentBytegetOverContent(int pageNum)
Gets a PdfContentByte to write over the page of the original document.
MapgetPdfLayers()
Gets the PdfLayer objects in an existing document as a Map with the names/titles of the layers as keys.
PdfReadergetReader()
Gets the underlying PdfReader.
PdfSignatureAppearancegetSignatureAppearance()
Gets the signing instance.
PdfContentBytegetUnderContent(int pageNum)
Gets a PdfContentByte to write under the page of the original document.
PdfWritergetWriter()
Gets the underlying PdfWriter.
voidinsertPage(int pageNumber, Rectangle mediabox)
Inserts a blank page.
booleanisFullCompression()
Gets the 1.5 compression status.
booleanisRotateContents()
Checks if the content is automatically adjusted to compensate the original page rotation.
voidmakePackage(PdfName initialView)
This is the most simple way to change a PDF into a portable collection.
voidmakePackage(PdfCollection collection)
Adds or replaces the Collection Dictionary in the Catalog.
booleanpartialFormFlattening(String name)
Adds name to the list of fields that will be flattened on close, all the other fields will remain.
voidreplacePage(PdfReader r, int pageImported, int pageReplaced)
Replaces a page from this document with a page from other document.
voidsetDuration(int seconds, int page)
Sets the display duration for the page (for presentations)
voidsetEncryption(byte[] userPassword, byte[] ownerPassword, int permissions, boolean strength128Bits)
Sets the encryption options for this document.
voidsetEncryption(byte[] userPassword, byte[] ownerPassword, int permissions, int encryptionType)
Sets the encryption options for this document.
voidsetEncryption(boolean strength, String userPassword, String ownerPassword, int permissions)
Sets the encryption options for this document.
voidsetEncryption(int encryptionType, String userPassword, String ownerPassword, int permissions)
Sets the encryption options for this document.
voidsetEncryption(Certificate[] certs, int[] permissions, int encryptionType)
Sets the certificate encryption options for this document.
voidsetFormFlattening(boolean flat)
Determines if the fields are flattened on close.
voidsetFreeTextFlattening(boolean flat)
Determines if the FreeText annotations are flattened on close.
voidsetFullCompression()
Sets the document's compression to the new 1.5 mode with object streams and xref streams.
voidsetMoreInfo(HashMap moreInfo)
An optional String map to add or change values in the info dictionary.
voidsetOutlines(List outlines)
Sets the bookmarks.
voidsetPageAction(PdfName actionType, PdfAction action, int page)
Sets the open and close page additional action.
voidsetRotateContents(boolean rotateContents)
Flags the content to be automatically adjusted to compensate the original page rotation.
voidsetThumbnail(Image image, int page)
Sets the thumbnail image for a page.
voidsetTransition(PdfTransition transition, int page)
Sets the transition for the page
voidsetViewerPreferences(int preferences)
Sets the viewer preferences.
voidsetXmpMetadata(byte[] xmp)
Sets the XMP metadata.

Field Detail

hasSignature

private boolean hasSignature

moreInfo

private HashMap moreInfo

sigApp

private PdfSignatureAppearance sigApp

stamper

protected PdfStamperImp stamper
The writer

Constructor Detail

PdfStamper

public PdfStamper(PdfReader reader, OutputStream os)
Starts the process of adding extra content to an existing PDF document.

Parameters: reader the original document. It cannot be reused os the output stream

Throws: DocumentException on error IOException on error

PdfStamper

public PdfStamper(PdfReader reader, OutputStream os, char pdfVersion)
Starts the process of adding extra content to an existing PDF document.

Parameters: reader the original document. It cannot be reused os the output stream pdfVersion the new pdf version or '\0' to keep the same version as the original document

Throws: DocumentException on error IOException on error

PdfStamper

public PdfStamper(PdfReader reader, OutputStream os, char pdfVersion, boolean append)
Starts the process of adding extra content to an existing PDF document, possibly as a new revision.

Parameters: reader the original document. It cannot be reused os the output stream pdfVersion the new pdf version or '\0' to keep the same version as the original document append if true appends the document changes as a new revision. This is only useful for multiple signatures as nothing is gained in speed or memory

Throws: DocumentException on error IOException on error

Method Detail

addAnnotation

public void addAnnotation(PdfAnnotation annot, int page)
Adds an annotation of form field in a specific page. This page number can be overridden with PdfAnnotation.

Parameters: annot the annotation page the page

addComments

public void addComments(FdfReader fdf)
Adds the comments present in an FDF file.

Parameters: fdf the FDF file

Throws: IOException on error

addFileAttachment

public void addFileAttachment(String description, byte[] fileStore, String file, String fileDisplay)
Adds a file attachment at the document level. Existing attachments will be kept.

Parameters: description the file description fileStore an array with the file. If it's null the file will be read from the disk file the path to the file. It will only be used if fileStore is not null fileDisplay the actual file name stored in the pdf

Throws: IOException on error

addFileAttachment

public void addFileAttachment(String description, PdfFileSpecification fs)
Adds a file attachment at the document level. Existing attachments will be kept.

Parameters: description the file description fs the file specification

addJavaScript

public void addJavaScript(String js)
Adds a JavaScript action at the document level. When the document opens all this JavaScript runs. The existing JavaScript will be replaced.

Parameters: js the JavaScript code

addViewerPreference

public void addViewerPreference(PdfName key, PdfObject value)
Adds a viewer preference

Parameters: key a key for a viewer preference value the value for the viewer preference

See Also: PdfViewerPreferences

close

public void close()
Closes the document. No more content can be written after the document is closed.

If closing a signed document with an external signature the closing must be done in the PdfSignatureAppearance instance.

Throws: DocumentException on error IOException on error

createSignature

public static PdfStamper createSignature(PdfReader reader, OutputStream os, char pdfVersion, File tempFile, boolean append)
Applies a digital signature to a document, possibly as a new revision, making possible multiple signatures. The returned PdfStamper can be used normally as the signature is only applied when closing.

A possible use for adding a signature without invalidating an existing one is:

 KeyStore ks = KeyStore.getInstance("pkcs12");
 ks.load(new FileInputStream("my_private_key.pfx"), "my_password".toCharArray());
 String alias = (String)ks.aliases().nextElement();
 PrivateKey key = (PrivateKey)ks.getKey(alias, "my_password".toCharArray());
 Certificate[] chain = ks.getCertificateChain(alias);
 PdfReader reader = new PdfReader("original.pdf");
 FileOutputStream fout = new FileOutputStream("signed.pdf");
 PdfStamper stp = PdfStamper.createSignature(reader, fout, '\0', new
 File("/temp"), true);
 PdfSignatureAppearance sap = stp.getSignatureAppearance();
 sap.setCrypto(key, chain, null, PdfSignatureAppearance.WINCER_SIGNED);
 sap.setReason("I'm the author");
 sap.setLocation("Lisbon");
 // comment next line to have an invisible signature
 sap.setVisibleSignature(new Rectangle(100, 100, 200, 200), 1, null);
 stp.close();
 

Parameters: reader the original document os the output stream or null to keep the document in the temporary file pdfVersion the new pdf version or '\0' to keep the same version as the original document tempFile location of the temporary file. If it's a directory a temporary file will be created there. If it's a file it will be used directly. The file will be deleted on exit unless os is null. In that case the document can be retrieved directly from the temporary file. If it's null no temporary file will be created and memory will be used append if true the signature and all the other content will be added as a new revision thus not invalidating existing signatures

Returns: a PdfStamper

Throws: DocumentException on error IOException on error

createSignature

public static PdfStamper createSignature(PdfReader reader, OutputStream os, char pdfVersion)
Applies a digital signature to a document. The returned PdfStamper can be used normally as the signature is only applied when closing.

Note that the pdf is created in memory.

A possible use is:

 KeyStore ks = KeyStore.getInstance("pkcs12");
 ks.load(new FileInputStream("my_private_key.pfx"), "my_password".toCharArray());
 String alias = (String)ks.aliases().nextElement();
 PrivateKey key = (PrivateKey)ks.getKey(alias, "my_password".toCharArray());
 Certificate[] chain = ks.getCertificateChain(alias);
 PdfReader reader = new PdfReader("original.pdf");
 FileOutputStream fout = new FileOutputStream("signed.pdf");
 PdfStamper stp = PdfStamper.createSignature(reader, fout, '\0');
 PdfSignatureAppearance sap = stp.getSignatureAppearance();
 sap.setCrypto(key, chain, null, PdfSignatureAppearance.WINCER_SIGNED);
 sap.setReason("I'm the author");
 sap.setLocation("Lisbon");
 // comment next line to have an invisible signature
 sap.setVisibleSignature(new Rectangle(100, 100, 200, 200), 1, null);
 stp.close();
 

Parameters: reader the original document os the output stream pdfVersion the new pdf version or '\0' to keep the same version as the original document

Returns: a PdfStamper

Throws: DocumentException on error IOException on error

createSignature

public static PdfStamper createSignature(PdfReader reader, OutputStream os, char pdfVersion, File tempFile)
Applies a digital signature to a document. The returned PdfStamper can be used normally as the signature is only applied when closing.

A possible use is:

 KeyStore ks = KeyStore.getInstance("pkcs12");
 ks.load(new FileInputStream("my_private_key.pfx"), "my_password".toCharArray());
 String alias = (String)ks.aliases().nextElement();
 PrivateKey key = (PrivateKey)ks.getKey(alias, "my_password".toCharArray());
 Certificate[] chain = ks.getCertificateChain(alias);
 PdfReader reader = new PdfReader("original.pdf");
 FileOutputStream fout = new FileOutputStream("signed.pdf");
 PdfStamper stp = PdfStamper.createSignature(reader, fout, '\0', new File("/temp"));
 PdfSignatureAppearance sap = stp.getSignatureAppearance();
 sap.setCrypto(key, chain, null, PdfSignatureAppearance.WINCER_SIGNED);
 sap.setReason("I'm the author");
 sap.setLocation("Lisbon");
 // comment next line to have an invisible signature
 sap.setVisibleSignature(new Rectangle(100, 100, 200, 200), 1, null);
 stp.close();
 

Parameters: reader the original document os the output stream or null to keep the document in the temporary file pdfVersion the new pdf version or '\0' to keep the same version as the original document tempFile location of the temporary file. If it's a directory a temporary file will be created there. If it's a file it will be used directly. The file will be deleted on exit unless os is null. In that case the document can be retrieved directly from the temporary file. If it's null no temporary file will be created and memory will be used

Returns: a PdfStamper

Throws: DocumentException on error IOException on error

getAcroFields

public AcroFields getAcroFields()
Gets the AcroFields object that allows to get and set field values and to merge FDF forms.

Returns: the AcroFields object

getImportedPage

public PdfImportedPage getImportedPage(PdfReader reader, int pageNumber)
Gets a page from other PDF document. Note that calling this method more than once with the same parameters will retrieve the same object.

Parameters: reader the PDF document where the page is pageNumber the page number. The first page is 1

Returns: the template representing the imported page

getMoreInfo

public HashMap getMoreInfo()
Gets the optional String map to add or change values in the info dictionary.

Returns: the map or null

getOverContent

public PdfContentByte getOverContent(int pageNum)
Gets a PdfContentByte to write over the page of the original document.

Parameters: pageNum the page number where the extra content is written

Returns: a PdfContentByte to write over the page of the original document

getPdfLayers

public Map getPdfLayers()
Gets the PdfLayer objects in an existing document as a Map with the names/titles of the layers as keys.

Returns: a Map with all the PdfLayers in the document (and the name/title of the layer as key)

Since: 2.1.2

getReader

public PdfReader getReader()
Gets the underlying PdfReader.

Returns: the underlying PdfReader

getSignatureAppearance

public PdfSignatureAppearance getSignatureAppearance()
Gets the signing instance. The appearances and other parameters can the be set.

Returns: the signing instance

getUnderContent

public PdfContentByte getUnderContent(int pageNum)
Gets a PdfContentByte to write under the page of the original document.

Parameters: pageNum the page number where the extra content is written

Returns: a PdfContentByte to write under the page of the original document

getWriter

public PdfWriter getWriter()
Gets the underlying PdfWriter.

Returns: the underlying PdfWriter

insertPage

public void insertPage(int pageNumber, Rectangle mediabox)
Inserts a blank page. All the pages above and including pageNumber will be shifted up. If pageNumber is bigger than the total number of pages the new page will be the last one.

Parameters: pageNumber the page number position where the new page will be inserted mediabox the size of the new page

isFullCompression

public boolean isFullCompression()
Gets the 1.5 compression status.

Returns: true if the 1.5 compression is on

isRotateContents

public boolean isRotateContents()
Checks if the content is automatically adjusted to compensate the original page rotation.

Returns: the auto-rotation status

makePackage

public void makePackage(PdfName initialView)
This is the most simple way to change a PDF into a portable collection. Choose one of the following names: Pass this name as a parameter and your PDF will be a portable collection with all the embedded and attached files as entries.

Parameters: initialView can be PdfName.D, PdfName.T or PdfName.H

makePackage

public void makePackage(PdfCollection collection)
Adds or replaces the Collection Dictionary in the Catalog.

Parameters: collection the new collection dictionary.

partialFormFlattening

public boolean partialFormFlattening(String name)
Adds name to the list of fields that will be flattened on close, all the other fields will remain. If this method is never called or is called with invalid field names, all the fields will be flattened.

Calling setFormFlattening(true) is needed to have any kind of flattening.

Parameters: name the field name

Returns: true if the field exists, false otherwise

replacePage

public void replacePage(PdfReader r, int pageImported, int pageReplaced)
Replaces a page from this document with a page from other document. Only the content is replaced not the fields and annotations. This method must be called before getOverContent() or getUndercontent() are called for the same page.

Parameters: r the PdfReader from where the new page will be imported pageImported the page number of the imported page pageReplaced the page to replace in this document

Since: iText 2.1.1

setDuration

public void setDuration(int seconds, int page)
Sets the display duration for the page (for presentations)

Parameters: seconds the number of seconds to display the page. A negative value removes the entry page the page where the duration will be applied. The first page is 1

setEncryption

public void setEncryption(byte[] userPassword, byte[] ownerPassword, int permissions, boolean strength128Bits)
Sets the encryption options for this 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 AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly and AllowDegradedPrinting. The permissions can be combined by ORing them.

Parameters: userPassword the user password. Can be null or empty ownerPassword the owner password. Can be null or empty permissions the user permissions strength128Bits true for 128 bit key length, false for 40 bit key length

Throws: DocumentException if anything was already written to the output

setEncryption

public void setEncryption(byte[] userPassword, byte[] ownerPassword, int permissions, int encryptionType)
Sets the encryption options for this 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 AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly and AllowDegradedPrinting. The permissions can be combined by ORing them.

Parameters: userPassword the user password. Can be null or empty ownerPassword the owner password. Can be null or empty permissions the user permissions encryptionType the type of encryption. It can be one of STANDARD_ENCRYPTION_40, STANDARD_ENCRYPTION_128 or ENCRYPTION_AES128. Optionally DO_NOT_ENCRYPT_METADATA can be ored to output the metadata in cleartext

Throws: DocumentException if the document is already open

setEncryption

public void setEncryption(boolean strength, String userPassword, String ownerPassword, int permissions)
Sets the encryption options for this 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 AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly and AllowDegradedPrinting. The permissions can be combined by ORing them.

Parameters: strength true for 128 bit key length, false for 40 bit key length userPassword the user password. Can be null or empty ownerPassword the owner password. Can be null or empty permissions the user permissions

Throws: DocumentException if anything was already written to the output

setEncryption

public void setEncryption(int encryptionType, String userPassword, String ownerPassword, int permissions)
Sets the encryption options for this 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 AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly and AllowDegradedPrinting. The permissions can be combined by ORing them.

Parameters: encryptionType the type of encryption. It can be one of STANDARD_ENCRYPTION_40, STANDARD_ENCRYPTION_128 or ENCRYPTION_AES128. Optionally DO_NOT_ENCRYPT_METADATA can be ored to output the metadata in cleartext userPassword the user password. Can be null or empty ownerPassword the owner password. Can be null or empty permissions the user permissions

Throws: DocumentException if anything was already written to the output

setEncryption

public void setEncryption(Certificate[] certs, int[] permissions, int encryptionType)
Sets the certificate encryption options for this 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 AllowPrinting, AllowModifyContents, AllowCopy, AllowModifyAnnotations, AllowFillIn, AllowScreenReaders, AllowAssembly and AllowDegradedPrinting. The permissions can be combined by ORing them. Optionally DO_NOT_ENCRYPT_METADATA can be ored to output the metadata in cleartext

Parameters: certs the public certificates to be used for the encryption permissions the user permissions for each of the certificates encryptionType the type of encryption. It can be one of STANDARD_ENCRYPTION_40, STANDARD_ENCRYPTION_128 or ENCRYPTION_AES128.

Throws: DocumentException if the encryption was set too late

setFormFlattening

public void setFormFlattening(boolean flat)
Determines if the fields are flattened on close. The fields added with PdfStamper will never be flattened.

Parameters: flat true to flatten the fields, false to keep the fields

setFreeTextFlattening

public void setFreeTextFlattening(boolean flat)
Determines if the FreeText annotations are flattened on close.

Parameters: flat true to flatten the FreeText annotations, false (the default) to keep the FreeText annotations as active content.

setFullCompression

public void setFullCompression()
Sets the document's compression to the new 1.5 mode with object streams and xref streams. It can be set at any time but once set it can't be unset.

setMoreInfo

public void setMoreInfo(HashMap moreInfo)
An optional String map to add or change values in the info dictionary. Entries with null values delete the key in the original info dictionary

Parameters: moreInfo additional entries to the info dictionary

setOutlines

public void setOutlines(List outlines)
Sets the bookmarks. The list structure is defined in SimpleBookmark.

Parameters: outlines the bookmarks or null to remove any

setPageAction

public void setPageAction(PdfName actionType, PdfAction action, int page)
Sets the open and close page additional action.

Parameters: actionType the action type. It can be PdfWriter.PAGE_OPEN or PdfWriter.PAGE_CLOSE action the action to perform page the page where the action will be applied. The first page is 1

Throws: PdfException if the action type is invalid

setRotateContents

public void setRotateContents(boolean rotateContents)
Flags the content to be automatically adjusted to compensate the original page rotation. The default is true.

Parameters: rotateContents true to set auto-rotation, false otherwise

setThumbnail

public void setThumbnail(Image image, int page)
Sets the thumbnail image for a page.

Parameters: image the image page the page

Throws: PdfException on error DocumentException on error

setTransition

public void setTransition(PdfTransition transition, int page)
Sets the transition for the page

Parameters: transition the transition object. A null removes the transition page the page where the transition will be applied. The first page is 1

setViewerPreferences

public void setViewerPreferences(int preferences)
Sets the viewer preferences.

Parameters: preferences the viewer preferences

See Also: PdfViewerPreferences

setXmpMetadata

public void setXmpMetadata(byte[] xmp)
Sets the XMP metadata.

Parameters: xmp

See Also: (byte[])