Creating Portfolios with the webPDF wsclient Library

Minimum Technical Requirements​

  • Java version: 8
  • webPDF version: 8
  • wsclient version: 2

In this article, we use the Portfolio operation as an example to show how you can work with operations of the webPDF Toolbox Webservice using the wsclient library.

Important Note​

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

Creating a REST or SOAP Session​

To call the webservice as presented here, it is assumed that you have already created a REST or SOAP session and can therefore create either a ToolboxWebService object for a SOAP session by calling WebserviceFactory:

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

Or a ToolboxRestWebService object for a REST session:

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

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

How Do You Get Write Access to a Document?​

To get write 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 on the created toolboxWebService object:

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

If the document does not have corresponding password protection, you can skip this step.

The Toolbox Webservice​

The Toolbox Webservice is an endpoint of your webPDF server that combines a range of operations for directly manipulating PDF documents. One of these operations is the Portfolio operation, which we would like to introduce here as part of the webPDF 8.0 update.

The Portfolio operation allows you to store multiple documents in a shared PDF document as a document collection.

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

The base document is generally displayed only as a placeholder for the portfolio, for example if the display application cannot render portfolios or while the portfolio contents 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 on 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, add a PortfolioFileType object to the Add object:

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

The following parameters can be set on the file object.

path (default value: "")​

Defines the slash-separated path at which the document should be added to the portfolio. The paths build on the portfolio's directory structure and extend it where necessary.

file.setPath("a/b");

fileName (default value: "")​

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

file.setFileName("xyz.json");

mimeType (default value: "")​

Defines the MIME type of the document and thus provides a suggestion for how the document should be displayed.

The portfolioFileData Object​

Lets you select the 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 should be obtained. The following values can be set:

  • VALUE = The data is passed directly as a byte array.
  • URI = A URI reference to the data is passed.
data.setSource(FileDataSourceType.VALUE);

value​

Passes the attachment as a byte array. The source value should be set to VALUE.

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

uri​

Passes a URI reference to the document data. The source value should be set to URI.

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

The folder Object​

A directory structure can be built inside a portfolio. To add a new directory directly to the document, add 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 slash-separated path that should be created in the portfolio's directory structure.

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 in order to select entries for deletion.

The extract Object​

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 on the extract object.

singleFileAsZip (default value: "true")​

If this value is set to false, an extraction that results in the selection of a single document returns that document directly instead of packaging it into a ZIP archive.

extract.setSingleFileAsZip(false);

The selection Object​

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

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

The following parameters can be set on the selection object.

path (default value: "")​

Together with fileName, selects the paths or documents that should be deleted or extracted. Path expressions following the glob selection pattern are supported. This means, for example, that the asterisk character can be used to select all elements of a level. The path a/b/*, for example, selects all subdirectories contained in the path a/b.

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

fileName (default value: "")​

Selects the pattern used for document selection. Names follow the glob selection pattern, which means the asterisk character can be used, for example, to select files of any name with a certain extension, such as *.xls.

selection.setFileName("*.xls");

More Detailed Example​

Here is a more detailed example of the full webservice call for addressing the SOAP interface:

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 ex)

Final Notes​

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

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