JCCKit logo

3. Configuration Concept

JCCKit is highly configurable. For example, one can
  • choose color of curves, symbols, and texts
  • choose text fonts and size
  • configure coordinate systems
  • etc.

This chapter explains in its sections

  1. how configuration parameters are accessed,
  2. how they are used,
  3. how they are stored, and
  4. the concept of inheritance of configuration parameters.
There is also a Configuration Manual (PDF 180kb) explaining all parameters.

3.1 Accessing Configuration Parameters

Configuration parameters can be accessed from an instance of ConfigParameters. It is a read-only set of key-value pairs where the keys are strings (like in a Properties instance). The type of the value can be one of the following
  • String
  • int
  • double
  • double[]
  • Color
  • ConfigParameters
Because a ConfigParameters object itself can be a value configuration parameters are organized hierarchically.

For each value type two types of getter methods exist: One with only a key argument and one with a key argument and a default argument. If no key-value pair exists for the specified key the first method throws an IllegalArgumentException whereas the second method returns the default value. An exception from this rules are key-value pairs where the value is a ConfigParameters object. In this case only one get method exists which returns in any case a value even it is an empty set.

3.2 A General Purpose Factory Method

An important key-value pair of a ConfigParameters object is the className. It denotes a fully-qualified Java class name. It is used by the factory method Factory.create(ConfigParameters) to create a new instance of that class. This factory method assumes that there is either
  • a constructor with a signature like MayClass(ConfigParameters config) where config is the ConfigParameters object from the argument of the create() method
  • or the default constructor with no arguments.

This general-purpose factory method together with the hierachically organized configuration parameters allows to create complex objects by just one line of code. For example, inside the constructor of the class Plot the factory method is invoked three times in order to create a CoordinateSystem , a CurveFactory, and an initial Hint. The constructors of all these objects may also call the factory method.

3.3 Sources of Configuration Parameters

In general configuration parameters are read from a persistent source. Currently Java .properties files (or more precicely Properties objects) and applet parameters are supported. But other mechanisms (e.g., XML files, data bases) can be easily incorporated because persistency of configuration data is separated from ConfigParameters.

Actually ConfigParameters delegates (in accordance with the Strategy Design Pattern) the primary data access to an object which implements the interface ConfigData. ConfigParameters is responsible only for parsing the plain string value delivered by ConfigData to the requested data type (int, Color, etc.) and error handling.

PropertiesBasedConfigData is an implementation of ConfigData based on a single Properties instance. A similar implementation for applets is AppletBasedConfigData. Here the Properties object is replaced by an Applet instance which has also "properties" called parameters.

PropertiesBasedConfigData and AppletBasedConfigData have internally only one set of key-value pairs where both keys and values are strings. In order to simulate hierarchically organized key-value pairs a key is stored together with the keys of all its ancestors. The keys of the ancestors are separated by '/'. They form a path in the tree of configuration data.

For example, the length of the x-axis of a plot is written in a .properties file like 

plot/coordinateSystem/xAxis/axisLength = 0.9
In an applet element of an HTML page one would write 
<param name="plot/coordinateSystem/xAxis/axisLength" value="0.9">
In this example it is assumed that an instance of PlotCanvas should be created from ConfigParameters based on such a .properties file or applet parameters.

How to find out which parameters are needed? Look into the Configuration Manual (PDF 180kb), Fortunately, for many parameters default values are defined. Thus only a few parameters are needed to be set. Most notable are the minimum/maximum values for both axes, i.e., plot/coordinateSystem/xAxis/minimum, plot/coordinateSystem/xAxis/maximum, plot/coordinateSystem/yAxis/minimum, and plot/coordinateSystem/yAxis/maximum (see AxisParameters.createXAxis()).

3.4 Inheritance of Configuration Parameters

PropertiesBasedConfigData and AppletBasedConfigData (in general any subclass of FlatConfigData) have the nice feature of inheritance of sets of configuration parameters. This allows to define common parameters (e.g., label font for both axes) in a single place.

Inheritance means that a ConfigParameters object can inherit all key-value pairs (including child ConfigParameters objects) from another ConfigParameters object in the tree of configuration parameters. Inherited parameters can be override. A ConfigParameters object can inherit from a ConfigParameters object which itself inherits from another one. The maximum level of inheritance is 20.

In .properties files and applet parameters such an inheritance is stored in special key-value pairs: The key is the full path of a ConfigParameters object how wants to extends another ConfigParameters object. The value is the full path of the extended ConfigParameters object. Note, key and path have to end with '/'.

Here is an example: 

defaultAxisParameters/ticLabelFormat = %d
defaultAxisParameters/ticLabelAttributes/fontSize = 0.03
defaultAxisParameters/axisLabelAttributes/textColor = 0xa0
defaultAxisParameters/axisLabelAttributes/fontSize = 0.04
defaultAxisParameters/axisLabelAttributes/fontStyle = bold
plot/coordinateSystem/xAxis/ = defaultAxisParameters/
plot/coordinateSystem/xAxis/axisLabel = year
plot/coordinateSystem/xAxis/minimum = 1994.5
plot/coordinateSystem/xAxis/maximum = 2002.5
plot/coordinateSystem/xAxis/minimumTic = 1995
plot/coordinateSystem/xAxis/maximumTic = 2002
plot/coordinateSystem/yAxis/ = defaultAxisParameters/
plot/coordinateSystem/yAxis/axisLabel = number of articles
plot/coordinateSystem/yAxis/axisLabelAttributes/textColor = 0xa000
plot/coordinateSystem/yAxis/maximum = 500
plot/coordinateSystem/yAxis/grid = true
The special key-value pairs defining inheritance are high-lighted. Both axes inherit from defaultAxisParameters. For the y-axis the text color of the axis label is overriden (green instead of blue). For each axis additional parameters are definied separately.
Java and all Java-based trademarks and logos are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries.
(C) 2003-2004 Franz-Josef Elmer. All rights reserved. Last modified: 12/14/2004