Code-Beispiel Attachment Operation des Toolbox Webservice

Anhänge verwalten mit der wsclient Bibliothek

In diesem Beitrag möchten wir Ihnen die Attachment Operation des Toolbox Webservices von webPDF vorstellen und wie Sie diese mittels der Bibliothek webPDF wsclient nutzen 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

Erster Schritt

Um den Webservice genauso aufzurufen, wie wir möchten, sollten Sie bereits eine REST- oder SOAP-Session erzeugt haben und somit über Aufruf der WebserviceFactory entweder ein ToolboxWebService Objekt (für eine SOAP Session) oder ein ToolboxRestWebService Objekt (für eine REST Session) erzeugen können. Und diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben haben.

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

Code-Schnipsel 2:

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

Webservice Parameter – Open oder Permission Passwort mitgeben

Um ändernden Zugriff auf ein Dokument zu erhalten, müssen Sie (sofern ihr Dokument über einen entsprechenden Passwortschutz verfügt) dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mit zu geben. Dies können Sie direkt am erzeugten toolboxWebService Objekt erledigen:

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

Was ist der Toolbox Webservice?

Der Toolbox Webservice fungiert als Endpunkt Ihres webPDF Servers, der einige Operationen zusammenfasst, mit denen Sie Ihr PDF Dokument bearbeiten können. Wir möchten das hier anhand eines Coding-Beispiels zeigen. In diesem Fall geht es um die Attachment Operation. Mit dieser können Sie Anhänge in ein Dokument einbetten, sie entfernen oder aus dem Dokument extrahieren.

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

AttachmentType attachment = new AttachmentType();
toolboxWebService.getOperation().add(attachment);

Am Objekt attachment lassen sich folgende Parameter setzen:

Das Objekt „add“

Um Anhänge in das Dokument einzubetten, fügen Sie dem attachment Objekt ein AttachmentType.Add Objekt hinzu.

AttachmentType.Add add = new AttachmentType.Add();
attachment.setAdd(add);

Am Objekt add lassen sich folgende Parameter setzen:

Das Objekt „file“

Um einen oder mehrere Anhänge für die Einbettung zu wählen, fügen Sie dem add Objekt ein oder mehrere FileAttachmentType Objekt/e hinzu.

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

Am Objekt file lassen sich folgende Parameter setzen:

fileName (Standardwert: „“)

Legt den Namen fest, mit dem der Anhang im Dokument hinterlegt werden soll.

file.setFileName("xyz.json");

Das Objekt „data“

Die Wahl des einzubettenden Anhangs, indem Sie dem file Objekt ein AttachmentFileDataType Objekt hinzufügen.

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

Am Objekt data lassen sich folgende Parameter setzen:

source

Gibt an, aus welcher Quelle der Anhang 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.) Der Byte Array wird hier mittels der Klasse FileUtils der Bibliothek Apache Commons IO erzeugt

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

uri

Übergibt eine URI Referenz auf den einzubettenden Anhang. (source sollte auf uri gesetzt sein.)

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

Das Objekt „annotation“

Soll der Anhang nicht auf Dokumentenebene, sondern auf einer Seite des Dokuments als Annotation eingebettet werden, so fügen Sie dem file Objekt ein FileAnnotationType Objekt hinzu.

FileAnnotationType annotation = new FileAnnotationType();
file.setAnnotation(annotation);

Am Objekt file lassen sich folgende Parameter setzen:

page (Standardwert: 1)

Dieser Wert wählt die Seite, auf der die Annotation platziert werden soll.

annotation.setPage(1);

