webPDF Toolbox Webservice Image: Graphic Export

In this article we would like to introduce the image operation of the webPDF ToolboxWebService using code examples and show how you can use it with 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

To follow this example exactly, you should call the webservice exactly as presented here. Therefore you should first create a REST- or SOAP-Session and then either create a ToolboxWebService object (for a SOAP session) by calling the WebserviceFactory:

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

Or create a ToolboxRestWebService object (for a REST session):

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

And then either a RestDocument or a SoapDocument object should be passed to this WebService object by calling the method setDocument().

Password protection: Get changing access

How do you get changing access to a document in order to change it specifically?

To get changing access to a document, it is often necessary to give the open and/or permission password of the document to the webservice call. You can do this with the created ToolboxWebService object:

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

(If the document does not have an appropriate password protection, you can skip this point.)

The Webservice parameter Image

The ToolboxWebService is an endpoint of your webPDF server that summarizes a number of operations with which you can manipulate your PDF document. One of these operations is the Image operation, which is used here as an example.

The Image operation allows you to export pages of a PDF document as an image.

You add an image operation to your WebService object as follows:

ImageType image = new ImageType();
toolboxWebService.getOperation().add(image);

Possible parameters of the Image object

pages (default value: „1“)

Defines the page area from whose pages images are to be generated. 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“) can be specified. All pages of the document can be selected using  „*“.

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

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

If several pages of the document are exported, the individual images are usually stored in a ZIP archive. This template determines the name of the individual image files in the archive. The character string „%d“ must be included and is replaced by the page number.

image.setFileNameTemplate("p[%d]");

Select the image format

If an object of the types JpegType, GifType, PngType, TiffType or BmpType is passed to the object Image, all exported images are created in the selected format.

In the following we will first discuss the common parameters and then briefly discuss the peculiarities of the different formats.

The following parameters can be set for all of these objects:

metrics (default value: „mm“)

Specifies the unit of measurement in which the sizes of other parameters are specified. The following values can be set here:

• mm = millimeter
• px = Pixel

format.setMetrics(MetricsType.PX);

height (default value: 0)

The maximum height of the exported images. (A value of 0 means no limitation.)

format.setHeight(600);

width (Default value: 0)

The maximum width of the exported images. (A value of 0 means no limitation.)

format.setHeight(600);

dpi (Default value: 72)

This parameter determines the DPI resolution of the graphic. The larger the value, the larger the X/Y resolution of the graphic. In addition, the byte size of the graphic file increases with increasing DPI resolution.

format.setDpi(200);

The „jpeg“ image format

If a JpegType object is passed to the Image object, all exported images are exported in JPEG format.

JpegType jpeg = new JpegType();
image.setJpeg(jpeg);

In addition to the standard parameters, the following parameters can also be set for the Jpeg object:

jpegQuality (default value: 80)

With this percentage value the compression of the JPEG images is influenced. This value can be between 1 and 100. The higher the value, the lower the loss of quality compared to the original will be, but the less compressed the image will be.

jpeg.setJpegQuality(100);

The image format „bmp“

If a BmpType object is passed to the Image object, all exported images are exported in bitmap format.

BmpType bmp = new BmpType();
image.setBmp(bmp);

There are no other parameters available for the bitmap format, except the standard parameters.

The image format „png“

If a PngType object is passed to the Image object, all exported images are exported in PNG format.

PngType png = new PngType();
image.setPng(png);

There are no other parameters available for the PNG format, except the standard parameters.

The „gif“ image format

If a GifType object is passed to the Image object, all exported images are exported in GIF format.

GifType gif = new GifType();
image.setGif(gif);

There are no other parameters available for the GIF format, except the standard parameters.

The „tiff“ image format

If a TiffType object is transferred to the Image object, all exported images are exported in TIFF format.

TiffType tiff = new TiffType();
image.setTiff(tiff);

In addition to the standard parameters, the following parameters can also be set for the TIFF object:

multipage (default value: false)

If this value is set to true, a Multipage Tiff is created for a multi-page export instead of a ZIP archive.

tiff.setMultipage(true);

compression (default value: false)

This value determines the compression method for the exported tiffs. The following values can be set here:

• rle = TIFF CCITT Modified Huffman RLE compression
• deflate = TIFF Deflate lossless compression (Zip-in-TIFF).
• group3 = TIFF CCITT Group 3 fax encoding
• group4 = TIFF CCITT Group 4 fax encoding
• jpeg = TIFF JPEG-in-TIFF compression
• lzw = TIFF LZW Compression
• packbits = TIFF Byte-oriented run-length encoding “PackBits” compression
• zlib = TIFF ZLib Compression

tiff.setCompression(TiffCompressionType.DEFLATE);

Our code example

Finally, here is an even more detailed example of our entire webservice call (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 that is 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");

    // Object-oriented parameterization of the call:
    ImageType image = new ImageType();
    toolboxWebService.getOperation().add(image);

    image.setPages("1,3-5,6");
    image.setFileNameTemplate("p[%d]");
    
    PngType png = new PngType();
    image.setPng(png);

    png.setMetrics(MetricsType.PX);
    png.setHeight(600);
    png.setWidth(800);
    png.setDpi(200);

    // Execution.
    toolboxWebService.process();
} catch (ResultException | MalformedURLException ex) {
    // To evaluate possible errors that 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.