Coding example: toolbox forms operation

How to export, import or flatten form data with the wsclient library?

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Here we want to introduce you to the Forms operation of the webPDF ToolboxWebservice and show you with concrete coding examples how to use it with the webPDF wsclient library.

To follow our example completely and be able to call the webservice, you should first have created a REST or SOAP session and thus be able to create a ToolboxWebService object (for a SOAP session) by calling the WebserviceFactory:

ToolboxWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

REST and SOAP session:

ToolboxRestWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );

Finally you should have passed either a RestDocument or a SoapDocument object to the WebService object by calling the method setDocument().

The next steps describe how to get changing access to a document.

Description of the Webservice Parameters

You should give the current open and/or permission password of the document to the webservice call. This is done at the created ToolboxWebService object:

toolboxWebService.getPassword().setOpen("password");
toolboxWebService.getPassword().setPermission("password");

If the document does not have an appropriate password protection, you can skip this point.

The Toolbox Webservice: Operation Forms

With the Forms operation it is possible to export or import form data. This means you can edit your PDF accordingly.

To add a Forms operation to your WebService object:

FormsType forms = new FormsType();
toolboxWebService.getOperation().add(forms);

The following parameters can then be set for the Forms object:

The “export” object

To export the form data and configure its export, add a FormsExportType object to the Forms object.

FormsExportType export = new FormsExportType();
forms.setExport(export);

The following parameters can be set for the Export object:

format (default value: “xml”)

Specifies the file format in which form data is to be exported. The following values can be set here:

• xml = XML
• fdf = FDF
• xfdf = XFDF
• xdp = XDP (only for XFA data)

export.setFormat(FormsFormatType.FDF);

The schema http://schema.webpdf.de/1.0/form/data.xsd is used for the XML export.

fdfFileName (default value: “”)

Specifies the name of the PDF document to be loaded automatically when the FDF file is opened. (only for the export format FDF)

export.setFdfFileName("fdf file name");

The “import” object

To import form data and configure its import, add a FormsImportType object to the Forms object.

FormsImportType importData = new FormsImportType();
forms.setImport(importData);

The following parameters can be set for the Import object:

flatten (default value: false)

If this value is set to true, the form is flattened after importing the form data.

importData.setFlatten(true);

format (default value: “xml”)

Specifies the format of the data to be imported. The following values can be set here:

• xml = XML
• fdf = FDF
• xfdf = XFDF
• xdp = XDP (only for documents with XFA data)

importData.setFormat(FormsFormatType.FDF);

The schema http://schema.webpdf.de/1.0/form/data.xsd is used for the XML import.

The data itself is set via a FormsFileDataType object:

The object “data”

You select the form data to be imported by adding a FormsFileDataType object to the ImportData object.

FormsFileDataType data = new FormsFileDataType();
importData.setData(data);

The following parameters can be set for the Data object:

source

Specifies the source from which the form data is to be obtained. The following values can be set here:

• value = The data is passed directly as byte array.
• uri = A URI reference to the data is passed.

data.setSource(FileDataSourceType.VALUE);

value

Passes the form data in the form of a byte array. (source should be set to value.)

data.setValue(FileUtils.readFileToByteArray(new File("…")));

uri

Passes a URI reference to the form data to be used. (source should be set to uri.)

data.setUri(new File("...").toURI().toString());

The object “flatten”

To flatten the forms and their contents, for example to lock them against further changes, you can add a FormsFileFlattenType object to the Forms object.

forms.setFlatten(new FormsFlattenType());

This operation only supports “AcroForms”. “Static XFA Forms and Dynamic XFA forms are not supported.

This operation has no other parameters.

Webservice Call (SOAP) Example

Here we want to give another detailed example for our entire webservice call (for addressing the SOAP interface):

try (
    // Setup of a session with the webPDF server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Make available the document that is to be processed
    // and the file in which the result is to be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Selection of the webservices via a factory:
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.TOOLBOX
        );
    toolboxWebService.setDocument(soapDocument);
    toolboxWebService.getPassword().setOpen("password");
    toolboxWebService.getPassword().setPermission("password");

    // Object-oriented parameterization of the call:
    FormsType forms = new FormsType();
    toolboxWebService.getOperation().add(forms);

    FormsImportType importData = new FormsImportType();
    forms.setImport(importData);
    importData.setFlatten(true);
    importData.setFormat(FormsFormatType.FDF);

    FormsFileDataType data = new FormsFileDataType();
    importData.setData(data);

    data.setSource(FileDataSourceType.VALUE);
    data.setValue(FileUtils.readFileToByteArray(new File("…")));

    // execution.
    toolboxWebService.process();
} catch (IOException ex) {
    // To evaluate possible errors that have occurred, the
    // wsclient library appropriate methods are available:
}

More coding examples for webservices that you can use with the ws-client library can be found here.