wsclient Bibliothek: Webservice Converter

Wie läuft die Konvertierung diverser Formate mit der webPDF wsclient Bibliothek ab? Hier wollen wir die Operation des webPDF Webservices Converter detailliert vorstellen und zeigen, wie Sie diese mit Hilfe der webPDF wsclient Bibliothek am besten 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

Start mit einer REST oder SOAP Session

Wir gehen davon aus, dass Sie als Vorbereitung bereits eine REST- oder SOAP-Session erzeugt haben und somit über Aufruf der WebserviceFactory entweder ein ConverterWebService Objekt (für eine SOAP Session) erzeugen können:

ConverterWebService converterWebService = WebServiceFactory
.createInstance(session, WebServiceType.CONVERTER)

..oder ein ConverterRestWebService Objekt (für eine REST Session) erzeugen können:

ConverterRestWebService converterWebService = WebServiceFactory
.createInstance(session,WebServiceType.CONVERTER);

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

Beschreibung des Converter Webservice

Der Converter Webservice ist ein Endpunkt Ihres webPDF Servers, der die Konvertierung von diversen Formaten hin zum PDF-Format ermöglicht. Die Converter Operation vom Typ ConverterType können Sie neu initialisieren und im Webservice setzen oder die automatisch generierte Instanz des Webservices nutzen.

ConverterType converterType=converterWebService.getOperation();

Für die ConverterType Instanz lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den auszugebenden Seitenbereich für das Konvertierungsergebnis fest.  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.

converterType.setPages("*");

accessPassword (Standardwert: „“)

Mit dem Parameter kann ein Passwort angegeben werden, das zum Öffnen des Ausgangsdokument verwendet wird, wenn dieses geschützt ist.

converterType.setAccessPassword("password");

compression (Standardwert: true)

Legt fest ob alle Datenobjekte im Ergebnis-PDF komprimiert werden sollen. Dies reduziert die Größe des Dokumentes.

converterType.setCompression(true);

dpi (Standardwert: 300)

Gibt die DPI-Auflösung (Punkte pro Zoll) für das zu erzeugende Dokument an.

converterType.setDpi(300);

embedFonts (Standardwert: false)

Mit diesem Parameter kann angegeben werden, ob die originalen Schriftarten in das Dokument eingebunden werden. Wenn diese nicht auf dem Server verfügbar sind kann es dazu kommen, dass Ersatzschriften eingebunden werden. Ist Vorgesehen ein PDF/A Dokument zu erzeugen sollte das Parameter nicht gesetzt werden(wird anderweitig automatisch vorgenommen).

converterType.setEmbedFonts(true);

jpegQuality (Standardwert: 90)

Über diesen Parameter kann die angestrebte Qualität für JPEG-Grafiken in Prozent für das zu erzeugende Dokument prozentual angegeben werden.

converterType.setJpegQuality(90);

fileExtension (Standardwert: „“)

Mit dem Parameter kann die automatische Erkennung des Dateiformates von webPDF umgangen werden. Das Parameter sollte nur in seltenen Ausnahmefällen genutzt werden. Die automatische Erkennung von webPDF erkennt in der Regel das Dateiformat und verarbeitet es dementsprechend.

converterType.setFileExtension("xml")

Das Objekt „html“

In diesem Objekt werden Einstellungen gesetzt die für die Konvertierung von HTML und HTML-basierenden Dokumenten(beispielsweise E-Mails) relevant sind.

ConverterHtmlType html=new ConverterHtmlType();
converterType.setHtml(html);

adjustFonts (Standardwert: false)

Ändert automatisch die Schriftangaben in HTML basierenden Dokumenten von „Arial“, „Helvetica“ und „Sans-Serif“ in dem erzeugten PDF-Dokument zu „Arial Unicode MS“. Dies verbessert das Schriftbild in der PDF-Ausgabe.

html.setAdjustFonts(true);

baseURL (Standardwert: „“)

Mit dem Parameter kann die Basis für alle im HTML enthaltenen URL’s definiert werden, die nicht absolut sind.

html.setBaseURL("https://www.webpdf.de/");

downloadImages (Standardwert: false)

Mit dem Parameter kann angegeben werden, dass alle Bilder des HTML Inhaltes heruntergeladen werden sollen

html.setDownloadImages(true);

Das Objekt „mail“

In diesem Objekt werden Einstellungen gesetzt, die für die Konvertierung von Mail-Dokumenten relevant sind.

ConverterMailType mail=new ConverterMailType();
converterType.setMail(mail);

adjustFonts (Standardwert: false)

Ändert automatisch die Schriftangaben im Mail-Dokument von „Arial“, „Helvetica“ und „Sans-Serif“ in dem erzeugten PDF-Dokument zu „Arial Unicode MS“. Dies verbessert das Schriftbild in der PDF-Ausgabe.

mail.setAdjustFonts(true);

attachmentMode (Standardwert: embed)

