Merge: Combining Documents

Technical Minimum Requirements​

  • Java version: 7
  • webPDF version: 7
  • wsclient version: 1

Toolbox Webservice: Combining Documents with the webPDF wsclient Library​

This article introduces the Merge operation of the ToolboxWebService and shows how it can be used with the wsclient library.

Important Note​

The following coding example is based on the webPDF wsclient library. To understand and apply the example, the related blog post should be reviewed first.

To call the webservice in the way shown here, you should already have created a REST or SOAP session. Using the WebServiceFactory, you can create either a ToolboxWebService object for SOAP or a ToolboxRestWebService object for REST:

ToolboxWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );
ToolboxRestWebService toolboxWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.TOOLBOX
    );
  1. Then pass either a RestDocument or a SoapDocument to the WebService object using setDocument().

Password Protection​

You should pass the current open and/or permission password of the document to the webservice call. If the document is not password protected, you can skip this step.

Directly on 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 bundles a range of operations for directly manipulating PDF documents. One of these operations is Merge, which allows documents to be combined.

To 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: "atTheEnd")​

Determines how the merge is performed and, in particular, where the new pages are inserted in the document:

  • atTheEnd = appends the new pages to the end of the document
  • atTheBeginning = prepends the new pages to the document
  • afterPage = inserts the new pages after a specific page
  • beforePage = inserts the new pages before a specific page
merge.setMode(MergeModeType.BEFORE_PAGE);

page (default: "1")​

Defines the page number for afterPage or beforePage:

merge.setPage(3);

outlineName (default: "")​

Defines the base path for the outlines of the source document. This parameter may contain a path and ideally ends with the document name, for example A/B/Filename. If it is not set, all outlines are appended to the root element.

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

resetMetadata (default: false)​

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

merge.setResetMetadata(true);

The Data Object​

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

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

The following parameters can be set on the Data object:

format​

Specifies whether a single PDF or a ZIP archive containing PDF files should be attached:

  • pdf = attach a single PDF
  • zip = attach a ZIP archive containing multiple PDFs
data.setFormat(FileDataFormatType.PDF);

outlineName (default: "")​

Defines the base path for the outlines of the attached document. This parameter may contain a path and ideally ends with the document name, for example A/B/Filename. If it 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 obtained:

  • value = pass the data directly as a byte array
  • uri = pass a URI reference to the data
data.setSource(FileDataSourceType.VALUE);

value​

Passes the attached document as a byte array. In this case, source should be set to Value.

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

uri​

Passes a URI reference to the attached document. In this case, source should be set to Uri.

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

Example of a Full Webservice Call​

Finally, here is a more detailed example of the webservice call for the SOAP interface:

try (
    // Set up a session with the webPDF server (SOAP in this example):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Provide the document to be processed
    // and the file to which the result should be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Path to the source document").toURI(),
        new File("Path to the target document")
    )
) catch (IOException ex) {
    // Error handling
}

Further Information​

More coding examples for webservices that can be used with the wsclient library can be found here.