config
Product: xTier™/LWC 2.3 Whitepaper:  Technical Whitepaper	support@fitechlabs.com  Download  Buy
Depends: log  Related: n/a
xTier™ Navigator: cache cluster config email i18n ioc info jmx jndi security log marshal objpool os fs tx uidgen workflow jobs db startup jms grid

Description
The xTier™ configuration service provides the API for accessing configuration properties. Static properties are commonly used to easily define the application behavior prior to start. xTier™ extends the idea of Java's Properties providing better solution for modern application development environments. Often, engineers work from multiple locations, additionally on-shore and off-shore, multiple stages for development, testing, staging and production produce a myriad of property and configuration files in different formats with confusing definitions and usage. Even if there is good control of the configuration parameters, by the very nature of developing software applications, many times the parameters must be changed on each developer’s local machine.

xTier™ configuration service provides a solution to these problems. The configuration service provides an XML-based language for defining configuration properties in an "object-oriented" manner using rich type specification capabilities. Using the configuration service a developer can separate configuration properties into hierarchical regions according to their natural structure and meaning, where each region can further differentiate properties into groups where each property can be strongly typed. See XtierKernel for more information about xTier™ configuration regions.

 Top

Configuration
The 'config' service provides strongly typed, XML-driven, runtime access to configuration properties. An important characteristic of the 'config' service is that it is designed for configuration parameters that cannot be changed in runtime. In other words, configuration parameters are defined in an XML file and read once during the service startup. The 'config' service does, however, provide a “reload” operation that will re-read the configuration parameters from the XML file, possibly with new values.

The 'config' service is configured via a pre-defined xtier_config.xml configuration file. This file follows the standard xTier™ service configuration pattern that can be demonstrated by the following complete example of the 'config' service configuration:

1		<region name="super" abstract="true">
2		<group name="constants">
3		<config-prop name="min.value" type="int8">
4		<single>33</single>
5		</config-prop>
6
7		<config-prop name="max.value" type="int8">
8		<single>126</single>
9		</config-prop>
10		</group>
11
12		<group name="group">
13		<config-prop name="single_int8" type="int8">
14		<range>
15		<min>${constants:min.value}</min>
16		<max>${constants:max.value}</max>
17		</range>
18		<single>125</single>
19		</config-prop>
20		<config-prop name="single_float32" type="float32">
21		<single>7.85485454949769</single>
22		</config-prop>
23
24		<!--
25		Some utility object potentially needed by
26		factory.
27		-->
28		<ioc policy="new" uid="util1">
29		<java class="for.bar.Factory"/>
30		<clr class="For.Bar.Factory" assembly="asm"/>
31		</ioc>
32
33		<!-- IoC based property. -->
34		<config-prop name="pi" type="obj">
35		<ioc policy="singleton">
36		<java class="java.math.BigDecimal">
37		<ctor>
38		<arg type="string">
39		3.141592653589793238462643383279502884
40		</arg>
41		</ctor>
42		</java>
43		</ioc>
44		</config-prop>
45
46		<!-- Keyed IoC based property. -->
47		<config-prop name="pi2" type="obj">
48		<ioc policy="keyed">
49		<java class="java.math.BigDecimal">
50		<ctor>
51		<arg type="string">
52		3.141592653589793238462643383279502884
53		</arg>
54		</ctor>
55		</java>
56		</ioc>
57		</config-prop>
58
59		<!-- String array property. -->
60		<config-prop name="array_string" type="string">
61		<regex>^x.*x$</regex>
62		<array>
63		<item>x1x</item>
64		<item>x2x</item>
65		</array>
66		</config-prop>
67
68		<!-- Map property. -->
69		<config-prop name="map_date_float32"
70		type="float32">
71		<valid-set name="set1">
72		<valid>2.5</valid>
73		<valid>3.5</valid>
74		</valid-set>
75		<invalid-set name="set2">
76		<invalid>7.5</invalid>
77		<invalid>6.5</invalid>
78		</invalid-set>
79		<map key-type="date">
80		<entry key="1:00 am">2.51</entry>
81		<entry key="5:25 pm">2.52</entry>
82		<entry key="11/1/03">2.5</entry>
83		<entry key="11/1/03">2.5</entry>
84		</map>
85		</config-prop>
86		</group>
87		</region>
88
89		<region name="examples">
90		<extend>
91		<parent name="super"/>
92		<extend>
93		<group name="constants">
94		<config-prop name="one" type="int8">
95		<single>5</single>
96		</config-prop>
97		<config-prop name="two" type="int8">
98		<single>${constants:one}</single>
99		</config-prop>
100		</group>
101		</region>

