Java POS

Home

Docs

Changes

To-do

End Users

FAQs

Getting Started

Developers

JCL RI

Sample Code

JavaDOC

References

jpos.config/loader (JCL) - JCL RI

(Reference Implementation)


The JCL RI (aka "Simple JCL") is a all Java lightweight implementation of the core JCL interfaces.  This implementation has gone through a few iterations which makes it a bit more complex then what it started with.  However, the implementation remains still somewhat "simple" yet allowing various options to be customized, for instance as of JCL 2.0.0 you can use an XML populator option or specify more than one populator to be used.

The following will describe how to use (in-depth) and customize the JCL RI.  If you want information on its architecture and design then see the JCL White Paper.

NOTE: the JCL White Paper is out of date.  It needs to account for changes in 1.2 and 2.0 release.

This page is Under Construction (needs updating for 2.0.0 release)


Setting up and using the JCL RI

Setup the JCL RI by making sure that the jclall.jar file OR jcl.jar and jcl_simple.jar file is in your CLASSPATH.  Please see the setting up the JCL for details on how to do that.

Sources: If you want to see the source files, extract the src.jar file in the "src" directory to get the source to the JCL (including the "JCL RI" implementation).  Use the following command with the jar utility found in Java 2 (issued in the "src" directory):

>jar xvf src.jar


JCL RI properties options

The JCL properties options are defined as part of the "jpos.properties" file.  

Using and Setting Options via the "jpos.properties" File

One of the new features in the JCL 1.2 release is the ability to define Java properties toconfigure the JCL and/or to customize its functionality.

The JCL properties are defined in a file called "jpos.properties" a sample of which is in the <jcl-dir>\res directory. This file is copied to the jcl-dir>\src\jpos\res directory and is included in the JCL JAR files. 

NOTE : to modify this properties file you must either recompile the JCL or easily edit the file and insert your modifications in the JCL JAR file that you are using (see the JAR tool documentation on how to update a JAR file).

The "jpos.properties" file is like other Java properties files in that it defines <key, value> pairs in a flat text file. Each key and value are defined as follows:

#Sample jpos.key key with value jpos.value (this is a comment)

jpos.key = jpos.value

To avoid name clashing in the Java property namespace all the JCL properties follow the JCL package name convention.

