i-scream documentation viewer
configuration.txt
I-Scream System Configuration - initial draft
=============================
ajm4, 26/11/2000
This document will address all three areas of concern
regarding the configuration operational parameters of the
i-scream system to date. These areas being:
1) Configuration Mechanisms
- maintenance documentation
2) Using the Configuration System
- developer documentation
3) Configuring the I-Scream System
- user documentation
Configuration Mechanisms
------------------------
Configuration of the I-Scream system is predominantly
carried out through the ConfigurationManager component.
However there is another configuration option which should
be used to an absolute minimum, yet it is necessary to
explain it here as it is used!
Any configuration that should be carried out before any
component can initialise the ORB and obtain a reference to
the ConfigurationManager should be placed in a "properties"
file that is local to that component. At the time of
writing the only component to require this is the CORE. This
is because is requires some initialisation to get the system
up and running. However, it is NOT the norm to use this
method, and all elements of the system should make an effort
to attach to the orb and obtain the ConfigurationManager
before requiring any specific configuration. For information
on what is currently contained within the
"default.properties" file please refer to the user
documentation.
The main form of configuration mechanism is the afore
mentioned ConfigurationManager. This component acts as a
centralised holder for configuration for every part of the
system. Components get a referance to this well known
service either directly through the CORBA Naming Service
(see to-be-published conventions on Naming for the I-Scream
project). Or via a local proxy, in the case of a Host this
is through the FilterManager, a hosts first connection to
the system. This allows both CORBA aware and
non-aware components to be configured through this system.
The ConfigurationManager also provides support for
determining if a configuration has changed and thus (if the
component is programmed in such a way), support for dynamic
re-loading of configuration. For information on how to use
the ConfigurationManager, please see the next section on
"Using the Configuration System". For information on the
file format and structure, together with what is currently
contained with the standard configuraton file, please refer
to "Configuring the I-Scream System".
Using the Configuration System
------------------------------
The configuration system itself has two main components.
The ConfigurationManager and the Configuration objects.
It is currently envisaged that there will only ever be one
instance of the ConfigurationManager registered with the ORB
in use at any given time. It has the well known service
name of "iscream.ConfigurationManager" which a component
can used to get a reference to it.
Once a component has reference to the ConfigurationManager
it should then request its configuration using the
getConfiguration(<name>) method. eg,
Configuration myConfig =
configManager.getConfiguration("FilterManager");
The above request causes the ConfigurationManager to look
in the system configuration file for the property:
"config.FilterManager=<config file>"
It then creates a Configuration object based on the contents
of <config file> using the system configuration for the
defaults of any values. The ConfigurationManager also has
support for including other configurations within a file.
For more information on this feature please refer to the
next section on "Configuring the I-Scream System".
A refernce to this Configuration object is then passed back
to the calling component. At which point that component can
interrogate the Configuration object to obtain its
configuration. It should be noted that the Configuration
object uses a java.util.Properties object to store the
configuration internally, so essentially Configuration acts
as a CORBA wrapper for a java.util.Properties object.
If the entry cannot be found, the component is returned a
reference to the system configuration. This allows
components to be configured without the need to a
configuration file is only a small amount is needed.
If there is an error at any stage of obtaining the
configuration, an appropriate entry will be made in the log,
but the component will be returned a NULL reference.
To obtain entries from a Configuration, a component calls
the getProperty(<name>) method. eg,
myConfig.getProperty("FilterManager.listenPort")
This will return the String value for that property. The
entry in the configuration file would appear as:
FilterManager.listenPort = <value>
The configuration system also has support for detecting that
a currently loaded configuration has been changed. It
achieves this by monitoring the date stamps of the
configuration files. The interface to this functionality is
provided in two areas. The Configuration object has two
further methods, getFileList() and getLastModified(). The
first returns a ";" separated list of filenames used to
obtain the configuration that was built for that instance.
The second returns a long (in the programming sense) number
of representing the date stamp of the most recently modified
file in the list. Using these two attributes a component
can ask the ConfigurationManager to see if its configuration
has changed. This is done by calling the isModified(<list>,
<last modified>) method. eg,
configManager("conf1.conf;conf2.conf", 2897938472)
The ConfigurationManager would then check the file list
given together with the system configuration file (as that
file is the root of all configurations) to see if the date
stamp on any of them is more recent than the given date. If
a change is detected this method returns "true" otherwise
it returns false. It is then up to the calling component to
act, the system does not enforce configuration changes it
mearly supports the facility to detect it.
(note: this next section deals with the naming conventions
used withing the configuration files ONLY. ie, from a
sys admins point of view (ie, our users).)
Configuring the I-Scream System
-------------------------------
Although there are three main configuration sections to be
delt with, all configuration files use the same formatting
conventions. These follow.
Formatting
----------
Each line should be terminated by a line terminator (\n or
\r or \r\n). A line that contains only whitespace or whose
first non-whitespace character is an ASCII # or ! is ignored
(thus, # or ! indicate comment lines). Every line other than
a blank line or a comment line describes one property to be
added to the table (except that if a line ends with \, then
the following line, if it exists, is treated as a
continuation line, as described below). The key consists of
all the characters in the line starting with the first
non-whitespace character and up to, but not including, the
first ASCII =, :, or whitespace character. All of the key
termination characters may be included in the key by
preceding them with a \. Any whitespace after the key is
skipped; if the first non-whitespace character after the key
is = or :, then it is ignored and any whitespace characters
after it are also skipped. All remaining characters on the
line become part of the associated element string. Within
the element string, the ASCII escape sequences \t, \n, \r,
\\, \", \', \ (a backslash and a space), and \uxxxx are
recognized and converted to single characters. Moreover, if
the last character on the line is \, then the next line is
treated as a continuation of the current line; the \ and
line terminator are simply discarded, and any leading
whitespace characters on the continuation line are also
discarded and are not part of the element string.
As an example, each of the following four lines specifies
the key "Truth" and the associated element value "Beauty":
Truth = Beauty
Truth:Beauty
Truth :Beauty
As another example, the following three lines specify a
single property:
fruits apple, banana, pear, \
cantaloupe, watermelon, \
kiwi, mango
The key is "fruits" and the associated element is:
"apple, banana, pear, cantaloupe, watermelon,kiwi, mango"
Note that a space appears before each \ so that a space will
appear after each comma in the final result; the \, line
terminator, and leading whitespace on the continuation line
are merely discarded and are not replaced by one or more
other characters. As a third example, the line:
cheeses
specifies that the key is "cheeses" and the associated
element is the empty string.
default.properties
------------------
This file is loaded by the CORE. The CORE either loads this
file from the working directory, or from a specific location
using the "-l" command line option. This file provides
intial bootstrapping configuration to the system to get the
whole thing on its feet. The requirement for entries here
is kept to a bare minimum, however all entries listed below
MUST have an option set for the system to start. Current
configurable options in this file are:
----
org.omg.CORBA.ORBClass= jacorb.orb.ORB
org.omg.CORBA.ORBSingletonClass= jacorb.orb.ORBSingleton
These two options specifiy which ORB the sytem is to use.
By default these are set to the above values, as the JacORB
ORB is the one that is distributed with the system, however
should you wish to change ORB's to fit with your
organisation, it is supported.
----
uk.ac.ukc.iscream.Verbosity= 5
This sets the logging verbosity to be used by the system,
ie, how much information will be printed to the log file,
where the number is:
FATAL - (0) Fatal or Critical Errors
ERROR - (1) All Errors
WARNING - (2) Warnings
SYSMSG - (3) System Component messages
SYSINIT - (4) System Component initialisation
DEBUG - (5) All debugging messages
----
uk.ac.ukc.iscream.ConfigurationLocation=../etc
uk.ac.ukc.iscream.SystemConfigurationFile=system.conf
These set up the configuration component. The first entry
tells where the root directory of all configurations for the
system are to be found. The second entry specifies the name
of the system configuration file to be used.
----
uk.ac.ukc.iscream.LoggerClass=ScreenLogger
uk.ac.ukc.iscream.LoggerClassParam=
These set up the logging facility. The first entry is a
class name of the Logger class to be used by the system.
The second line may or may not appear depending on the
logging class in use. Logging classes require different
configuration options to operate, please refer to their
documentation for details. A variety of logging classes
will be included with the i-scream system, again, please
refer to their documentation for what functionality they
provide.
System Configuration File
-------------------------
This file is used as the defaults for all configurations
used by the system. When a property is requested from a
configuration, if it can't be found in any of the other
files in its configuration tree, this file is checked before
returning null. This allows for global defaults to be
placed here. Another function of this file is that if no
individual configuration file exists for a component it is
returned a reference to this file alone. This means that
a configuration file does not HAVE to be created for every
component.
There are several key things to be noted for this file.
Individual entries for various components are not detailed
in this document, but are instead listed in the
documentation for the component in question.
config.<elementname> = <config file>
where <elementname> can be:
Host.<hostname>
Client.<clientname>
<componentname>
The <hostname> must FQDN, it should all be in lower case.
The <clientname> is the configured name for the particular
client.
The <componentname> the name as given in the component for
any particular component.
The <config file> is file name of a configuration under the
configurtion root directory.
An example of how this can be used:
FilterManager.listenPort=4567
This line for the <componentname> of FilterManager can
appear in the system configuration. Or if the following
line exists in the system configuration:
config.FilterManager = filterManager.conf
The file "filterManager.conf" and any included files will
be checked for the entry, before looking for it in the
system configuration.
Other Configuration Files
-------------------------
The main entry of other configuration files to be aware of
is the:
include = file1.conf;file2.conf;file3.conf
This line can be in the configuration file. Each include
would will be processed in turn, checking to see if they
have any includes. All of these would then be brought
together into one list.
Assuming a configuration above, and that each of the
includes has two includes, we would get the following list
of configuration files, which are checked for configuration
properties in the following order:
conf.conf;file1.conf;file1a.conf;file1b.conf;
file2.conf;file2a.conf;file2b.conf;file3.conf;
file3a.conf;file3b.conf;system.conf
Note the order of precedence of the includes of the included
files, namely that their includes take higher priority over
the includes of the lower down includes. Also note that
they system configuration appears last, allowing global
values to be placed there.
For further information on configurating other components of
the system, please refer to the components individual
documentation.
About
-----
This document was written by Alex Moore for use by the team working on
a 3rd year Computer Science project called "i-scream". More details
can be found on the project website;
http://www.i-scream.org
