Split Operation: Split Documents

Using the webservice „split documents“ with the wsclient library

Our coding example for the application of the Split Oparation of the webPDF ToolboxWebService with the help of the wsclient library of webPDF.

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

Webservice Call

Before we start with the description of the split operation, we will show you how to call the webservice. First create a REST or SOAP session. So either a ToolboxWebService object (for a SOAP session) or a ToolboxRestWebService object (for a REST session) is created by calling the WebserviceFactory:

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

REST:

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

Then you should pass either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument().

Please also note our two blog posts about SOAP and REST:

Webservice Parameters

Since you usually need changing access to a document, you should give the current open and/or permission password of the document to the webservice call.

This is done directly at the ToolboxWebService object created:

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

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

Toolbox Webservice Operations

The Toolbox Webservice is an endpoint of your webPDF server that summarizes some operations with which you can manipulate your PDF document. We want to describe these operations in detail using the Split application example. Split means that you can split your PDF documents and extract pages accordingly.

You add a split operation to your WebService object as follows:

SplitType split = new SplitType();
toolboxWebService.getOperation().add(split);

The following parameters can be set for the split object:

pages (default value: „1“)

Specifies the page area to be processed according to the selected mode. You can specify either a single page (“1”), a list of pages (“1,3,5”), a page range (“1-5”), or a combination of these elements (“1,3-5,6”). All pages of the document can be selected using “*”.

split.setPages("1,3-5,6");

fileNameTemplate (default value: „page[%d]“)

If the selected mode and page range lead to the creation of a ZIP archive, the structure of the file names of the PDF documents in the ZIP archive can be determined via this template. The template should contain the placeholder %d, which will be replaced by the corresponding page number.

split.setFileNameTemplate("p[%d]");

mode (default value: „last“)

Defines the way in which the PDF document is to be split. The following values can be set here:

  • last = Defines via “pages” the last page contained in the new PDF document.
  • first = Defines via “pages” the first page contained in the new PDF document.
  • list = Adds all pages selected via “pages” to a new PDF document.
  • single = Removes all pages selected via “pages” from the PDF document and stores each as a separate document in a ZIP archive.
  • each = Removes every x-th page from the document. The rhythm of this selection is determined via “pages”. “startPage” defines from which page this process should start. The result is a ZIP file with one single document per page.
  • group = selects corresponding “pages” for each group from x pages in the document and stores them as a document in a ZIP file. “startPage” determines the page with which this process is to begin.
  • burst = A single document is created from each page of the document. The result is a ZIP file.
split.setMode(SplitModeType.LIST);

startPage (default value: „1“)

Defines the first viewed page of the document for the modes each and group.

split.setStartPage(3);

More detailed example for setting up a session with the webPDF server (here SOAP):

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("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    // Selection of the webservice 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:
    SplitType split = new SplitType();
    toolboxWebService.getOperation().add(split);

    split.setPages("1,3-5,6");
    split.setFileNameTemplate("p[%d]");
    split.setMode(SplitModeType.LIST);
    split.setStartPage(3);

    // execution.
    toolboxWebService.process();
} catch (ResultException | MalformedURLException 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.