jMax Phoenix use XML as its configuration language
At startup, and in some case during execution, a number of xml files are loaded in an internal data structure called the XML registry, that every module can access.
There are number of general rules about the way this mechanism works, that need to be understood if you want to master the details of the jMax Phoenix configuration. You also need some very basic knowledge of XML. Most of the sophisticated aspects of XML are not used in jMax.
When multiple XML files are read in memory one after the other, they are not textually concatenated, but they are merged together. To give an idea, consider this two example XML files:
<?xml version="1.0"?> <jmax> <preferences> <background color="red"/> </preferences> </jmax>
And
<?xml version="1.0"?> <jmax> <preferences> <foreground color="white"/> </preferences> </jmax>
If the two files where concatenaded, the registry content would be equivante to loading the file:
<?xml version="1.0"?> <jmax> <preferences> <background color="red"/> </preferences> </jmax> <jmax> <preferences> <foreground color="white"/> </preferences> </jmax>
That you can image would not means a lot. Instead, the merging rules are such that this result is obtained:
<?xml version="1.0"?> <jmax> <preferences> <background color="red"/> <foreground color="white"/> </preferences> </jmax>
that make a lot more sense. The file being read is matched with the registry content, and existing nodes are not duplicated, but merged together, and the children elements merged to the existing node children.
The main merge rule is the following: two nodes are merged (considered the same), if the are identical, i.e. they have the same element name, and the same set of attributes and attribute values.
Actually, we consider two nodes to be the same also if the new one have more attributes of the existing one; the new attributes are added to the existing ones in the existing nodes.
Actually, the rules are a little more complex: for there are cases where you want to modify existing elements, modifying existing attribute values.
There are two rules added rules that help in this case: if the nodes have
a name attribute, they are considered the same and merged regardless of the
other attributes. The attribute of the node take the precedence on the existing
one.
The second rule is: if the existing node have a default attribute with value
yes, than the new node is always merged with the exiting one; this allows to explicitly
mark an element representing a default value as such, and is tipically used in the
main configuration file.
For making an example, the jmax.xml and $(os.name)/defaults.xml files fix defaut values for io configuration and for user interfaces. The result is equivalent to this XML fragment:
<?xml version="1.0"?> <jmax> <preferences> <ui name="ide" default="yes"/> <io-configuration name="portaudio" default="yes"/> </preferences> </jmax>
If no other file declare the same element, this values are used by jMax.
If for example the user configuration file set them, like in:
<?xml version="1.0"?> <!-- The jMax configuration file. --> <jmax> <preferences> <io-configuration name="profile" /> <ui name="tabbedIde"/> </preferences> </jmax>
thanks to the merging rules they overwrite the default ones, and become the actual configuration.
jMax Phoenix use a standard way to identify a file resources (contained in a package or elsewhere) using the standard URL syntax.
A jMax URL is in the form:
jmax://<packageName>/<path to file>
The URL is dynamically translated to the actual filename of the resource,
by prefixing the path with the directory path where the package packageName actually
reside.
This allows the use of package resources without knowing its exact installation location (and Note that with downloaded packages you will not know the package directory).
jMax support two special package names: home that always refer to the user home directory, and core that refer to the jMax distribution. This allows portable references to personal resources or to jMax core resources.
A jMax URL can also contains variables, like for example:
jmax://mypackage/$(os.name)/module.so
The variable correspond either to the Java System properties (of which os.name, os.arch and user.name are the most interesting) and to command line arguments. This allows to customise a package, mostly to adapt it to multiple architecture, but other customisation are possible, of course.
In general, jMax accept absolute paths where jMax Urls are expected, and
it also accept paths starting with ~/; the tilde is trasformed in jmax:home,
so the tilde notation is accepted in all the plateforms.
==== Include ====
A configuration file can include an other one, specified with a
jMax URL. This allows to modularize and parametrize the configuration.
For example, the jmax.xml include the following XML elements:
<code xml>
<?xml version=“1.0”?>
<!– The jMax configuration file. –>
<jmax>
<!– Include the platform default and the user configuration –>
<include file=“jmax:core/config/$(os.name)/defaults.xml”/>
<include file=“jmax:home/.jmax.xml”/>
…..
</jmax>
</code>
That include a file defaults.xml file from a directory that correspond to
the operating system we are running on, and the personal include file.
Notes that even for simplicity the term used here is include'', the file is
not included in place, but merged after the current file has been completely read,
following the above merge rules.
==== Configuration files ====
The configuration files used by jMax Phoenix are the following (using a jMax URL notation)
* <file>jmax:config/boot.xml</file> Include the basic bootstrap sequence. Do not touch unless you really know what you are doing.
* <file>jmax:config/jmax.xml</file> The main configuration file. Read it to learn everything that can be done with a configuration file. In most of the case you should not need to modify it, but you can if you want (for example to modify the list of packages loaded at boot time).
* <file>jmax:config/$(os.name)/defaults.xml</file> A configuration file containing input output configurations that are specific to the operating system jMax is running it, and the default choice of configuration.
* <file>jmax:home/.jmax.xml</file> The user configuration files, that typically include user preferences, but can also define alternative user interfaces, alternatives input output configuration and many other things.
* <file>jmax:<package>/<package>.jpkd</file> The jMax package description file is a configuration file like the others, that is merged in the configuration registry at the moment the package is loaded. As such, the package may contains, other than package specific information, also some generic configuration, for example to adapt the user interface to the package and so on.
Please notes that the package description file are loaded after the system start up, and some of the configuration parameters are currently taken in account only at system start up time, so check the documentation of the parameter you are interested in.