com.lowagie.text.pdf

Class AcroFields


public class AcroFields
extends java.lang.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

private static class
AcroFields.InstHit
static class
AcroFields.Item
The field representations for retrieval and modification.
private static class
AcroFields.RevisionStream
private static class
AcroFields.SorterComparator

Field Summary

private static int
DA_COLOR
private static int
DA_FONT
private static int
DA_SIZE
static int
FIELD_TYPE_CHECKBOX
A field type.
static int
FIELD_TYPE_COMBO
A field type.
static int
FIELD_TYPE_LIST
A field type.
static int
FIELD_TYPE_NONE
A field type invalid or not found.
static int
FIELD_TYPE_PUSHBUTTON
A field type.
static int
FIELD_TYPE_RADIOBUTTON
A field type.
static int
FIELD_TYPE_SIGNATURE
A field type.
static int
FIELD_TYPE_TEXT
A field type.
private boolean
append
private HashMap
fieldCache
Holds value of property fieldCache.
(package private) HashMap
fields
private boolean
generateAppearances
Holds value of property generateAppearances.
private boolean
lastWasString
private HashMap
localFonts
(package private) PdfReader
reader
private HashMap
sigNames
private static HashMap
stdFieldFontNames
private int
topFirst
private int
totalRevisions
Holds value of property totalRevisions.
(package private) PdfWriter
writer

Constructor Summary

AcroFields(PdfReader reader, PdfWriter writer)

Method Summary

void
exportAsFdf(FdfWriter writer)
Export the fields as a FDF.
InputStream
extractRevision(String field)
Extracts a revision from the document.
(package private) void
fill()
(package private) PdfAppearance
getAppearance(PdfDictionary merged, String text, String fieldName)
String[]
getAppearanceStates(String fieldName)
Gets the list of appearance names.
ArrayList
getBlankSignatureNames()
Gets the field names that have blank signatures.
String
getField(String name)
Gets the field value.
HashMap
getFieldCache()
Gets the appearances cache.
AcroFields.Item
getFieldItem(String name)
Gets the field structure.
float[]
getFieldPositions(String name)
Gets the field box positions in the document.
int
getFieldType(String fieldName)
Gets the field type.
HashMap
getFields()
Gets all the fields.
(package private) Color
getMKColor(PdfArray ar)
int
getRevision(String field)
Gets this field revision.
PdfDictionary
getSignatureDictionary(String name)
Gets the signature dictionary, the one keyed by /V.
ArrayList
getSignatureNames()
Gets the field names that have signatures and are signed.
int
getTotalRevisions()
Gets the total number of revisions this document has.
boolean
isGenerateAppearances()
Gets the property generateAppearances.
(package private) boolean
isInAP(PdfDictionary dic, PdfName check)
private void
markUsed(PdfObject obj)
boolean
removeField(String name)
Removes a field from the document.
boolean
removeField(String name, int page)
Removes a field from the document.
boolean
removeFieldsFromPage(int page)
Removes all the fields from page.
private int
removeRefFromArray(PdfArray array, PdfObject refo)
boolean
renameField(String oldName, String newName)
Renames a field.
boolean
setField(String name, String value)
Sets the field value.
boolean
setField(String name, String value, String display)
Sets the field value and the display string.
void
setFieldCache(HashMap fieldCache)
Sets a cache for field appearances.
boolean
setFieldProperty(String field, String name, Object value, inst[] )
Sets a field property.
boolean
setFieldProperty(String field, String name, int value, inst[] )
Sets a field property.
void
setFields(FdfReader fdf)
Sets the fields by FDF merging.
void
setFields(XfdfReader xfdf)
Sets the fields by XFDF merging.
void
setGenerateAppearances(boolean generateAppearances)
Sets the option to generate appearances.
boolean
signatureCoversWholeDocument(String name)
Checks is the signature covers the entire document or just part of it.
private static Object[]
splitDAelements(String da)
private void
updateByteRange(PdfPKCS7 pkcs7, PdfDictionary v)
PdfPKCS7
verifySignature(String name)
Verifies a signature.
PdfPKCS7
verifySignature(String name, String provider)
Verifies a signature.

Field Details

DA_COLOR

private static final int DA_COLOR
Field Value:
2

DA_FONT

private static final int DA_FONT
Field Value:
0

DA_SIZE

private static final int DA_SIZE
Field Value:
1

FIELD_TYPE_CHECKBOX

public static final int FIELD_TYPE_CHECKBOX
A field type.
Field Value:
2

FIELD_TYPE_COMBO

public static final int FIELD_TYPE_COMBO
A field type.
Field Value:
6

FIELD_TYPE_LIST

public static final int FIELD_TYPE_LIST
A field type.
Field Value:
5

FIELD_TYPE_NONE

