Coding Beispiel: Anmerkungen und Kommentare einfügen

webPDF Toolbox Webservices: Annotationen verwalten mit der wsclient Bibliothek

Hier möchten wir an einem Beispiel (Annotation Operation) zeigen, die Sie Operationen der 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

Start mit dem Webservice Aufruf

Um den Webservice wie in diesem Beispiel aufzurufen, müssen Sie vorher bereits eine REST- oder SOAP-Session erzeugt haben. Dann kann über den Aufruf der WebserviceFactory entweder ein ToolboxWebService Objekt (für eine SOAP Session) oder ein ToolboxRestWebService Objekt (für eine REST Session) erzeugt werden.

ToolboxWebService Objekt (für eine SOAP Session):

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

ToolboxRestWebService Objekt (für eine REST Session):

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

Danach sollte dem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben werden.

Wie erhalten Sie ändernden Zugriff auf ein Dokument?

Um ändernden Zugriff zu erhalten, ist es oft nötig dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mit zu geben.

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

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

Der Toolbox Webservice als Endpunkt Ihres webPDF Servers

Der Toolbox Webservice fasst eine Reihe von Operationen zusammen, mit denen Sie Ihr PDF Dokument manipulieren können.

Hier soll es jetzt um die Annotation Operation gehen. Mit dieser können Sie Anmerkungen, Korrekturhinweise oder Kommentare am Dokument anbringen.

Dafür fügen Sie Ihrem WebService Objekt wie folgt eine Annotation Operation hinzu:

AnnotationType annotation = new AnnotationType();
toolboxWebService.getOperation().add(annotation);

Am Objekt Annotation lassen sich folgende Parameter setzen:

Das Objekt „add“

Um Annotationen für Ihre Dokument zu erstellen, fügen Sie dem Annotation Objekt ein AnnotationType.Add Objekt hinzu.

AnnotationType.Add add = new AnnotationType.Add();
annotation.setAdd(add);

Am Objekt Add lassen sich folgende Parameter setzen:

Das Objekt „markup“

Markup Annotationen dienen dazu Textelemente hervorzuheben oder anderweitig zu markieren. Um eine oder mehrere Markup-Annotation zu erstellen, fügen Sie dem Add Objekt ein oder mehrere MarkupAnnotationType Objekt/e hinzu.

MarkupAnnotationType markup = new MarkupAnnotationType();
add.getMarkup().add(markup);

Am Objekt Markup lassen sich folgende Parameter setzen:

markupType (Standardwert: „highlight“)

Legt den MarkupType der Annotation fest. Folgende Werte können hier gesetzt werden:

• highlight = Text hervorheben
• underline = Text unterstreichen mit gerader Linie
• strikeOut = Text durchstreichen
• squiggly = Text unterstreichen mit gewellter Linie

markup.setMarkupType(MarkupsAnnotationType.HIGHLIGHT);

Das Objekt „path“

Gibt die Position des zu markierenden Textes als eine Folge von Rechtecken an. Fügen Sie hierfür dem Markup Objekt ein oder mehrere RectangleType Objekte hinzu.

RectangleType path = new RectangleType();
markup.getPathElement().add(path);

Am Objekt Path lassen sich folgende Parameter setzen:

x Position (Standardwert: „0“)

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

path.setX(15);

y Position (Standardwert: „0“)

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

path.setY(15);

width (Standardwert: 0)

Legt die Breite der Annotation unter Nutzung der gewählten metrics fest.

path.setWidth(200);

height (Standardwert: 0)

Legt die Breite der Annotation unter Nutzung der gewählten metrics fest.

path.setHeight(16);

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)

path.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

path.setMetrics(MetricsType.PX);

Das Objekt „text“

Text Annotationen dienen dazu Anmerkungen und Korrekturhinweise auf einer Seite zu platzieren. Um eine oder mehrere Text-Annotation zu erstellen, fügen Sie dem Add Objekt ein oder mehrere TextAnnotationType Objekt/e hinzu.

TextAnnotationType text = new TextAnnotationType();
add.getText().add(text);

Am Objekt Text lassen sich folgende Parameter setzen:

icon (Standardwert: „note“)

Wählt das Symbol, das für diese Textannotation auf der Seite angezeigt werden soll. Folgende Werte können hier gesetzt werden:

• comment = Kommentar
• key = Schlüssel
• note = Textnotiz
• help = Hilfe
• newParagraph = neuer Absatz
• paragraph = Absatz
• insert = Text einfügen

text.setIcon(TextAnnotationIconsType.NEW_PARAGRAPH);

