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:

Sun Application Server (Glassfish). Open the adminitration console in the URL http://yourserver:4848 , login, select web applications and select deploy.
IBM Websphere: Start the administration console from the windows IBM Websphere menu , login, select deploy new from the applications main menu.
JBoss: just drop the war in the jboss/server/default/deploy directory and it will be installed automatically.

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:

Barcode 1D: http://localhost:8080/j4lrbarcode/BarcodeWS?wsdl
QRCode: http://localhost:8080/j4lqrcode/QRCodeWS?wsdl
PDF417: http://localhost:8080/j4lpdf417/PDF417WS?wsdl
Datamatrix: http://localhost:8080/j4ldatamatrix/DatamatrixWS?wsdl

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:

Barcode 1D:
- type: type of barcode to create. Valid values are: BAR39, BAR38EXT, CODE128, CODE11, CODABAR,CODE93, CODE93EXT, MSI, IND25, MAT25, INTERLEAVED25, EAN13, EAN8, EAN128, UPCA, UPCE or POSTNET.
- value: value to be encoded
- set: value A, B or C (for type CODE128 only)
- processTilde.See J4L Barcodes documentation
- text: value to be displayed below the barcode.
- barHeight: height of bars in pixels
- X: width of narrow bars in pixels
- N: multiplier for wide bars. A value of 2, means that wide bars will be 2 times the width of narrow bars. The default vaue is 2
- barColor. Color of bars. Valid values are RED, BLACK, BLUE, CYAN, DARKGRAY, GRAY, GREEN, LIGHTGRAY, MAGENTA, PINK, WHITE or YELLOW. You can also use the RGB value.
- fontColor: color of the text.
- backColor: background color.
- font: font of the text, for example "ARIAL|BOLD|10", the format is <family|style|size>
- leftMargin: margin in pixels
- topMargin: margin in pixels
QRCode

<xs:complexType name="createBarcode">
<xs:sequence>
<xs:element minOccurs="0" name="code" type="xs:string" />
<xs:element name="moduleSize" type="xs:int" />
<xs:element name="processTilde" type="xs:boolean" />
<xs:element name="margin" type="xs:int" />
<xs:element minOccurs="0" name="ecLevel" type="xs:string" />
<xs:element minOccurs="0" name="encoding" type="xs:string" />
<xs:element name="configuration" type="xs:int" />
</xs:sequence>
</xs:complexType>

code: value to be encoded.
processTilde: See QRCode documentation in evaluation version.
moduleSize: size (pixels) of the modules (dots) of the matrix.
margin: margin in pixels.
ecLevel: can be H, L, M or Q.
encoding: can be ALPHA, BYTE, NUMERIC, KANJI or AUTO.
configuration: the configuration is the size of the qrcode. Valid values are 1 to 40, set 1 for automatic configuration selection.

Datamatrix

<xs:complexType name="createBarcode">
<xs:sequence>
<xs:element minOccurs="0" name="code" type="xs:string" />
<xs:element name="processTilde" type="xs:boolean" />
<xs:element name="moduleSize" type="xs:int" />
<xs:element name="margin" type="xs:int" />
<xs:element minOccurs="0" name="encoding" type="xs:string" />
<xs:element minOccurs="0" name="format" type="xs:string" />
</xs:sequence>
</xs:complexType>

code: value to be encoded.
processTilde: See J4L Barcodes documentation
moduleSize: size (pixels) of the modules (dots) of the matrix.
margin: margin in pixels
encoding: The default is ASCII. Posible values are ASCII, C40, TEXT, BASE256 and AUTO.
format: If empty the format will be selected automatically, if not you can specify the format (e.g. C24X24).

PDF417

<xs:complexType name="createBarcode">
<xs:sequence>
<xs:element minOccurs="0" name="code" type="xs:string" />
<xs:element name="rows" type="xs:int" />
<xs:element name="maxRows" type="xs:int" />
<xs:element name="cols" type="xs:int" />
<xs:element name="ecLevel" type="xs:int" />
<xs:element minOccurs="0" name="compaction" type="xs:string" />
<xs:element name="X" type="xs:int" />
<xs:element name="H" type="xs:int" />
<xs:element name="margin" type="xs:int" />
</xs:sequence>
</xs:complexType>

code: value to be encoded
rows: number of rows
maxRows: maximum number of rows
cols: number of columns
ecLevel: error correction level
compaction: can be NUMERIC, TEXT or BINARY
X: width of narrows bars in pixels
H: height of bars
margin: margin in pixels

Getting help

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


Copyright © 2000-2018 Java4Less.com. About us. Oracle, APEX, Java, JSP, JDBC, JDK and all Java-based marks are trademarks or registered trademarks of Oracle and/or its affiliates. J4L Components is independent of Oracle.