Advanced Unblu Server Configuration
The information on this page assumes you have already read Unblu Server Configuration.
In addition to the standard configuration mechanisms described in Unblu Server Configuration, unblu has a set of additional configuration features that allow for more complex and dynamic setups.
2. Dynamic Reconfiguration
The unblu server has the ability to dynamically reload configuration while the server is running.
CAUTION: Not all configuration settings support dynamic reconfiguration. Not all configuration settings that appear in the STATIC section in the log file at server startup support dynamic reconfiguration.
Dynamic reconfiguration must be triggered explicitly by calling the /sys-unblu/rest/propertyCascade/reload rest service. If your server is running on localhost on port 8080, you need to request http://localhost:8080/sys-unblu/rest/propertyCascade/reload to trigger dynamic reconfiguration.
CAUTION: Make sure the /sys-unblu path is properly protected. (See System Entry Path Concept#Securityconsiderations.)
3. Using Multiple Configuration Files
Instead of using a single configuration file, it is also possible to split configuration across multiple files. Multiple configuration files are specified using a coma separated list of file path or urls in the com.unblu.propertyoverlay System Property instead of a single value. (See using configuration files.)
This example specifies two configuration files: http://configurationserver/unblu/unblu-configuration.com and /opt/unblu/unblu-configuration.properties.
When using multiple configuration files, the ones that are defined later will always take precedence over the ones defined earlier.
In the example above this means that properties defined in /opt/unblu/unblu-configuration.properties will take precedence over properties defined in http://configurationserver/unblu/unblu-configuration.properties.
Using multiple configuration files can make sense, for instance, in an unblu cluster where servers share some, but not all, of the configuration. A second scenario for using multiple configuration files is when there are multiple environments (i.e. prod, stage, development) that share most of the configuration but still need some individual configuration.
4. Scope-Specific Configuration
Usually, configuration properties are global to the unblu server. This means that a configuration property is always applied.
In addition to global configuration properties, unblu also provides a number of other scopes for configuration properties. Scoped configuration properties are only applied in a certain context, i.e. for a specific user or for a specific domain.
Scope-specific configuration is only supported if xml (see XMLConfigurationFiles below) files are used (instead of java properties files).
The available configuration scopes are described below.
4.1. "Global" Scope
The global scope is the default scope. If you use properties files for configuration, then the scope is always global. Globally-scoped properties are effective for the whole unblu server.
4.2. "Domain" Scope
The domain scope is defined by the origin (schema + fully qualified domain) of the (web-) page the user is currently visiting. If an unblu installation is shared for multiple domains (i.e. http://trading.bank.com and http://www.bank.com), then domain-scoped configuration can be used to apply individual configuration settings for the "trading" and the "www" part of the site.
4.3. "User" Scope
The user scope is defined by the currently executing authenticated user. Using user scoped configuration settings, you can specify individual configuration for users.
5. XML Configuration Files
In addition to java properties files, unblu also supports an xml-based configuration file format. Certain configuration features (such as scope-specific configurations; see above) are only supported in the xml based format.
The xml based format has the following general format:
The xml file must be a valid xml file starting with a <?xml version="1.0" encoding="<character-encoding>"?> line. We recommend using UTF-8 (as in the sample above) but all other character encodings supported by the java virtual machine in use are also supported.
The document element MUST be named "configuration".
The document element can contain any number of sections where every section must be a valid section as described below and must be unique within the file.
Every section can contain any number of property elements but MUST NOT contain more than one property element using the same key.
Everly property element MUST define a "key" attribute.
The value of the property is the text contents of the property element.
Section elements must conform with one of the section types described below.
5.1. Section Type "Global"
The "global" section type defines properties that are valid globally (for the whole unblu server).
The "global" section type does not have any attributes and MUST not be declared more than once in a configuration file.
5.2. Section Type "Domain"
The "domain" section type defines properties that are valid for a certain domain (fully-qualified domain with protocol, <protocol>://<fqdn>:<optionalport>, i.e. http://www.unblu.com)
The "domain" section type MUST declare an "origin" attribute holding the origin of the domain (fully qualified domain with protocol, no path, no trailing slash, i.e. http://www.unblu.com)
A configuration file MUST NOT contain more than one domain section with the same "origin" attribute.
5.3. Section Type "User"
The "user" section type defines properties that are valid for a certain authenticated user.
The "user" section type MUST declare an "id" attribute holding the id of the user the section is valid for.
A configuration file MUST NOT contain more than one user section with the same "id" attribute.
5.4. Example XML Configuration File
Example of a valid xml configuration file. Property key must be valid keys (see Unblu Server Configuration Reference) for real life files.