initialOpen (Standardwert: false)

Gibt an, ob das Popup (also der eigentlich Textinhalt der Text Annotation) bei Betrachtung der Seite direkt sichtbar sein soll.

text.setInitialOpen(true);

Das Objekt „position“

Um die Text Annotationen auf der Seite zu positionieren, fügen Sie dem Text Objekt ein RectangleType Objekt hinzu.

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

Am Objekt Position lassen sich folgende Parameter setzen:

x Position (Standardwert: „0“)

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

path.setX(15);

y Position (Standardwert: „0“)

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

path.setY(15);

width (Standardwert: 0)

Legt die Breite der Annotation unter Nutzung der gewählten Metrics fest.

path.setWidth(200);

height (Standardwert: 0)

Legt die Breite der Annotation unter Nutzung der gewählten Metrics fest.

path.setHeight(16);

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)

path.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

path.setMetrics(MetricsType.PX);

Allgemeine Parameter für „text“ und „markup“ Annotationen

An sowohl Text-, als auch Markup Annotationen lassen sich darüber hinaus folgende Parameter setzen:

creator (Standardwert: „“)

Legt den Verfasser der Annotation fest.

[markup/text].setCreator("Creator");

name (Standardwert: „“)

Legt den Namen der Annotation fest.

[markup/text].setName("Annotationsname");

subject (Standardwert: „“)

Legt das Thema der Annotation fest.

[markup/text].setSubject("Annotationsthema");

contents (Standardwert: „“)

Legt den textuellen Inhalt der Annotation fest, der in Abhängigkeit von der gewählten Annotation dargestellt wird. (Für eine Textannotation als Inhalt des Popups)

[markup/text].setContents("Inhalt der Annotation");

intents (Standardwert: „“)

Legt einen Text fest, der die Intention, diese Annotation zu erstellen, beschreibt.

[markup/text].setIntents("Zweck der Annotation");

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 gewählt werden.

[markup/text].setOpacity(60);

hidden (Standardwert: false)

Wird dieser Wert auf true gesetzt, wird die Annotation weder in Anzeigeprogrammen, noch auf Ausdrucken sichtbar sein.

[markup/text].setHidden(true);

invisible (Standardwert: false)

Wenn dieser Wert auf true gesetzt wird, wird die Annotation nur dann auf der Seite sichtbar sein, sofern es sich um eine PDF Standardannotation handelt, wenn sie gedruckt wird.

[markup/text].setHidden(true);

printable (Standardwert: false)

Wird dieser Wert auf true gesetzt, wird die Annotation auf Ausdrucken der Seite sichtbar sein.

[markup/text].setPrintable(true);

locked (Standardwert: false)

Wird dieser Wert auf true gesetzt, ist die Annotation gegen Änderungen gesperrt.

[markup/text].setLocked(true);

color (Standardwert: „#4800FF“)

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

[markup/text].setColor("#FFFFFF");

viewable (Standardwert: „true“)

Wird dieser Wert auf true gesetzt, wird die Annotation auf der Seite des Dokuments angezeigt.

[markup/text].setViewable(true);

writable (Standardwert: „true“)

Wird dieser Wert auf true gesetzt, kann die Annotation verändert werden.

[markup/text].setWritable(false);

zoomable (Standardwert: „true“)

Wird dieser Wert auf true gesetzt, passt die Annotation ihre Darstellung dynamisch an Änderungen des Zoomfaktors an, um stets gut erkennbar zu bleiben.

[markup/text].setZoomable(false);

Ausführliches Beispiel für den gesamten Webservice-Auruf (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");

    AnnotationType annotation = new AnnotationType();
    toolboxWebService.getOperation().add(annotation);

    AnnotationType.Add add = new AnnotationType.Add();
    annotation.setAdd(add);

    MarkupAnnotationType markup = new MarkupAnnotationType();
    add.getMarkup().add(markup);

    markup.setCreator("Creator");
    markup.setName("Annotationsname");
    markup.setSubject("Annotationsthema");
    markup.setContents("Inhalt der Annotation");
    markup.setIntents("Zweck der Annotation");
    markup.setHidden(true);
    markup.setInvisible(true);
    markup.setViewable(true);
    markup.setZoomable(false);

    markup.setMarkupType(MarkupsAnnotationType.HIGHLIGHT);

    RectangleType path = new RectangleType();
    markup.getPathElement().add(path);

    path.setX(15);
    path.setY(20);
    path.setWidth(80);
    path.setHeight(14);
    path.setCoordinates(CoordinatesType.USER);
    path.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.