Is there any documentation on creating schema files?

The configuration system uses a schema file to load and configure the tree map. Advanced users may customize the schema file to provide additional capabilities. Creating schema files can be complex and should not be undertaken by most users. Lab Escape makes no guarantees that edits to a schema file will be supported in either service or point releases to Enterprise Tree Map. If you do decide to extend or modify the schema file, it is recommend you do so using an override file, rather than modifying the schema file directly. This will minimize the impact of schema changes during upgrades.

The following is the current documentation for the schema files. It is not complete, but provides a basic overview of the different elements. If you need further details, please contact support.

Overview

The schema is simply a configuration file that uses a set of specific elements and attributes to define the elements used in the main configuration. Like normal configuration files, schemas can be layered on top of one another, with properties from earlier files being overridden by properties from later files. This provides a mechanism by which schemas can be extended without affecting the core schema.

Regardless of how many files are used to construct a schema, the composite schema created becomes the single schema that is used for every configuration file.

Structure

The schema file is divided into two sections: types and definition. These sections exist as elements under the root schema element. Both sections contain nested sets of elements that define how a specific element in the configuration file should be parsed.

Types Section

The types section is used to define generic types which can be referenced by elements and attributes within the main schema definition. Types are useful for providing a common definition for configuration elements that exist at multiple points in the configuration hierarchy.

For instance, the following border type is used to define a re-usable type that is referenced by different configuration elements:

Note: This is an old version of a border type that is no longer used. But it provides the general idea. For the current version, see your schema file.

XML
<types>
    <border properties="renderLevel,width,color,style,visible">
        <width class="Integer" />
        <color class="java.awt.Color" />
        <visible class="Boolean" />
        <style class="Integer" mapValues="distinct">
              <solid value="0" />
              <beveled value="1" />
        </style>
    </border>
</types>

Properties
schema.types.border@properties=renderLevel,width,color,style,visible
schema.types.border.width@class=Integer
schema.types.border.color@class=java.awt.Color
schema.types.border.visible@class=java.awt.Boolean
schema.types.border.style@class=Integer
schema.types.border.style@mapValues=distinct
schema.types.border.style.solid@value=0
schema.types.border.style.solid@value=1

It is referenced using the type element on the element being defined:

XML
<border key="renderLevel" type="border" />

Properties
schema.definition.config.border@key=renderLevel
schema.definition.config.border@type=border

Definition Section

The definition section of the schema contains the actual definition of which elements are valid for a configuration file. The element hierarchy under the definition element mimicks the hierarchy that exists in the configuration. The attributes of each of these schema elements define how the element should be parsed in the configuration.

For example, one of the most basic attributes used in the schema definition is the class attribute. This attribute defines which class the element will be instantiated as when the .instance() function is applied to the element. The following code shows how a menu element would use the class attribute to return an instance of JMenu when the config.menu.instance() property is retrieved:

XML
<menu class="javax.swing.JMenu" />

Properties
schema.definition.config.menu@class=javax.swing.JMenu

The next section will describe the different attributes that can be applied to schema elements.

Schema Processing Attributes

These are attributes which affect how the schema is processed.

  • reference
    Applies To: elements, attributes
    Indicates that the schema attributes for this element are located elsewhere in the schema. Attributes defined on this element will override those defined on the referenced element.

  • switch
    Applies To: elements, attributes
    Indicates the attribute on the element that should be used to determine which of the given sub-elements should be used for the schema information for this element.

  • default
    Applies To: elements, attributes
    Indicates the default value used for the switch.

Schema Configuration Attributes

The attributes of the elements in a schema define how the corresponding element in the configuration file should be instantiated and configured. The attributes used for schema elements are:

  • class
    Applies To: elements, attributes
    Defines which class this element or attribute should be instantiated as.

  • instance
    Applies To: elements, attributes
    References an instance of an element defined elsewhere in the schema or in the main configuration file. If this attribute is defined, all the other "element" attributes on this attribute will be ignored, and instead return the values of the attributes on the referenced element.

  • defaultCondition
    Applies To: elements, attributes
    Indicates that a default instance should be created even though the element or attribute does not exist in the configuration.

  • defaultValue
    Applies To: attributes
    The value to use when creating a default attribute.

  • key
    Applies To: elements
    Indicates which attribute should be used as a key when referencing the elements in the configuration file using the associative array syntax. (ie: border['leaf']).

  • attributes
    Applies To: elements
    Lists the names of the attributes that are valid for this element as a comma-separated list.

  • elements
    Applies To: elements
    Lists the names of the elements that are valid for this element as a comma-separated list.

  • constructorParameters
    Applies To: elements, attributes
    Lists the values that should be passed as parameters into the constructor for this element as a comma-separated list.

  • constructorClasses
    Applies To: elements, attributes
    Lists the classes for each parameter that should be passed into the constructor for this element as a comma-separated list. If this attribute is missing, but constructorParameters is defined, then the classes are guessed based on the classes of the parameters being passed in.

  • propertyName
    Applies To: attributes
    Defines the name that should be used to set this property on its parent element. This defaults to the name of the element itself.

  • propertyMethod
    Applies To: attributes
    Defines the name of the method used to set the property on its parent element. This defaults to a name derived by applying the JavaBean property naming standard to the propertyName attribute.

  • propertyParameters
    Applies To: attributes
    Lists the values that should be passed as parameters into the method specified by the propertyMethod attribute for this element. This defaults to the value for the current element.

  • propertyClasses
    Applies To: attributes
    Lists the classes for each parameter that should be passed into the method specified by the propertyMethod attribute for this element. If this attribute is missing, but propertyParameters is defined, then the classes are guessed based on the classes of the parameters being passed in.

  • propertySetCondition
    Applies To: attributes
    Determines the conditions under which this property should be set on its parent element. The acceptable values are: always, notNull, and never. notNull indicates the property should only be set if its value is not null. The default is notNull.

  • arrayClass
    Applies To: elements, attributes
    Indicates the class to use when creating an array of this element using the .array() function.

  • mapValues
    Applies To: attributes
    Indicates the value for this attribute should be mapped to a different value based on a value map.

  • value
    Applies To: attributes
    The value that the attribute should be mapped to in a value map.

Variables

Variables are used to reference configuration values from within attributes and element text fields. Variables allow the ability to perform substitutions of values, or to reference values from elsewhere in the configuration.

Variables take the form:

${<variable element>|<variable element>|...}

Where <variable element> is either a quoted string, a number or a configuration path. The pipes (|) are used to separate alternative values if the first value turns out to be null.

The following demonstrates the use of variables to set the class for the treemap element:

<treemap class="${config.treemap@class|'com.labescape.treemap.awtui.AWTTreeMap'}

This says to first look at the configuration path config.treemap@class for a non-null value. If this exists, then use it; otherwise use the value specified after the pipe as the default value.

Functions

Element Functions

  • instance()

  • array()

  • keys()

  • exists()

Attribute Functions

  • instance()

  • array()

  • exists()