Base OCF Reference Implementation  Changes for OCF version 1.1 Changes of OCF version 1.1.1

  Changes of OCF version 1.2 Configuration  OpenCard Home
OCF Banner
Please read the  License!

Configuring the Framework

The OPENCARD FRAMEWORK reference implementation obtains configuration information via the JAVA system properties. JAVA system properties are a platform-independent mechanism to make operating system and run-time environment variables available to programs. The JAVA run-time environment defines a set of default properties that are always part of the system properties. Applications can extend this set of properties by loading additional properties and merging them with the system properties. OPENCARD FRAMEWORK configuration parameters are added in this way to the system properties.
 

Loading properties from the OPENCARD properties file

The OPENCARD ARCHITECTURE does not define the mechanism by which the system properties are extended because there is no single mechanism that is guaranteed to be available on all platforms on which the OPENCARD FRAMEWORK reference implementation will run. However, the OPENCARD FRAMEWORK reference implementation does provide a utility class opencard.opt.util.OpenCardPropertyFileLoader to load properties from a file. This file based properties loading mechanism is the default used to extend the system properties. You can change this mechanism and we show you how do that in the section Loading properties with your own mechanism below.

Let's now look at how the default properties loader works. The OpenCardPropertyFileLoader looks in the following places for property files (in the order given):

  1. [java.home]/lib/opencard.properties
  2. [user.home]/.opencard.properties
  3. [user.dir]/opencard.properties
  4. [user.dir]/.opencard.properties
where [xxx.xxx] are the respective path variables as defined in the default system properties. It loads the properties from each of these files in turn merging them with the system properties. In the situation, where the properties file being read contains a property name that is already defined in the properties set, the new definition will be ignored by default.

In case you wish to override a property that is already defined in the properties set you can do that by defining the property name name anew and adding an additional property with the name name.override that has the value true to your property file.

The following example will set the property OpenCard.property to the value new_value no matter what its value was before: 

# Overriding a possibly already defined OpenCard property 
# with a new value 
   OpenCard.property = new_value
   OpenCard.property.override = true
Using the same properties strings as in the examples above, your properties file might look like this: 
# Configuring the CardServiceRegistry
OpenCard.services = com.ibm.opencard.service.MFCCardServiceFactory

# Configuring the CardTerminalRegistry
# The parameters after the class name are: 
#             name, type, and address of the card terminal
OpenCard.terminals = \
  com.ibm.opencard.terminal.ibm5948.IBMCardTerminalFactory|IBM5948-1|IBM5948-B02|1 \
  com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory

# Configuring Tracing
OpenCard.trace = opencard.core:6 opencard.opt:0 com.ibm.opencard:3 \
                 com.ibm.opencard.terminal.ibm5948.IBM5948CardTerminal:8

# Overriding OpenCard.property
OpenCard.property = new_value
OpenCard.property.override = true
back to top of page

Configuring the Registries

The system-wide CardTerminalRegistry and CardServiceRegistry keep track of CardTerminals and CardServiceFactorys, respectively. In order for the OPENCARD FRAMEWORK reference implementation to work properly, the CardTerminalRegistry must know at least one terminal. When the framework starts up, the Card[Terminal|Service]Registrys are initialized by the system based on properties that the user defined and added to the system properties.

You can configure the CardTerminalRegistry via the OpenCard.terminals property and the CardServiceRegistry via the OpenCard.services property.

The syntax of the property string for either property is as follows: 

   <record-0> <record-1> ... <record-N>
where records are separated by white-space and each record consists of a class name and optional string parameters separated by a ``|'', i.e., 
   class-name|param-1|param-2| ... |param-N
The following example illustrates how the property strings might look like: 
  Property name:      Property string:
  OpenCard.services   com.ibm.opencard.service.MFCCardServiceFactory
  OpenCard.terminals  com.ibm.opencard.terminal.ibm5948.IBMCardTerminalFactory|IBM5948-1|IBM5948-B02|1 \
                      com.ibm.opencard.terminal.pcsc10.Pcsc10CardTerminalFactory
back to top of page

Enabling tracing output

The OPENCARD FRAMEWORK reference implementation is comprehensively instrumented to produce detailed tracing information at run-time. This provides valuable feedback about the operation of the FRAMEWORK and helps to locate problems should they occur. You can flexibly adjust the amount of tracing information produced by setting the OpenCard.trace system property.

The utility class opencard.core.util.Tracer distinguishes the following trace levels:

EMERGENCY
System is unusable; numeric value is 0
ALERT
Action must be taken immediately; numeric value is 1
CRITICAL
Critical condition; numeric value is 2
ERROR
Error condition; numeric value is 3
WARNING
Warning condition; numeric value is 4
NOTICE
Normal but significant condition; numeric value is 5
INFO
Informational; numeric value is 6
DEBUG
Debugging information; numeric value is 7
LOWEST
Even more details; numeric value is 8
The syntax of the property string is as follows: 
  package-prefix:trace-level
where package-prefix specifies the prefix of a package or class name and level specifies a number between 0 and 8 corresponding to the desired trace-level.

Example: 

  opencard.core:6 opencard.opt:0 com.ibm.opencard:3 \
    com.ibm.opencard.terminal.ibm5948.IBM5948CardTerminal:8
back to top of page

Loading properties with your own mechanism

The default property loading mechanism, implemented by the class opencard.opt.util.OpenCardPropertyFileLoader, may not be adequate in all environments. For instance, it cannot be used on platforms that do not have a file system.

You can implement a different property loading mechanism that fits your purpose or platform better and have it replace the default mechanism. In order for your property loader to integrate with the FRAMEWORK, it must implement the interface

opencard.core.util.OpenCardConfigurationProvider.

You must tell the FRAMEWORK to use your class instead of the default loader. You do that via the following system property:

OpenCard.loaderClassName= fully-qualified_class_name

NOTE: Obviously, you must set this property prior to the OPENCARD properties loading mechanism being invoked, for instance via a command line flag of the JAVA interpreter or, if applicable, in the system-wide .properties file.

back to top of page

Reto Hermann

Thu May 28 14:32:41 MDT 1998