com.lowagie.text.pdf

Class AcroFields

public class AcroFields extends Object

Query and change fields in existing documents either by method calls or by FDF merging.

Author: Paulo Soares (psoares@consiste.pt)

Nested Class Summary
static classAcroFields.InstHit
static classAcroFields.Item
The field representations for retrieval and modification.
static classAcroFields.RevisionStream
static classAcroFields.SorterComparator
Field Summary
booleanappend
static PdfName[]buttonRemove
static intDA_COLOR
static intDA_FONT
static intDA_SIZE
HashMapextensionFonts
floatextraMarginLeft
floatextraMarginTop
HashMapfieldCache
Holds value of property fieldCache.
HashMapfields
static intFIELD_TYPE_CHECKBOX
A field type.
static intFIELD_TYPE_COMBO
A field type.
static intFIELD_TYPE_LIST
A field type.
static intFIELD_TYPE_NONE
A field type invalid or not found.
static intFIELD_TYPE_PUSHBUTTON
A field type.
static intFIELD_TYPE_RADIOBUTTON
A field type.
static intFIELD_TYPE_SIGNATURE
A field type.
static intFIELD_TYPE_TEXT
A field type.
booleangenerateAppearances
Holds value of property generateAppearances.
booleanlastWasString
HashMaplocalFonts
PdfReaderreader
HashMapsigNames
static HashMapstdFieldFontNames
ArrayListsubstitutionFonts
inttopFirst
inttotalRevisions
Holds value of property totalRevisions.
PdfWriterwriter
XfaFormxfa
Constructor Summary
AcroFields(PdfReader reader, PdfWriter writer)
Method Summary
voidaddSubstitutionFont(BaseFont font)
Adds a substitution font to the list.
voiddecodeGenericDictionary(PdfDictionary merged, BaseField tx)
voidexportAsFdf(FdfWriter writer)
Export the fields as a FDF.
InputStreamextractRevision(String field)
Extracts a revision from the document.
voidfill()
PdfAppearancegetAppearance(PdfDictionary merged, String text, String fieldName)
String[]getAppearanceStates(String fieldName)
Gets the list of appearance names.
ArrayListgetBlankSignatureNames()
Gets the field names that have blank signatures.
StringgetField(String name)
Gets the field value.
HashMapgetFieldCache()
Gets the appearances cache.
AcroFields.ItemgetFieldItem(String name)
Gets the field structure.
float[]getFieldPositions(String name)
Gets the field box positions in the document.
HashMapgetFields()
Gets all the fields.
intgetFieldType(String fieldName)
Gets the field type.
String[]getListOption(String fieldName, int idx)
String[]getListOptionDisplay(String fieldName)
Gets the list of display option values from fields of type list or combo.
String[]getListOptionExport(String fieldName)
Gets the list of export option values from fields of type list or combo.
ColorgetMKColor(PdfArray ar)
PushbuttonFieldgetNewPushbuttonFromField(String field)
Creates a new pushbutton from an existing field.
intgetRevision(String field)
Gets this field revision.
PdfDictionarygetSignatureDictionary(String name)
Gets the signature dictionary, the one keyed by /V.
ArrayListgetSignatureNames()
Gets the field names that have signatures and are signed.
ArrayListgetSubstitutionFonts()
Gets the list of substitution fonts.
intgetTotalRevisions()
Gets the total number of revisions this document has.
XfaFormgetXfa()
Gets the XFA form processor.
booleanisGenerateAppearances()
Gets the property generateAppearances.
booleanisInAP(PdfDictionary dic, PdfName check)
voidmarkUsed(PdfObject obj)
voidmergeXfaData(Node n)
Merges an XML data structure into this form.
booleanregenerateField(String name)
Regenerates the field appearance.
booleanremoveField(String name, int page)
Removes a field from the document.
booleanremoveField(String name)
Removes a field from the document.
booleanremoveFieldsFromPage(int page)
Removes all the fields from page.
intremoveRefFromArray(PdfArray array, PdfObject refo)
booleanrenameField(String oldName, String newName)
Renames a field.
booleanreplacePushbuttonField(String field, PdfFormField button)
Replaces the field with a new pushbutton.
voidsetExtraMargin(float extraMarginLeft, float extraMarginTop)
Sets extra margins in text fields to better mimic the Acrobat layout.
booleansetField(String name, String value)
Sets the field value.
booleansetField(String name, String value, String display)
Sets the field value and the display string.
voidsetFieldCache(HashMap fieldCache)
Sets a cache for field appearances.
booleansetFieldProperty(String field, String name, Object value, int[] inst)
Sets a field property.
booleansetFieldProperty(String field, String name, int value, int[] inst)
Sets a field property.
voidsetFields(FdfReader fdf)
Sets the fields by FDF merging.
voidsetFields(XfdfReader xfdf)
Sets the fields by XFDF merging.
voidsetGenerateAppearances(boolean generateAppearances)
Sets the option to generate appearances.
booleansetListOption(String fieldName, String[] exportValues, String[] displayValues)
Sets the option list for fields of type list or combo.
voidsetSubstitutionFonts(ArrayList substitutionFonts)
Sets a list of substitution fonts.
booleansignatureCoversWholeDocument(String name)
Checks is the signature covers the entire document or just part of it.
static Object[]splitDAelements(String da)
voidupdateByteRange(PdfPKCS7 pkcs7, PdfDictionary v)
PdfPKCS7verifySignature(String name)
Verifies a signature.
PdfPKCS7verifySignature(String name, String provider)
Verifies a signature.

