webPDF Toolbox Webservice Image: Grafikexport

In diesem Beitrag möchten wir anhand von Code-Beispielen die Image Operation des webPDF ToolboxWebService vorstellen und zeigen, wie Sie diese mit der wsclient Bibliothek nutzen können.

Wichtiger Hinweis:

Das nun folgende Coding-Beispiel beruht auf der Nutzung der webPDF wsclient Bibliothek. Um das Beispiel zu verstehen und anzuwenden, sollte zunächst folgender Blogbeitrag beachtet werden:

webPDF und Java: mit der „wsclient“ Bibliothek ganz einfach

 

Um diesem Beispiel genau zu folgen, sollten Sie den Webservice genau so aufrufen, wie hier vorgestellt. Dafür sollte zunächst eine REST- oder SOAP-Session erzeugt werden und somit über Aufruf der WebserviceFactory entweder ein ToolboxWebService Objekt (für eine SOAP Session) erzeugen können:

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

Oder ein ToolboxRestWebService Objekt (für eine REST Session) erzeugen können:

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

Und dann sollte diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben werden.

Passwortschutz: Ändernden Zugriff erhalten

Wie erhalten Sie ändernden Zugriff auf ein Dokument, um es gezielt zu verändern?

Um ändernden Zugriff auf ein Dokument zu erhalten, ist es häufig nötig dem Webserviceaufruf das open und/oder permission Passwort des Dokuments mit zu geben. Das können Sie am erzeugten ToolboxWebService Objekt tun:

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

(Verfügt das Dokument nicht über einen entsprechenden Passwortschutz, so können Sie diesen Punkt überspringen.)

Der Webservice Parameter Image

Der ToolboxWebService ist ein Endpunkt Ihres webPDF Servers, der eine Reihe von Operationen zusammenfasst, mit denen Sie ihr PDF Dokument manipulieren können. Eine dieser Operationen ist die Image Operation, die uns hier als Beispiel dient.

Die Image Operation (Grafikexport) ermöglicht es, Seiten des PDF Dokuments als Bild zu exportieren.

Sie fügen Ihrem WebService Objekt wie folgt eine Image Operation hinzu:

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

Mögliche Parameter am Objekt Image

pages (Standardwert: „1“)

Legt den Seitenbereich fest, von dessen Seiten Bilder erzeugt werden soll. Es kann entweder eine Einzelseite („1“) eine Auflistung von Seiten („1,3,5“), ein Seitenbereich („1-5“) oder eine Kombination dieser Elemente („1,3-5,6“) angegeben werden. Alle Seiten des Dokuments können über „*“ ausgewählt werden.

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

fileNameTemplate (Standardwert: „page[%d]“)

Werden mehrere Seiten des Dokuments exportiert, so werden die Einzelbilder üblicherweise in einem ZIP-Archiv hinterlegt. Dieses Template bestimmt über den Namen der einzelnen Bilddateien im Archiv. Die Zeichenfolge „%d“ muss hierbei enthalten sein und wird durch die Seitennummer ersetzt.

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

Das Bildformat wählen

Wird dem Objekt Image ein Objekt der Typen JpegType, GifType, PngType, TiffType oder BmpType übergeben, so werden sämtliche exportierten Bilder im gewählten Format erzeugt.

Im Folgenden möchten wir zunächst die gemeinsamen Parameter besprechen und dann kurz auf die Eigenarten der verschiedenen Formate eingehen.

An sämtlichen dieser Objekte lassen sich folgende Parameter setzen:

metrics (Standardwert: „mm“)

Gibt die Maßeinheit an, in der die Größenangaben übriger Parameter erfolgen. Folgende Werte können hier gesetzt werden:

• mm = Millimeter
• px = Pixel

format.setMetrics(MetricsType.PX);

height (Standardwert: 0)

Die maximale Höhe, der exportierten Bilder. (Ein Wert von 0 bedeutet keine Beschränkung.)

