Coding Example: Insert Notes and Comments

Technical Minimum Requirements​

  • Java version: 7
  • webPDF version: 7
  • wsclient version: 1

webPDF Toolbox Webservices: Manage Annotations with the wsclient Library​

This example shows how to use the Annotation operation of the webPDF Toolbox Webservices with the wsclient library.

Important Note​

The following coding example is based on the webPDF wsclient library. To understand and apply the example, the related blog post should be reviewed first.

Starting the Webservice Call​

To call the webservice as shown here, you must already have created a REST or SOAP session. Then, using the WebServiceFactory, you can create either a ToolboxWebService object for SOAP or a ToolboxRestWebService object for REST.

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

Then pass either a RestDocument or a SoapDocument to the WebService object using setDocument().

How Do You Get Write Access to a Document?​

To get modifying access, it is often necessary to provide the current open and/or permission password of the document to the webservice call.

You can do this directly on the created ToolboxWebService object:

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

If the document is not password protected, you can skip this step.

The Toolbox Webservice as an Endpoint of Your webPDF Server​

The Toolbox Webservice combines a range of operations for manipulating PDF documents.

Here, the focus is on the Annotation operation. With it, you can add notes, correction hints, or comments to a document.

Add an Annotation operation to your WebService object like this:

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

The following parameters can be set on the Annotation object:

The add Object​

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 markup Object​

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 on the Markup object:

markupType (default: "highlight")​

Defines the annotation's markup type. The following values can be set:

  • highlight = highlight text
  • underline = underline text with a straight line
  • strikeOut = strike out text
  • squiggly = underline text with a wavy line
markup.setMarkupType(MarkupsAnnotationType.HIGHLIGHT);

The path Object​

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: "0")​

Defines the x-coordinate where the annotation should be positioned.

path.setX(15);

y Position (default: "0")​

Defines the y-coordinate where the annotation should be positioned.

path.setY(15);

width (default: 0)​

Sets the width of the annotation using the selected metrics.

path.setWidth(200);

height (default: 0)​

Sets the height of the annotation using the selected metrics.

path.setHeight(16);

coordinates (default: "user")​

Selects the coordinate system used for positioning:

  • user = user coordinate system, origin top left
  • pdf = PDF coordinate system, origin bottom left
path.setCoordinates(CoordinatesType.USER);

metrics (default: "mm")​

Defines the measurement unit used for coordinates:

  • mm = millimeter
  • px = pixel
path.setMetrics(MetricsType.PX);

The text Object​

Text annotations are used to place notes and correction hints 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 on the Text object:

icon (default: "note")​

Selects the icon shown on the page for the text annotation. The following values can be set:

  • comment = comment
  • key = key
  • note = text note
  • help = help
  • newParagraph = new paragraph
  • paragraph = paragraph
  • insert = insert text
text.setIcon(TextAnnotationIconsType.NEW_PARAGRAPH);

initialOpen (default: false)​

Specifies whether the popup, meaning the actual text content of the annotation, should be visible immediately when the page is viewed.

text.setInitialOpen(true);

The position Object​

To position 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 on the Position object:

x Position (default: "0")​

Defines the x-coordinate where the annotation should be positioned.

position.setX(15);

y Position (default: "0")​

Defines the y-coordinate where the annotation should be positioned.

position.setY(15);

width (default: 0)​

Sets the width of the annotation using the selected metrics.

position.setWidth(200);

height (default: 0)​

Sets the height of the annotation using the selected metrics.

position.setHeight(16);

coordinates (default: "user")​

Selects the coordinate system used for positioning:

  • user = user coordinate system, origin top left
  • pdf = PDF coordinate system, origin bottom left
position.setCoordinates(CoordinatesType.USER);

metrics (default: "mm")​

Defines the measurement unit used for coordinates:

  • mm = millimeter
  • px = pixel
position.setMetrics(MetricsType.PX);

General Parameters for text and markup Annotations​

The following parameters can also be set on both Text and Markup annotations:

creator (default: "")​

Defines the author of the annotation.

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

name (default: "")​

Defines the name of the annotation.

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

subject (default: "")​

Defines the subject of the annotation.

[markup/text].setSubject("Annotation topic");

contents (default: "")​

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

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

intents (default: "")​

Defines a text describing the purpose of creating the annotation.

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

opacity (default: 100)​

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

[markup/text].setOpacity(60);

hidden (default: false)​

If set to true, the annotation is neither visible in viewers nor on printouts.

[markup/text].setHidden(true);

invisible (default: false)​

If set to true, the annotation is only visible when it is a standard PDF annotation and the document is printed.

[markup/text].setInvisible(true);

printable (default: false)​

If set to true, the annotation is visible on printouts of the page.

[markup/text].setPrintable(true);

locked (default: false)​

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

[markup/text].setLocked(true);

color (default: "#4800FF")​

Selects the annotation color using a HEX-RGB value.

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

viewable (default: "true")​

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

[markup/text].setViewable(true);

writable (default: "true")​

If set to true, the annotation can be changed.

[markup/text].setWritable(false);

zoomable (default: "true")​

If set to true, the annotation dynamically adapts its display to zoom changes in order to remain clearly visible.

[markup/text].setZoomable(false);

Detailed Example for the Full Webservice Call​

SOAP interface example:

try (
    // Set up a session with the webPDF server (SOAP in this example):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Provide the document to be processed
    // and the file to which the result should be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Path to the source document").toURI(),
        new File("Path to the target document")
    )
) catch (ResultException | MalformedURLException ex) {
    // Error handling
}

More coding examples for webservices that can be used with the wsclient library can be found here.