Code-Example: Attachment operation

Manage attachments with the wsclient library

In this article we would like to introduce you to the Attachment operation of the ToolboxWebService of webPDF and how you can use it via the webPDF 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

First step

To call the Webservice exactly as we want, you should already have created a REST or SOAP session and be able to create either a ToolboxWebService object (for a SOAP session) or a ToolboxRestWebService object (for a REST session) by calling the WebserviceFactory. And have passed either a RestDocument or a SoapDocument object to this WebService object by calling the method setDocument().

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

Code snippet 2:

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

Webservice parameters – specify Open or Permission password

To get changing access to a document, you have to give the current open and/or permission password of the document to the webservice call (if your document has an appropriate password protection). You can do this directly on the created toolboxWebService object:

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

What is the Toolbox Webservice?

The ToolboxWebservice acts as the endpoint of your webPDF server, which summarizes some operations with which you can edit your PDF document. We would like to demonstrate this here with a coding example. In this case it is the attachment operation. This allows you to embed, remove or extract attachments from a document.

To add an attachment operation to your WebService object:

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

The following parameters can be set for the attachment object:

The “add” object

To embed attachments in the document, add an AttachmentType.Add object to the attachment object.

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

The following parameters can be set on the add object:

The “file” object

To select one or more attachments for embedding, add one or more FileAttachmentType objects to the add object.

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

The following parameters can be set for the file object:

fileName (default value: “”)

Defines the name with which the attachment is to be stored in the document.

file.setFileName("xyz.json");

The “data” object

Select the attachment to embed by adding an AttachmentFileDataType object to the file object.

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

The following parameters can be set for the data object:

source

Specifies the source from which the attachment is to be obtained. The following values can be set here:

• value = The data is transferred directly as byte array.
• uri = A URI reference to the data is passed.

data.setSource(FileDataSourceType.VALUE);

value

Passes the attachment in the form of a byte array. (source should be set to value.)

(The byte array is created using the FileUtils class of the Apache Commons IO library.)

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

uri

Passes a URI reference to the attachment to be embedded. (source should be set to uri.)

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

The “annotation” object

If the attachment is to be embedded as an annotation on a page of the document rather than on the document level, add a FileAnnotationType object to the file object.

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

The following parameters can be set for the file object:

page (default value: 1)

This value selects the page on which the annotation is to be placed.

annotation.setPage(1);

color (default value: “#4800FF”)

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

annotation.setColor("#FFFFFF");

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 percent can be selected.

annotation.setOpacity(60);

icon (default value: “paperclip”)

This value selects the icon with which the attachment is displayed on the page. The following values can be set here:

• graph = Diagram
• paperclip = paperclip
• pushPin = pin
• tag = label

annotation.setIcon(IconsType.PUSH_PIN);

lockedPosition (default value: true)

If this value is set to true, the annotation cannot be moved.

annotation.setLockedPosition(false);

popupText (default value: “”)

This value determines the tooltip to be displayed for the annotation.

annotation.setPopupText("Example popup text");

The object “point

To determine the position of the annotation on the page, add a PointType object to the annotation object.

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

At the object point the following parameters can be set:

x Position (default value: “0”)

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

point.setX(15);

y Position (default value: “0”)

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

point.setY(15);

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)

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

point.setMetrics(MetricsType.PX);

The “remove” object

You can remove an attachment from a document by adding an AttachmentType.Remove object to the attachment object.

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

You can set the following parameters on the remove object:

The “selection” object

To delete one or more attachments from the document, add one or more SelectionAttachmentType objects to the remove object.

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

The following parameters can be set on the selection object:

pages (default value: „“)

Specifies the page area from which attachments are to be removed. You can specify either a single page („1“), a list of pages („1,3,5“), a page range („1-5“), or a combination of these elements („1,3-5,6“). All pages of the document can be selected using „*“.

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

context (default value: „all“)

Attachments can be embedded at document and page level. This value determines the level from which attachments are to be deleted. The following values can be set here:

• all = All levels
• document = Only from the document level
• page = Only from the page level

selection.setContext(ContextType.PAGE);

If document is selected here, the value set for pages has no effect.

fileMask (default value: „“)

The names of all attachments found in the selected area are checked against this mask and are either selected for deletion or excluded from deletion. The specification of wildcards is possible. For example, the mask "*.xls" would delete all attachments with the extension "xls" from the area. Direct selection of attachments with a certain file name is also possible. The mask "xyz.json" would remove all attachments with exactly this name.

selection.setFileMask("*.xls");

The object „extract“

To extract one or more attachments from the document into a ZIP archive, add an AttachmentType.Extract object(s) to the attachment object.

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

At the object selection the following parameters can be set:

folderNameTemplate (default value: „page[%d]“)

A separate folder is created in the ZIP archive for each page from which attachments are extracted. This value determines the name of these folders, whereby the placeholder "%d" is replaced by the page number and must be contained.

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

The object „selection“

To extract one or more attachments from the document, add one or more SelectionAttachmentType objects to the extract object.

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

The following parameters can be set for the selection object:

pages (default value: „“)

Specifies the page range from which attachments are to be extracted. You can specify either a single page (“1”), a list of pages (“1,3,5”), a page range (“1-5”), or a combination of these elements (“1,3-5,6”). All pages of the document can be selected using “*”.

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

context (default value: „all“)

Attachments can be embedded at document and page level. This value determines the level from which attachments are to be extracted. The following values can be set here:

• all = All levels
• document = Only from the document level
• page = Only from the page level

selection.setContext(ContextType.PAGE);

If document is selected here, the value set for pages has no effect.

fileMask (default value: „“)

The names of all attachments found in the selected area are checked against this mask and either selected for extraction or excluded from it. The specification of wildcards is possible. For example, the mask "*.xls" would extract all attachments with the ending "xls" from the area. Direct selection of attachments with a certain file name is also possible. The mask "xyz.json" would extract all attachments with exactly this name.

selection.setFileMask("*.xls");

More detailed example for 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 in 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");

    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("Example popup text");

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

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

    // execution.
    toolboxWebService.process();
} catch (ResultException | MalformedURLException ex) {
    // To evaluate possible errors that may have occurred, the
    // wsclient library appropriate methods are available:
}

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