Legt den Umgang mit den Anhängen von Emails fest. AttachmentModeType.EMBED sorgt dafür, dass Anhänge in das PDF-Dokument eingebettet warden. AttachmentModeType.REMOVE sorgt dafür, dass Anhänge nicht im PDF-Dokument enthalten sind.

mail.setAttachmentMode(AttachmentModeType.EMBED);

downloadImages (Standardwert: false)

Mit dem Parameter kann angegeben werden, dass alle Bilder des HTML Inhaltes der Email heruntergeladen werden sollen

mail.setDownloadImages(true);

Das Objekt „officeBridge“

Durch das Hinzufügen eines Objektes dieses Typs wird angegeben, dass für die Konvertierung die Office Bridge verwendet werden soll. Wenn diese eingerichtet ist, werden Word, Excel und PowerPoint Dokumente über diese konvertiert.

converterType.setOfficeBridge(new OfficeBridgeType());

Das Objekt „sharePointBridge“

Wenn die SharePointBridge aktiviert ist wird durch das Setzen eines Objektes diesen Typs festgelegt, dass ein Word Dokument über einen SharePoint-Dienst konvertiert werden soll.

converterType.setSharePointBridge(new SharePointBridgeType());

Das Objekt „page“

Über Objekte dieses Typs können Angaben zum zu erzeugenden Seiten Format gemacht werden.

PageType page=new PageType();
converterType.setPage(page);

bottom (Standardwert: 20)

top (Standardwert: 20)

left (Standardwert: 20)

right (Standardwert: 20)

Legt die Randabstände des PDF-Dokuments fest. Der Wert bezieht sich jeweils auf die mit „metrics“ definierte Einheit (standartmäßig Millimeter).

page.setTop(20);
page.setBottom(20);
page.setLeft(20);
page.setRight(20);

height (Standardwert: 297)

width (Standardwert: 210)

Mit den Parametern kann die Seiten-Höhe und -Breite des PDF- Dokumentes angegeben werden. Der Wert bezieht sich jeweils auf die mit „metrics“ definierte Einheit (standartmäßig Millimeter).

page.setHeight(297);
page.setWidth(210);

metrics(Standardwert: mm)

Gibt die zu verwendenden Maßeinheit für die Einstellungen des Objektes an. Die Standartmaßeinheit ist Millimeter mit MetricsType.MM. Alternativ kann die Einheit Pixel mit MetricsType.PX gesetzt werden.

page.setMetrics(MetricsType.MM);

Das Objekt „pdfa“

Über ein Objekt dieses Typs wird die direkte Konvertierung zu PDF/A eingerichtet. Alle zu setzenden Eigenschaften finden Sie in der webPDF Dokumentation und in dem Artikel zur Nutzung des Pdfa-Webservices mit wsclient.

PdfaType pdfa=new PdfaType();
converterType.setPdfa(pdfa);

Das Objekt „signature“

Durch ein Objekt dieses Typs können dem Ergebnis Dokument Signaturen hinzugefügt werden. Alle zu setzenden Eigenschaften finden Sie in der webPDF Dokumentation und in dem Artikel zur Nutzung des Signature-Webservices mit wsclient.

SignatureType signature = new SignatureType();
converterType.setSignature(signature);

Das Objekt „report“

Ein Objekt dieses Typs ermöglicht ein erweitertes Fehler-Reporting für Text basierende Dokumente.

ConverterReportType report = new ConverterReportType();
converterType.setReport(report);

contentProblems (Standardwert: false)

Löst zu Problemen mit dem Dateiinhalt den spezifischen Fehler ERR_CONVERTER_CONTENT_PROBLEMS aus.

report.setContentProblems(true);

fontAliasUsage (Standardwert: false)

Löst im Fall, dass eine Schriftart nicht vorhanden ist und eine Ersatzschriftart genutzt wird den spezifischen Fehler ERR_CONVERTER_FONT_ALIAS_USED aus.

report.setFontAliasUsage(true);

fontIsMissing (Standardwert: false)

Löst im Fall, dass eine Schriftart nicht vorhanden ist den spezifischen Fehler ERR_CONVERTER_FONT_IS_MISSING aus.

report.setFontIsMissing(true);

Das Objekt „template“

Ermöglicht die Definition der Einstellungen für Dateiformate, für deren Konvertierung ein Template benötigt wird.

ConverterTemplateType template = new ConverterTemplateType();
converterType.setTemplate(template);

language (Standardwert „“)

Setzt den Sprach-Code, um ein lokalisiertes Template zu laden.

template.setLanguage("de");

Beispiel für 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:
    ConverterWebService converterWebService = WebServiceFactory.createInstance(session, WebServiceType.CONVERTER);
    converterWebService.setDocument(soapDocument);

    // Objektorientierte Parametrisierung des Aufrufs:
    ConverterType converterOperation = converterWebService.getOperation();
    
    PageType page = new PageType();
    converterOperation.setPage(page);
    page.setHeight(100);
    page.setWidth(300);
    
    // Ausführung.
    converterWebService.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.