ToolboxWebService Extraction: Seiten entnehmen

Extraktion von Inhalten mit der webPDF wsclient Bibliothek

Hier geben wir ein konkretes Coding Beispiel für die Extraction Operation des webPDF ToolboxWebService und wie diese mit der wsclient Bibliothek umgesetzt werden kann.

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

Wichtige Vorarbeiten

Um den Webservice Art aufrufen zu können, sollten Sie vorher eine REST- oder SOAP-Session erzeugt haben. Danach ist es dann möglich, ü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
    );

Sie können dann diesem WebService Objekt über Aufruf der Methode setDocument() entweder ein RestDocument oder ein SoapDocument Objekt übergeben.

Wie sehen die Webservice Parameter aus?

Vor allen Dingen, um ändernden Zugriff auf ein Dokument zu erhalten, müssen Sie dem Webserviceaufruf das aktuelle open und/oder permission Passwort des Dokuments mitgeben. Tun Sie das am Besten direkt am erzeugten ToolboxWebService Objekt:

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

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

Der ToolboxWebService im Detail

Der ToolboxWebService ist ein Endpunkt Ihres webPDF Servers, welcher eine Reihe von Operationen zusammenfasst. Mit diesen Operationen können Sie Ihr PDF Dokument bearbeiten. Eine dieser Operationen ist die Extraction Operation. Um dieses Beispiel soll es hier konkret gehen. Mit der Extraction Operation können bestimmte Inhalte aus einem PDF-Dokument extrahiert, also herausgezogen werden.

So fügen Sie Ihrem WebService Objekt eine Extraction Operation hinzu:

ExtractionType extraction = new ExtractionType();
toolboxWebService.getOperation().add(extraction);

Die Auswahl der Inhalte, die extrahiert werden sollen, erfolgt indem dem Objekt Extraction ein entsprechendes Objekt hinzugefügt wird. Folgendes sind hier Ihre Wahlmöglichkeiten:

Das Objekt „text“

Sollen Texte aus dem Dokument extrahiert werden, dann setzen Sie ein ExtractionTextType Objekt am Extraction Objekt. (erzeugt wahlweise eine Text-, XML- oder JSON-Datei)

ExtractionTextType text = new ExtractionTextType();
extraction.setText(text);

Am Objekt Text lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „xml“)

Legte das Ausgabeformat der extrahierten Inhalte fest. Folgende Werte können hier gesetzt werden:

• text = Textdokument
• xml = XML-Dokument
• json = JSON-Dokument

text.setFileFormat(ExtractionFileFormatType.XML);

Das Objekt „links“

Sollen Links aus dem Dokument extrahiert werden, dann setzen Sie ein ExtractionLinksType Objekt am Extraction Objekt. (erzeugt wahlweise eine Text-, XML- oder JSON-Datei)

ExtractionLinksType links = new ExtractionLinksType();
extraction.setLinks(links);

Am Objekt Links lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „xml“)

Legte das Ausgabeformat der extrahierten Inhalte fest. Folgende Werte können hier gesetzt werden:

• text = Textdokument
• xml = XML-Dokument
• json = JSON-Dokument

links.setFileFormat(ExtractionFileFormatType.XML);

Das Objekt „text“ (ExtractionLinksType Unterstruktur)

Üblicherweise extrahiert die Extraktion von Links lediglich Annotationen, die klar als solche markiert sind. Sollen Links auch direkt aus den Seitentexten extrahiert werden, so kann dem Objekt Links ein ExtractionLinksType.Text Objekt hinzugefügt werden.

ExtractionLinksType.Text text = new ExtractionLinksType.Text();
links.setText(text);

Am Objekt Text lassen sich folgende Parameter setzen:

fromText (Standardwert: false)

Wird dieser Wert auf true gesetzt, so werden links auch aus den Seiteninhalten extrahiert.

text.setFromText(true);

protocol (Standardwert: „“)

Bietet die Möglichkeit, nur Links eines bestimmten Protokolls zu extrahieren. Es ist möglich mehrere Protokolle durch Kommata getrennt anzugeben (zum Beispiel: „http,https,ftp“).

text.setProtocol("http,https,ftp");

withoutProtocol (Standardwert: true)

Wird dieser Wert auf true gesetzt, dann werden auch URL/URI ähnliche Strukturen extrahiert, bei denen kein Protokoll angegeben ist. (also beispielsweise: www.webpdf.de)

text.setWithoutProtocol(false);

Das Objekt „info“

Sollen Informationen und Metainformationen aus dem Dokument extrahiert werden, (wie zum Beispiel die Sicherheitseinstellungen, PDF-Eigenschaften oder den PDF/A-Status) dann setzen Sie ein ExtractionInfoType Objekt am Extraction Objekt. (erzeugt wahlweise eine XML- oder JSON-Datei)

ExtractionInfoType info = new ExtractionInfoType();
extraction.setInfo(info);

Am Objekt Info lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „xml“)

Legte das Ausgabeformat der extrahierten Inhalte fest. Folgende Werte können hier gesetzt werden:

• text = Textdokument
• xml = XML-Dokument
• json = JSON-Dokument

info.setFileFormat(ExtractionFileFormatType.XML);

Das Objekt „words“