public static final int FIELD_TYPE_NONE
A field type invalid or not found.
Field Value:
0

FIELD_TYPE_PUSHBUTTON

public static final int FIELD_TYPE_PUSHBUTTON
A field type.
Field Value:
1

FIELD_TYPE_RADIOBUTTON

public static final int FIELD_TYPE_RADIOBUTTON
A field type.
Field Value:
3

FIELD_TYPE_SIGNATURE

public static final int FIELD_TYPE_SIGNATURE
A field type.
Field Value:
7

FIELD_TYPE_TEXT

public static final int FIELD_TYPE_TEXT
A field type.
Field Value:
4

append

private boolean append

fieldCache

private HashMap fieldCache
Holds value of property fieldCache.

fields

(package private)  HashMap fields

generateAppearances

private boolean generateAppearances
Holds value of property generateAppearances.

lastWasString

private boolean lastWasString

localFonts

private HashMap localFonts

reader

(package private)  PdfReader reader

sigNames

private HashMap sigNames

stdFieldFontNames

private static final HashMap stdFieldFontNames

topFirst

private int topFirst

totalRevisions

private int totalRevisions
Holds value of property totalRevisions.

writer

(package private)  PdfWriter writer

Constructor Details

AcroFields

(package private)  AcroFields(PdfReader reader,
                              PdfWriter writer)

Method Details

exportAsFdf

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

extractRevision

public InputStream extractRevision(String field)
            throws IOException
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

fill

(package private)  void fill()

getAppearance

(package private)  PdfAppearance getAppearance(PdfDictionary merged,
                                               String text,
                                               String fieldName)
            throws IOException,
                   DocumentException

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].
Parameters:
name - the field name
Returns:
the positions or null if field does not exist

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

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

getMKColor

(package private)  Color getMKColor(PdfArray ar)

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

getTotalRevisions

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

isGenerateAppearances

public boolean isGenerateAppearances()
Gets the property generateAppearances.
Returns:
the property generateAppearances

isInAP

(package private)  boolean isInAP(PdfDictionary dic,
                                  PdfName check)

markUsed

private void markUsed(PdfObject obj)

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

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

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

setField

public boolean setField(String name,
                        String value)
            throws IOException,
                   DocumentException
Sets the field value.
Parameters:
name - the fully qualified field name
value - the field value
Returns:
true if the field was found and changed, false otherwise
Throws:
DocumentException - on error

setField

public boolean setField(String name,
                        String value,
                        String display)
            throws IOException,
                   DocumentException
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
value - the field value
display - the string that is used for the appearance
Returns:
true if the field was found and changed, false otherwise
Throws:
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,
                                inst[] )
Sets a field property. Valid property names are:

  • textfont - sets the text font. The value for this entry is a BaseFont.
  • textcolor - sets the text color. The value for this entry is a java.awt.Color.
  • textsize - sets the text size. The value for this entry is a Float.
  • bgcolor - sets the background color. The value for this entry is a java.awt.Color. If null removes the background.
  • bordercolor - sets the border color. The value for this entry is a java.awt.Color. If null removes the border.
Parameters:
field - the field name
name - the property name
value - the property value
Returns:
true if the property exists, false otherwise

setFieldProperty

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

  • flags - a set of flags specifying various characteristics of the field?s widget annotation. The value of this entry replaces that of the F entry in the form?s corresponding annotation dictionary.
  • setflags - a set of flags to be set (turned on) in the F entry of the form?s corresponding widget annotation dictionary. Bits equal to 1 cause the corresponding bits in F to be set to 1.
  • clrflags - a set of flags to be cleared (turned off) in the F entry of the form?s corresponding widget annotation dictionary. Bits equal to 1 cause the corresponding bits in F to be set to 0.
  • fflags - a set of flags specifying various characteristics of the field. The value of this entry replaces that of the Ff entry in the form?s corresponding field dictionary.
  • setfflags - a set of flags to be set (turned on) in the Ff entry of the form?s corresponding field dictionary. Bits equal to 1 cause the corresponding bits in Ff to be set to 1.
  • clrfflags - a set of flags to be cleared (turned off) in the Ff entry of the form?s corresponding field dictionary. Bits equal to 1 cause the corresponding bits in Ff to be set to 0.
Parameters:
field - the field name
name - the property name
value - the property value
Returns:
true if the property exists, false otherwise

setFields

public void setFields(FdfReader fdf)
            throws IOException,
                   DocumentException
Sets the fields by FDF merging.
Parameters:
fdf - the FDF form
Throws:
DocumentException - on error

setFields

public void setFields(XfdfReader xfdf)
            throws IOException,
                   DocumentException
Sets the fields by XFDF merging.
Parameters:
xfdf - the XFDF form
Throws:
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

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

private 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