The 'config' service configuration region consists of zero or one <extend> tags defining the parent region, and zero or more <group> tags each defining a config group. The <extend> consists of zero or more <parent> tags. <parent> tags specify which regions the current region extends. All properties from base regions will be inherited. Sub regions can override properties with the same name and type. The <parent> XML tag has the following required attributes:

name	Points to the base config region

The group is the set of properties that belongs to a specific subsystem or logical unit. The <group> XML tag has the following required attributes:

name	Unique name of the group. This name can be used later at runtime to access properties of this group.

The <group> tag can contain zero or more <config-prop> tags each defining configuration properties. The <config-prop> XML tag has the following required attributes:

name

Name of the property. Should be unique within the config group. This name can be used later at runtime to get the property value.

type

Type of property. Can be one of the following values: int8 - byte property. int16 - short property. int32 - int property. int64 - long property. char16 - char property. float64 - double property. float32 - float property. boolean - boolean property. string - string property. The 'config' service returns a String instance as the property value. date - date property. The 'config' service returns a Date instance as the property value. Note that if time-only component is specified it will be returned as a time of the day of January 1, 1970, i.e. number of milliseconds since the January 1, 1970, 00:00:00 GMT ("the epoch"). obj - object property. The 'config' service returns Object that can be cast to its real type. This property is specified in the XML configuration as an IoC object. See IocService for more detail on IoC configuration.

A property value can be represented by <single>, <array> or <map> tags:

• <single> XML tag defines the property singular value.
• <array> XML tag defines the property array value; each single value in an array is represented by a <item> tag. Order of the items is significant. Note that this property can be retrieved as either a Java array or a java.util.List.
• The <map> XML tag defines a property map value. Order of the items is insignificant. The type of the property applies to the map's values only. The <map> XML tag has the following required attributes:

  type	Type of the map key. Can be one of the same values set as the type attribute in the <config-prop> tag, except the obj.

  The <map> tag consists of zero or more <entry> tags, which represent map entries. The <entry> XML tag has the following required attributes:

  key	Entry key.

 Top

Property Substitution
Any property value can include the ${[group:]prop-name} construct (more specifically, match \$\{[^:}]+(:[^}]+)?\} regular expression) where:

• group - is name of another configuration group, and
• prop-name - is name of another property in group.

 Top

Property Qualifiers
A property contains the value itself and an optional value qualifier. On 'config' service start up or reload all properties will be checked against these qualifiers. If property value will pass all specified qualifications 'config' service starts up. If at least one qualification will fail 'config' service will throw an exception. The value qualifier can be defined by the following XML tags: <range>, <valid-set>, <invalid-set>, <regex>, <custom-qualif> and <type>:

• The <range> XML tag defines the optional maximum and minimum inclusive range qualifier for the property value, provided by the <min> and <max> tags. Valid and invalid ranges can be specified using valid boolean attribute which by default is set to true. Range has an optional name attribute. The name will be used only in error reporting to indicate which type qualifier has failed. It also has optional attribute inclusive which can take values true or false. It indicates whether end points of the range should be included in the range of valid values (default value is true). Not that you can specify both or one of the range borders, for example, specify only minimum or only maximum value for property, or both minimum and maximum.
• The <valid-set> XML tag defines a set of valid values for the property value. The set is provided by <valid> tags. The <valid-set> tag has an optional name attribute. The name will be used only in error reporting to indicate which type qualifier has failed.
• The <invalid-set> XML tag defines the set of values that cannot appear in the property value. The set is provided by the <invalid> tags. The <invalid-set> tag has an optional name attribute. The name will be used only in error reporting to indicate which type qualifier has failed.
• The <regex> XML tag defines an optional regular expression value qualifier for the property value. Qualifiers can be valid and invalid depending on optional valid attribute. By default all regex qualifiers are valid ones. The <regex> tag has an optional name attribute. The name will be used only in error reporting to indicate which type qualifier has failed. See http://www.regxlib.com for more documentation on regular expressions.
• The <custom-qualif> XML tag defines custom IoC qualifier for the property value. Custom qualifier should implement ConfigCustomQualifier interface. Custom qualifiers are instantiated on service’s startup using IoC mechanism. Unlike other types of qualifiers, custom qualifies can be used for IoC-based properties (except those properties which have 'keyed' creation policy), and for other types properties as well. See ConfigCustomQualifier for more info on custom qualifiers. The <custom-qualif> tag has an optional name attribute. The name will be used only in error reporting to indicate which type qualifier has failed.
• The <hierarchy> XML tag defines type qualifier, which is applicable for IoC properties only. <type> element can have optional <extends> tag, whose class attribute contains fully qualified name of the class which IoC object should extend, and zero or more <implements> tags, whose class attribute contains fully qualified names of interfaces IoC object should implement. IoC property value object is valid, if it extends all specified classes and interfaces. Note that validation is successfull even if inheritance is indirect, and also if class specified by <extends> tag is exactly the same class as IoC object's class.

 Top

