Webservice coding example: read and create barcodes

Here we want to give a concrete code example for the Barcode Webservice including use with the webPDF wsclient library.

Important note:

The following coding example is based on the use of the webPDF wsclient library. In order to understand and apply the example, the following blog post should be considered first:

webPDF and Java: very easy with the “wsclient” library

Preliminary work for calling the webservice

To call the webservice in the way described here, you must first create a REST or SOAP session. You can then either create a BarcodeWebService object (for a SOAP session) by calling the WebserviceFactory:

BarcodeWebService barcodeWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.BARCODE
    );

..or a BarcodeRestWebService object (for a REST session):

BarcodeRestWebService barcodeWebService =
    WebServiceFactory.createInstance(
        session, WebServiceType.BARCODE
    );

And then pass a RestDocument or a SoapDocument object to the WebService object by calling the method setDocument().

More about the Webservice parameters

To get changing access to a document, you have to give the current open and/or permission password to the webservice call. You can do this on the generated barcodeWebService object:

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

(Note: If the document does not have an appropriate password protection, you can skip this point.)

Description of the Barcode Webservice

The Barcode Webservice is an endpoint of your webPDF server that allows you to create barcodes in your PDF document or recognize them and output their contents.

You retrieve the BarcodeType object from your barcodeWebService object as follows to pass further parameters to it:

BarcodeType barcode = barcodeWebService.getOperation();

The following parameters can be set for the Barcode object:

The object „add“

To add new barcodes to the document, transfer a BarcodeType.Add object to the Barcode object:

BarcodeType.Add add = new BarcodeType.Add();
barcode.setAdd(add);

The Add object supports the following barcode types:

• Aztec – AztecBarcodeType
• Codabar – CodabarBarcodeType
• Code128 – Code128BarcodeType
• Code39 – Code39BarcodeType
• Datamatrix – DataMatrixBarcodeType
• EAN13 – EAN13BarcodeType
• EAN8 – EAN8BarcodeType
• ITF – ItfBarcodeType
• PDF417 – Pdf417BarcodeType
• QR-CODE – QrBarcodeType
• UPCA – UpcaBarcodeType

The Add object can be given one or more barcodes of the same type at once by adding them to the appropriate list – for example for an Aztec barcode:

AztecBarcodeType aztec = new AztecBarcodeType();
add.getAztec().add(aztec);

General barcode parameters

The following parameters can be set for all barcode types:

value (default value: „“)

The value to be encoded in the barcode. You can find out which requirements a value must meet from this barcode description.

typedBarcode.setValue("http://www.softvision.de");

pages (default value: „“)

Defines the page area in which the barcode is to be applied. You can specify either a single page („1“), a list of pages („1,3,5“), a page range („1-5“), or a combination of these elements („1,3-5,6“). All pages of the document can be selected using „*“.

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

charset (default value: „utf-8“)

Specifies the character set in which the value of the barcode is to be stored.

typedBarcode.setCharset("utf-8");

rotation (default value: 0)

This value determines the rotation of the barcode. 90° steps can be specified.

typedBarcode.setRotation(90);

margin (default value: 0)

Specifies the width of the empty frame around the barcode. (This blank area can significantly speed up the recognition of barcodes.)

typedBarcode.setMargin(5);

The object „position“

For all barcode types, the position and dimensions of the barcode can be determined by adding a RectangleType object.

RectangleType position = new RectangleType();
typedBarcode.setPosition(position);

The best possible attempt is made to maintain the desired dimensions. However, since the readability of barcodes depends on the fact that all code elements adhere to certain proportions, the creation of a barcode can be rejected if a too small area is selected. In addition, it can happen that the given area cannot be filled completely or opaquely.

The following parameters can be set at the object position:

x Position (default value: „0“)

This value determines the x-coordinate on which the barcodes are to be positioned.

position.setX(15);

y Position (default value: „0“)

This value determines the y-coordinate on which the barcodes are to be positioned.

position.setY(15);

width (default value: 0)

Sets the width of the barcodes using the selected metrics.

position.setWidth(200);

height (default value: 0)

Sets the width of the barcodes using the selected metrics.

position.setHeight(16);

coordinates (default value: „user“)

Selects the coordinate system to which the position is to be referenced. The following values can be set here:

• user = user coordinate system (origin left-above)
• pdf = PDF coordinate system (origin left-bottom)

position.setCoordinates(CoordinatesType.USER);

metrics (default value: „mm“)

The unit of measurement in which coordinates are to be specified. The following values can be set here:

• mm = millimeter
• px = Pixel

position.setMetrics(MetricsType.PX);

The barcode type „aztec“

In addition to the standard parameters, the following parameters can be set for AztecBarcodeType objects:

errorCorrection (default value: 7)

