Merge: Dokumente zusammenfügen

Toolbox Webservice: Dokumente zusammenführen mit der webPDF wsclient Bibliothek

In diesem Beitrag möchten wir Ihnen die Merge Operation des ToolboxWebService vorstellen und wie diese mittels der wsclient Bibliothek verwendet wird.

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

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

1.

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

2.

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

3. Und anschließend diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben.

Passwortschutz

Sie sollten dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mitgeben. Verfügt das Dokument nicht über einen entsprechenden Passwortschutz, so können Sie diesen Punkt überspringen.

Direkt am erzeugten ToolboxWebService Objekt:

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

Beschreibung des Toolbox Webservice Merge anhand von Code-Beispielen

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 Merge Operation welche es ermöglicht, Dokumente zusammen zu führen.

So fügen Sie Ihrem WebService Objekt eine Merge Operation hinzu:

MergeType merge = new MergeType();
toolboxWebService.getOperation().add(merge);

Welche Parameter lassen sich am Objekt Merge setzen?

mode (Standardwert: „atTheEnd“)

Bestimmt die Art und Weise der Zusammenführung und vor allem die Position der neuen Seiten im Dokument. Folgende Werte können hier gesetzt werden:

• atTheEnd = Hängt die neuen Seiten am Ende des Dokuments an.
• atTheBeginning = Stellt die neuen Seiten dem Dokument voran.
• afterPage = Fügt die neuen Seiten nach einer bestimmten Seite des Dokuments ein.
• beforePage = Fügt die neuen Seiten vor einer bestimmten Seite des Dokuments ein.

merge.setMode(MergeModeType.BEFORE_PAGE);

page (Standardwert: „1“)

Legt eine Seitennummer für die Modi afterPage oder beforePage fest.

merge.setPage(3);

outlineName (Standardwert: „“)

Legt den zu wählenden Basispfad für die Outlines des Quelldokuments fest – dieser Parameter darf einen Pfad enthalten und endet am besten auf den Namen des Dokuments („A/B/Dateiname“). Ist dieser Parameter nicht gesetzt, so werden sämtliche Outlines dem Wurzelelement angefügt.

merge.setOutlineName("A/B/base.pdf");

resetMetadata (Standardwert: false)

Wird dieser boolesche Wert auf true gesetzt, so werden neue Metadaten für das entstehende Dokument erzeugt, statt die des Quelldokuments zu übernehmen.

merge.setResetMetadata(true);

Das Objekt Data

Die Auswahl der Datei, die dem Quelldokument hinzugefügt werden soll, erfolgt durch Erzeugung eines MergeFileDataType Objekts.

merge.setData(data);

Am Objekt Data lassen sich folgende Parameter setzen:

format

Gibt an, ob eine einzelne PDF Datei oder ein ZIP-Archiv mit PDF Dateien angehängt werden sollen. Folgende Werte können hier gesetzt werden:

• pdf = Es wird eine einzelne PDF angehangen.
• zip = Es wird ein ZIP-Archiv mit mehreren PDFs angehangen.

data.setFormat(FileDataFormatType.PDF);

outlineName (Standardwert: „“)

Legt den zu wählenden Basispfad für die Outlines des angehängten Dokuments fest – dieser Parameter darf einen Pfad enthalten und endet am besten auf den Namen des Dokuments („A/B/Dateiname“). Ist dieser Parameter nicht gesetzt, so werden sämtliche Outlines dem Wurzelelement angefügt.

data.setOutlineName("A/B/appended.pdf");

source

Gibt an, aus welcher Quelle das anzuhängende Dokument bezogen werden soll. 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 das anzuhängende Dokument in Form eines byte arrays. (source sollte auf Value gesetzt sein.)

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

uri

Übergibt eine URI Referenz auf das anzuhängende Dokument. (source sollte auf Uri gesetzt sein.)

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

Beispiel für gesamten Webserviceaufruf

Schließlich noch ein etwas ausführlicheres Beispiel für den Webserviceaufruf (für die Ansprache der SOAP Schnittstelle):

try (
    // Aufbau einer Session mit dem webPDF Server(hier SOAP):
    SoapSession 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:
    MergeType merge = new MergeType();
    toolboxWebService.getOperation().add(merge);
    merge.setMode(MergeModeType.BEFORE_PAGE);
    merge.setPage(3);
    merge.setOutlineName("A/B/base.pdf");
    merge.setResetMetadata(true);

    MergeFileDataType data = new MergeFileDataType();
    merge.setData(data);

    data.setFormat(FileDataFormatType.PDF);
    data.setOutlineName("A/B/appended.pdf");
    data.setSource(FileDataSourceType.VALUE);
    data.setValue(FileUtils.readFileToByteArray(new File("...")));

    // Ausführung.
    toolboxWebService.process();
} catch (IOException ex) {
    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
}

Weiterführende Informationen:

• Mehr zur Merge Parameterstruktur in unserer Doku

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