Home Examples Download User Guide Introduction Usage as a library Configuration Concept JCCKit's PlotApplet Extending JCCKit API documentation SourceForge project page | # 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 how configuration parameters are accessed, how they are used, how they are stored, and 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