Split Operation: Splitting Documents

Minimum Technical Requirements​

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

Using the "Split Documents" Webservice with the wsclient Library​

This article provides a concrete example of how to use the Split operation of the webPDF ToolboxWebService with the help of the webPDF wsclient library.

Important Note​

The following code example is based on the webPDF wsclient library. To understand and apply the example correctly, you should first read the relevant introductory blog post.

Calling the Webservice​

Before we start describing the Split operation, we first show how the webservice should be called. Start by creating either a REST or a SOAP session. Calling WebserviceFactory then creates either a ToolboxWebService object for a SOAP session or a ToolboxRestWebService object for a REST session:

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

REST Example​

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

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

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

Webservice Parameters​

Because you generally need write access to a document, you should pass the current open and/or permission password of the document to the webservice call.

This is done directly on the created ToolboxWebService object:

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

If the document is not protected by a password, you can skip this step.

Toolbox Webservice Operations​

The Toolbox Webservice is an endpoint of your webPDF server that combines several operations for targeted PDF manipulation. Here, we describe these operations using the Split use case. Split means that you can divide 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 on the Split object.

pages (default value: "1")​

Defines the page range to be processed according to the selected mode. You can specify 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 with "*".

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

fileNameTemplate (default value: "page[%d]")​

If the selected mode and page range produce a ZIP archive, this template defines the structure of the PDF file names inside the ZIP archive. The template should contain the placeholder %d, which is replaced by the corresponding page number.

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

mode (default value: "last")​

Defines how the PDF document should be split. The following values are available:

  • last = Uses pages to define the last page included in the new PDF document.
  • first = Uses pages to define the first page included in the new PDF document.
  • list = Adds all pages selected via pages to a new PDF document.
  • single = Extracts all pages selected via pages from the PDF document and stores each as a separate document in a ZIP archive.
  • each = Extracts every x-th page from the document. The selection interval is defined via pages. startPage defines the page from which this process begins. The result is a ZIP file with one separate document per page.
  • group = Selects the corresponding pages from each group of x pages in the document and stores them as a document in a ZIP file. startPage defines the page from which this process begins.
  • burst = Creates a separate document from every page of the document. The result is a ZIP file.
split.setMode(SplitModeType.LIST);

startPage (default value: "1")​

Defines the first page to be considered for the each and group modes.

split.setStartPage(3);

More Detailed Example of Creating a Session with the webPDF Server, Here Using SOAP​

try (
    // Set up a session with the webPDF server, here using SOAP.
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Provide the document to be processed and the target file.
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) catch (ResultException | MalformedURLException ex)

More code examples for webservices that you can use with the wsclient library can be found here.