color (Standardwert: „#4800FF“)

Wählt über einen HEX-RGB Wert die Farbe des Textes.

annotation.setColor("#FFFFFF");

opacity (Standardwert: 100)

Ein prozentualer Wert, der die Deckkraft der Annotation festlegt. Je höher der Wert ist, desto weniger durchsichtig wird die Annotation dargestellt. Es kann ein Wert zwischen 0 und 100 Prozent gewählt werden.

annotation.setOpacity(60);

icon (Standardwert: „paperclip“)

Dieser Wert wählt das Symbol, mit dem der Anhang auf der Seite dargestellt wird. Folgende Werte können hier gesetzt werden:

• graph = Diagramm
• paperclip = Büroklammer
• pushPin = Stecknadel
• tag = Etikett

annotation.setIcon(IconsType.PUSH_PIN);

lockedPosition (Standardwert: true)

Wird dieser Wert auf true gesetzt, so kann die Annotation nicht verschoben werden.

annotation.setLockedPosition(false);

popupText (Standardwert: „“)

Dieser Wert bestimmt über den Tooltip, der für die Annotation angezeigt werden soll.

annotation.setPopupText("Beispiel Popuptext");

Das Objekt „point“

Um die Position der Annotation auf der Seite zu bestimmten, fügen Sie dem annotation Objekt ein PointType Objekt hinzu.

PointType point = new PointType();
annotation.setPoint(point);

Am Objekt point lassen sich folgende Parameter setzen:

x Position (Standardwert: „0“)

Dieser Wert bestimmt über die x-Koordinate, auf der die Annotation positioniert werden soll.

point.setX(15);

y Position (Standardwert: „0“)

Dieser Wert bestimmt über die y-Koordinate, auf der die Annotation positioniert werden soll.

point.setY(15);

coordinates (Standardwert: „user“)

Wählt das Koordinatensystem fest auf das bezogen die Position bestimmt werden soll. Folgende Werte können hier gesetzt werden:

• user = Nutzer-Koordinatensystem (Ursprung links-oben)
• pdf = PDF-Koordinatensystem (Ursprung links-unten)

point.setCoordinates(CoordinatesType.USER);

metrics (Standardwert: „mm“)

Die Maßeinheit, in der Koordinaten angegeben werden sollen. Folgende Werte können hier gesetzt werden:

• mm = Millimeter
• px = Pixel

point.setMetrics(MetricsType.PX);

Das Objekt „remove“

Sie können einen Anhang aus einem Dokument entfernen, indem Sie dem Objekt attachment Objekt ein AttachmentType.Remove Objekt hinzufügen.

AttachmentType.Remove remove = new AttachmentType.Remove();
attachment.setRemove(remove);

Am Objekt „remove“ lassen sich folgende Parameter setzen:

Das Objekt „selection“

Um einen oder mehrere Anhänge aus dem Dokument zu löschen, fügen Sie dem „remove“ Objekt ein oder mehrere SelectionAttachmentType Objekt/e hinzu.

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

Am Objekt „selection“ lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Anhänge entfernt werden soll. Es kann entweder eine Einzelseite („1“) eine Auflistung von Seiten („1,3,5“), ein Seitenbereich („1-5“) oder eine Kombination dieser Elemente („1,3-5,6“) angegeben werden. Alle Seiten des Dokuments können über „*“ ausgewählt werden.

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

context (Standardwert: „all“)

Anhänge können auf Dokumenten- und auf Seitenebene eingebettet werden. Dieser Wert bestimmt über die Ebene, von der Anhänge gelöscht werden sollen. Folgende Werte können hier gesetzt werden:
• all = Alle Ebenen
• document = Nur von der Dokumentenebene
• page = Nur von der Seitenebene

selection.setContext(ContextType.PAGE);

Wird hier „document“ gewählt, so hat der für „pages“ gesetzte Wert keine Auswirkungen.

fileMask (Standardwert: „“)

Die Namen sämtlicher im gewählten Bereich gefundenen Anhänge werden gegen diese Maske geprüft und entsprechend entweder zur Löschung selektiert oder von der Löschung ausgenommen. Die Angabe von Wildcards ist hierbei möglich. Zum Beispiel würde die Maske „*.xls“ sämtliche Anhänge mit der Endung „xls“ aus dem Bereich löschen. Auch die direkte Anwahl von Anhängen mit einem bestimmten Dateinamen ist somit möglich. Die Maske „xyz.json“ würde alle Anhänge mit exakt diesem Namen entfernen.

selection.setFileMask("*.xls");

Das Objekt „extract“

Um einen oder mehrere Anhänge aus dem Dokument in ein ZIP Archiv zu extrahieren, fügen Sie dem „attachment“ Objekt ein AttachmentType.Extract Objekt/e hinzu.

AttachmentType.Extract extract = new AttachmentType.Extract();
attachment.setExtract(extract);

Am Objekt „selection“ lassen sich folgende Parameter setzen:

folderNameTemplate (Standardwert: „page[%d]“)

Für jede Seite, aus der Anhänge extrahiert werden, wird ein eigener Ordner im ZIP-Archiv erstellt. Dieser Wert bestimmte über den Namen dieser Ordner, wobei der Platzhalter „%d“ durch die Seitennummer ersetzt wird und enthalten sein muss.

extract.setFolderNameTemplate("page[%d]");

Das Objekt „selection“

Um einen oder mehrere Anhänge aus dem Dokument zu extrahieren, fügen Sie dem extract Objekt ein oder mehrere SelectionAttachmentType Objekt/e hinzu.

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

Am Objekt selection lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Anhänge extrahiert werden soll. Es kann entweder eine Einzelseite („1“) eine Auflistung von Seiten („1,3,5“), ein Seitenbereich („1-5“) oder eine Kombination dieser Elemente („1,3-5,6“) angegeben werden. Alle Seiten des Dokuments können über „*“ ausgewählt werden.

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

context (Standardwert: „all“)

Anhänge können auf Dokumenten- und auf Seitenebene eingebettet werden. Dieser Wert bestimmt über die Ebene, von der Anhänge extrahiert werden sollen. Folgende Werte können hier gesetzt werden:

• all = Alle Ebenen
• document = Nur von der Dokumentenebene
• page = Nur von der Seitenebene

selection.setContext(ContextType.PAGE);

Wird hier document gewählt, so hat der für pages gesetzte Wert keine Auswirkungen.

fileMask (Standardwert: „“)

Die Namen sämtlicher im gewählten Bereich gefundenen Anhänge werden gegen diese Maske geprüft und entsprechend entweder zur Extraktion selektiert oder von dieser ausgenommen. Die Angabe von Wildcards ist hierbei möglich. Zum Beispiel würde die Maske „*.xls“ sämtliche Anhänge mit der Endung „xls“ aus dem Bereich extrahieren. Auch die direkte Anwahl von Anhängen mit einem bestimmten Dateinamen ist somit möglich. Die Maske „xyz.json“ würde alle Anhänge mit exakt diesem Namen extrahieren.

selection.setFileMask("*.xls");

Ausführlicheres Beispiel 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");

    AttachmentType attachment = new AttachmentType();
    toolboxWebService.getOperation().add(attachment);

    AttachmentType.Add add = new AttachmentType.Add();
    attachment.setAdd(add);

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

    file.setFileName("xyz.json");

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

    FileAnnotationType annotation = new FileAnnotationType();
    file.setAnnotation(annotation);

    annotation.setPage(1);
    annotation.setColor("#FFFFFF");
    annotation.setOpacity(60);
    annotation.setIcon(IconsType.PUSH_PIN);
    annotation.setLockedPosition(false);
    annotation.setPopupText("Beispiel Popuptext");

    PointType point = new PointType();
    annotation.setPoint(point);

    point.setX(15);
    point.setY(20);
    point.setCoordinates(CoordinatesType.USER);
    point.setMetrics(MetricsType.PX);

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

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