format.setHeight(600);

width (Standardwert: 0)

Die maximale Breite, der exportierten Bilder. (Ein Wert von 0 bedeutet keine Beschränkung.)

format.setHeight(600);

dpi (Standardwert: 72)

Mit diesem Parameter wird die DPI-Auflösung der Grafik festgelegt. Je größer der Wert, desto größer die X/Y-Auflösung der Grafik. Außerdem steigt mit zunehmender DPI-Auflösung auch die Byte-Größe der Grafikdatei.

format.setDpi(200);

Das Bildformat „jpeg“

Wird dem Objekt Image ein JpegType Objekt übergeben, so werden sämtliche exportierten Bilder im JPEG Format exportiert.

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

Zusätzlich zu den Standardparametern, kann am Objekt Jpeg zusätzlich folgender Parameter gesetzt werden:

jpegQuality (Standardwert: 80)

Mit diesem prozentualen Wert wird die Kompression der erzeugten JPEG Bilder beeinflusst. Dieser Wert kann zwischen 1 und 100 liegen. Je höher der Wert gewählt wird, desto geringer werden die Qualitätsverluste gegenüber dem Original sein, aber desto geringer wird das Bild auch komprimiert sein.

jpeg.setJpegQuality(100);

Das Bildformat „bmp“

Wird dem Objekt Image ein BmpType Objekt übergeben, so werden sämtliche exportierten Bilder im Bitmap Format exportiert.

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

Für das Bitmap Format stehen keine weiteren Parameter zur Verfügung, außer den Standardparametern.

Das Bildformat „png“

Wird dem Objekt Image ein PngType Objekt übergeben, so werden sämtliche exportierten Bilder im PNG Format exportiert.

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

Für das PNG Format stehen keine weiteren Parameter zur Verfügung, außer den Standardparametern.

Das Bildformat „gif“

Wird dem Objekt Image ein GifType Objekt übergeben, so werden sämtliche exportierten Bilder im GIF Format exportiert.

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

Für das GIF Format stehen keine weiteren Parameter zur Verfügung, außer den Standardparametern.

Das Bildformat „tiff“

Wird dem Objekt Image ein TiffType Objekt übergeben, so werden sämtliche exportierten Bilder im TIFF Format exportiert.

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

Zusätzlich zu den Standardparametern, können am Objekt Tiff zusätzlich folgender Parameter gesetzt werden:

multipage (Standardwert: false)

Wird dieser Wert auf true gesetzt, so wird für einen mehrseitigen Export statt eines ZIP-Archivs ein Multipage Tiff erstellt.

tiff.setMultipage(true);

compression (Standardwert: false)

Mit diesem Wert wird die Kompressionsmethode für die exportierten Tiffs festgelegt. Folgende Werte können hier gesetzt werden:

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

Unser Code-Beispiel

Abschließend folgt hier ein noch ausführlicheres Beispiel für unseren gesamten Webserviceaufruf (für die Ansprache der SOAP Schnittstelle):

try (
    // Aufbau einer Session mit dem webPDF Server(hier SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Bereit stellen des Dokuments, das verarbeitet werden soll
    // und der Datei, in die das Ergebnis geschrieben werden soll:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Wahl des Webservices über eine Factory:
    ToolboxWebService toolboxWebService =
        WebServiceFactory.createInstance(
            session, WebServiceType.TOOLBOX
        );
    toolboxWebService.setDocument(soapDocument);
    toolboxWebService.getPassword().setOpen("password");
    toolboxWebService.getPassword().setPermission("password");

    // Objektorientierte Parametrisierung des Aufrufs:
    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);

    // Ausführung.
    toolboxWebService.process();
} catch (ResultException | MalformedURLException ex) {
    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
}

Weitere Coding-Beispiele für Webservices, welche Sie mit der ws-client Bibliothek nutzen können finden Sie hier.