Toolbox Webservice: Merge documents with the webPDF wsclient library

In this article we would like to introduce the merge operation of the ToolboxWebService and how it is used 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

In order to be able to call the webservice exactly as we would like to present it here, you should already have created a REST or SOAP session and be able to create either a ToolboxWebService object (for a SOAP session) or a ToolboxRestWebService object (for a REST session) by calling the WebserviceFactory:

1.

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

2.

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

3. and then pass either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument().

Password protection

You should give the current open and/or permission password of the document to the webservice call. If the document does not have an appropriate password protection, you can skip this point.

Directly at the created ToolboxWebService object:

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

Description of the Toolbox Webservice Merge based on code examples

The Toolbox Webservice is an endpoint of your webPDF server that summarizes a number of operations with which you can directly manipulate your PDF document. One of these operations is the Merge operation which allows you to merge documents.

This is how you add a merge operation to your WebService object:

MergeType merge = new MergeType();
toolboxWebService.getOperation().add(merge);

Which parameters can be set on the Merge object?

mode (default value: „atTheEnd“)

Determines the way of merging and, above all, the position of the new pages in the document. The following values can be set here:

• atTheEnd = Appends the new pages to the end of the document.
• atTheBeginning = Prepend the new pages to the document.
• afterPage = Inserts the new pages after a specific page of the document.
• beforePage = Inserts the new pages before a specific page of the document.

merge.setMode(MergeModeType.BEFORE_PAGE);

page (default value: „1“)

Specifies a page number for the afterPage or beforePage modes.

merge.setPage(3);

outlineName (default value: „“)

Defines the base path to choose for the outlines of the source document – this parameter may contain a path and ends best with the name of the document (“A/B/Filename”). If this parameter is not set, all outlines are appended to the root element.

merge.setOutlineName("A/B/base.pdf");

resetMetadata (default value: false)

If this boolean value is set to true, new metadata will be created for the resulting document instead of the source document.

merge.setResetMetadata(true);

The Data Object

The file to be added to the source document is selected by creating a MergeFileDataType object.

MergeFileDataType data = new MergeFileDataType();
merge.setData(data);

The following parameters can be set for the Data object:

format

Specifies whether to attach a single PDF file or a ZIP archive of PDF files. The following values can be set here:

• pdf = A single PDF is attached.
• zip = A ZIP archive with several PDFs will be attached.

data.setFormat(FileDataFormatType.PDF);

outlineName (default value: „“)

Specifies the base path to be selected for the outlines of the attached document – this parameter may contain a path and ends best with the name of the document (“A/B/Filename”). If this parameter is not set, all outlines are appended to the root element.

data.setOutlineName("A/B/appended.pdf");

source

Specifies the source from which the attached document 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 attached document in the form of a byte array. (source should be set to Value.)

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

uri

Transfers a URI reference to the document to be attached. (source should be set to Uri.)

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

Example for an entire webservice call

Finally a more detailed example for the 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 to be processed 
   // and the file to 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 web service 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:
    MergeType merge = new MergeType();
    toolboxWebService.getOperation().add(merge);
    merge.setMode(MergeModeType.BEFORE_PAGE);
    merge.setPage(3);
    merge.setOutlineName("A/B/base.pdf");
    merge.setResetMetadata(true);

    MergeFileDataType data = new MergeFileDataType();
    merge.setData(data);

    data.setFormat(FileDataFormatType.PDF);
    data.setOutlineName("A/B/appended.pdf");
    data.setSource(FileDataSourceType.VALUE);
    data.setValue(FileUtils.readFileToByteArray(new File("...")));

    // Execution.
    toolboxWebService.process();
} catch (IOException ex) {
    // For the evaluation of possible errors, the 
   // wsclient library provides appropriate methods:
}

Further information:

• More about the merge parameter structure in our docu

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