Field Detail

append

private boolean append

buttonRemove

private static final PdfName[] buttonRemove

DA_COLOR

public static final int DA_COLOR

DA_FONT

public static final int DA_FONT

DA_SIZE

public static final int DA_SIZE

extensionFonts

private HashMap extensionFonts

extraMarginLeft

private float extraMarginLeft

extraMarginTop

private float extraMarginTop

fieldCache

private HashMap fieldCache
Holds value of property fieldCache.

fields

HashMap fields

FIELD_TYPE_CHECKBOX

public static final int FIELD_TYPE_CHECKBOX
A field type.

FIELD_TYPE_COMBO

public static final int FIELD_TYPE_COMBO
A field type.

FIELD_TYPE_LIST

public static final int FIELD_TYPE_LIST
A field type.

FIELD_TYPE_NONE

public static final int FIELD_TYPE_NONE
A field type invalid or not found.

FIELD_TYPE_PUSHBUTTON

public static final int FIELD_TYPE_PUSHBUTTON
A field type.

FIELD_TYPE_RADIOBUTTON

public static final int FIELD_TYPE_RADIOBUTTON
A field type.

FIELD_TYPE_SIGNATURE

public static final int FIELD_TYPE_SIGNATURE
A field type.

FIELD_TYPE_TEXT

public static final int FIELD_TYPE_TEXT
A field type.

generateAppearances

private boolean generateAppearances
Holds value of property generateAppearances.

lastWasString

private boolean lastWasString

localFonts

private HashMap localFonts

reader

PdfReader reader

sigNames

private HashMap sigNames

stdFieldFontNames

private static final HashMap stdFieldFontNames

substitutionFonts

private ArrayList substitutionFonts

topFirst

private int topFirst

totalRevisions

private int totalRevisions
Holds value of property totalRevisions.

writer

PdfWriter writer

xfa

private XfaForm xfa

Constructor Detail

AcroFields

AcroFields(PdfReader reader, PdfWriter writer)

Method Detail

addSubstitutionFont

public void addSubstitutionFont(BaseFont font)
Adds a substitution font to the list. The fonts in this list will be used if the original font doesn't contain the needed glyphs.

Parameters: font the font

decodeGenericDictionary

public void decodeGenericDictionary(PdfDictionary merged, BaseField tx)

exportAsFdf

public void exportAsFdf(FdfWriter writer)
Export the fields as a FDF.

Parameters: writer the FDF writer

extractRevision

public InputStream extractRevision(String field)
Extracts a revision from the document.

Parameters: field the signature field name

Returns: an InputStream covering the revision. Returns null if it's not a signature field

Throws: IOException on error

fill

void fill()

getAppearance

PdfAppearance getAppearance(PdfDictionary merged, String text, String fieldName)

getAppearanceStates

public String[] getAppearanceStates(String fieldName)
Gets the list of appearance names. Use it to get the names allowed with radio and checkbox fields. If the /Opt key exists the values will also be included. The name 'Off' may also be valid even if not returned in the list.

Parameters: fieldName the fully qualified field name

Returns: the list of names or null if the field does not exist

getBlankSignatureNames