Configuration Convertion Utility
xTier™ ships with special utility xtier-config-converter.{sh|exe} that can be found in ${XTIER_ROOT}/bin directory. This command lint utility allows to convert file in Windows *.ini and java.lang.Properties formats to config service XML format.

Usage: xtier-config-converter.{sh|exe} <options>, where options are:
    [-w -in <file> -out <file> -region <name> [-spaces <count>] [-encoding <encoding>]]
    [-j -in <file> -out <file> -region <name> [-spaces <count>] [-encoding <encoding>]]
    [-help | -?]

-w (windows *.ini file)

-in <file>

Windows *.ini file path.

-out <file>

xTier™ 'config' XML file path.

-region <name>

xTier™ 'config' region name.

-spaces <count>

Optional parameter. Number of spaces in tabulation.

-spaces <encoding>

Optional parameter. XML encoding string(UTF-8 by default).

-j (java.util.Properties file)

-in <file>

Java properties file path.

-out <file>

xTier™ 'config' XML file path.

-region <name>

xTier™ 'config' region name.

-spaces <count>

Optional parameter. Number of spaces in tabulation.

-spaces <encoding>

Optional parameter. XML encoding string(UTF-8 by default).

-help or -?

Show help message.

Examples:
-w -in "c:\Program Files\Program\config.ini" -out c:\temp\xtier_config.xml -spaces 4
-j -in "c:\Program Files\Program\config.properties" -out c:\temp\xtier_config.xml -encoding windows-1251

 Top

Configuration JSP Support
'config' service comes with JSP tag that can be used to access service's functionality directly via JSP tag. In ${XTIER_ROOT}/lib/xtier/taglib directory there is JAR xtier-taglib.jar that contains code for custom JSP tags. The same directory also contains JSP taglib file xtier-taglib.tld with standard definition for xTier™ custom JSP tags. Consult this file for detailed usage information. Following JSP example demonstrates some basic usage of JSP i18n tag:

Given the following JSP taglib definition:

<%@ taglib uri="/xtier" prefix="xtier" %>

the following JSP code can illustrate its usage:

1		<html>
2		<head>
3		<title>Sample JSP page</title>
4		</head>
5
6		<body>
7		<span>Byte property:<span>
8		<xtier:config group="group" prop="single_int8"
9		type="byte"/>
10
11		<span>Long property:<span>
12		<xtier:config group="group" prop="single_int64"
13		type="long"/>
14		</body>
15		</html>

 Top

Examples
Usage of the 'config' service follows the standard pattern of using an xTier™ service: you need to obtain an instance of the xTier™ kernel that serves as a service registry. Once you have the xTier™ kernel you can get an instance of any service, in our case the 'config' service. Once the service instance is obtained the service API can be used.

The following example illustrates these basic steps (assuming the above configuration example):

1		// Get the instance of xTier kernel.
2		XtierKernel xtier = XtierKernel.getInstance();
3
4		// Get the instance of 'config' service.
5		ConfigService config = xtier.config();
6
7		// Gets byte max.value constant value.
8		byte b = config.getByte("constants", "max.value");
9
10		// Gets date value of property constants:some_date.
11		Date d = config.getDate("constants", "some_date");
12
13		// Gets ioc object value of property group:pi.
14		BigDecimal pi = null;
15
16		try {
17		pi = (BigDecimal)config.getIocObj("group", "pi");
18		}
19		catch (ConfigException e) {
20		e.printStackTrace();
21		}
22
23		// Gets keyed ioc object.
24		BigDecimal pi2 = null;
25
26		try {
27		pi2 = (BigDecimal)config.getIocObj("group", "pi2",
28		new Integer(1));
29		}
30		catch (ConfigException e) {
31		e.printStackTrace();
32		}
33
34		// Gets different types arrays.
35		byte[] ba = config.getByteArr("group",
36		"array_int8");
37		String[] str = config.getStringArr("group",
38		"array_string");
39
40		// Gets array as list.
41		List strList = config.getList("group",
42		"array_string");
43
44		// Reloads config.
45		try {
46		config.reload();
47		}
48		catch (ConfigException e) {
49		e.printStackTrace();
50		}

 Top