Portfolios erstellen mit der webPDF wsclient Bibliothek

In diesem Artikel möchten wir an einem Beispiel (Portfolio Operation) zeigen, wie Sie Operationen des webPDF Toolbox Webservices mit Hilfe der wsclient Bibliothek einsetzen können.

Wichtiger Hinweis:

Das nun folgende Coding-Beispiel beruht auf der Nutzung der webPDF wsclient Bibliothek. Um das Beispiel zu verstehen und anzuwenden, sollte zunächst folgender Blogbeitrag beachtet werden:

webPDF und Java: mit der „wsclient“ Bibliothek ganz einfach

REST- oder SOAP-Session erzeugen

Um den Webservice so aufrufen zu können, wie wir es hier vorstellen möchten, wird davon ausgegangen, dass Sie bereits eine REST- oder SOAP-Session erzeugt haben und somit über Aufruf der WebserviceFactory entweder ein ToolboxWebService Objekt (für eine SOAP Session) erzeugen können:

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

Oder ein ToolboxRestWebService Objekt (für eine REST Session) erzeugen können:

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

Und diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben haben.

Wie erhalten Sie ändernden Zugriff auf ein Dokument?

Um ändernden Zugriff auf ein Dokument zu erhalten, müssen Sie dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mitgeben. Dies können Sie direkt am erzeugten toolboxWebService Objekt tun:

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

Verfügt das Dokument nicht über einen entsprechenden Passwortschutz, so können Sie diesen Punkt allerdings überspringen.

Der Toolbox Webservice…

Der Toolbox Webservice ist ein Endpunkt Ihres webPDF Servers, der eine Reihe von Operationen zusammenfasst, mit denen Sie ihr PDF Dokument direkt manipulieren können. Eine dieser Operationen ist die Portfolio Operation, die wir im Rahmen des Updates auf webPDF 8.0 hier vorstellen möchten.

Die Portfolio Operation ermöglicht es Ihnen mehrere Dokumente in einem gemeinsamen PDF Dokument als Dokumentensammlung zu hinterlegen.
Wird der Session ein leeres oder inhaltsloses Ausgangsdokument übergeben, so wird ein Standard Portfolio Basisdokument erzeugt.

Das Basisdokument wird in der Regel nur als Platzhalter für das Portfolio angezeigt, wenn zum Beispiel das Anzeigeprogramm nicht in der Lage ist Portfolios anzuzeigen oder während die Inhalte des Portfolios geladen werden.

Sie fügen ihrem WebService Objekt wie folgt eine Portfolio Operation hinzu:

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

Am Objekt portfolio lassen sich folgende Parameter setzen:

Das Objekt „add“

Um dem Portfolio Dokumente und Verzeichnisse hinzuzufügen, fügen Sie dem portfolio Objekt ein PortfolioAddType Objekt hinzu.

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

Am Objekt add lassen sich folgende Parameter setzen:

Das Objekt „file“

Einem Portfolio können Dokumente eines beliebigen Formats hinzugefügt werden. Um dem Portfolio ein Dokument hinzuzufügen, kann dem Objekt Add ein PortfolioFileType Objekt hinzugefügt werden:

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

Am Objekt file lassen sich folgende Parameter setzen:

path (Standardwert: „“)

Legt den durch Slashes (/) abgetrennten Pfad fest, an dem das Dokument dem Portfolio hinzugefügt werden soll. Die Pfade bauen auf der Verzeichnisstruktur des Portfolios auf und ergänzen diese, wenn nötig.

file.setPath("a/b");

fileName (Standardwert: „“)

Legt den Namen des Dokuments in der Verzeichnisstruktur des Portfolios fest.

file.setFileName("xyz.json");

mimeType (Standardwert: „“)

Legt den MIME type des Dokuments fest und gibt somit einen Vorschlag zur Anzeige des Dokuments.

Das Objekt „portfolioFileData“

Ermöglicht die Wahl der Dokumentendaten, indem Sie dem file Objekt ein PortfolioFileDataType Objekt hinzufügen.

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

Am Objekt data lassen sich folgende Parameter setzen:

source

Gibt an, aus welcher Quelle die Dokumentdaten bezogen werden sollen. Folgende Werte können hier gesetzt werden:

• VALUE = Die Daten werden direkt als byte array übergeben.
• URI = Es wird eine URI Referenz auf die Daten übergeben.

data.setSource(FileDataSourceType.VALUE);