public ArrayList getBlankSignatureNames()
Gets the field names that have blank signatures.

Returns: the field names that have blank signatures

getField

public String getField(String name)
Gets the field value.

Parameters: name the fully qualified field name

Returns: the field value

getFieldCache

public HashMap getFieldCache()
Gets the appearances cache.

Returns: the appearances cache

getFieldItem

public AcroFields.Item getFieldItem(String name)
Gets the field structure.

Parameters: name the name of the field

Returns: the field structure or null if the field does not exist

getFieldPositions

public float[] getFieldPositions(String name)
Gets the field box positions in the document. The return is an array of float multiple of 5. For each of this groups the values are: [page, llx, lly, urx, ury]. The coordinates have the page rotation in consideration.

Parameters: name the field name

Returns: the positions or null if field does not exist

getFields

public HashMap getFields()
Gets all the fields. The fields are keyed by the fully qualified field name and the value is an instance of AcroFields.Item.

Returns: all the fields

getFieldType

public int getFieldType(String fieldName)
Gets the field type. The type can be one of: FIELD_TYPE_PUSHBUTTON, FIELD_TYPE_CHECKBOX, FIELD_TYPE_RADIOBUTTON, FIELD_TYPE_TEXT, FIELD_TYPE_LIST, FIELD_TYPE_COMBO or FIELD_TYPE_SIGNATURE.

If the field does not exist or is invalid it returns FIELD_TYPE_NONE.

Parameters: fieldName the field name

Returns: the field type

getListOption

private String[] getListOption(String fieldName, int idx)

getListOptionDisplay

public String[] getListOptionDisplay(String fieldName)
Gets the list of display option values from fields of type list or combo. If the field doesn't exist or the field type is not list or combo it will return null.

Parameters: fieldName the field name

Returns: the list of export option values from fields of type list or combo

getListOptionExport

public String[] getListOptionExport(String fieldName)
Gets the list of export option values from fields of type list or combo. If the field doesn't exist or the field type is not list or combo it will return null.

Parameters: fieldName the field name

Returns: the list of export option values from fields of type list or combo

getMKColor

Color getMKColor(PdfArray ar)

getNewPushbuttonFromField

public PushbuttonField getNewPushbuttonFromField(String field)
Creates a new pushbutton from an existing field. This pushbutton can be changed and be used to replace an existing one, with the same name or other name, as long is it is in the same document. To replace an existing pushbutton call replacePushbuttonField.

Parameters: field the field name that should be a pushbutton

Returns: a new pushbutton or null if the field is not a pushbutton

getRevision

public int getRevision(String field)
Gets this field revision.

Parameters: field the signature field name

Returns: the revision or zero if it's not a signature field

getSignatureDictionary

public PdfDictionary getSignatureDictionary(String name)
Gets the signature dictionary, the one keyed by /V.

Parameters: name the field name

Returns: the signature dictionary keyed by /V or null if the field is not a signature

getSignatureNames

public ArrayList getSignatureNames()
Gets the field names that have signatures and are signed.

Returns: the field names that have signatures and are signed

getSubstitutionFonts

public ArrayList getSubstitutionFonts()
Gets the list of substitution fonts. The list is composed of BaseFont and can be null. The fonts in this list will be used if the original font doesn't contain the needed glyphs.

Returns: the list

getTotalRevisions

public int getTotalRevisions()
Gets the total number of revisions this document has.

Returns: the total number of revisions

getXfa

public XfaForm getXfa()
Gets the XFA form processor.

Returns: the XFA form processor

isGenerateAppearances

public boolean isGenerateAppearances()
Gets the property generateAppearances.

Returns: the property generateAppearances

isInAP

boolean isInAP(PdfDictionary dic, PdfName check)

markUsed

private void markUsed(PdfObject obj)

mergeXfaData

public void mergeXfaData(Node n)
Merges an XML data structure into this form.

Parameters: n the top node of the data structure

Throws: java.io.IOException on error com.lowagie.text.DocumentException o error

regenerateField

public boolean regenerateField(String name)
Regenerates the field appearance. This is usefull when you change a field property, but not its value, for instance form.setFieldProperty("f", "bgcolor", Color.BLUE, null); This won't have any effect, unless you use regenerateField("f") after changing the property.

Parameters: name the fully qualified field name or the partial name in the case of XFA forms

