Webservice Wasserzeichen einfügen mit wsclient

Watermark Operation des ToolboxWebService

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

Hier soll die Watermark Operation des webPDF ToolboxWebService und die Nutzung mit der webPDF wsclient-Bibliothek näher vorgestellt werden.

Erster Schritt: Zunächst sollten Sie eine REST- oder SOAP-Session erzeugen und somit über Aufruf der WebserviceFactoryentweder 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
    );

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

Details zum Webservice Parameter

Wenn Sie ändernden Zugriff auf ein Dokument erhalten möchten, ist es notwendig, dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mit zu geben.

Das können Sie direkt am erzeugten ToolboxWebService Objekt tun:

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

Info: Wenn das Dokument nicht über einen entsprechenden Passwortschutz verfügt, dann können Sie diesen Punkt überspringen.

ToolboxWebService: Beispiel Watermark Operation

Zur Erklärung: Der ToolboxWebService ist ein Endpunkt Ihres webPDF Servers, der mehrere Operationen zusammenfasst, mit denen Sie Ihr PDF Dokument direkt anpassen können. Eine dieser Operationen ist die Watermark Operation. Diese ermöglicht es, auf Seiten Ihres Dokuments Wasserzeichen anzubringen.

Sie fügen Ihrem WebService Objekt wie folgt eine Watermark Operation hinzu:

WatermarkType watermark = new WatermarkType();
toolboxWebService.getOperation().add(watermark);

Am Objekt Watermark lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, von dessen Seiten Bilder erzeugt 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.

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

angle (Standardwert: „45“)

Legt eine beliebige Rotation für das Wasserzeichen fest, im Wertebereich von 0 bis 360 Grad. Die Rotation erfolgt im Uhrzeigersinn.

watermark.setAngle(66);

Das Objekt „image“

Soll eine Grafik für das Wasserzeichen verwendet werden, so kann diese in Form eines WatermarkImageTypeObjekts am Watermark Objekt gesetzt werden.Am Objekt Image lassen sich folgende Parameter setzen:

opacity (Standardwert: 25)

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

image.setOpacity(32);

scale (Standardwert: 0)

Ein prozentualer Wert, der die Skalierung der Grafik festlegt.

image.setScale(200);

Das Objekt „data“

Die Wahl der Grafik für das Watermark erfolgt, indem Sie dem Image Objekt ein WatermarkFileDataType Objekt hinzufügen.

WatermarkFileDataType data = new WatermarkFileDataType();
image.setData(data);

Am Objekt Data lassen sich folgende Parameter setzen:

source

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

• value = Die Datei wird direkt als byte array übergeben.
• uri = Es wird eine URI Referenz auf die Datei übergeben.

data.setSource(FileDataSourceType.VALUE);

value

Übergibt die Formulardaten 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());

Das Objekt „text“

Soll ein Text für das Wasserzeichen verwendet werden, so kann diese in Form eines MergeFileDataType Objekts am Watermark Objekt gesetzt werden.

WatermarkTextType text = new WatermarkTextType();
watermark.setText(text);

Am Objekt Text lassen sich folgende Parameter setzen:

text (Standardwert: „Confidential“)

Legt den Text fest, der als Wasserzeichen ausgegeben wird.

position.setAspectRatio(false);

Das Objekt „font“

Die Wahl des Fonts des Wasserzeichens erfolgt, indem Sie dem Text Objekt ein WatermarkFontType Objekt hinzufügen.

WatermarkFontType font = new WatermarkFontType();
text.setFont(font);

Am Objekt Font lassen sich folgende Parameter setzen:

opacity (Standardwert: 100)

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

font.setOpacity(35);

name (Standardwert: „“)

Legt den Namen des zu verwendenden Fonts fest. Wird kein Font bestimmt, so wird Helvetica verwendet.

font.setName("FontName");

bold (Standardwert: false)

Wird dieser Wert auf true gesetzt, wird eine höhere Schriftstärke für den Text gewählt.

font.setBold(true);

