Webservice Barcodes lesen und erstellen
Minimum technical requirements
- Java version: 7
- webPDF version: 7
- wsclient version: 1
Hier wollen wir ein konkretes Code-Beispiel für den Barcode Webservice samt Nutzung mit der webPDF wsclient Bibliothek geben:
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:
Vorarbeiten für den Aufruf des Webservice
Um den Webservice auf die Art aufrufen zu können, die wie hier beschreiben, ist es nötig, dass Sie zuvor eine REST- oder SOAP-Session erzeugt haben. Somit können Sie dann über Aufruf der WebserviceFactory entweder ein BarcodeWebService Objekt (für eine SOAP Session) erzeugen:
BarcodeWebService barcodeWebService =
WebServiceFactory.createInstance(
session, WebServiceType.BARCODE
);
..oder ein BarcodeRestWebService Objekt (für eine REST Session):
BarcodeRestWebService barcodeWebService =
WebServiceFactory.createInstance(
session, WebServiceType.BARCODE
);
Und dann dem WebService Objekt über Aufruf der Methode setDocument() ein RestDocument oder ein SoapDocument Objekt übergeben.
Mehr zu den Webservice Parametern
Um ändernden Zugriff auf ein Dokument zu erhalten, müssen Sie dem Webserviceaufruf das aktuelle open und/oder permission Passwort mitgeben. Das können Sie am erzeugten barcodeWebService Objekt tun:
barcodeWebService.getPassword().setOpen("password");
barcodeWebService.getPassword().setPermission("password");
(Hinweis: Verfügt das Dokument nicht über einen entsprechenden Passwortschutz, so können Sie diesen Punkt überspringen.)
Beschreibung des Barcode Webservice
Der Barcode Webservice ist ein Endpunkt Ihres webPDF Servers, der es Ihnen ermöglicht, Barcodes in Ihrem PDF Dokument zu erstellen oder sie zu erkennen und ihre Inhalte auszugeben.
Sie rufen das BarcodeType Objekt wie folgt an Ihrem barcodeWebService Objekt ab, um ihm weitere Parameter zu übergeben:
BarcodeType barcode = barcodeWebService.getOperation();
Am Objekt Barcode lassen sich folgende Parameter setzen:
Das Objekt „add“
Um dem Dokument neue Barcodes hinzuzufügen, übergeben Sie dem Objekt Barcode ein BarcodeType.Add Objekt:
BarcodeType.Add add = new BarcodeType.Add(); barcode.setAdd(add);
Das Objekt Add unterstützt folgende Barcode-Arten:
• Aztec – AztecBarcodeType
• Codabar – CodabarBarcodeType
• Code128 – Code128BarcodeType
• Code39 – Code39BarcodeType
• Datamatrix – DataMatrixBarcodeType
• EAN13 – EAN13BarcodeType
• EAN8 – EAN8BarcodeType
• ITF – ItfBarcodeType
• PDF417 – Pdf417BarcodeType
• QR-CODE – QrBarcodeType
• UPCA – UpcaBarcodeType
Dem Add Objekt können einer oder mehrere Barcodes der gleichen Art auf einmal übergeben werden, indem sie zur jeweils passenden Liste hinzugefügt werden – beispielsweise für einen Aztec Barcode:
AztecBarcodeType aztec = new AztecBarcodeType(); add.getAztec().add(aztec);
Allgemeine Barcode Parameter
An sämtlichen Barcode Typen lassen sich folgende Parameter setzen:
value (Standardwert: „“)
Der Wert, der im Barcode encodiert werden soll. Welche Anforderungen ein Wert erfüllen muss, können Sie diesen Barcode Beschreibungen entnehmen.
typedBarcode.setValue("http://www.softvision.de");
pages (Standardwert: „“)
Legt den Seitenbereich fest, in dem der Barcode angebracht 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.
typedBarcode.setPages("1,3-5,6");
charset (Standardwert: „utf-8“)
Gibt den Zeichensatz an, in dem der Wert des Barcodes hinterlegt werden soll.
typedBarcode.setCharset("utf-8");
rotation (Standardwert: 0)
Dieser Wert bestimmt über die Rotation des Barcodes. Es können 90° Schritte angegeben werden.
typedBarcode.setRotation(90);
margin (Standardwert: 0)
Gibt die Breite des leeren Rahmens rund um den Barcode an. (Dieser Leerbereich, kann die Erkennung von Barcodes deutlich beschleunigen.)
typedBarcode.setMargin(5);
Das Objekt „position“
An sämtlichen Barcode Typen kann die Position und die Dimensionen des Barcodes über das Hinzufügen eines RectangleType Objekts bestimmt werden.
RectangleType position = new RectangleType(); typedBarcode.setPosition(position);
Es wird bestmöglich versucht, die gewünschten Dimensionen einzuhalten. Da aber die Lesbarkeit von Barcodes davon abhängig ist, dass sämtliche Codeelemente bestimmte Größenverhältnisse einhalten, kann die Erzeugung eines Barcodes abgelehnt werden, falls ein zu kleiner Bereich gewählt wird. Außerdem kann es passieren, dass der gegebene Bereich nicht vollständig oder deckend ausgefüllt werden kann.
Am Objekt Position lassen sich folgende Parameter setzen:
x Position (Standardwert: „0“)
Dieser Wert bestimmt über die x-Koordinate, auf der die Barcodes positioniert werden soll.
position.setX(15);
y Position (Standardwert: „0“)
Dieser Wert bestimmt über die y-Koordinate, auf der die Barcodes positioniert werden soll.
position.setY(15);
width (Standardwert: 0)
Legt die Breite der Barcodes unter Nutzung der gewählten metrics fest.
position.setWidth(200);
height (Standardwert: 0)
Legt die Breite der Barcodes unter Nutzung der gewählten metrics fest.
position.setHeight(16);
coordinates (Standardwert: „user“)
Wählt das Koordinatensystem fest auf das bezogen die Position bestimmt werden soll. Folgende Werte können hier gesetzt werden:
• user = Nutzer-Koordinatensystem (Ursprung links-oben)
• pdf = PDF-Koordinatensystem (Ursprung links-unten)
position.setCoordinates(CoordinatesType.USER);
metrics (Standardwert: „mm“)
Die Maßeinheit, in der Koordinaten angegeben werden sollen. Folgende Werte können hier gesetzt werden:
• mm = Millimeter
• px = Pixel
position.setMetrics(MetricsType.PX);
Der Barcode Typ „aztec“
Über die Standardparameter hinaus, lassen sich an AztecBarcodeType Objekten folgende Parameter setzen:
errorCorrection (Standardwert: 7)
Legt die Redundanzen und somit Fehlerkorrektur des Barcodes auf einen bestimmten prozentualen Wert zwischen 0 und 100% fest. Je höher dieser Wert gewählt wird, desto resistenter ist der Barcode gegen Beschädigungen, ohne unlesbar zu werden.
aztec.setErrorCorrection(50);
layers (Standardwert: 0)
Legt die Anzahl der Ebenen des Aztec Codes fest. Eine höhere Anzahl an Ebenen resultiert in einer höheren potentiellen Datenkapazität, aber möglicherweise auch in einem höheren Platzbedarf.
• -4 bis -1 = Ein kompakter Barcode mit einer minimalen Kapazität von 13 Zeichen und einer Fläche von 15 mal 15 Pixeln.
• 0 = Ein Standard Aztec Code, der frei die minimal nötige Anzahl an Ebenen wählt, um den gegebenen Wert abzubilden.
• 1 bis 32 = Ein Aztec Code mit einer maximalen Kapazität von 3832 Zeichen und einer Fläche von 151 mal 151 Pixeln.
aztec.setLayers(10);
Der Barcode Typ „datamatrix“
Über die Standardparameter hinaus, lassen sich an DataMatrixBarcodeType Objekten folgende Parameter setzen:
errorCorrection (Standardwert: 2)
Legt die Redundanzen und somit Fehlerkorrektur des Barcodes auf ein festgelegtes Niveau fest, das zwischen 1 und 8 liegen darf. Je höher dieser Wert gewählt wird, desto resistenter ist der Barcode gegen Beschädigungen, ohne unlesbar zu werden.
dataMatrix.setErrorCorrection(7);
shape (Standardwert: default)
Erzwingt eine bestimmte Grundform für Datamatrix Barcodes. Folgende Werte können hier gesetzt werden:
• default = Es wird frei die bestmögliche Form gewählt, um den Inhalt des Barcodes abzubilden.
• rectangle = Es wird immer versucht eine rechteckige Form mit ungleicher Höhe und Breite zu wählen
• square = Es wird immer versucht eine quadratische Form zu erzwingen.
dm.setShape(DataMatrixShapeType.RECTANGLE);
Der Barcode Typ „qrcode“
Über die Standardparameter hinaus, lassen sich an QRBarcodeType Objekten folgende Parameter setzen:
errorCorrection (Standardwert: „l“)
Legt die Redundanzen und somit Fehlerkorrektur des Barcodes auf ein festgelegtes Niveau fest. Je höher dieser Wert gewählt wird, desto resistenter ist der Barcode gegen Beschädigungen, ohne unlesbar zu werden. Folgende Werte sind hier möglich:
• l = Low
• m = Medium
• q = Quartile
• h = High
qrBarcodeType.setErrorCorrection(QrCodeErrorCorrectionType.M);
Der Barcode Typ „pdf417“
Über die Standardparameter hinaus, lassen sich an Pdf417BarcodeType Objekten folgende Parameter setzen:
errorCorrection (Standardwert: 2)
Legt die Redundanzen und somit Fehlerkorrektur des Barcodes auf ein festgelegtes Niveau fest, das zwischen 1 und 8 liegen darf. Je höher dieser Wert gewählt wird, desto resistenter ist der Barcode gegen Beschädigungen, ohne unlesbar zu werden.
pdf417.setErrorCorrection(7);
compact (Standardwert: false)
Wird dieser Wert auf true gesetzt, werden die Inhalte entsprechend der gewählten Kompressionsmethode komprimiert.
pdf417.setCompact(true);
compactionMode (Standardwert: „auto“)
Dieser Wert wählt die Kompressionsmethode für den pdf417 Barcode, wenn der compact auf true gesetzt wurde. Folgende Werte sind hier möglich:
• auto = Versuche automatisiert die bestgeeignetste Kompressionsmethode zu ermitteln.
• byte = Wähle eine Byte Codierung, in der je 5 Codewörter 6 Bytes repräsentieren.
• numeric = Wähle eine nummerische Codierung, in der eine Gruppe von je 15 Codewörtern bis 44 Dezimalziffern repräsentiert.
• text = Wähle eine Text Codierung, in der jedes Codewort bis zu 2 Buchstaben repräsentiert.
pdf417.setCompactionMode(Pdf417CompactionModeType.BYTE);
shape (Standardwert: „default“)
Erzwingt eine bestimmte Grundform für PDF417 Barcodes. Folgende Werte können hier gesetzt werden:
• default = Es wird frei die bestmögliche Form gewählt, um den Inhalt des Barcodes abzubilden.
• rectangle = Es wird immer versucht eine rechteckige Form mit ungleicher Höhe und Breite zu wählen
• square = Es wird immer versucht eine quadratische Form zu erzwingen.
pdf417.setShape(DataMatrixShapeType.SQUARE);
dataCodewordsMax
Gibt die Anzahl der Codeworte an, die maximal in einer Zeile des PDF417 Codes encodiert sein dürfen.
pdf417.setDataCodewordsMax(7);
dataCodewordsMin
Gibt die Anzahl der Codeworte an, die minimal in einer Zeile des PDF417 Codes encodiert sein dürfen.
pdf417.setDataCodewordsMin(4);
symbolsPerCodewordMax
Gibt die Anzahl der Codezeichen an, die maximal in einem Codewort des PDF417 Codes encodiert sein dürfen.
pdf417.setSymbolsPerCodewordMax(8);
symbolsPerCodewordMin
Gibt die Anzahl der Codezeichen an, die minimal in einem Codewort des PDF417 Codes encodiert sein dürfen.
pdf417.setSymbolsPerCodewordMin(4);
Das Objekt „detect“
Um Barcodes im Dokument zu erkennen und Informationen über diese auszulesen, übergeben Sie dem Objekt Barcode ein BarcodeType.Detect Objekt:
BarcodeType.Detect detect = new BarcodeType.Detect(); barcode.setDetect(detect);
Folgende Parameter können am Objekt Detect gesetzt werden:
inputFormat (Standardwert: „pdf“)
Wählt das Format der Datei deren Inhalt nach Barcodes durchsucht werden soll. Folgende Werte können hier gesetzt werden:
• pdf = PDF-Dokument
• img = Grafik-Dokument (JPG, PNG, TIF)
detect.setInputFormat(BarcodeDetectInputFormatType.PDF);
outputFormat (Standardwert: „json“)
Wählt das Format der Datei in der die Erkennungsergebnisse strukturiert zurück gegeben werden sollen. Folgende Werte können hier gesetzt werden:
• json = JSON-Dokument
• xml = XML-Dokument
detect.setOutputFormat(BarcodeDetectOutputFormatType.XML);
Das Objekt „selection“
Um die Art der erkannten Barcodes einzuschränken und deren Erkennung weiter zu konfigurieren, übergeben Sie dem Objekt Detect ein oder mehrere BarcodeSelectionType Objekt/e:
BarcodeSelectionType selection = new BarcodeSelectionType(); detect.getSelection().add(selection);
Folgende Parameter können am Objekt Selection gesetzt werden:
formats
Gibt die Barcode Typen an (getrennt durch Komma), nach denen gesucht werden soll. Es muss mindestens ein Barcode Format angegeben werden. Folgende Werte können hier gesetzt werden:
• aztec = AztecBarcodeType
• codabar = CodabarBarcodeType
• code128 = Code128BarcodeType
• code39 = Code39BarcodeType
• datamatrix = DataMatrixBarcodeType
• ean13 = EAN13BarcodeType
• ean8 = EAN8BarcodeType
• itf = ItfBarcodeType
• pdf417 = Pdf417BarcodeType
• qrcode = QrBarcodeType
• upca = UpcaBarcodeType
selection.setFormats("qrcode,aztec,code39");
charset (Standardwert: „utf-8“)
Gibt den Zeichensatz an, in dem der Wert des Barcodes hinterlegt werden soll.
selection.setCharset("utf-8");
pages (Standardwert: „“)
Legt den Seitenbereich fest, in dem Barcodes erkannt werden sollen. 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.
selection.setPages("1,3-5,6");
allowedLengths (Standardwert: „“)
Wird dieser Wert gesetzt, beschränkt er die mögliche Anzahl an Zeichen, die ein Barcode Inhalt haben kann. Zum Beispiel: („13,8,25“)
selection.setCharset("14");
barcode39CheckDigit (Standardwert: false)
Wird dieser Wert auf true gesetzt, müssen alle erkannten Code39 Barcodes eine korrekte Prüfziffer enthalten.
selection.setBarcode39CheckDigit(true);
codabarStartEndDigits (Standardwert: false)
Wird dieser Wert auf true gesetzt, werden Codabar inklusive ihrer Start und Endziffern ausgelesen.
selection.setCodabarStartEndDigits(true);
gs1 (Standardwert: false)
Wird dieser Wert auf true gesetzt, werden alle Barcodes als GS1 konforme Barcodes behandelt und die ausgelesenen Werte dementsprechend angepasst.
selection.setGs1(true);
pureBarcode (Standardwert: false)
Wird dieser Wert auf true gesetzt, wird davon ausgegangen, dass der gescannte Bereich keine weiteren Elemente außer den Barcodes enthält. Ist dies der Fall, beschleunigt dies die Erkennung deutlich, verhindert aber bei störenden Elementen eine Erkennung teils völlig.
selection.setPureBarcode(true);
resolution (Standardwert: 200)
Wählt die Auflösung für den Erkennungsvorgang, abhängig von Format und Qualität des Barcodes können niedrigere oder höhere Werte zu besseren Ergebnissen führen – höhere Werte bedeuten in jedem Fall eine langsamere Verarbeitung.
selection.setResolution(300);
tryHarder (Standardwert: true)
Wird dieser Wert auf true gesetzt wird Rechenzeit in weitere Erkennungsverfahren investiert, um Barcodes zu erkennen.
selection.setTryHarder(false);
upcEanExtensions (Standardwert: „“)
Wird dieser Wert gesetzt, beschränkt er die mögliche Anzahl an Zeichen, die eine EAN oder UPC Barcode Extension haben kann. Zum Beispiel: („13,8,25“)
selection.setUpcEanExtensions("8");
Das Objekt „scanArea“
Um den Bereich einzuschränken, in dem Barcodes erkannt werden, übergeben Sie dem Objekt Detect ein oder mehrere BarcodeSelectionType Objekt/e:
RectangleType scanArea = new RectangleType(); selection.setScanArea(scanArea);
Die besten und sichersten Erkennungsergebnisse werden Sie erzielen, wenn Sie Barcode für Barcode gezielt scannen und den Bereich exakt auf die Position des Barcodes einschränken. Dies wird vor allem für einfachere Strichcodes die Erkennung von Fehltreffern deutlich reduzieren.
Folgende Parameter können am Objekt Selection gesetzt werden:
x Position (Standardwert: „0“)
Dieser Wert bestimmt über die x-Koordinate, auf der die Barcodes positioniert werden soll.
position.setX(15);
y Position (Standardwert: „0“)
Dieser Wert bestimmt über die y-Koordinate, auf der die Barcodes positioniert werden soll.
position.setY(15);
width (Standardwert: 0)
Legt die Breite der Barcodes unter Nutzung der gewählten Metrics fest.
position.setWidth(200);
height (Standardwert: 0)
Legt die Breite der Barcodes unter Nutzung der gewählten Metrics fest.
position.setHeight(16);
coordinates (Standardwert: „user“)
Wählt das Koordinatensystem fest auf das bezogen die Position bestimmt werden soll. Folgende Werte können hier gesetzt werden:
• user = Nutzer-Koordinatensystem (Ursprung links-oben)
• pdf = PDF-Koordinatensystem (Ursprung links-unten)
position.setCoordinates(CoordinatesType.USER);
metrics (Standardwert: „mm“)
Die Maßeinheit, in der Koordinaten angegeben werden sollen. Folgende Werte können hier gesetzt werden:
• mm = Millimeter
• px = Pixel
position.setMetrics(MetricsType.PX);
Hier geben wir ein ausführlicheres Beispiel
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:
BarcodeWebService barcodeWebService =
WebServiceFactory.createInstance(
session, WebServiceType.BARCODE
);
barcodeWebService.setDocument(soapDocument);
barcodeWebService.getPassword().setOpen("password");
barcodeWebService.getPassword().setPermission("password");
BarcodeType barcode = barcodeWebService.getOperation();
BarcodeType.Add add = new BarcodeType.Add();
barcode.setAdd(add);
AztecBarcodeType aztec = new AztecBarcodeType();
add.getAztec().add(aztec);
aztec.setCharset("utf-8");
aztec.setMargin(5);
aztec.setPages("1-5");
aztec.setRotation(90);
aztec.setValue("http://www.softvision.de");
aztec.setErrorCorrection(50);
aztec.setLayers(10);
RectangleType position = new RectangleType();
aztec.setPosition(position);
position.setMetrics(MetricsType.PX);
position.setX(15);
position.setY(20);
position.setWidth(50);
position.setHeight(50);
position.setCoordinates(CoordinatesType.USER);
// Ausführung.
barcodeWebService.process();
} catch (ResultException | MalformedURLException ex) {
// Zur Auswertung möglicher aufgetretener Fehler, stellt ihnen die
// wsclient Bibliothek entsprechende Methoden zur Verfügung:
}
Hintergrundinfos:
- Unser Blog-Beitrag „Die webPDF wsclient Bibliothek“
- Blogbeitrag zur Nutzung der REST-Schnittstelle
- Blogartikel zur Nutzung der SOAP-Schnittstelle
- Für dieses konkrete Beispiel: Hier gehts zur Barcode Parameterstruktur im Nutzerhandbuch
Weitere Coding-Beispiele für Webservices, welche Sie mit der ws-client Bibliothek nutzen können finden Sie hier.