Insert comments and annotations with wsclient library – Coding Example

webPDF Toolbox Webservices: Manage annotations with the wsclient library

Here we would like to show an example (Annotation Operation), which you can use to implement operations of the webPDF Toolbox Webservices with the help of the wsclient library.

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Start with the webservice call

To call the webservice as in this example, you must have already created a REST or SOAP session. Then either a ToolboxWebService object (for a SOAP session) or a ToolboxRestWebService object (for a REST session) can be created by calling the WebserviceFactory.

ToolboxWebService object (for a SOAP session):

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

ToolboxRestWebService object (for a REST session):

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

After that either a RestDocument or a SoapDocument object should be passed to the WebService object by calling the method setDocument().

How do you get changing access to a document?

To get modifying access, it is often necessary to give the current open and/or permission password of the document to the web service call. (If the document does not have an appropriate password protection, you can skip this point.)

You can do this directly at the created ToolboxWebService object:

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

The Toolbox Webservice as endpoint of your webPDF server

The Toolbox Webservice summarizes a number of operations with which you can manipulate your PDF document.

This is the annotation operation. With this you can add annotations, corrections or comments to the document.

To do this, add an annotation operation to your WebService object as follows:

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

The following parameters can be set for the Annotation object:

The object „add“

To create annotations for your document, add an AnnotationType.Add object to the Annotation object.

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

The following parameters can be set on the add object:

The object „markup“

Markup annotations are used to highlight or otherwise mark text elements. To create one or more markup annotations, add one or more MarkupAnnotationType objects to the Add object.

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

The following parameters can be set for the Markup object:

markupType (default value: „highlight“)

Defines the markup type of the annotation. The following values can be set here:

• highlight = Highlight text
• underline = underline text with straight line
• strikeOut = cross out text
• squiggly = underline text with wavy line

markup.setMarkupType(MarkupsAnnotationType.HIGHLIGHT);

The object „path“

Specifies the position of the text to be marked as a sequence of rectangles. Add one or more RectangleType objects to the markup object.

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

The following parameters can be set on the Path object:

x Position (default value: „0“)

This value determines the x-coordinate on which the annotation is to be positioned.

path.setX(15);

y Position (default value: „0“)

This value determines the y-coordinate on which the annotation is to be positioned.

path.setY(15);

width (default value: 0)

Sets the width of the annotation using the selected metrics.

path.setWidth(200);

height (default value: 0)

Sets the width of the annotation using the selected metrics.

path.setHeight(16);

coordinates (default value: „user“)

Selects the coordinate system to which the position is to be referenced. The following values can be set here:

• user = user coordinate system (origin left-above)
• pdf = PDF coordinate system (origin left-bottom)

path.setCoordinates(CoordinatesType.USER);

metrics (default value: „mm“)

The unit of measurement in which coordinates are to be specified. The following values can be set here:

• mm = millimeter
• px = Pixel

path.setMetrics(MetricsType.PX);

The object „text“

Text annotations are used to place annotations and correction notes on a page. To create one or more text annotations, add one or more TextAnnotationType objects to the Add object.

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

The following parameters can be set for the Text object:

icon (default value: „note“)

Selects the icon to be displayed on the page for this text annotation. The following values can be set here:

• comment = Comment
• key = key
• note = Text note
• help = Help
• newParagraph = new paragraph
• paragraph = paragraph
• insert = insert text

text.setIcon(TextAnnotationIconsType.NEW_PARAGRAPH);

initialOpen (default value: false)

Specifies whether the popup (i.e. the actual text content of the text annotation) should be directly visible when viewing the page.

text.setInitialOpen(true);

The object „position“

To position the text annotations on the page, add a RectangleType object to the text object.

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

The following parameters can be set at the object position:

x Position (default value: „0“)

This value determines the x-coordinate on which the annotation is to be positioned.

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);

General parameters for „text“  and „markup“  annotations

In addition, the following parameters can be set for both text and markup annotations:

creator (default value: „“)

Specifies the author of the annotation.

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

name (default value: „“)

Specifies the name of the annotation.

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

subject (default value: „“)

Sets the theme of the annotation.

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

contents (default value: „“)

Defines the textual content of the annotation, which is displayed depending on the selected annotation. (For a text annotation as content of the popup)

[markup/text].setContents("Content of the annotation");

intents (default value: „“)

Specifies a text describing the intention to create this annotation.

[markup/text].setIntents("Purpose of annotation");

opacity (default value: 100)

A percentage value that determines the opacity of the annotation. The higher the value, the less transparent the annotation will be. A value between 0 and 100 can be selected.

[markup/text].setOpacity(60);

hidden (default value: false)

If this value is set to true, the annotation will be visible neither in display programs nor on printouts.

[markup/text].setHidden(true);

invisible (default value: false)

If this value is set to true, the annotation will only be visible on the page if it is a PDF standard annotation when printed.

[markup/text].setHidden(true);

printable (default value: false)

If this value is set to true, the annotation will be visible on printouts of the page.

[markup/text].setPrintable(true);

locked (default value: false)

If this value is set to true, the annotation is locked against changes.

[markup/text].setLocked(true);

color (default value: „#4800FF“)

Selects the color of the text via a HEX-RGB value.

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

viewable (default value: „true“)

If this value is set to true, the annotation is displayed on the page of the document.

[markup/text].setViewable(true);

writable (default value: „true“)

If this value is set to true, the annotation can be changed.

[markup/text].setWritable(false);

zoomable (default value: „true“)

If this value is set to true, the annotation dynamically adapts its display to changes in the zoom factor in order to remain clearly visible at all times.

[markup/text].setZoomable(false);

Detailed example for the entire webservice call (addressing the SOAP interface):

try (
    // Setup of a session with the webPDF server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Make available the document to be processed 
   // and the file to which the result is to be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) {
    // Selection of the webservice via a 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("Annotationstopic");
    markup.setContents("Content of the annotation");
    markup.setIntents("Purpose of 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);

    // execution.
    toolboxWebService.process();
} catch (ResultException | MalformedURLException ex) {
    // For the evaluation of possible errors  
    // the wsclient library provides corresponding methods:
}

More coding examples for webservices that you can use with the ws-client library can be found here.