Returns: true if the field was found and changed, false otherwise

Throws: IOException on error DocumentException on error

removeField

public boolean removeField(String name, int page)
Removes a field from the document. If page equals -1 all the fields with this name are removed from the document otherwise only the fields in that particular page are removed.

Parameters: name the field name page the page to remove the field from or -1 to remove it from all the pages

Returns: true if the field exists, false otherwise

removeField

public boolean removeField(String name)
Removes a field from the document.

Parameters: name the field name

Returns: true if the field exists, false otherwise

removeFieldsFromPage

public boolean removeFieldsFromPage(int page)
Removes all the fields from page.

Parameters: page the page to remove the fields from

Returns: true if any field was removed, false otherwise

removeRefFromArray

private int removeRefFromArray(PdfArray array, PdfObject refo)

renameField

public boolean renameField(String oldName, String newName)
Renames a field. Only the last part of the name can be renamed. For example, if the original field is "ab.cd.ef" only the "ef" part can be renamed.

Parameters: oldName the old field name newName the new field name

Returns: true if the renaming was successful, false otherwise

replacePushbuttonField

public boolean replacePushbuttonField(String field, PdfFormField button)
Replaces the field with a new pushbutton. The pushbutton can be created with getNewPushbuttonFromField from the same document or it can be a generic PdfFormField of the type pushbutton.

Parameters: field the field name button the PdfFormField representing the pushbutton

Returns: true if the field was replaced, false if the field was not a pushbutton

setExtraMargin

public void setExtraMargin(float extraMarginLeft, float extraMarginTop)
Sets extra margins in text fields to better mimic the Acrobat layout.

Parameters: extraMarginLeft the extra marging left extraMarginTop the extra margin top

setField

public boolean setField(String name, String value)
Sets the field value.

Parameters: name the fully qualified field name or the partial name in the case of XFA forms value the field value

Returns: true if the field was found and changed, false otherwise

Throws: IOException on error DocumentException on error

setField

public boolean setField(String name, String value, String display)
Sets the field value and the display string. The display string is used to build the appearance in the cases where the value is modified by Acrobat with JavaScript and the algorithm is known.

Parameters: name the fully qualified field name or the partial name in the case of XFA forms value the field value display the string that is used for the appearance. If null the value parameter will be used

Returns: true if the field was found and changed, false otherwise

Throws: IOException on error DocumentException on error

setFieldCache

public void setFieldCache(HashMap fieldCache)
Sets a cache for field appearances. Parsing the existing PDF to create a new TextField is time expensive. For those tasks that repeatedly fill the same PDF with different field values the use of the cache has dramatic speed advantages. An example usage:

 String pdfFile = ...;// the pdf file used as template
 ArrayList xfdfFiles = ...;// the xfdf file names
 ArrayList pdfOutFiles = ...;// the output file names, one for each element in xpdfFiles
 HashMap cache = new HashMap();// the appearances cache
 PdfReader originalReader = new PdfReader(pdfFile);
 for (int k = 0; k < xfdfFiles.size(); ++k) {
    PdfReader reader = new PdfReader(originalReader);
    XfdfReader xfdf = new XfdfReader((String)xfdfFiles.get(k));
    PdfStamper stp = new PdfStamper(reader, new FileOutputStream((String)pdfOutFiles.get(k)));
    AcroFields af = stp.getAcroFields();
    af.setFieldCache(cache);
    af.setFields(xfdf);
    stp.close();
 }
 

Parameters: fieldCache an HasMap that will carry the cached appearances

setFieldProperty

public boolean setFieldProperty(String field, String name, Object value, int[] inst)
Sets a field property. Valid property names are:

Parameters: field the field name name the property name value the property value inst an array of int indexing into AcroField.Item.merged elements to process. Set to null to process all

Returns: true if the property exists, false otherwise

setFieldProperty

public boolean setFieldProperty(String field, String name, int value, int[] inst)
Sets a field property. Valid property names are:

Parameters: field the field name name the property name value the property value inst an array of int indexing into AcroField.Item.merged elements to process. Set to null to process all

Returns: true if the property exists, false otherwise

setFields

public void setFields(FdfReader fdf)
Sets the fields by FDF merging.

Parameters: fdf the FDF form

Throws: IOException on error DocumentException on error

setFields

public void setFields(XfdfReader xfdf)
Sets the fields by XFDF merging.

