Webservice PDF/A

In diesem Coding-Beispiel möchten wir Ihnen die Operation des webPDF Webservice pdfa vorstellen und wie Sie diese mit Hilfe der webPDF 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

Webservice aufrufen

Um den Webservice aufzurufen, sollten Sie zuvor bereits eine REST- oder SOAP-Session erzeugt haben und somit über Aufruf der WebserviceFactory entweder ein PdfaWebService Objekt (für eine SOAP Session) erzeugen können:

PdfaWebService pdfaWebService= WebServiceFactory.createInstance(session, WebServiceType.PDFA);

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

PdfaRestWebService pdfaWebService= WebServiceFactory.createInstance(session, WebServiceType.PDFA);

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

Der pdfa Webservice

Der pdfa Webservice ist ein Endpunkt Ihres webPDF Servers, der die Umwandlung von PDF-Dokumenten in PDF/A-Formate und deren Validierung ermöglicht.

Die Pdfa Operation vom Typ PdfaType können Sie neu initialisieren und im Webservice setzen oder die automatisch generierte Instanz des Webservices nutzen.

PdfaType pdfaType=pdfaWebService.getOperation();

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

Das Objekt „convert“

In diesem Objekt werden alle Einstellungen für eine Konvertierung zu PDF/A gesetzt.

PdfaType.Convert convert = new PdfaType.Convert();
pdfaType.setConvert(convert);

level (Standardwert: „1b“)

Gibt die angestrebte Konformitätsebene für die PDF/A-Erstellung (gemäß ISO 19005) an.

• 1a = PDF/A-1a
• 1b = PDF/A-1b
• 2a = PDF/A-2a
• 2b = PDF/A-2b
• 2u = PDF/A-2u
• 3a = PDF/A-3a
• 3b = PDF/A-3b
• 3u = PDF/A-3u

convert.setLevel("3b");

imageQuality (Standardwert: 75)

Mit dem Parameter wird die Qualität für Bilder festgelegt, die während der Konvertierung umgewandelt werden müssen, weil sie eine nicht erlaubte Komprimierung (z.B. JPX ist nicht in PDF/A-1 erlaubt) verwenden. Es sind Werte im Bereich von 1 bis 100 erlaubt, wobei ein höherer Wert bessere Qualität bedeutet, aber auch größere PDF-Dokumente.

convert.setImageQuality(90);

errorReport (Standardwert: „none“)

Über diesen Parameter wird mit einem Feld des Enum Typs PdfaErrorReportType bestimmt, ob und wenn in welcher Form der XML-Bericht für eine fehlgeschlagene Konvertierung zurückgeliefert wird.

• PdfaErrorReportType.NONE = XML-Bericht wird nicht zurückgeliefert
• PdfaErrorReportType.MESSAGE = XML-Bericht wird als Bestandteil der Fehlernachricht geliefert
• PdfaErrorReportType.FILE = XML-Bericht wird in Datei gespeichert

convert.setErrorReport(PdfaErrorReportType.MESSAGE);

successReport (Standardwert: „none“)

Über diesen Parameter wird mit einem Feld des Enum Typs PdfaSuccessReportType bestimmt, ob und wenn in welcher Form der XML-Bericht für eine erfolgreiche Konvertierung zurückgeliefert wird.

• PdfaSuccessReportType.NONE = XML-Bericht wird nicht zurückgeliefert
• PdfaSuccessReportType.LINKED = XML-Bericht wird an das Ende des PDF/A-Dokuments angehangen(XML muss aus dem PDF-Dokument nach dem auslesen entfernt werden).
• PdfaSuccessReportType.ZIP = PDF/A-Dokument und XML-Bericht werden zusammen in ein ZIP-Archiv gepackt.

convert.setSuccessReport(PdfaSuccessReportType.NONE);

Das Objekt „zugferd“

Mit diesem Bereich kann optional ein ZUGFeRD-Dokument eingebunden werden, welches mindestens mit dem Level PDF/A-3a konvertiert werden muss.

ZugferdType zugferd = new ZugferdType();
convert.setZugferd(zugferd);

Das Objekt „xmlFile“

ZUGFeRD-Datei als „Base64 encoded“. Die Datei wird vor der Einbettung gegen das ZUGFeRD XSD-Schema validiert. Sollte Sie nicht gültig sein, so wird der Vorgang abgebrochen. Ein Objekt vom Typ ZugferdFileDataType wird mit einem Objekt vom Typ FileDataSourceType, welches die Base64 encodierten XML-Daten enthält, befüllt und an das Objekt des Typs ZugferdType übergeben.

ZugferdFileDataType zugferdFileData = new ZugferdFileDataType();
FileDataSourceType fileDataSource = FileDataSourceType
        .fromValue(Base64.encodeBase64String(FileUtils.readFileToByteArray(zugferdXmlFile)));
zugferdFileData.setSource(fileDataSource);
zugferd.setXmlFile(zugferdFileData);

Das Objekt „analyze“

Operation Objekt zur Überprüfung auf PDF/A -Konformität eines Dokumentes.

PdfaType.Analyze analyze = new PdfaType.Analyze();
pdfaType.setAnalyze(analyze);

level (Standardwert: „1b“)

PDF/A-Level zu dem die Konformität geprüft werden soll.

analyze.setLevel("3b");

Beispiel Webserviceaufruf (SOAP):

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:
    PdfaWebService pdfaWebService = WebServiceFactory.createInstance(session, WebServiceType.PDFA);
    pdfaWebService.setDocument(soapDocument);

    // Objektorientierte Parametrisierung des Aufrufs:
    PdfaType pdfaType = pdfaWebService.getOperation();

    PdfaType.Convert convert=new PdfaType.Convert();
    pdfaType.setConvert(convert);        
    convert.setLevel("3b");        
    convert.setSuccessReport(PdfaSuccessReportType.NONE);        
    convert.setErrorReport(PdfaErrorReportType.FILE);        
    convert.setImageQuality(90);

    // Ausführung.
    pdfaWebService.process();
} catch (ResultException | MalformedURLException ex) {

    // Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
    // wsclient Bibliothek entsprechende Methoden zur Verfügung:
}

Hinweis: Die Parameter sind natürlich auch in unserem Nutzerhandbuch dokumentiert.

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