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

      Changes for OCF version 1.2 Configuration  OpenCard Home

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
- Configuring the `Registries`
- Enabling tracing output
- Loading properties with your own mechanism

## 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 `CardTerminal`s and `CardServiceFactory`s, 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]Registry`s 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