color (Standardwert: „#A0A0A0“)

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

font.setColor("#FFFFFF");

italic (Standardwert: false)

Wird dieser Wert auf true gesetzt, wird eine kursive Schriftlage für den Text gewählt.

font.setItalic(true);

outline (Standardwert: false)

Wird dieser Wert auf true gesetzt, wird eine Outline Font für den Text gewählt.

font.setOutline(true);

size (Standardwert: 24)

Legt die Schriftgröße des Texts fest.

font.setSize(12);

Das Objekt „position“

Die Wahl der Position des Wasserzeichens erfolgt, indem Sie dem Image oder Text Objekt ein WatermarkPositionType Objekt hinzufügen.

WatermarkPositionType position = new WatermarkPositionType();
image.setPosition(position);

Am Objekt Position lassen sich folgende Parameter setzen:

x (Standardwert: 0)

Legt die x-Position des Wasserzeichens in Relation zur gewählten Position und unter Nutzung der gewählten Metrics fest.

position.setX(15);

y (Standardwert: 0)

Legt die y-Position des Wasserzeichens in Relation zur gewählten Position und unter Nutzung der gewählten Metrics fest.

position.setY(-6);

width (Standardwert: 0)

Legt die Breite des Wasserzeichens in unter Nutzung der gewählten Metrics fest, sobald der Wert von 0 abweicht. (Kann zu Qualitätsverlusten durch Verzerrungen führen.)

position.setWidth(200);

height (Standardwert: 0)

Legt die Höhe des Wasserzeichens in unter Nutzung der gewählten Metrics fest, sobald der Wert von 0 abweicht. (Kann zu Qualitätsverlusten durch Verzerrungen führen.)

position.setHeight(16);

metrics (Standardwert: „mm“)

Gibt die Maßeinheit an, in der die Größenangaben übriger Parameter erfolgen. Folgende Werte können hier gesetzt werden:

• mm = Millimeter
• px = Pixel

position.setMetrics(MetricsType.PX);

position (Standardwert: „center_center“)

Nutzt eine von mehreren voreingestellten Positionen, um das Wasserzeichen auf der Seite zu platzieren. Folgende Werte können hier gesetzt werden:

• custom = Deaktiviere die Nutzung einer voreingestellten Position.
• top_left = Positioniere das Wasserzeichen in der oberen, linken Ecke.
• top_center = Positioniere das Wasserzeichen in der Mitte am oberen Rand.
• top_right = Positioniere das Wasserzeichen in der oberen, rechten Ecke.
• center_left = Positioniere das Wasserzeichen in der Seitenmitte links.
• center_center = Positioniere das Wasserzeichen mitten auf der Seite.
• center_right = Positioniere das Wasserzeichen in der Seitenmitte rechts.
• bottom_left = Positioniere das Wasserzeichen in der unteren, linken Ecke.
• bottom_center = Positioniere das Wasserzeichen in der Mitte am unteren Rand.
• bottom_right = Positioniere das Wasserzeichen in der unteren, rechten Ecke.

position.setPosition(WatermarkPositionModeType.BOTTOM_RIGHT);

aspectRatio (Standardwert: true)

Wird dieser Wert auf true gesetzt, so wird versucht das Seitenverhältnis des Wasserzeichens beizubehalten, wenn eine fixierte Höhe oder Breite gesetzt wird. Diese verhindert Verzerrungen der Grafik.

position.setAspectRatio(false);

Bei den Beschreibungen der Webservice-Aufrufe geben wir jeweils noch ein etwas ausführlicheres Beispiel für die Ansprache der SOAP Schnittstelle in diesem Stil:

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:
    WatermarkType watermark = new WatermarkType();
    toolboxWebService.getOperation().add(watermark);

    watermark.setPages("1,3-5,6");
    watermark.setAngle(66);

    WatermarkTextType text = new WatermarkTextType();
    watermark.setText(text);

    WatermarkFontType font = new WatermarkFontType();
    text.setFont(font);
    font.setOpacity(35);
    font.setName("FontName");
    font.setBold(true);
    font.setColor("#FFFFFF");
    font.setItalic(true);
    font.setOutline(true);
    font.setSize(12);

    WatermarkPositionType position = new WatermarkPositionType();
    text.setPosition(position);

    position.setX(15);
    position.setY(-6);
    position.setWidth(200);
    position.setHeight(16);
    position.setMetrics(MetricsType.PX);
    position.setPosition(WatermarkPositionModeType.BOTTOM_RIGHT);
    position.setAspectRatio(false);

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

Unser Tipp:

• Weitere Parameter werden Sie auch in unserem Nutzerhandbuch dokumentiert (dort ohne Beispiele zur Nutzung mittels der wsclient Bibliothek). Hier geht’s zur Watermark Parameterstruktur
• Beachten Sie bitte auch: Die Parameter sind mit bestimmten 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.