Webservice Addressing with the ant-task library

If you use Apache Ant, …

… then perhaps the question is obvious for you: Couldn’t the webPDF webservices be called from an Ant Target? This would allow you to define a fixed sequence of consecutive webservice calls that would be automatically repeatable for a large number of documents. (Picture: https://www.apache.org/)

The short answer:

Yes, I can!

The “webPDF ant-task” library (short “ant-task”) defines some simple tasks, which you can use to start single or multiple webPDF webservice calls or to sequence their execution. This library thus offers you a series of simple tools to realize complex workflows for the creation, manipulation or evaluation of PDF documents.

(The webservice calls themselves are carried out using the “webPDF wsclient” -library, which might also be of interest to you).

ant-task on GitHub and in Maven Central

The publicly accessible and free ant-task library can be integrated into all Ant-based construction processes (webPDF Server Version 7 and higher). We make the library available to you as a public project under GitHub:

https://github.com/softvision-dev/webpdf-ant

In this public project the library will be maintained by us, further developed and adapted to new versions of webPDF. Your feedback or comments and ideas for further development are always welcome. If you find problems, please report an error after searching for duplicates or create a pull request.

For direct and easy integration into your project, we always provide the latest version of the library as a Maven package via Maven-Central:

<dependency>
    <groupId>net.webpdf</groupId>
    <artifactId>webpdf-ant</artifactId>
    <version>1.0.0</version>
</dependency>

Using Apache IVY, you can include the library in your ivy.xml as follows:

<?xml version="1.0" encoding="UTF-8"?>
<ivy-module version="2.0">
  <info organisation="org.apache" module="hello-ivy"/>
  <dependencies>
    <dependency org="net.webpdf" name="webpdf-ant" rev="1.0.0"/>
  </dependencies>
</ivy-module>

webPDF webservicecall from an Ant Target

In the following, we want to develop an ant build file that is able to extract files from a folder, convert them to PDF format using the Converter webservice, and write the results to a target folder.

The Converter webservice serves here only as a placeholder for all other webPDF webservices. All other webservices can be called in a similar way.

Definition of the project and preliminary work

We start our Ant build file as usual with the declaration of the project and define the namespaces ivy (to get the webPDF Ant task library via IVY) and webpdf (to call the tasks easier.):

<project name="ant-task" default="executeWebPDFTask" basedir="."
         xmlns:ivy="antlib:org.apache.ivy.ant"
         xmlns:webpdf="http://schema.webpdf.de/1.0/operation">

We now define the target to be called and first make sure that both our source and target folders are available:

<target name="executeWebPDFTask">
    <mkdir dir="source-documents"/>
    <mkdir dir="target-documents"/>

Then we get the necessary libraries via ivy and load the task definitions (antlib.xml) for our webservice call from the ant-task library:

<ivy:resolve/>
<ivy:retrieve/>
<taskdef resource="antlib.xml"
    classpath="lib/webpdf-ant-1.0.0.jar"/>

The „webpdf“ task

The webpdf task is the entry point for the definition of a webPDF webservice call and defines basic options and parameters for the connection setup to the webPDF server and the webservices to be executed.

The task is defined as follows:

<webpdf serverurl="http://localhost:8080/webPDF"
        targetdir="target-documents"
        failonerror="true">

The task itself provides the following attributes:

• serverurl The address (and port) of the webPDF server on which webservices are to be executed.
• tempdir (optional) If this path is passed, temporary files are created here instead of in the system-wide temporary directory.
• targetdir Specifies a path in which the results of the webservice calls are stored.
• failonerror (optional) If this boolean value is set to “true”, execution is interrupted immediately if the first error occurs.

Authentication

If the webPDF server requires a user name and password, these can be specified in the element webpdf in an element usercredentials:

<usercredentials username="admin" password="admin"/>

The element provides the following attributes:

• username The user name.
• password The associated password.

Selection of source files

To pass one or more source documents to the task for processing, we can pass either a “file” or a “fileset” element to the webpdf task. For example, the following definition would cause all PNG files that we place in our source folder to be processed one by one by the task:

<fileset dir="source-documents">
    <include name="**/*.png"/>
</fileset>

The choice of name for the generated documents can be influenced here by an appropriate mapping – for example, the following mapping would result in all generated documents having the same name as their source document, but with the extension “pdf” instead of “png”.

<globmapper from="*.png" to="*.pdf"/>

The „operation“ task

To select and parameterize the desired webPDF webservice endpoint, we use the operation task. There we can store an element that reflects the addressed endpoint, makes all its parameters available via attributes and may contain all substructures, as described in the user manual. In our case, this is the converter element, which we define as follows:

<webpdf:operation>
    <webpdf:converter pages="1" jpegQuality="100"/>
</webpdf:operation>

The „group“ task

An operation task cannot be added directly to the webpdf task and must always be included in a group task. A group task bundles several webservice calls and places them in a fixed execution order. Each webservice call defined in the group task uses the result document of the previous call as its source document. By default, all intermediate results are only temporarily saved and deleted as soon as they are no longer needed.

In this case we would like to call the Converter webservice first and put it into a group task as follows:

<group>
    <webpdf:operation>
        <webpdf:converter pages="1" jpegQuality="100"/>
    </webpdf:operation>
</group>

group tasks are defined in the webpdf task. Only the result of the last operation, the last group of the webpdf task, is usually written to the target directory.

The result

The overall result is therefore as follows:

<?xml version="1.0" encoding="UTF-8"?>
<project name="ant-task" default="executeWebPDFTask" basedir="."
         xmlns:ivy="antlib:org.apache.ivy.ant"
         xmlns:webpdf="http://schema.webpdf.de/1.0/operation">

    <target name="executeWebPDFTask">
        <echo>+++ PREPARE +++</echo>
        <mkdir dir="source-documents"/>
        <mkdir dir="target-documents"/>

        <echo>+++ IVY RESOLVE DEPENDENCIES +++</echo>
        <ivy:resolve/>
        <ivy:retrieve/>
        <taskdef resource="antlib.xml"
        classpath="lib/webpdf-ant-1.0.0.jar"/>

        <echo>+++ EXECUTE WEBPDF-TASK +++</echo>
        <webpdf serverurl="http://localhost:8080/webPDF"
                targetdir="target-documents"
                failonerror="true">
            <!--Authentifizierungsoptionen-->
            <usercredentials username="admin" password="admin"/>
            <!--Wahl der Quelldokumente-->
            <fileset dir="source-documents">
                <include name="**/*.png"/>
            </fileset>
            <globmapper from="*.png" to="*.pdf"/>
            <!--Abfolge der Webseriveaufrufe-->
            <group>
                <webpdf:operation>
                    <webpdf:converter pages="1" jpegQuality="100"/>
                </webpdf:operation>
            </group>
        </webpdf>
        <echo>+++ EXECUTION FINISHED +++</echo>
    </target>
</project>

The build file and the target executeWebPDFTask are now ready for execution. It will automatically obtain the necessary libraries, prepare source and destination folders and automatically convert all PNG documents of the source folder into PDF documents using the webPDF Converter webservice and store them in the destination folder.

Concatenation of operations and groups

As mentioned above, a group task can perform multiple operations in a row, using the result of a previous operation as the source document for the subsequent operation.

For this purpose, several operation elements are simply defined one after the other in a group:

<group>
    <webpdf:operation>...</webpdf:operation>
    <webpdf:operation>...</webpdf:operation>
</group>

It is also possible to concatenate several groups in this way, whereby the following group uses the result of the previous group as the source document:

<webpdf>
    <group>...</group>
    <group>...</group>
</webpdf>

Redirecting Intermediate Results to a Variable

To implement more complex operations, the result of a group can be redirected to a variable so that it can be accessed later. For this purpose, the generated results can be stored in OUTPUT variables for later use. (The corresponding temporary file will be excluded from deletion in this case)

For example, the result of a group could be stored in a variable called out:

<group>
    <var name="out" role="OUTPUT"/>
    <webpdf:operation>…</webpdf:operation>
    <webpdf:operation>…</webpdf:operation>
</group>

The path to the last result generated in this group is stored in a variable named out. This variable can then be accessed via ${out} as usual.

The document stored in out would also correspond to the processing state at this time if other groups were to follow which use this document as their source document.

Setting the source document using a variable

Usually the webpdf task processes the files of a fileset or a similar selection. It sets the selected documents one after the other as the source document of the first group. The group performs operations on the basis of this document, generates an intermediate result and passes this on to a subsequent group as its source document and so on.

If we do not want a subsequent group to continue working with the result of the previous group, we can use an INPUT variable to define the path to a file that it should use as the source document instead:

<group>
    <var name="in" role="INPUT" value="any file path"/>
    <webpdf:operation>…</webpdf:operation>
    <webpdf:operation>…</webpdf:operation>
</group>

This only replaces the document processed by the first operation of the group, the resulting result and all subsequent intermediate results are passed on to the successors as usual.

Use of Input and Output Variables

To illustrate the benefits of input and output variables, we consider the following example:

<group>
    <var name="out" role="OUTPUT"/>
    <webpdf:operation>
        <webpdf:converter/>
    </webpdf:operation>
</group>
<group>
    <var name="in" role="INPUT" value="any file path"/>
    <var name="out2" role="OUTPUT"/>
    <webpdf:operation>
        <webpdf:converter/>
    </webpdf:operation>
</group>
<group>
    <var name="in2" role="INPUT" value="${out}"/>
    <webpdf:operation>
        <webpdf:merge>
            <webpdf:data source="uri" uri="file:///${out2}"/>
        </webpdf:merge>
    </webpdf:operation>
</group>

The first group regularly converts a document determined by the webpdf Task using the Converter webservice and generates an intermediate result, the path to this result is stored in the variable out.

The second group would now usually continue working with the created intermediate result, but instead a document is passed to it via the variable in using a fixed file path. It converts this document using the Converter webservice and generates an intermediate result whose path is stored in the variable out2.

The third group finally receives the result of the first group as source document via the variable in2, the contained Merge operation receives the result of the second group as data parameter. The second generated intermediate result is appended to the back of the first generated intermediate result.

Finally, the result of the third group represents the overall result of these three groups.