10Duke
Contents
Configuration is used to customize an application built on the 10Duke SDK to meet application specific requirements and to reflect an application's deployment environment. The SDK provides single configuration that is serialized in java.util.Properties format. Most parts of the configuration consist of simple key-value pairs that applications access via getter functions of Configuration singleton class, e.g. Configuration.instance().getString(String key).
Some features of 10Duke SDK have more sophisticated configuration. This Configuration Guide describes the configuration mechanism in general and provides more detailed information of the more sophisticated or more complex configuration cases.
Although the 10Duke SDK configuration is logically a single configuration, it can be quite freely organized into several configuration files. The goal for organizing the configuration should be to make maintenance of the configuration easy in the application's deployment. For instance, parts of configuration that are different for each node in a distributed deployment can be separated from common parts of the configuration.
Singleton Configuration class provides programmatic access to configuration. Configuration is always accessed by configuration key name, for instance calling Configuration.instance().getString(String key) with messaging.send.mail.host as the key retrieves send mail (SMTP) host configuration value. Example values for the messaging.send.mail.host configuration entry could be localhost or smtp.myexampleisp.com.
Configuration class has accessor methods for typed access to different kinds of configuration entry values. The accessor methods may return simple types or complex types. Examples of accessor methods returning simple type values are Configuration.instance().getString(String key) that returns configuration entry value as String and Configuration.instance().getInt(String key) that returns entry value as Integer. Examples of accessor methods returning complex type values are Configuration.instance().getXmlElement(String key) that returns XML value and Configuration.instance().getProperties(String key) that provides access to nested configuration as PropertyBasedConfigurationProvider object.
Configuration is read from the configuration file defined by 10duke.configuration.main JVM system property whose value is read by using java.lang.System.getProperty("10duke.configuration.main"). The value of this JVM property should be an absolute or relative path to the configuration file. If value is not defined, ./conf/conf.xml is used as default configuration file path. In relative paths, including the default configuration file path, path is relative to process execution directory.
Value of 10duke.configuration.main property can be also defined as url, using one of the url schemes supported by IOUtils.getInputStream(URI url). Currently supported schemes include file, jndi and webapp, where webapp is a custom scheme that can be used for referring to internal structure inside a Web Application packaged as a .war. Examples of values for 10duke.configuration.main property using different schemes include:
10duke.configuration.main=file:/home/myusername/myapplication/conf/theConfiguration.xml defines configuration file by absolute file path
10duke.configuration.main=./conf/conf.xml would explicitly define configuration path to be the same as the default configuration path. Since no url scheme has been defined, file scheme is used as default. Since this is a relative path, it is interpreted as being relative to process execution directory.
10duke.configuration.main=webapp:/META-INF/resources/conf.xml defines configuration file as embedded in a .war package deployed on an application server
When developing a Web Application that is packaged in a .war and ServletContextLifecycleManager is used, configuration file location can be defined in the deployment descriptor WEB-INF/web.xml by setting an environment entry. The following snippet sets the 10duke.configuration.main configuration key to its default value.
<env-entry>
<env-entry-name>10duke.configuration.main</env-entry-name>
<env-entry-type>java.lang.String</env-entry-type>
<env-entry-value>webapp:/META-INF/conf/conf.xml</env-entry-value>
</env-entry>ServletContextLifecycleManager does _not_ use the identically named JVM system property, since it doesn't make sense to bind configuration location to the web application container process. Some containers allow definition of environment entries in other files besides WEB-INF/web.xml, see get started page for examples.
The value of 10duke.configuration.main always refers to a single configuration file, called the primary configuration file in this chapter. However, it is possible and advisable to organize configuration into several files. Some criteria that should be considered when organizing configuration into several files include:
There are two directives that can be used in the primary configuration file for referring to other configuration files:
<?include url="url of configuration to include"?> can be used to include contents of another file into the primary configuration file. Contents of the included file are inserted into the primary configuration file as such, as if it would be written directly in the primary configuration file.
<?value url="url of file containing a configuration entry value" encoding="..." cache="true|false"?> can be used as value for a configuration entry. When the value directive is used, the actual value for the configuration entry is never inserted in the primary configuration but read from the file defined by url attribute of the value directive first time when the value is accessed using one of the getter methods in Configuration class.
<?include url="url of configuration to include"?> directive instructs the SDK configuration parser to insert contents of the file defined by url attribute to the primary configuration as such. The value of the url attribute can be a relative or absolute url. Relative urls are interpreted as being relative to value of 10duke.configuration.main property, and absolute urls can use any scheme allowed for the value of 10duke.configuration.main property. See above for description of the 10duke.configuration.main property.
Let's use an example primary configuration file whose contents would look like this:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties version="1.0"> <entry key="primary.configuration.key.1">Value of key 1</entry> <?include url="IncludedFile.xml?> </properties>
Contents of IncludedFile.xml referred by the include directive above would look like this:
<entry key="included.configuration.key.2">Value of key 2</entry>
When the SDK configuration parser reads the primary configuration file, it interprets the include directive and inserts contents of the file referred by url attribute of the directive, resulting in configuration like this:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties version="1.0"> <entry key="primary.configuration.key.1">Value of key 1</entry> <entry key="included.configuration.key.2">Value of key 2</entry> </properties>
include instructions are processed before xml parsing, and the contents of the configuration must be valid xml and conform to the java.util.Properties xml format after include instructions have been processed. This is why contents of included files usually only contain entry elements, and include directives are inside the properties element in the primary configuration file.
<?value url="url of file containing a configuration entry value" encoding="..." cache="true|false"?> directive can be used only as value of an entry element, and it must always be wrapped in a CDATA section. Below are contents of an example configuration file that uses the value directive:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties version="1.0"> <entry key="configuration.key.1"><![CDATA[<?value url="ValueOfConfigurationKey1.xml" encoding="utf-8" cache="true"?>]]></entry> </properties>
Contents of ValueOfConfigurationKey1.xml referred by the value directive above would be:
<?xml version="1.0" encoding="utf-8"?> <!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd"> <properties version="1.0"> <entry key="nested.configuration.key.1">This is value of configuration key in a nested configuration file</entry> </properties>
The value directive is evaluated first time when the value is accessed using one of the getter methods in Configuration class. In our example case, the value is actually a nested configuration in java.util.Properties xml format, and it could be accessed by calling Configuration.instance().getProperties("configuration.key.1"). This returns an instance of PropertyBasedConfigurationProvider, and calling PropertyBasedConfigurationProvider.getString("nested.configuration.key.1") on this instance would return a value of nested.configuration.key.1 in the nested configuration, returning String value "This is value of configuration key in a nested configuration file".
Since value is not evaluated before parsing the configuration file, files referred by value directives may contain any character data. value directive also gives some control over how the referred value data is treated by the system. Attributes of the value directive are:
url: Relative or absolute url to file from which actual value of the configuration entry is read. Relative urls are interpreted as being relative to value of 10duke.configuration.main property, and absolute urls can use any scheme allowed for the value of 10duke.configuration.main property. See above for description of the 10duke.configuration.main property.
encoding: Character encoding used to read the referred file. Default is utf-8.
cache: Allowed values are true or false, controls whether value read from the referred file is cached after first read. If cache is disabled, the referred file is read every time the value is accessed by methods of the Configuration class.
<?var name="name of a variable" value="value of the variable"?> directive allows you to define variables to be used in configuration files. A variable is expanded using <?ref name="name of the variable"?>"/> directive which replaces the directive by the variable value as is.
Variable definition must occur before the variable is used, otherwise the <?ref?> directive is replaced by an empty string. In some cases it may be convenient to aggregate several variable definitions into a single file. In that case you need to add an include directive to any configuration file using those variables.
For example, suppose you have variables defined a conf/variables.xml file
<?var name="httpPort" value="8080"?> <?var name="httpsPort" value="8081"?>
Then suppose you have a configuration for an embedded Jetty web server in a conf/web/webServerConf.xml file. The configuration syntax is Jetty specific, but the variables can be referred as follows
<?include url="../variables.xml"?>
...
<Set name="port">
<SystemProperty name="jetty.port" default="<?ref name="httpPort"?>" />
</Set>
<Set name="confidentialPort"><?ref name="httpsPort"?></Set>
...
Configuration file is an xml file in java.util.Properties xml format. This format allows defining key-value pairs that are used as configuration parameters by the SDK configuration engine. The following example shows a configuration file with few configuration parameters:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">
<properties version="1.0">
<!-- Use XML comments to document the configuration file -->
<entry key="logging.consolelogwriter.template.error">[{0}] {1} ({2}) {3}
{4} {5}</entry>
<entry key="logging.consolelogwriter.template.warning">[{0}] {1} ({2}) {3}
{4} {5}</entry>
<entry key="logging.consolelogwriter.template.info">[{0}] {1} ({2}) {3}
{4} {5}</entry>
<entry key="logging.consolelogwriter.debug.level">3</entry>
</properties>In this example, &#xD; is an xml escape code for carriage return. The example contains four configuration parameters. Parameters where key name starts with logging.consolelogwriter.template. contain String values, logging.consolelogwriter.debug.level contains an Integer value. These values can be accessed in Java using respective getter methods of Configuration singleton class, i.e. Configuration.instance().getString(String key) and Configuration.instance().getInt(String key).
Contents of the configuration file must always be valid xml and conform to java.util.Properties xml format DTD. If a configuration parameter value should contain characters that are reserved xml characters, they must be escaped or wrapped in CDATA sections. For instance, parameter value 1<2 can be written in the following two ways:
<entry key="value.with.less.than">1<2</entry>
or
<entry key="value.with.less.than"><![CDATA[1<2]]></entry>
Key-value pairs are simple and convenient for expressing simple configurations. However, in some cases it is necessary to allow more complex configuration. The following example shows how to use xml as configuration parameter value:
<entry key="usermanagement.logincontext.BasicLoginContext.loginmodules">
<![CDATA[<loginModules>
<loginModule class="com.tenduke.usermanagement.LoginModuleForPasswordAuthentication" controlFlag="SUFFICIENT">
<options>
<option name="ignoreLoginNameCase" value="true"/>
</options>
</loginModule>
</loginModules>]]>
</entry>Now this configuration can be accessed directly as an xml element by calling Configuration.instance().getXmlElement("com.tenduke.usermanagement.LoginModuleForPasswordAuthentication").
It is often more convenient to write complex configuration like this in separate files. This can be done by using <?value?> directive for referring to a file where the complex configuration is stored. For instance, if the xml content inside the CDATA section in the example above would be stored in file.xml, the configuration entry could be written like this:
<entry key="usermanagement.logincontext.BasicLoginContext.loginmodules"><![CDATA[<?value url="file.xml"?>]]></entry>
The SDK uses parameter naming conventions that resemble Java package naming conventions. This way configuration parameters names also describe the context in which they are used, and sorting parameters by parameter creates logical parameter groups. For instance, all configuration parameters where the name starts with networking are related to networking. Parameter names starting with networking.crawler further narrow down the scope, telling you that parameter is related to crawling networks. Most general scope is described by the left-most part of parameter names, most specific by the right-most part.
Naming conventions:
Top level scopes in which parameters are grouped are:
content.* contains parameters for file based data.
content.storage.* contains parameters for classes which realize StorageProvider interface.
data.* contains parameters non-file based data.
data.database.* contains parameters related to using databases.
distribution.* contains parameters for configuring distribution and distributed computing
external.* contains parameters for configuring usage of external components and applications
lifecycle.* contains parameters for application lifecycle management.
lifecycle.servicemanager.* contains parameters for ServiceManager class.
logging.* contains parameters for logging.
usermanagement.* contains parameters for user management.
messaging.* contains parameters for email, sms, mms etc. messaging features and functions.
media.* contains parameter for media (and multimedia).
networking.* contains parameters for networking.
reporting.* contains parameters for reporting.
search.* contains parameters for configuring indexing, crawling and search
security.* contains parameters for security.
serialization.* contains parameters for class serialization.
serialization.serializableobjectfactory.* contains parameters for SerializableObjectFactory class.
The 10Duke SDK uses JVM system properties, accessed by java.lang.System.getProperty(String name), for a few special configuration cases. Most notably, a JVM system property is used for configuring location of the configuration file.
JVM system properties are described separately in Configuration Reference.
Web application environment entries, usually stored in context.xml file under a META-INF directory of the web application, are also used in few special configuration cases. The following example shows using an environment entry for configuring 10Duke SDK configuration location:
<?xml version="1.0" encoding="UTF-8"?> <Context antiJARLocking="true" path="/examples/socialmedia"> <Environment name="10duke.configuration.main" type="java.lang.String" value="webapp:/META-INF/resources/myConf.xml"/> </Context>
Web application environment entries are described separately in Configuration Reference.
See samples page.