For more details on the JCL properties and what the values should be set to, please read the sample properties file (either in the JAR files or in the <jcl-dir>\res directory.

jpos.properties

This file contains extensive comments describing all the JCL properties: their meaning and possible values.

With the jpos.properties file you can:

1.Specify the JCL implementation to use. If none is defined then the default simple is used.

2.Specify the populator class and/or file or URL to use if you are using the JCL RI implementation. That's how you would specify to use the simple XML populator. 
.
3.Turn tracing ON or OFF in the JCL.

Verify (print out) Current Properties

You can also printout the name and values of all the current "jpos.properties" that will be loaded by the JCL by using the simple console app provided in the jpos.util package:

>java jpos.util.JposPropertiesViewer

It will print out to System.out a listing of all the properties configured with the current JCL configuration. The output will look something like this:

JavaPOS jpos.config/loader (JCL) defined Java properties:
<!-- name = "propName" value = "propValue" -->
<name = "jpos.config.regPopulatorClass" value =
"jpos.config.simple.xml.SimpleXmlRegPopulator" />
<name = "jpos.loader.serviceManagerClass" value =
"jpos.loader.simple.SimpleServiceManager" />
<name = "jpos.config.populatorFile" value = "./res/sample.xml" />
<name = "jpos.util.tracing" value = "ON" />

NOTE : more options are bound to come in newer releases of the JCL. Please try to learn this facility now!

See two sections below on how to use the default "serialization" populator and the new XML populator.


Using the default "serialization" populator

The default populator used by the JCL is the "serialization" populator.  It is named that way because it looks for the defined JposEntries in a file named "jpos.cfg" which needs to contain serialized objects whose class implements the JposEntry interface.

This populator is used by either:

not defining the jpos.config.regPopulatorClass 

OR defining it to be:

jpos.config.regPopulatorClass = jpos.config.simple.SimpleRegPopulator

Default search algorithm

For historical reasons the default search algorithm of the default populator is the following:

  1. Look for a "jpos.cfg" file that contain serialized JposEntry objects
  2. Search for file in all paths define in the CLASSPATH in order
  3. If no file is found then look for the file in all JAR and Zip files in CLASSPATH at the root of each JAR or Zip file.
  4. If no file is found then saving the registry will save a "jpos.cfg" file containing any new JposEntry defined in the registry at the current directory (the directory in which the JVM was started).

Overriding the search algorithm

The search algorithm can be overridden by defining either following two properties.

jpos.config.populatorFile
jpos.config.populatorFileURL

The populator file property must be set to a valid file containing the serialized entries and the URL must be a "well-formed" URL (with any protocols supported by Java i.e. http, file, ...)

NOTE: if both are defined then the populator file is used.

NOTE 2: when using the populator file in Win32 either define the paths with "/" or remember to use "\\" (e.g. C:\\temp\\jpos.cfg or C:/temp/jpos.cfg)

NOTE 3: when using the populator URL you may not be able to save the registry if the protocol does not support output.


Using the XML populator:  JCL DTD and XML files

The XML populator is a new addition to the JCL.  It allows you to define your properties using an XML file and allows you to save the registry contents in XML.

The XML populator requires the Apache Xerces-J XML support for Java to be installed and setup on your system (the Xerces-J package was known in its early age as the IBM XML4J).

Please download and install the Xerces-J 3.0 or later package before using the XML populator (it can be as simple as a 1-JAR file setup)

Setup

To use the XML populator you must have the Xerces-J package installed. 

Modify the jpos.properties file to:

  1. Specify the SimpleXmlRegPopulator as your jpos.config.regPopulatorClass
  2. And, use the jpos.config.populatorFile OR jpos.config.populatorFileURL to specify the location and name of the XML file with the entries.  See details above.

DTD

The XML populator uses the following DTD (jcl.dtd) which requires that various properties be defined as well as allowing any property to be defined:

<?xml encoding="UTF-8"?>

<!-- Revision: 0 1.2 http://www.nrf-arts.com/JavaPOS/JCL/jcl.dtd, docs, xml4j2, xml4j2_0_13 -->

<!ELEMENT JposEntries (JposEntry)*>

<!ELEMENT JposEntry (creation, vendor, jpos, product, prop+)>
<!ATTLIST JposEntry logicalName CDATA #REQUIRED>

<!ELEMENT creation (#PCDATA)>
<!ELEMENT vendor (#PCDATA)>
<!ELEMENT jpos (#PCDATA)>
<!ELEMENT product (#PCDATA)>
<!ELEMENT prop (#PCDATA)>

<!ATTLIST creation
factoryClass CDATA #REQUIRED
serviceClass CDATA #REQUIRED>

<!ATTLIST vendor
name CDATA #REQUIRED
url CDATA #IMPLIED>

<!ATTLIST jpos
version CDATA #REQUIRED
category ( BumpBar | CashChanger | CashDrawer | CoinDispenser | FiscalPrinter |
HardTotals | Keylock | RemoteOrderDisplay | Scale | Scanner | SignatureCapture |
ToneIndicator | LineDisplay | MICR | MSR | PinPad | POSKeyboard |
POSPrinter ) #REQUIRED>

<!ATTLIST product 
name CDATA #REQUIRED
description CDATA #REQUIRED
url CDATA #IMPLIED>

<!ATTLIST prop
name CDATA #REQUIRED
value CDATA #REQUIRED>

NOTE: this populator requires that all the properties agreed upon at the NY-2K meeting be defined.  They are grouped into 4 XML elements: creation, jpos, vendor and product.  The DTD also allows any property to be defined (these should be the vendor specific properties)

NOTE 2: in a future version of the JCL, I will define elements for the standard RS232 and RS485 properties.

Example

The best way to create your XML entries file is to start with the example jcl.xml file provided.

This file shows how to setup the sample LineDisplay service from the sample code and how to setup an IBM POSPrinter.

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE JposEntries PUBLIC "JposEntries"
"jpos/res/jcl.dtd">
<JposEntries>
<!--Saved by JavaPOS jpos.config/loader (JCL) version 1.2.0 on 2/3/00 11:59 AM-->

<JposEntry logicalName="POSPrinter0">
<creation factoryClass="com.ibm.jpos.IBMJposServiceInstanceFactory" serviceClass="com.ibm.jpos.services.IBM4610Printer"/>
<vendor name="IBM, Corp." url="http://www.ibm.com"/>
<jpos category="POSPrinter" version="1.4a"/>
<product description="IBM&apos;s POSPrinter Service for IBM&apos;s 4610 POS Printer" name="IBM Services for JavaPOS(TM) Standard" url="http://www.clearlakes.ibm.com"/>

<!--Other non JavaPOS required property (mostly vendor properties and bus specific properties i.e. RS232 )-->
<prop name="impClass" value="com.ibm.jpos.services.poss.IBM4610PrinterImp"/>
<prop name="abstractionClass" value="com.ibm.jpos.services.IBM4610Printer"/>
</JposEntry>


<JposEntry logicalName="LineDisplay0">
<creation factoryClass="com.xyz.jpos.XyzJposServiceInstanceFactory" serviceClass="com.xyz.jpos.LineDisplayService"/>
<vendor name="Xyz, Corp." url="http://www.javapos.com"/>
<jpos category="LineDisplay" version="1.4a"/>
<product description="Example virtual LineDisplay JavaPOS Service from virtual Xyz Corporation" name="Xyz Virutal LineDiaply Service for JavaPOS(TM) Standard" url="http://www.javapos.com"/>

<!--Other non JavaPOS required property (mostly vendor properties and bus specific properties i.e. RS232 )-->
</JposEntry>

</JposEntries>

NOTE: you should specify the location of the jcl.dtd in the <!DOCTYPE> so that the XML file can be validated.


Compiling Sources

With each version of the JCL you will get the complete source files listed in the <jcl-dir>\src directory. This also includes a makefile to build the JCL.

NOTE: the sample sources are located in the <jcl-dir>\sample directory. See the Sample Code section for more info. 

To compile/build the JCL you will need the following:

  1. Java 1.1: JDK 1.1.8 or later with Swing 1.1 FCS or later (for the
    jpos.config.simple.editor code) 
  2. Java 2: JDK 1.2.2 or later 
  3. The current make files are provided in two formats: 
    1.  Win32 NMAKE. This file is named "makefile" 
    2.  UNIX make: This file is named "unix_makefile" 

NOTE: both makefiles are equivalent except for "\" changed to "/". Also, I did not have a chance to test the UNIX make files. I will do so soon and update if a change is needed.

At this point, you will most likely need to set the current directory i.e. "." in your CLASSPATH and remove the JCL JAR files from the CLASSPATH.

Checking make options

To check the different make options. change to the "src" directory and type:

DEFINITION: UNIX replace "nmake" with "make" and for WIN32 it means then make utility

>nmake

This will output all the options of the makefile

Compiling

To do a clean compile, change to the "src" directory and type:

>nmake clean

>nmake all

This will delete all the .class files and compile all the jpos.* packages (controls and JCL)

Creating JAR files

To create all the JCL JAR files (not including the jcl_sample.jar file) do the following:

>nmake jars

This will create the jcl.jar, jcl_simple.jar, jpos.jar (this is an unofficial set of JCL-enabled
JavaPOS controls, based on the 1.4 controls).


Last modified by KDR on 03/07/2001 12:39 AM

Java