value

Übergibt den Anhang in Form eines byte arrays. (source sollte auf VALUE gesetzt sein.)

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

uri

Übergibt eine URI Referenz auf die Dokumentendaten. (source sollte auf URI gesetzt sein.)

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

Das Objekt „folder“

In einem Portfolio kann eine Verzeichnisstruktur aufgebaut werden. Ein neues Verzeichnis kann dem Dokument direkt hinzugefügt werden, indem sie dem Objekt Add ein Folder Objekt hinzufügen:

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

Am Objekt folder lassen sich folgende Parameter setzen:

path (Standardwert: „“)

Legt den durch Slashes (/) abgetrennten Pfad fest, der in der Verzeichnisstruktur des Portfolios angelegt werden soll.

folder.setPath("a/b");

Das Objekt „remove“

Um aus dem Portfolio Dokumente und Verzeichnisse zu entfernen, fügen Sie dem portfolio Objekt ein PortfolioRemoveType Objekt hinzu.

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

Dem Objekt remove können beliebig viele selection Objekte hinzugefügt werden, um Einträge für die Löschung zu selektieren.

Das Objekt „extract“

Um aus dem Portfolio Dokumente zu extrahieren, fügen Sie dem portfolio Objekt ein PortfolioExtractType Objekt hinzu.

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

Dem Objekt extract können beliebig viele selection Objekte hinzugefügt werden, um Einträge für die Extraktion zu selektieren.

Am Objekt extract lassen sich folgende Parameter setzen:

singleFileAsZip (Standardwert: „true“)

Wird dieser Wert auf false gesetzt, so wird eine Extraktion, die zur Auswahl eines einzelnen Dokumentes führt, dieses Dokument direkt zurückgeben, statt diese in ein ZIP Archiv zu packen.

extract.setSingleFileAsZip(false);

Das Objekt „selection“

Um aus dem Portfolio Dokumente und Verzeichnisse zu entfernen oder extrahieren, fügen Sie dem remove oder extract Objekt selection Objekte hinzu.

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

Am Objekt selection lassen sich folgende Parameter setzen:

path (Standardwert: „“)

Selektiert zusammen mit fileName die Pfade/die Dokumente, die gelöscht/extrahiert werden sollen. Hierbei sind Pfadangaben nach dem „Glob“ Selektionsmuster möglich, was bedeutet, dass beispielsweise das Asterisk Zeichen genutzt werden kann, um alle Elemente einer Ebene zu selektieren. Der Pfad „a/b/*“ beispielsweise führt zur Selektion sämtlicher Unterverzeichnisse, die im Pfad a/b enthalten sind.

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

fileName (Standardwert: „“)

Wählt das Selektionsmuster für die Dokumentenselektion. Hierbei werden Namen nach dem „Glob“ Selektionsmuster angegeben, was bedeutet, dass beispielsweise das Asterisk Zeichen genutzt werden kann, um Dateien beliebigen Namens, mit bestimmter Dateiendung zu wählen: „*.xls“

selection.setFileName("*.xls");

Ausführlicheres Beispiel

Beispiel für unseren gesamten Webserviceaufruf (für die Ansprache der SOAP Schnittstelle):

try (
    // Aufbau einer Session mit dem webPDF Server(hier SOAP):
    Session session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Bereit stellen des Dokuments, das verarbeitet werden soll
    // und der Datei, in die das Ergebnis geschrieben werden soll:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Wahl des Webservices über eine Factory:
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.TOOLBOX
        );
    toolboxWebService.setDocument(soapDocument);
    toolboxWebService.getPassword().setOpen("password");
    toolboxWebService.getPassword().setPermission("password");

    // Objektorientierte Parametrisierung des Aufrufs:
    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("…")));

    // Ausführung.
    toolboxWebService.process();

} catch (ResultException ex) {
    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
}

Abschließende Hinweise

• Mehr Infos zur Portfolio Parameterstruktur sowie Error-Codes finden Sie in unserem Nutzerhandbuch.
• Beachten Sie bitte auch: Sämtliche Parameter sind mit gewissen Standardwerten vorbelegt. Ist ein Standardwert angegeben und weicht dieser nicht von Ihrem gewünschten Wert ab, so ist es nicht zwingend nötig diesen Parameter zu setzen.

Weitere Coding-Beispiele für Webservices, welche Sie mit der ws-client Bibliothek nutzen können finden Sie hier.