documentation/specification/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
Revision:	1.4
Committed:	Wed Jul 16 14:54:47 2008 UTC (16 years, 5 months ago) by tdb
Content type:	text/plain
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.3:	+3 -4 lines
Log Message:	Remove AJ's email address.
#	Content
1	I-Scream System Configuration - initial draft
2	=============================
3
4	ajm4, 26/11/2000
5
6	This document will address all three areas of concern
7	regarding the configuration operational parameters of the
8	i-scream system to date. These areas being:
9
10	1) Configuration Mechanisms
11	- maintenance documentation
12
13	2) Using the Configuration System
14	- developer documentation
15
16	3) Configuring the I-Scream System
17	- user documentation
18
19	Configuration Mechanisms
20	------------------------
21
22	Configuration of the I-Scream system is predominantly
23	carried out through the ConfigurationManager component.
24	However there is another configuration option which should
25	be used to an absolute minimum, yet it is necessary to
26	explain it here as it is used!
27
28	Any configuration that should be carried out before any
29	component can initialise the ORB and obtain a reference to
30	the ConfigurationManager should be placed in a "properties"
31	file that is local to that component. At the time of
32	writing the only component to require this is the CORE. This
33	is because is requires some initialisation to get the system
34	up and running. However, it is NOT the norm to use this
35	method, and all elements of the system should make an effort
36	to attach to the orb and obtain the ConfigurationManager
37	before requiring any specific configuration. For information
38	on what is currently contained within the
39	"default.properties" file please refer to the user
40	documentation.
41
42	The main form of configuration mechanism is the afore
43	mentioned ConfigurationManager. This component acts as a
44	centralised holder for configuration for every part of the
45	system. Components get a referance to this well known
46	service either directly through the CORBA Naming Service
47	(see to-be-published conventions on Naming for the I-Scream
48	project). Or via a local proxy, in the case of a Host this
49	is through the FilterManager, a hosts first connection to
50	the system. This allows both CORBA aware and
51	non-aware components to be configured through this system.
52	The ConfigurationManager also provides support for
53	determining if a configuration has changed and thus (if the
54	component is programmed in such a way), support for dynamic
55	re-loading of configuration. For information on how to use
56	the ConfigurationManager, please see the next section on
57	"Using the Configuration System". For information on the
58	file format and structure, together with what is currently
59	contained with the standard configuraton file, please refer
60	to "Configuring the I-Scream System".
61
62
63	Using the Configuration System
64	------------------------------
65
66	The configuration system itself has two main components.
67	The ConfigurationManager and the Configuration objects.
68	It is currently envisaged that there will only ever be one
69	instance of the ConfigurationManager registered with the ORB
70	in use at any given time. It has the well known service
71	name of "iscream.ConfigurationManager" which a component
72	can used to get a reference to it.
73
74	Once a component has reference to the ConfigurationManager
75	it should then request its configuration using the
76	getConfiguration(<name>) method. eg,
77
78	Configuration myConfig =
79	configManager.getConfiguration("FilterManager");
80
81	The above request causes the ConfigurationManager to look
82	in the system configuration file for the property:
83
84	"config.FilterManager=<config file>"
85
86	It then creates a Configuration object based on the contents
87	of <config file> using the system configuration for the
88	defaults of any values. The ConfigurationManager also has
89	support for including other configurations within a file.
90	For more information on this feature please refer to the
91	next section on "Configuring the I-Scream System".
92
93	A refernce to this Configuration object is then passed back
94	to the calling component. At which point that component can
95	interrogate the Configuration object to obtain its
96	configuration. It should be noted that the Configuration
97	object uses a java.util.Properties object to store the
98	configuration internally, so essentially Configuration acts
99	as a CORBA wrapper for a java.util.Properties object.
100
101	If the entry cannot be found, the component is returned a
102	reference to the system configuration. This allows
103	components to be configured without the need to a
104	configuration file is only a small amount is needed.
105
106	If there is an error at any stage of obtaining the
107	configuration, an appropriate entry will be made in the log,
108	but the component will be returned a NULL reference.
109
110	To obtain entries from a Configuration, a component calls
111	the getProperty(<name>) method. eg,
112
113	myConfig.getProperty("FilterManager.listenPort")
114
115	This will return the String value for that property. The
116	entry in the configuration file would appear as:
117
118	FilterManager.listenPort = <value>
119
120	The configuration system also has support for detecting that
121	a currently loaded configuration has been changed. It
122	achieves this by monitoring the date stamps of the
123	configuration files. The interface to this functionality is
124	provided in two areas. The Configuration object has two
125	further methods, getFileList() and getLastModified(). The
126	first returns a ";" separated list of filenames used to
127	obtain the configuration that was built for that instance.
128	The second returns a long (in the programming sense) number
129	of representing the date stamp of the most recently modified
130	file in the list. Using these two attributes a component
131	can ask the ConfigurationManager to see if its configuration
132	has changed. This is done by calling the isModified(<list>,
133	<last modified>) method. eg,
134
135	configManager("conf1.conf;conf2.conf", 2897938472)
136
137	The ConfigurationManager would then check the file list
138	given together with the system configuration file (as that
139	file is the root of all configurations) to see if the date
140	stamp on any of them is more recent than the given date. If
141	a change is detected this method returns "true" otherwise
142	it returns false. It is then up to the calling component to
143	act, the system does not enforce configuration changes it
144	mearly supports the facility to detect it.
145
146	(note: this next section deals with the naming conventions
147	used withing the configuration files ONLY. ie, from a
148	sys admins point of view (ie, our users).)
149
150
151	Configuring the I-Scream System
152	-------------------------------
153
154	Although there are three main configuration sections to be
155	delt with, all configuration files use the same formatting
156	conventions. These follow.
157
158	Formatting
159	----------
160
161	Each line should be terminated by a line terminator (\n or
162	\r or \r\n). A line that contains only whitespace or whose
163	first non-whitespace character is an ASCII # or ! is ignored
164	(thus, # or ! indicate comment lines). Every line other than
165	a blank line or a comment line describes one property to be
166	added to the table (except that if a line ends with \, then
167	the following line, if it exists, is treated as a
168	continuation line, as described below). The key consists of
169	all the characters in the line starting with the first
170	non-whitespace character and up to, but not including, the
171	first ASCII =, :, or whitespace character. All of the key
172	termination characters may be included in the key by
173	preceding them with a \. Any whitespace after the key is
174	skipped; if the first non-whitespace character after the key
175	is = or :, then it is ignored and any whitespace characters
176	after it are also skipped. All remaining characters on the
177	line become part of the associated element string. Within
178	the element string, the ASCII escape sequences \t, \n, \r,
179	\\, \", \', \ (a backslash and a space), and \uxxxx are
180	recognized and converted to single characters. Moreover, if
181	the last character on the line is \, then the next line is
182	treated as a continuation of the current line; the \ and
183	line terminator are simply discarded, and any leading
184	whitespace characters on the continuation line are also
185	discarded and are not part of the element string.
186
187	As an example, each of the following four lines specifies
188	the key "Truth" and the associated element value "Beauty":
189
190
191	Truth = Beauty
192	Truth:Beauty
193	Truth :Beauty
194
195	As another example, the following three lines specify a
196	single property:
197
198	fruits apple, banana, pear, \
199	cantaloupe, watermelon, \
200	kiwi, mango
201
202	The key is "fruits" and the associated element is:
203
204	"apple, banana, pear, cantaloupe, watermelon,kiwi, mango"
205
206	Note that a space appears before each \ so that a space will
207	appear after each comma in the final result; the \, line
208	terminator, and leading whitespace on the continuation line
209	are merely discarded and are not replaced by one or more
210	other characters. As a third example, the line:
211
212	cheeses
213
214	specifies that the key is "cheeses" and the associated
215	element is the empty string.
216
217	default.properties
218	------------------
219
220	This file is loaded by the CORE. The CORE either loads this
221	file from the working directory, or from a specific location
222	using the "-l" command line option. This file provides
223	intial bootstrapping configuration to the system to get the
224	whole thing on its feet. The requirement for entries here
225	is kept to a bare minimum, however all entries listed below
226	MUST have an option set for the system to start. Current
227	configurable options in this file are:
228
229	----
230	org.omg.CORBA.ORBClass= jacorb.orb.ORB
231	org.omg.CORBA.ORBSingletonClass= jacorb.orb.ORBSingleton
232
233	These two options specifiy which ORB the sytem is to use.
234	By default these are set to the above values, as the JacORB
235	ORB is the one that is distributed with the system, however
236	should you wish to change ORB's to fit with your
237	organisation, it is supported.
238
239	----
240	uk.ac.ukc.iscream.Verbosity= 5
241
242	This sets the logging verbosity to be used by the system,
243	ie, how much information will be printed to the log file,
244	where the number is:
245
246	FATAL - (0) Fatal or Critical Errors
247	ERROR - (1) All Errors
248	WARNING - (2) Warnings
249	SYSMSG - (3) System Component messages
250	SYSINIT - (4) System Component initialisation
251	DEBUG - (5) All debugging messages
252
253	----
254	uk.ac.ukc.iscream.ConfigurationLocation=../etc
255	uk.ac.ukc.iscream.SystemConfigurationFile=system.conf
256
257	These set up the configuration component. The first entry
258	tells where the root directory of all configurations for the
259	system are to be found. The second entry specifies the name
260	of the system configuration file to be used.
261
262	----
263	uk.ac.ukc.iscream.LoggerClass=ScreenLogger
264	uk.ac.ukc.iscream.LoggerClassParam=
265
266	These set up the logging facility. The first entry is a
267	class name of the Logger class to be used by the system.
268	The second line may or may not appear depending on the
269	logging class in use. Logging classes require different
270	configuration options to operate, please refer to their
271	documentation for details. A variety of logging classes
272	will be included with the i-scream system, again, please
273	refer to their documentation for what functionality they
274	provide.
275
276	System Configuration File
277	-------------------------
278
279	This file is used as the defaults for all configurations
280	used by the system. When a property is requested from a
281	configuration, if it can't be found in any of the other
282	files in its configuration tree, this file is checked before
283	returning null. This allows for global defaults to be
284	placed here. Another function of this file is that if no
285	individual configuration file exists for a component it is
286	returned a reference to this file alone. This means that
287	a configuration file does not HAVE to be created for every
288	component.
289
290	There are several key things to be noted for this file.
291	Individual entries for various components are not detailed
292	in this document, but are instead listed in the
293	documentation for the component in question.
294
295	config.<elementname> = <config file>
296
297	where <elementname> can be:
298
299	Host.<hostname>
300	Client.<clientname>
301	<componentname>
302
303	The <hostname> must FQDN, it should all be in lower case.
304	The <clientname> is the configured name for the particular
305	client.
306	The <componentname> the name as given in the component for
307	any particular component.
308
309	The <config file> is file name of a configuration under the
310	configurtion root directory.
311
312	An example of how this can be used:
313
314	FilterManager.listenPort=4567
315
316	This line for the <componentname> of FilterManager can
317	appear in the system configuration. Or if the following
318	line exists in the system configuration:
319
320	config.FilterManager = filterManager.conf
321
322	The file "filterManager.conf" and any included files will
323	be checked for the entry, before looking for it in the
324	system configuration.
325
326	Other Configuration Files
327	-------------------------
328
329	The main entry of other configuration files to be aware of
330	is the:
331
332	include = file1.conf;file2.conf;file3.conf
333
334	This line can be in the configuration file. Each include
335	would will be processed in turn, checking to see if they
336	have any includes. All of these would then be brought
337	together into one list.
338
339	Assuming a configuration above, and that each of the
340	includes has two includes, we would get the following list
341	of configuration files, which are checked for configuration
342	properties in the following order:
343
344	conf.conf;file1.conf;file1a.conf;file1b.conf;
345	file2.conf;file2a.conf;file2b.conf;file3.conf;
346	file3a.conf;file3b.conf;system.conf
347
348	Note the order of precedence of the includes of the included
349	files, namely that their includes take higher priority over
350	the includes of the lower down includes. Also note that
351	they system configuration appears last, allowing global
352	values to be placed there.
353
354
355	For further information on configurating other components of
356	the system, please refer to the components individual
357	documentation.
358
359
360	About
361	-----
362
363	This document was written by Alex Moore for use by the team working on
364	a 3rd year Computer Science project called "i-scream". More details
365	can be found on the project website;
366
367	http://www.i-scream.org