Parameters: xfdf the XFDF form

Throws: IOException on error DocumentException on error

setGenerateAppearances

public void setGenerateAppearances(boolean generateAppearances)
Sets the option to generate appearances. Not generating apperances will speed-up form filling but the results can be unexpected in Acrobat. Don't use it unless your environment is well controlled. The default is true.

Parameters: generateAppearances the option to generate appearances

setListOption

public boolean setListOption(String fieldName, String[] exportValues, String[] displayValues)
Sets the option list for fields of type list or combo. One of exportValues or displayValues may be null but not both. This method will only set the list but will not set the value or appearance. For that, calling setField() is required.

An example:

 PdfReader pdf = new PdfReader("input.pdf");
 PdfStamper stp = new PdfStamper(pdf, new FileOutputStream("output.pdf"));
 AcroFields af = stp.getAcroFields();
 af.setListOption("ComboBox", new String[]{"a", "b", "c"}, new String[]{"first", "second", "third"});
 af.setField("ComboBox", "b");
 stp.close();
 

Parameters: fieldName the field name exportValues the export values displayValues the display values

Returns: true if the operation succeeded, false otherwise

setSubstitutionFonts

public void setSubstitutionFonts(ArrayList substitutionFonts)
Sets a list of substitution fonts. The list is composed of BaseFont and can also be null. The fonts in this list will be used if the original font doesn't contain the needed glyphs.

Parameters: substitutionFonts the list

signatureCoversWholeDocument

public boolean signatureCoversWholeDocument(String name)
Checks is the signature covers the entire document or just part of it.

Parameters: name the signature field name

Returns: true if the signature covers the entire document, false otherwise

splitDAelements

public static Object[] splitDAelements(String da)

updateByteRange

private void updateByteRange(PdfPKCS7 pkcs7, PdfDictionary v)

verifySignature

public PdfPKCS7 verifySignature(String name)
Verifies a signature. An example usage is:

 KeyStore kall = PdfPKCS7.loadCacertsKeyStore();
 PdfReader reader = new PdfReader("my_signed_doc.pdf");
 AcroFields af = reader.getAcroFields();
 ArrayList names = af.getSignatureNames();
 for (int k = 0; k < names.size(); ++k) {
    String name = (String)names.get(k);
    System.out.println("Signature name: " + name);
    System.out.println("Signature covers whole document: " + af.signatureCoversWholeDocument(name));
    PdfPKCS7 pk = af.verifySignature(name);
    Calendar cal = pk.getSignDate();
    Certificate pkc[] = pk.getCertificates();
    System.out.println("Subject: " + PdfPKCS7.getSubjectFields(pk.getSigningCertificate()));
    System.out.println("Document modified: " + !pk.verify());
    Object fails[] = PdfPKCS7.verifyCertificates(pkc, kall, null, cal);
    if (fails == null)
        System.out.println("Certificates verified against the KeyStore");
    else
        System.out.println("Certificate failed: " + fails[1]);
 }
 

Parameters: name the signature field name

Returns: a PdfPKCS7 class to continue the verification

verifySignature

public PdfPKCS7 verifySignature(String name, String provider)
Verifies a signature. An example usage is:

 KeyStore kall = PdfPKCS7.loadCacertsKeyStore();
 PdfReader reader = new PdfReader("my_signed_doc.pdf");
 AcroFields af = reader.getAcroFields();
 ArrayList names = af.getSignatureNames();
 for (int k = 0; k < names.size(); ++k) {
    String name = (String)names.get(k);
    System.out.println("Signature name: " + name);
    System.out.println("Signature covers whole document: " + af.signatureCoversWholeDocument(name));
    PdfPKCS7 pk = af.verifySignature(name);
    Calendar cal = pk.getSignDate();
    Certificate pkc[] = pk.getCertificates();
    System.out.println("Subject: " + PdfPKCS7.getSubjectFields(pk.getSigningCertificate()));
    System.out.println("Document modified: " + !pk.verify());
    Object fails[] = PdfPKCS7.verifyCertificates(pkc, kall, null, cal);
    if (fails == null)
        System.out.println("Certificates verified against the KeyStore");
    else
        System.out.println("Certificate failed: " + fails[1]);
 }
 

Parameters: name the signature field name provider the provider or null for the default provider

Returns: a PdfPKCS7 class to continue the verification