org.faceless.pdf2

## Class FDF

- java.lang.Object
- - org.faceless.pdf2.FDF

-     public final class FDF
      extends Object

  A class representing an `FDF` object. "FDF" stands for "Forms Data Format", and is Adobes format for submitting form data from a PDF to a server, and generating a response. XFDF, an XML representation of FDF, can be handled the same way.

  This class supports both loading an existing FDF file which can be imported into a PDF via the `PDF.importFDF()` method, and creating a new FDF from a PDF which can then be rendered via the `render(java.io.OutputStream)` method.

  Here's a simple example showing how to complete a PDF form with an FDF and save the completed PDF to an `OutputStream`.

       PDF pdf = new PDF(new PDFReader(new FileInputStream("blankform.pdf")));
       FDF fdf = new FDF(new InputStream("data.fdf"));
       pdf.importFDF(fdf);
       pdf.render(outputstream);

  And here's an example showing how to create an FDF and an XFDF file of all the fields in a PDF's Form

       FDF fdf = new FDF(pdf);
       fdf.setFields(pdf.getForm().getElements().values());
       fdf.render(new FileOutputStream("out.fdf"));
       Document xfdf = fdf.getXFDF();
       OutputStream out = new FileOutputStream("out.xfdf");
       Transformer tr = TransformerFactory.newInstance().newTransformer();
       tr.transform(new DOMSource(xfdf), new StreamResult(out));

  Note that an FDF may include JavaScript which may be executed when the FDF is imported into the PDF. See `willExecuteJavaScript()` and `getJavaScript(java.lang.String)`
  Since:
    1.2.1
  See Also:
    `PDF.importFDF(org.faceless.pdf2.FDF)`, `Form`

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static Collection<PDFAnnotation>` | `ALLANNOTATIONS` Special value that can be passed to `setAnnotations(java.util.Collection<org.faceless.pdf2.PDFAnnotation>)` to include all annotations in the PDF

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `FDF(InputStream fdfstream)` Create a new FDF from the specified InputStream.
    `FDF(PDF pdf)` Create a new FDF from the specified PDF.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `static String` | `getCanonicalDate(FormElement field)` For the given field, if it is a Date field return it's value in the "canonical" date format described in the PDF specification (necessary for form submission).
    `String` | `getDocumentID(boolean primary)` Return the document ID that this FDF belongs to.
    `Map<String,String>` | `getFields()` Return a read-only map of all the field values in the FDF.
    `String` | `getFile()` Return the file associated with this FDF (the "F" entry), or `null` if not set.
    `String` | `getJavaScript(String type)` Get the JavaScript from this FDF for the specified event, or `null` if none is defined.
    `Document` | `getXFDF()` Get the FDF object as an XFDF Document.
    `void` | `render(OutputStream out)` Save the FDF file to the specified OutputStream.
    `void` | `setAnnotations(Collection<PDFAnnotation> annots)` Add the specified annotations to the FDF.
    `void` | `setCanonicalDates(boolean canonicaldates)` Set whether to format dates as canonical dates when creating a new FDF or XFDF file.
    `void` | `setFields(Collection<FormElement> fields)` Set the fields that are to be included in this FDF.
    `void` | `setFile(String file)` Set the filename associated with this FDF (the "F" entry).
    `void` | `setIgnoreErrors(boolean ignore)` Whether to ignore errors when importing this FDF.
    `void` | `setIncludeEmptyFields(boolean includeempty)` Set whether to include empty fields when creating a new FDF or XFDF file.
    `void` | `setIncludeUniqueID(boolean includenm)` Set whether to include the "NM" or `Unique ID` for each annotation.
    `void` | `setJavaScript(String type, String script)` Set the JavaScript for this FDF for the specified event, or `null` if none is defined.
    `boolean` | `willExecuteJavaScript()` Return true if this FDF will execute JavaScript on the PDF when it is imported - checks for a "Before", "After" or "AfterPermsReady" event.

    - ### Methods inherited from class java.lang.Object

      `equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### ALLANNOTATIONS

          public static final Collection<PDFAnnotation> ALLANNOTATIONS

      Special value that can be passed to `setAnnotations(java.util.Collection<org.faceless.pdf2.PDFAnnotation>)` to include all annotations in the PDF
      Since:
        2.11.7

  - ### Constructor Detail

    - #### FDF

          public FDF(InputStream fdfstream)
              throws IOException

      Create a new FDF from the specified InputStream. The InputStream must be formatted as an FDF file, or since 2.2.4 an XFDF file (although this requires a SAX implementation to run). Note the InputStream is not closed by this method, and should be closed by the user.
      Parameters:
        `fdfstream` - an InputStream containing the form data.
      Throws:
        `IOException`

    - #### FDF

          public FDF(PDF pdf)

      Create a new FDF from the specified PDF. This FDF may eventually be rendered using the `render(java.io.OutputStream)` method.
      Since:
        2.8.3

  - ### Method Detail

    - #### setFields

          public void setFields(Collection<FormElement> fields)

      Set the fields that are to be included in this FDF. Can only be called if the FDF was created using the `FDF(PDF)` constructor.
      Parameters:
        `fields` - the fields to include - eg. `pdf.getForm().getElements().values()` or ``PDFAction.getFormSubmitFields()``
      Since:
        2.8.3

    - #### setAnnotations

          public void setAnnotations(Collection<PDFAnnotation> annots)

      Add the specified annotations to the FDF. Passing in `ALLANNOTATIONS` will add every annotation in the PDF. Since 2.11.7

    - #### getFields

          public Map<String,String> getFields()

      Return a read-only map of all the field values in the FDF. Note this is just the field values - if the FDF contains other details, like annotations and the like, these will not be included.
      Since:
        2.10

    - #### setFile

          public void setFile(String file)

      Set the filename associated with this FDF (the "F" entry).
      Parameters:
        `file` - the Filename, or null to clear it
      Since:
        2.11.6

    - #### getFile

          public String getFile()

      Return the file associated with this FDF (the "F" entry), or `null` if not set.
      Since:
        2.2.2

    - #### getDocumentID

          public String getDocumentID(boolean primary)

      Return the document ID that this FDF belongs to. This method functions exactly the same as the `PDF.getDocumentID(boolean)` method, but returns the ID of the document associated with this FDF (or null if this is not specified)
      Parameters:
        `primary` - whether to return the primary or secondary ID
      Returns:
        a 32-character String representing the ID, or `null` if no ID is set
      Since:
        2.2.2

    - #### setIgnoreErrors

          public void setIgnoreErrors(boolean ignore)

      Whether to ignore errors when importing this FDF. The default value is false, which means trying to set a field to an illegal value will throw an Exception. By setting this value to true, a warning will be displayed instead and the import will continue
      Since:
        2.2.6

    - #### setIncludeEmptyFields

          public void setIncludeEmptyFields(boolean includeempty)

      Set whether to include empty fields when creating a new FDF or XFDF file.
      Since:
        2.11.7

    - #### setCanonicalDates

          public void setCanonicalDates(boolean canonicaldates)

      Set whether to format dates as canonical dates when creating a new FDF or XFDF file.
      Since:
        2.11.7

    - #### setIncludeUniqueID

          public void setIncludeUniqueID(boolean includenm)

      Set whether to include the "NM" or `Unique ID` for each annotation. The default is no.
      Since:
        2.11.18

    - #### render

          public void render(OutputStream out)
                      throws IOException

      Save the FDF file to the specified OutputStream. The OutputStream is not closed by this method.
      Throws:
        `IOException`

    - #### getXFDF

          public Document getXFDF()

      Get the FDF object as an XFDF Document. This can be then be written to an OutputStream using the usual DOM serialization routine, eg:

           DOMSource source = new DOMSource(fdf.getXFDF());
           Transformer tr = TransformerFactory.newInstance().newTransformer();
           tr.transform(source), new StreamResult(System.out));

      Since:
        2.11.6

    - #### getCanonicalDate

          public static String getCanonicalDate(FormElement field)

      For the given field, if it is a Date field return it's value in the "canonical" date format described in the PDF specification (necessary for form submission). For all other fields this method returns the regular `Field Value`
      Since:
        2.11.18

    - #### willExecuteJavaScript

          public boolean willExecuteJavaScript()

      Return true if this FDF will execute JavaScript on the PDF when it is imported - checks for a "Before", "After" or "AfterPermsReady" event. If this isn't desired, simply call `setJavaScript(java.lang.String, java.lang.String)` on the FDF to clear out the action that would be run before it is imported.
      Since:
        2.11.18

    - #### getJavaScript

          public String getJavaScript(String type)

      Get the JavaScript from this FDF for the specified event, or `null` if none is defined.
      Parameters:
        `type` - one of Doc, Before, After, AfterPermsReady
      Since:
        2.11.18

    - #### setJavaScript

          public void setJavaScript(String type,
                                    String script)

      Set the JavaScript for this FDF for the specified event, or `null` if none is defined.
      Parameters:
        `type` - one of Doc, Before, After, AfterPermsReady
      Since:
        2.11.18

Copyright © 2001-2015 Big Faceless Organization