Code Example: Attachment Operation of the Toolbox Webservice

Minimum Technical Requirements​

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

Managing Attachments with the wsclient Library​

In this article, we introduce the Attachment operation of the webPDF Toolbox Webservice and show how to use it with the webPDF wsclient library.

Important Note​

The following code example is based on the webPDF wsclient library. To understand and apply it correctly, you should first read the relevant introductory blog post.

First Step​

To call the webservice exactly as required, you should already have created a REST or SOAP session. You should also be able to create either a ToolboxWebService object for a SOAP session or a ToolboxRestWebService object for a REST session via WebserviceFactory. In addition, you should already have passed either a RestDocument or a SoapDocument object to this webservice object using the setDocument() method.

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

Code Snippet 2​

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

Webservice Parameters: Passing the Open or Permission Password​

If your document is password-protected and you need to modify it, you must pass the current open and/or permission password to the webservice call. 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 an endpoint on your webPDF server that combines several operations for editing PDF documents. In this example, we focus on the attachment operation, which allows you to embed attachments into a document, remove them, or extract them from the document.

Adding an Attachment Operation to Your Webservice Object​

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

The following parameters can be configured on the attachment object.

The add Object​

To embed attachments into 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 configured on the add object.

The file Object​

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

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

The following parameters can be configured on the file object.

fileName (default value: "")​

Defines the name under which the attachment is 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 configured on the data object.

source​

Specifies the source from which the attachment is loaded. The following values are available:

  • value = The data is passed directly as a byte array.
  • uri = A URI reference to the data is passed.
data.setSource(FileDataSourceType.VALUE);

value​

Passes the attachment as a byte array. In this case, source should be set to value.

The byte array is created here using the FileUtils class from Apache Commons IO.

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

uri​

Passes a URI reference to the attachment to be embedded. In this case, source should be set to uri.

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

The annotation Object​

If the attachment should not be embedded at document level but as an annotation on a page, add a FileAnnotationType object to the file object.

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

The following parameters can be configured on the file object.

page (default value: 1)​

Selects the page on which the annotation should be placed.

annotation.setPage(1);

color (default value: "#4800FF")​

Selects the text color using a HEX RGB value.

annotation.setColor("#FFFFFF");

opacity (default value: 100)​

A percentage value that defines the opacity of the annotation. The higher the value, the less transparent the annotation appears. Any value between 0 and 100 percent can be used.

annotation.setOpacity(60);

icon (default value: "paperclip")​

Selects the symbol used to display the attachment on the page. The following values are available:

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

Defines the tooltip text displayed for the annotation.

annotation.setPopupText("Example popup text");

The point Object​

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

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

The following parameters can be configured on the point object.

x Position (default value: "0")​

Defines the x-coordinate at which the annotation should be positioned.

point.setX(15);

y Position (default value: "0")​

Defines the y-coordinate at which the annotation should be positioned.

point.setY(15);

coordinates (default value: "user")​

Selects the coordinate system to which the position refers. The following values are available:

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

metrics (default value: "mm")​

Defines the unit used for coordinates. The following values are available:

  • mm = Millimeters
  • px = Pixels
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);

The following parameters can be configured on the remove object.

The selection Object​

To remove 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 configured on the selection object.

pages (default value: "")​

Defines the page range from which attachments should be removed. You can specify 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"). Use "*" to select all pages of the document.

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

context (default value: "all")​

Attachments can be embedded at document level and page level. This value determines from which level attachments should be removed. The following values are available:

  • all = All levels
  • document = Document level only
  • page = Page level only
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 deletion or excluded from deletion. Wildcards are supported. For example, the mask "*.xls" removes all attachments with the xls extension from the selected area. You can also select attachments directly by file name. The mask "xyz.json" removes all attachments with exactly that name.

selection.setFileMask("*.xls");

The extract Object​

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

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

The following parameters can be configured on the extract object.

folderNameTemplate (default value: "page[%d]")​

For each page from which attachments are extracted, a separate folder is created in the ZIP archive. This value defines the name of those folders. The placeholder "%d" is replaced by the page number and must be included.

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

The selection Object​

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

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

The following parameters can be configured on the selection object.

pages (default value: "")​

Defines the page range from which attachments should be extracted. You can specify 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"). Use "*" to select all pages of the document.

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

context (default value: "all")​

Attachments can be embedded at document level and page level. This value determines from which level attachments should be extracted. The following values are available:

  • all = All levels
  • document = Document level only
  • page = Page level only
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 extraction. Wildcards are supported. For example, the mask "*.xls" extracts all attachments with the xls extension from the selected area. You can also select attachments directly by file name. The mask "xyz.json" extracts all attachments with exactly that name.

selection.setFileMask("*.xls");

More Detailed Example for Addressing the SOAP Interface​

try (
    // Set up a session with the webPDF server, here using SOAP.
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Provide the document to be processed and the target file.
    SoapDocument soapDocument = new SoapDocument(
        new File("Path of the source document").toURI(),
        new File("Path of the target document")
    )
) catch (ResultException | MalformedURLException ex)

More code examples for webservices that you can use with the wsclient library can be found here.