Sollen Texte Wortweise und mit Koordinatenangabe aus dem Dokument extrahiert werden, dann setzen Sie ein ExtractionWordsType Objekt am Extraction Objekt. (erzeugt wahlweise eine Text-, XML- oder JSON-Datei)

ExtractionWordsType words = new ExtractionWordsType();
extraction.setWords(words);

Am Objekt Words lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „xml“)

Legte das Ausgabeformat der extrahierten Inhalte fest. Folgende Werte können hier gesetzt werden:

• text = Textdokument
• xml = XML-Dokument
• json = JSON-Dokument

words.setFileFormat(ExtractionFileFormatType.XML);

delimitAfterPunctuation (Standardwert: true)

Wird dieser Wert auf true gesetzt, gelten auch sämtliche Satzzeichen als Wortbegrenzungen.

words.setDelimitAfterPunctuation(false);

extendedSequenceCharacter (Standardwert: false)

Wird dieser Wert auf true gesetzt, werden nicht nur Umklammerungszeichen (Eckige und runde Klammern) dem Wort angefügt, sondern auch Anführungszeichen, Apostrophe und ähnliches.

words.setExtendedSequenceCharacters(true);

removePunctuation (Standardwert: false)

Wird dieser Wert auf true gesetzt, werden sämtliche Satzzeichen vom Export ausgenommen.

words.setRemovePunctuation(true);

Das Objekt „paragraphs“

Sollen Texte Artikelweise aus dem Dokument extrahiert werden, dann setzen Sie ein ExtractionParagraphsType Objekt am Extraction Objekt. (erzeugt wahlweise eine Text-, XML- oder JSON-Datei)

ExtractionParagraphsType paragraphs = new ExtractionParagraphsType();
extraction.setParagraphs(paragraphs);

Am Objekt Paragraphs lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „xml“)

Legt das Ausgabeformat der extrahierten Inhalte fest. Folgende Werte können hier gesetzt werden:

• text = Textdokument
• xml = XML-Dokument
• json = JSON-Dokument

paragraphs.setFileFormat(ExtractionFileFormatType.XML);

Das Objekt „images“

Sollen Bilder als ZIP-Datei aus dem Dokument extrahiert werden, dann setzen Sie ein ExtractionImagesType Objekt am Extraction Objekt. (erzeugt eine ZIP-Datei)

ExtractionImagesType images = new ExtractionImagesType();
extraction.setImages(images);

Am Objekt Images lassen sich folgende Parameter setzen:

pages (Standardwert: „“)

Legt den Seitenbereich fest, aus dem Inhalte extrahiert 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.

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

fileFormat (Standardwert: „zip“)

Legt das Ausgabeformat für die zu extrahierenden Bilder fest. Folgende Werte können hier gesetzt werden:

• zip = ZIP-Archiv

paragraphs.setFileFormat(ExtractionFileFormatType.XML);

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

Dieser Wert ist ein Template für die Namen der Bilder im ZIP-Archiv. Der Platzhalte „%d“ muss enthalten werden und wird durch einen Index ersetzt.

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

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

Dieser Wert ist ein Template für die Namen der Ordner des ZIP-Archiv. Für jede Seite, von der Bilder extrahiert werden, wird ein solcher Ordner erschaffen. Der Platzhalte „%d“ muss enthalten werden und wird durch die Seitennummer ersetzt.

extractionImagesType.setFolderNameTemplate("page[%d]");

fallbackFormat (Standardwert: „png“)

Beim Export von Bildern aus einem PDF wird versucht die Bilder in dem Format zu extrahieren, in dem sie im PDF-Dokument hinterlegt wurden, sollte dies nicht möglich sein, da beispielsweise das betreffende Format nicht unterstützt wird, so legt dieser Wert das Format fest, auf das zurückgefallen werden soll. Folgende Werte können hier gesetzt werden:

• png = PNG-Datei
• jpeg = JPEG-Datei

extractionImagesType.setFallbackFormat(ExtractionImageFormat.PNG);

Webservice-Aufruf per Ansprache der SOAP Schnittstelle

Wir wollen nun ein ausführlicheres Beispiel für unseren gesamten Webserviceaufruf (für die Ansprache der SOAP Schnittstelle) geben:

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

    ExtractionType extraction = new ExtractionType();
    toolboxWebService.getOperation().add(extraction);

    ExtractionImagesType extractionImagesType = new ExtractionImagesType();
    extraction.setImages(extractionImagesType);

    extractionImagesType.setFileFormat(ExtractionFileFormatType.ZIP);
    extractionImagesType.setPages("1-5");

    extractionImagesType.setFileNameTemplate("image[%d]");
    extractionImagesType.setFolderNameTemplate("page[%d]");
    extractionImagesType.setFallbackFormat(ExtractionImageFormat.PNG);

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

Unsere Dokumentation

• Hier finden Sie eine ausführliche Darstellung der Parameter, hier ohne Beispiele zur Nutzung mittels der wsclient Bibliothek: extraction Parameterstruktur
• Eine Dokumentation der Errorcodes und eventuell auftretenden Fehler, finden Sie hier.
• Beachten Sie auch: Sämtliche Parameter sind mit gewissen Standardwerten vorbelegt. Ist ein Standardwert angegeben und weicht dieser nicht von Ihrem gewünschten Wert ab, so ist es nicht zwingend nötig diesen Parameter zu setzen.

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