ViewVC Help
View File | Revision Log | Show Annotations | Revision Graph | Root Listing
root/i-scream/projects/cms/documentation/specification/configuration.txt
Revision: 1.1
Committed: Mon Nov 27 00:04:38 2000 UTC (24 years, 1 month ago) by ajm
Content type: text/plain
Branch: MAIN
Log Message:
initial submission

File Contents

# User Rev Content
1 ajm 1.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> can either be a FQDN or an ip address. In
304     the case of a FQDN, it should be all in lower case.
305     The <clientname> is the configured name for the particular
306     client.
307     The <componentname> the name as given in the component for
308     any particular component.
309    
310     The <config file> is file name of a configuration under the
311     configurtion root directory.
312    
313     An example of how this can be used:
314    
315     FilterManager.listenPort=4567
316    
317     This line for the <componentname> of FilterManager can
318     appear in the system configuration. Or if the following
319     line exists in the system configuration:
320    
321     config.FilterManager = filterManager.conf
322    
323     The file "filterManager.conf" and any included files will
324     be checked for the entry, before looking for it in the
325     system configuration.
326    
327     Other Configuration Files
328     -------------------------
329    
330     The main entry of other configuration files to be aware of
331     is the:
332    
333     include = file1.conf;file2.conf;file3.conf
334    
335     This line can be in the configuration file. Each include
336     would will be processed in turn, checking to see if they
337     have any includes. All of these would then be brought
338     together into one list.
339    
340     Assuming a configuration above, and that each of the
341     includes has two includes, we would get the following list
342     of configuration files, which are checked for configuration
343     properties in the following order:
344    
345     conf.conf;file1.conf;file1a.conf;file1b.conf;
346     file2.conf;file2a.conf;file2b.conf;file3.conf;
347     file3a.conf;file3b.conf;system.conf
348    
349     Note the order of precedence of the includes of the included
350     files, namely that their includes take higher priority over
351     the includes of the lower down includes. Also note that
352     they system configuration appears last, allowing global
353     values to be placed there.
354    
355    
356     For further information on configurating other components of
357     the system, please refer to the components individual
358     documentation.
359    
360    
361     About
362     -----
363    
364     This document was written by Alex Moore [ajm4@ukc.ac.uk] for
365     use by the team working on a 3rd year Computer Science
366     project called "i-scream". More details can be found on the
367     project website;
368    
369     http://www.i-scream.org.uk