J4L Barcodes for Java Web Services

Copyright J4L Components (http://www.java4less.com) 2008.

 

Introduction

The J4L Barcode web services are Java EE web services that create barcode images. The following symbologies are currently supported:

The web services are not a standalone product but are included in the regular J4L Barcoding components , if you need general information about the barcode itself (meaning of format , encoding ...) please refer to the documentation of the barcoding components.

The web services receive an input XML document containing the parameters of the barcode to be created and returns an XML document that contains the barcode image. The transmission of the XML documents between the client and the web service is implemented using SOAP/HTTP protocol.

An example of a barcode creation request document is:

<S:Envelope xmlns:S="http://schemas.xmlsoap.org/soap/envelope/">
<S:Body>
<ns2:createBarcode xmlns:ns2="http://ws.datamatrix.java4less.com/">

<code>This is a Datamatrix</code>
<processTilde>false</processTilde>
<moduleSize>4</moduleSize>
<margin>10</margin>
<encoding>ASCII</encoding>
<format>C16X16</format>

</ns2:createBarcode>
</S:Body>
</S:Envelope>

an example of the barcode image (JPEG format and base64 encoded) returned by the web service is:

<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<soapenv:Body xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/">
<dlwmin:createBarcodeResponse xmlns:dlwmin="http://ws.datamatrix.java4less.com/">


<BarcodeImage>iVBORw0KGgoAAAANSUhEUgAAAGQAAABkCAIAAAD/gAIDAAABxElEQVR42u3a0ZLCIAxAUf7/p/VNR1tSQpIS0suD47CtSw8xpMX2og23BgFYYIEFFlhgQQAWWMmx2m877e8dv2O/4KDD+pzzQCx1ZMlY7dB6/fIpn9feX+Uwl/vlye69n4ms3kUKg5BxB4m1KNrJ+BuPD9bcjLWxdpzYkVMuh6SK3NOR3BdZlxd/HNBEZBXBuoyv06+AKidOLERaKf/VUJXgBTI53dyP9ROPqshSDVS7VI/8r5HjteeG1Fnj+aIY1jdO3SOrHtbk7Q5Y6jrLeJHGr3no54MFFljPwooGtSfpmx7+gQUWWBmewU8nS0u/9hhLAwsssGpiRSTaVZOR7qkDWGCBFYplKSa9HvhFF9VggQXWfliOe3AbFaJggQVWBSyvZBx9o26ZPLDAAmtvrOiNhojNVHtSBwsssHbF8rpJ9r0Ah63TVashWGCBlaoojU72cT+0BQsssCpgRSTjbIUrWGCB9Swsr+LTkrxTbFiABRZYZbBWbXbYFwqwwAKrGpZXwek1AakTPFhggbX891nRDwu9CtR0uztggQXWbXXWqg3X6Bt1sMACqw5W1QYWWGDtjUUDCyywwAILLBpYYIGVqr0BNV+ZhbGDz+4AAAAASUVORK5CYII=</BarcodeImage>
</dlwmin:createBarcodeResponse>
</soapenv:Body>
</soapenv:Envelope>

Since the communication between client and server (web service) is pure HTTP/SOAP based, the web service is language independent and can be consumed from any web service client application, like a .NET application or Javascript, which do not need to understand Java.

Requirements

The web services components run on a Java EE server (Java 1.5 or later). The following servers have been tested:

Since components used only standard functions, they should run on any certified Java EE server. Other servers like SAP Netweaver 7.1 and Oracle Application Server 11g will be tested also. Let us know if you use one of these.

Deployment

Deployment is the installation of the web service in a Java EE server. The web service is just a file with .war extension that needs to be installed in the server. There is one of such war files for each barcode symbology we support.

The deployment process depends on the server you use but here you have some simple directions:

Once the web service has been deployed you can see the web service description (WSDL file) opening once of the following URL, we assume your server is running on the localhost , port 8080, if that is not the case you need to modify the URL:

Sample client applications

We deliver a set of standalone Java applications which will call the web service and display the result in a Swing JFrame component. These applications are located in the /clients subdirectory.

In order to run the clients you would need to create some proxy classes. These proxy classes must be created with a tool named wsimport. This tool reads the WSDL files (see the URL in the previous section) and creates some Java classes. The generated classes take care of the XML and SOAP details so for your application, calling a web service is just calling a method in a Java class. For example:


URL url=new URL("http://localhost:8080/j4lqrcode/QRCodeWS?wsdl"); // Note this is the dynamic approach, we provide the URL of the web service at runtime.
Service service2=Service.create(url, new QName("http://ws.qrcode.java4less.com/","QRCodeWS"));
QRCodeWS port = service2.getPort(QRCodeWS.class);
java.awt.Image result = port.createBarcode("This is a QRCode", 4,false,10,"H","ALPHA",1);

 

In this example the QRCodeWS class is one of the proxy classes generated by wsimport.

We deliver the generated proxy classes in the clientProxies.jar file, so you do not have to worry about creating them with the wsimport tool (but you can if you want). The web service infrastructure is provided by the Java Metro open source product. You need to download this before running the clients (we used Metro 1.2) and make sure the metro/lib/webservices*.jar files are included in your classpath.

Of course you can also use other web service stack like Apache Axis2 (instead of Metro).

 

Parameters of the request

If you open the URL of the WSDL deployed in your server you will see the file starts with:

<?xml version="1.0" encoding="utf-8" ?>
<definitions xmlns="http://schemas.x. .........
<types>
<xsd:schema>
<xsd:import namespace="http://ws.rbarcode.java4less.com/" schemaLocation="http://localhost:8080/j4lrbarcode/BarcodeWS?xsd=../../WEB-INF/wsdl/BarcodeWS.xsd" />
</xsd:schema>
</types>

the schemaLocation attribute gives you the URL where you can see the schema of the XML document used as request to create a barcode. The XML schema describes the format of the document used in the web service request, this is similar to the method signature in a Java class which describes the parameters used in a method.

In this example the schema's URL would be:

http://localhost:8080/j4lrbarcode/BarcodeWS?xsd=../../WEB-INF/wsdl/BarcodeWS.xsd

if you open that XSD file you will see this complexType:

<xs:complexType name="CreateBarcode">
<xs:sequence>

<xs:element minOccurs="0" name="type" type="xs:string" />
<xs:element minOccurs="0" name="value" type="xs:string" />
<xs:element minOccurs="0" name="set" type="xs:string" />
<xs:element minOccurs="0" name="processTilde" type="xs:string" />
<xs:element minOccurs="0" name="text" type="xs:string" />
<xs:element name="rotate" type="xs:int" />
<xs:element name="barHeight" type="xs:int" />
<xs:element name="X" type="xs:int" />
<xs:element name="N" type="xs:int" />
<xs:element minOccurs="0" name="barColor" type="xs:string" />
<xs:element minOccurs="0" name="fontColor" type="xs:string" />
<xs:element minOccurs="0" name="backColor" type="xs:string" />
<xs:element minOccurs="0" name="font" type="xs:string" />
<xs:element name="leftMargin" type="xs:int" />
<xs:element name="topMargin" type="xs:int" />

</xs:sequence>
</xs:complexType>

these are the parameters of the Barcode 1D creation request.

This section provides now a short description of the meaning of the parameters without using the XML schema format:

Getting help

Send an email to java4lessATconfluencia.net if you have questions.