====== jMax Configuration Files ======


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.

==== Merging vs concatenation ====


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:

<code xml>
<?xml version="1.0"?>
<jmax>
	<preferences>
	     <background color="red"/>
	</preferences>
</jmax>
</code>

And 

<code xml>
<?xml version="1.0"?>
<jmax>
	<preferences>
	     <foreground color="white"/>
	</preferences>
</jmax>
</code>

If the two files where concatenaded, the registry content would
be equivante to loading the file:

<code xml>
<?xml version="1.0"?>
<jmax>
	<preferences>
	     <background color="red"/>
	</preferences>
</jmax>
<jmax>
	<preferences>
	     <foreground color="white"/>
	</preferences>
</jmax>
</code>

That you can image would not means a lot.
Instead, the merging rules are such that this result is obtained:

<code xml>
<?xml version="1.0"?>
<jmax>
	<preferences>
	     <background color="red"/>
	     <foreground color="white"/>
	</preferences>
</jmax>
</code>

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:

<code xml>
<?xml version="1.0"?>

<jmax>
  <preferences>
    <ui name="ide" default="yes"/>
    <io-configuration name="portaudio" default="yes"/>
  </preferences>
</jmax>
</code>

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:

<code xml>
<?xml version="1.0"?>

<!-- The jMax  configuration file. -->

<jmax>
  <preferences>
    <io-configuration name="profile" />
    <ui name="tabbedIde"/>
  </preferences>
</jmax>
</code>

thanks to the merging rules they overwrite the default ones,
and become the actual configuration.


==== Resource naming ====

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: 

<code>
  jmax://<packageName>/<path to file>
</code>

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:

<code>
jmax://mypackage/$(os.name)/module.so
</code>

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.