Creating portfolios with the webPDF wsclient library

In this article we would like to show an example (Portfolio Operation) how you can use operations of the webPDF Toolbox Webservices with the help of 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

Creating a REST or SOAP Session

In order to be able to call the Webservice as we would like to present it here, it is assumed that you have already created a REST or SOAP session and can therefore either create a ToolboxWebService object (for a SOAP session) by calling the WebserviceFactory:

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

Or create a ToolboxRestWebService object (for a REST session):

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

And have passed either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument().

How do you get changing access to a document?

To get modifying access to a document, you must pass the current open and/or permission password of the document to the webservice call. You can do this directly 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…

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 portfolio operation, which we would like to present here as part of the update to webPDF 8.0.

The portfolio operation allows you to store several documents in a common PDF document as a document collection.

If an empty or empty source document is transferred to the session, a standard portfolio base document is created.

The base document is usually only displayed as a placeholder for the portfolio if, for example, the display program is unable to display portfolios or while the contents of the portfolio are being loaded.

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

PortfolioType portfolio = new PortfolioType();
toolboxWebService.getOperation().add(portfolio);

The following parameters can be set for the portfolio object:

The “add” object

To add documents and directories to the portfolio, add a PortfolioAddType object to the portfolio object.

PortfolioAddType add = new PortfolioAddType();
portfolio.setAdd(add);

The following parameters can be set on the add object:

The “file” object

Documents of any format can be added to a portfolio. To add a document to the portfolio, a PortfolioFileType object can be added to the Add object:

PortfolioFileType file = new PortfolioFileType();
add.getFile().add(file);

The following parameters can be set for the file object:

path (default value: “”)

Specifies the path separated by slashes (/) where the document is to be added to the portfolio. The paths build on the directory structure of the portfolio and supplement it if necessary.

file.setPath("a/b");

fileName (default value: “”)

Defines the name of the document in the directory structure of the portfolio.

file.setFileName("xyz.json");

mimeType (default value: “”)

Defines the MIME type of the document and thus provides a proposal for displaying the document.

The object “portfolioFileData”.

Allows you to select document data by adding a PortfolioFileDataType object to the file object.

PortfolioFileDataType data = new PortfolioFileDataType();
file.setData(data);

The following parameters can be set on the data object:

source

Specifies the source from which the document 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 attachment 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 document data. (source should be set to URI.)

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

The “folder” object

A directory structure can be set up in a portfolio. A new directory can be added directly to the document by adding a folder object to the Add object:

PortfolioFolderType folder = new PortfolioFolderType();
add.getFolder().add(folder);

The following parameters can be set on the folder object:

path (default value: “”)

Defines the path separated by slashes (/) to be created in the directory structure of the portfolio.

folder.setPath("a/b");

The “remove” object

To remove documents and directories from the portfolio, add a PortfolioRemoveType object to the portfolio object.

PortfolioRemoveType remove = new PortfolioRemoveType();
portfolio.setRemove(remove);

Any number of selection objects can be added to the remove object to select entries for deletion.

The object “extract

To extract documents from the portfolio, add a PortfolioExtractType object to the portfolio object.

PortfolioExtractType extract = new PortfolioExtractType();
portfolio.setExtract(extract);

Any number of selection objects can be added to the extract object to select entries for extraction.

The following parameters can be set for the extract object:

singleFileAsZip (default value: “true”)

If this value is set to false, an extraction leading to the selection of a single document will return this document directly instead of packing it into a ZIP archive.

extract.setSingleFileAsZip(false);

The object “selection

To remove or extract documents and directories from the portfolio, add objects to the remove or extract object selection.

PortfolioSelectionType selection = new PortfolioSelectionType();
remove.getSelection().add(selection);

The following parameters can be set for the object selection:

path (default value: “”)

Together with fileName, selects the paths/documents to be deleted/extracted. Path specifications according to the “glob” selection pattern are possible, which means, for example, that the asterisk character can be used to select all elements of a layer. The path “a/b/*” for example leads to the selection of all subdirectories contained in the path a/b.

selection.setPath("a/b/*");

fileName (default value: “”)

Selects the selection pattern for the document selection. Names are specified after the “Glob” selection pattern, which means that for example the asterisk character can be used to select files of any name, with a certain file extension: “*.xls”.

selection.setFileName("*.xls");

More detailed example

Detailed example for our entire webservice call (for addressing the SOAP interface):

try (
    // Setup of a session with the webPDF server (here SOAP):
    Session 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:
    PortfolioType portfolio = new PortfolioType();
    toolboxWebService.getOperation().add(portfolio);

    PortfolioAddType add = new PortfolioAddType();
    portfolio.setAdd(add);

    PortfolioFileType file = new PortfolioFileType();
    add.getFile().add(file);
    file.setPath("a/b");
    file.setFileName("xyz.json");
    file.setMimeType("application/json");

    PortfolioFileDataType data = new PortfolioFileDataType();
    file.setData(data);
    data.setSource(FileDataSourceType.VALUE);
    data.setValue(FileUtils.readFileToByteArray(new File("…")));

    // execution.
    toolboxWebService.process();

} catch (ResultException ex) {
    // To evaluate possible errors that have occurred, the
    // wsclient library appropriate methods are available:
}

Concluding remarks

• More information about the portfolio parameter structure and error codes can be found in our user manual.
• Please also note: All parameters are preset with certain default values. If a default value is specified and does not deviate from your desired value, it is not absolutely necessary to set this parameter.

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