|
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.1.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>\src\jpos\\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>src\jpos\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:
- Look for a "jpos.cfg" file that contain serialized JposEntry
objects
- Search for file in all paths define in the CLASSPATH in order
- 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.
- 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:
- Specify the SimpleXmlRegPopulator
as your jpos.config.regPopulatorClass
- 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's POSPrinter Service for IBM'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:
- Java 1.1: JDK 1.1.8 or later with Swing 1.1 FCS or later (for the
jpos.config.simple.editor code)
- Java 2: JDK 1.2.2 or later
- 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 05/05/2002 10:51 PM
|
|