Defines the redundancies and thus the error correction of the barcode to a certain percentage value between 0 and 100%. The higher this value is selected, the more resistant the barcode is to damage without becoming unreadable.

aztec.setErrorCorrection(50);

layers (default value: 0)

Defines the number of levels of the Aztec code. A higher number of levels results in a higher potential data capacity, but possibly also in a higher space requirement.

• -4 to -1 = A compact barcode with a minimum capacity of 13 characters and an area of 15 by 15 pixels.
• 0 = A standard Aztec code that freely chooses the minimum number of layers required to map the given value.
• 1 to 32 = An Aztec code with a maximum capacity of 3832 characters and an area of 151 x 151 pixels.

aztec.setLayers(10);

The barcode type „datamatrix“

In addition to the standard parameters, the following parameters can be set for DataMatrixBarcodeType objects:

errorCorrection (default value: 2)

Defines the redundancies and thus the error correction of the barcode to a fixed level, which may lie between 1 and 8. The higher this value is selected, the more resistant the barcode is to damage without becoming unreadable.

dataMatrix.setErrorCorrection(7);

shape (default value: default)

Forces a certain basic form for Datamatrix barcodes. The following values can be set here:

• default = The best possible form is freely selected to represent the content of the barcode.
• rectangle = An attempt is always made to select a rectangular shape with unequal height and width.
• square = The system always tries to force a square shape.

dm.setShape(DataMatrixShapeType.RECTANGLE);

The barcode type „qrcode“

In addition to the standard parameters, the following parameters can be set for QRBarcodeType objects:

errorCorrection (default value: „l“)

Defines the redundancies and thus the error correction of the barcode to a fixed level. The higher this value is selected, the more resistant the barcode is to damage without becoming unreadable. The following values are possible here:

• l = Low
• m = medium
• q = quartiles
• h = High

qrBarcodeType.setErrorCorrection(QrCodeErrorCorrectionType.M);

The barcode type „pdf417“

In addition to the standard parameters, the following parameters can be set on Pdf417BarcodeType objects:

errorCorrection (default value: 2)

Defines the redundancies and thus the error correction of the barcode to a fixed level, which may lie between 1 and 8. The higher this value is selected, the more resistant the barcode is to damage without becoming unreadable.

pdf417.setErrorCorrection(7);

compact (default value: false)

If this value is set to true, the contents are compressed according to the selected compression method.

pdf417.setCompact(true);

compactionMode (default value: „auto“)

This value selects the compression method for the pdf417 barcode if the compact is set to true. The following values are possible:

• auto = Automatically attempts to determine the most suitable compression method.
• byte = Select a byte encoding in which 5 code words each represent 6 bytes.
• numeric = Select a numeric encoding in which a group of 15 code words each represents up to 44 decimal digits.
• text = Select a text encoding in which each codeword represents up to 2 characters.

pdf417.setCompactionMode(Pdf417CompactionModeType.BYTE);

shape (default value: „default“)

Forces a certain basic form for PDF417 barcodes. The following values can be set here:

• default = The best possible form is freely selected to display the content of the barcode.
• rectangle = An attempt is always made to select a rectangular shape with unequal height and width.
• square = The system always tries to force a square shape.

pdf417.setShape(DataMatrixShapeType.SQUARE);

dataCodewordsMax

Specifies the maximum number of code words that may be encoded in one line of the PDF417 code.

pdf417.setDataCodewordsMax(7);

dataCodewordsMin

Specifies the number of code words that may be minimally encoded in one line of the PDF417 code.

pdf417.setDataCodewordsMin(4);

symbolsPerCodewordMax

Specifies the maximum number of code characters that may be encoded in a code word of the PDF417 code.

pdf417.setSymbolsPerCodewordMax(8);

symbolsPerCodewordMin

Specifies the number of code characters that may be minimally encoded in a code word of the PDF417 code.

pdf417.setSymbolsPerCodewordMin(4);

The object „detect“

To recognize barcodes in the document and read information about them, pass a BarcodeType.Detect object to the Barcode object:

BarcodeType.Detect detect = new BarcodeType.Detect();
barcode.setDetect(detect);

The following parameters can be set for the Detect object:

inputFormat (default value: „pdf“)

Selects the format of the file whose contents are to be searched for barcodes. The following values can be set here:

• pdf = PDF document
• img = graphic document (JPG, PNG, TIF)

detect.setInputFormat(BarcodeDetectInputFormatType.PDF);

outputFormat (default value: „json“)

Selects the format of the file in which the recognition results are to be returned in a structured manner. The following values can be set here:

• json = JSON document
• xml = XML document

detect.setOutputFormat(BarcodeDetectOutputFormatType.XML);

The object „selection“

