Concept of the Jaspar Framework Version 1
The concept for version 1 is deprecated. If you need it for old driver implementations, you find the old concept
Concept of the Jaspar Framework Version 2
The concept for version 2.0 is deprecated. If you need it for old driver implementations, you find the old concept
Concept of the Jaspar Framework Version 3
While a physical device can sometimes be split into several device classes, this is not so easy for the driver that
must perform the communication with the device: Since there is only one physical device, all commands must go via
one specific software module that all logical devices must share. Therefore, my concept is as follows:
There is one Java class that contains the whole communication logic of a physical device. It must be derived
from class JposDevice. For each UPOS device this device supports, a class derived from
JposDeviceTypeProperties must be created that implements interface JposDeviceTypeInterface
which provides UPOS device class specific methods and property setters. Method getDeviceTypeProperties,
implemented in the Java class that contains the communication logic must return an instance of this class.
For each UPOS device class, two additional Java classes have been implemented: JposDeviceClass and
JposDeviceClassProperties. Even if DeviceClass is the same name as the UPOS programmatic
ID for some device types, it differs for some devices:
In addition, Jaspar contains classes that encapsulates serial IO and IO via TCP derived from a class named UniqueIOProcessor2. These classes (SerialIOProcessor2 and TcpClientIOProcessor2) allow easy read and
write operations, inclusive automatically generated logging output. Furthermore, a helper class named SyncObject
allows synchronization between several threads inclusive timeout control. The latter class will be used within the Jaspar
framework, for example for asynchronous processing and can be used by driver implementations as well.
Display for LineDisplay,
Drawer for CashDrawer,
Keyboard for POSKeyboard,
Printer for POSPrinter,
RODisplay for RemoteOrderDisplay.
Version 3 started with the following set of property classes:
All JposDeviceClassProperties classes contain the properties and their default values and implement
methods for property initialization during open, claim, first enable or enable, depending on when a property must be initialized.
They are derived from JposCommonProperties, a class that contains all common properties and some additional properties
that are needed for general event handling, e.g. FlagWhenIdle.
All JposDeviceClass classes contain the JavaPOS service implementation of the specific device class.
It holds an instance of the class derived from JposDeviceTypeProperties, returned by method
getDeviceTypeProperties of the device implementation class. Typically, getDeviceTypeProperties
returns an inner class of the device implementation class, but this is not mandatory: There must only be a way for that class to get access to the device implementation class.
Whenever for any property Property the corresponding getProperty method is called, the
corresponding value will be returned directly from the specific JposDeviceTypeProperties instance after
performing some plausibility checks (Device opened / claimed / enabled).
Whenever the property shall be set, the setter performs all possible validity checks for the value to be set that can be
made without knowledge of the specific hardware. If the value seems to be plausible and the device is in a state where
setting of that property is generally allowed, the corresponding setter method of the property class with name
property will be called. This method should perform all remaining validity checks and call the corresponding
method of its super-class to set the property value.
For each method that can only be called synchronously, JposDeviceType performs all plausibility checks that
are possible without specific device knowledge. Afterwards, it calls the corresponding method of the accessor class
(same name, same parameters).
For methods that can be called asynchronously, the corresponding method of the property class (same name, same parameters)
will be used only to perform plausibility checks that need knowledge of the specific hardware. On success, for some device
classes, the accessor methods must return an implementation specific object (can be null if not needed) to be passed
to a new instance of a class JposDeviceTypeMethodName, where MethodName is the name of the method.
This class holds all parameters passed to the method and has been derived from JposOutputRequest. Its invoke
method will be called either immediately (in synchronous mode) or when all previously buffered asynchronous requests have
For each physical device, the following prerequisits are important:
A string specifying the interface (e.g. the COM port for RS232 devices, IP address
and port for devices connected via IP, vendor, device ID and serial number for USB devices) must be specified
in jpos.xml. In addition, if a device supports more than one instances of one device category, a device index
must also be specified.
For each supported device class, the implementation class derived from JposDevice must override the
corresponding getDeviceTypeProperties method. This method return an instance of a class derived
from JposDeviceTypeProperties that implement device specific functionality.
For each device class, a class factory derived from JposDeviceClassFactory must be implemented.
Each device factory class implementation derived from JposDeviceClassFactory must perform the
Check whether property value of the deviceClass entry of jpos.xml matches the device class the
factory has been implemented for. If not, it shall throw a JposException.
Retrieve the interface the driver shall use for device interactions. In case of no or an invalid
interface specification, a JposException shall be thrown.
If the physical device supports more than one UPOS devices of the specific class (e.g., a combined keyboard
with central lock and electronic key reader would support one POSKeyboard and two Keylock instances), it
must be checked which device shall be handled. If no jpos.xml entry exists that specifies which device
shall be used, a JposException shall be thrown. Otherwise, the device specifier must be translated into a
device index between zero and (no. of supported devices of this device type minus one).
Use method getDevice to retrieve a driver object bound to the same interface. If it is not an
instance of the correct type, a JposException must be thrown. If getDevice returns null, create
a new instance of the type the class factory has been developed for.
Call the checkProperties function of the driver implementation to check and fill jpos.xml
configuration values the driver needs. Keep in mind that these properties are common for all UPOS devices the
driver supports. Therefore, there should not be different values in different jpos.xml entries for the
same physical device (e.g. if the device is connected to COM1, the baud rate of the keyboard must match the
baud rate of the keylock because the driver uses the same communication line for both devices).
Use method addDevice, passing the device index and the previously allocated implementation object, to
create a property set and an instance of JposDeviceType and to set links that bind the three classes
together to form the JavaPOS device service object.
If the driver object had to be created, use the putDevice method of JposDeviceFactory to
store the device oject for use by further JavaPOS devices.
There are the following requirements for device driver implementations derived from JposDevice:
The constructor must perform the following steps:
Pass the device id to the constructor of JposDevice.
Perform deviceClassInit, passing the maximum number of devices the driver supports for this
device class. In the above example, keyboardInit(1) and keylockInit(2) must be called.
Perform further initialization actions, like reading a property file, setting default values for
jpos.xml properties. Check and store the device id for validity (e.g., a driver supporting a device
connected to a COM port cannot work with an IP address and port number).
The checkProperties method must be implemented to check and store all jpos.xml properties that
are important for the driver, e.g. baud rate, configurable timeout values, ... It must also call
super.checkProperties to initialize the logging system based on
The changeDefaults methods must be implemented to change driver specific default property
To fire events, use the handleEvent functions. This simpifies the event handling because event
enqueueing due to specific property values (FreezeEvents, DataEventEnable, DeviceEnable) will be performed
automatically due to implementations in JposDevice.
To retrieve property sets for event handling or other purposes, use methods getClaimingInstance or
getPropertySetInstance of the implementation class or method getClaimingInstance of a property set.
The method clearOutputErrorProperties has been implemented in JposCommonProperties that calls
clearErrorProperties by default. It must be overwritten by a service implementation if the service handles
input and output errors and both error handlers must clear different error properties.
To support service specific error event handling, new methods getInputDataErrorEvent and clear
have been implemented in class JposErrorEvent. getInputDataErrorEvent generates a new error event
that may contain event specific data. clear calls the service specific clearOutput or clearInput
methods, depending on the error type (input or output error).
Method countCommands has been added to class JposOutputRequest. It counts the enqueued
commands for one specific logical device. Especially, if a service contains implementations for multiple logical
devices, e.g. a printer with a cash drawer, this is useful for error handling, where only those commands may be
cleared which belong to the same device.
Method setDirectIOProperties has been added to class JposDirectIOEvent. It allows to set property
values stored within the JposDirectIOEvent object immediately before the event will be fired. A similar method
is present for class JposOutputCompleteEvent.
The event handlers and error handlers in JposDeviceuse the above methods to perform service specific
actions in a standardized way. In addition, JposDevice new method newJposOutputRequest can be used to
retrieve a service specific object derived from JposOutputRequest as replacement for a JposOutputRequest
object, whenever necessary.
Property FlagWhenIdleViaDirectIOEventNumber of JposCommonProperties can be used to fire a
DirectIOEvent when a device that supports asynchronous processing becomes idle. Its value is 0 by default.
If set to a value != 0, a status change form busy to idle will be signalled by a DirectIO event
while AsyncMode and FlagWhenIdle are true. This can be used to perform vendor specific notification for device classes that support asynchronous processing without supporting FlagWhenIdle. To set FlagWhenIdle for such a device, method directIO can be used.
To simplify string parsing for Display and Printer devices, a List<Object> will be passed instead of a String
parameter in print and display methods. Such a list contains specific objects, each describing one part of the original
String object. For details, see documentation of classes JposPrinter and JposDisplay.
An overview over the general structure of JavaPOS services created with Jaspar can be found
For backward compatibility, a lot of methods and classes have been marked as deprecated. Even if these methods and classes shall not be used in
future, they remain present for unspecified time. Use of some of these classes and methods can be read in the old concept.
Use of deprecated classes and methods that are not described within the old concept are only for internal use and must not be used by any