Specifying property files

A "propFile" element in a script file specifies details about a file to which configuration properties will be written. In the simplest case, a "propFile" element specifies a file name and a set of properties to be written. For example:

  <propFile fileName="jnode.properties">
    <property name="jnode.vm.size"
                 type="integer.type"
                 description="Enter VM size in Mbytes"
                 default="512"/>
    <property name="jnode.vdisk.enabled" type="yesNo.type"
              description="Configure a virtual disk"
              default="no"/>
  </propFile<

This specifies a classic Java properties file called "jnode.properties" which will contain two properties. The "jnode.vm.size" property will have a value that matches the type named "integer.type", with a default value of "512". The "jnode.vdisk.enabled" will have a value that matches the "yesno.type", defaulting to "no".

The Configure tool will act as follows for the example above.

1. It will test to see if the "jnode.properties" file exists in the same directory as the script file.
2. If the file exists, it will be read using the java.util.Properties.load method, and the in-memory property set will be populated from the corresponding properties.
3. If the property file does not exist, the in-memory property set will be populated from the "default" attributes.
4. The "screen" elements will be processed as described in the "" page to capture new property values.
5. Finally, the "jnode.properties" file will be created or updated using the java.util.Properties.save method.

Attributes of a "property" element
Each "property" element can have the following attributes:

name

This attribute gives the name of the property. Property names should be restricted to ASCII letters, digits, '-', '-' and '_'. This attribute is mandatory.

type

This attribute gives the name of the property's type. This attribute is mandatory.

description

This attribute gives a short (20 chars or so) description of the property that will be included in the prompt for the property's value. This attribute is mandatory.

default

This attribute gives a default value for the property if none is supplied by other mechanisms. This attribute is optional, but if present it must contain a valid value for the property's type.

Attributes of a "propFile" element
The Configure tool will read and write properties in different ways depending on the "propFile" element's attributes:

fileName

This attribute specifies the name of the file to be written. Depending on the other attributes, it may also be a source of default values. This attribute is mandatory.

fileFormat

This attribute specifies various alternative file formats. Possible values are listed below.

defaultFile

This attribute specifies that default property values should be loaded from a default property file.

templateFile

This attribute specifies that the output file should be written by expanding the supplied template file, as described below.

marker

This attribute specifies an alternative marker character for template expansion; the default is '@'.

Alternative file formats

As described above, the Configure tool supports five different file types: more if you use plugin classes. These are as follows:

"properties"

This denotes a classic Java properties file, as documented in the Sun javadocs for the java.util.Properties class.

"xmlProperties"

This denotes a XML Java properties file, as documented in the Sun javadocs for the java.util.Prfoperties class (Java 1.5 or later).

"xml"

This denotes an XML file whose structure is not known.

"java"

This denotes a Java source code file.

"text"

This denotes an arbitrary text file.

other

org.jnode.configure.adapter.FileAdapter class. The behavior is as described below

The file types "xml", "java" and "text" require the use of a template file, and do not permit properties to be loaded.

Template file expansion

If Configure uses a java.util.Properties.saveXXX method to write properties, you do not have a great deal of control over how the file is generated. For example, you cannot include comments for each property, and you cannot control the order of the properties.

The alternative is to create a template of a file that you want the Configure tool to add properties to. Here is a simple example:

# This file contains some interesting properties

# The following property is interesting
interesting=@interesting@

# The following property is not at all interesting
boring=@boring@

If the file above is specified as the "templateFile" for a property set that includes the "interesting" and "boring" properties, the Configure tool will output the property set by expanding the template to replace "@interesting@" and "@boring@" with the corresponding property values.

The general syntax for @...@ sequences is:

    at_sequence ::= '@' name [ '/' modifiers ] '@'
    name        ::= ... # any valid property name
    modifiers   ::= ... # one or more modifier chars

The template expansion process replaces @...@ sequences as follows:

• If the <name> matches a property name in the property set, the sequence is replaced with the named property's value, rewritten as described below.
• If the @<name>@ does not match a property name in the property set, the sequence is replaced with an empty string. (This is a change from early versions of the tool which left sequence unchanged.)
• The sequence @@ is replaced a single '@' character.
• It is an error for an "opening" @ to not have a "closing" @ on the same line.

The template expansion is aware of the type of the file being expanded, and performs file-type specific escaping of properties before writing them to the output stream:

• The expander for a "properties" file escapes the value according to the Java property file syntax. Three <modifier> values are supported:
  • The '=' modifier causes the property name and value to be expanded; i.e. "<name>=<value>" where the name and value parts are suitably escaped.
  • The '!' modifier (with '=') causes an empty property value to be suppressed by replacing the @...@ sequence with an empty string.
  • The '#' modifier (with '=') causes an empty property value to be commented out; i.e. "# <name>=<value>"
• The expanders for "xmlProperties" and "xml" files escapes the value so that it can be embedded in the text content of an element.
• The expander for "java" files outputs the value with Java string literal escapes.