To restrict the type of detected barcodes and further configure their detection, pass one or more BarcodeSelectionType objects to the Detect object:

BarcodeSelectionType selection = new BarcodeSelectionType();
detect.getSelection().add(selection);

The following parameters can be set on the Selection object:

formats

Specifies the barcode types (separated by commas) to search for. At least one barcode format must be specified. The following values can be set here:

• 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 (default value: „utf-8“)

Specifies the character set in which the value of the barcode is to be stored.

selection.setCharset("utf-8");

pages (default value: „“)

Defines the page range in which barcodes are to be recognized. You can specify either a single page („1“), a list of pages („1,3,5“),, a page range („1-5“), or a combination of these elements („1,3-5,6“). All pages of the document can be selected using „*“.

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

allowedLengths (default value: „“)

If this value is set, it limits the possible number of characters that a barcode can contain. For example: („13,8,25“)

selection.setCharset("14");

barcode39CheckDigit (default value: false)

If this value is set to true, all recognized Code39 barcodes must contain a correct check digit.

selection.setBarcode39CheckDigit(true);

codabarStartEndDigits (default value: false)

If this value is set to true, Codabar including its start and end digits will be read.

selection.setCodabarStartEndDigits(true);

gs1 (default value: false)

If this value is set to true, all barcodes are treated as GS1-compliant barcodes and the read-out values are adapted accordingly.

selection.setGs1(true);

pureBarcode (default value: false)

If this value is set to true, it is assumed that the scanned area contains no elements other than the barcodes. If this is the case, the recognition is accelerated significantly, but in the case of disturbing elements, recognition is sometimes completely prevented.

selection.setPureBarcode(true);

resolution (default value: 200)

Selects the resolution for the recognition process, depending on the format and quality of the barcode, lower or higher values can lead to better results – higher values always mean slower processing.

selection.setResolution(300);

tryHarder (default value: true)

If this value is set to true, computing time is invested in further recognition procedures in order to recognize barcodes.

selection.setTryHarder(false);

upcEanExtensions (default value: „“)

If this value is set, it limits the possible number of characters that an EAN or UPC barcode extension can have. For example („13,8,25“)

selection.setUpcEanExtensions("8");

The object „scanArea“

To restrict the range in which barcodes are detected, pass one or more BarcodeSelectionType objects to the Detect object:

RectangleType scanArea = new RectangleType();
selection.setScanArea(scanArea);

You will achieve the best and most reliable recognition results if you scan barcode by barcode and restrict the area exactly to the position of the barcode. This will significantly reduce missed-measure detection, especially for simpler barcodes.

The following parameters can be set on the Selection object:

x Position (default value: „0“)

This value determines the x-coordinate on which the barcodes are to be positioned.

position.setX(15);

y Position (default value: „0“)

This value determines the y-coordinate on which the barcodes are to be positioned.

position.setY(15);

width (default value: 0)

Defines the width of the barcodes using the selected metrics.

position.setWidth(200);

height (default value: 0)

Defines the width of the barcodes using the selected metrics.

position.setHeight(16);

coordinates (default value: „user“)

Selects the coordinate system to which the position is to be referenced. The following values can be set here:

• user = user coordinate system (origin left-above)
• pdf = PDF coordinate system (origin left-bottom)

position.setCoordinates(CoordinatesType.USER);

metrics (default value: „mm“)

The unit of measurement in which coordinates are to be specified. The following values can be set here:

• mm = millimeter
• px = Pixel

position.setMetrics(MetricsType.PX);

Here we have a more detailed example

Example for our entire webservice call (for addressing the SOAP interface):

try (
    // Setup of a session with the webPDF server (here SOAP):
    SoapSession session = SessionFactory.createInstance(
        WebServiceProtocol.SOAP,
        new URL("https://localhost:8080/webPDF/")
    );
    // Make available the document to be processed 
   // and the file to which the result is to be written:
    SoapDocument soapDocument = new SoapDocument(
        new File("Pfad des Quelldokuments").toURI(),
        new File("Pfad des Zieldokuments")
    )
) {
    // Selection of the webservice via a 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);

    // Execution.
    barcodeWebService.process();
} catch (ResultException | MalformedURLException ex) {
    // For the evaluation of possible errors, the 
   // wsclient library provides appropriate methods:
}

Background information:

• Blog post about the use of the REST interface
• Blog article about the use of the SOAP interface
• All parameters can also be found in the user manual, there without examples for use with the wsclient library. Please also note: All parameters are preset with certain default values. If a default value is specified and does not differ from your desired value, it is not mandatory to set this parameter.
• For this concrete example: Here is the barcode parameter structure in the user manual
• You will also find a documentation of the error codes and any errors that may occur.

More coding examples for webservices that you can use with the ws-client library can be found here. bla