Advanced Configuration

INTERNAL REFERENCE CONTENT -- NOT FOR GENERAL USE!

WARNING: Configuration as described throughout this page is deprecated (from unblu version 4.2) and will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

The information on this page assumes you have already read Configuration.

In addition to the standard configuration mechanisms described in Configuration, unblu has a set of additional configuration features that allow for more complex and dynamic setups.

Dynamic Reconfiguration

The server has the ability to dynamically reload configuration while the server is running.

CAUTION: Not all configuration settings support dynamic reconfiguration. Configuration properties that are only allowed in the IMMUTABLE scope do not support dynamic reconfiguration.

Dynamic reconfiguration has to be triggered explicitly by calling the /sys-unblu/rest/propertyCascade/reloadrest 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.)

Dynamic reconfiguration also works for localized text settings. (See i18n Configuration and Advanced i18n Configuration.)

Scope-Specific Configuration

WARNING: File-based scoped configuration as described here is deprecated and will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

Usually, configuration properties are global to the 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 named area.

Scope-specific configuration is only supported if xml files (see XML Configuration Files below) are used (instead of java properties files).

The available configuration scopes are described below.

Global Scope

The global scope is the default scope. When using properties files for configuration, the scope is always global. Globally-scoped properties are effective for the whole server.

Named Area

WARNING: File-based scoped configuration as described here is deprecated and will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

The named area scope is defined by the named area of the (web-) page the user is currently visiting.

See Named Areas.

User Scope

WARNING: File-based scoped configuration as described here is deprecated and will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

The user scope is defined by the currently executing authenticated user. Using user-scoped configuration settings, you can specify individual configuration for users.

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, are only supported in the xml-based format.

The xml-based format has the following general format:

<?xml version="1.0" encoding="UTF-8"?>
<!-- this is a generic example of an unblu xml configuration file... SECTION1 and SECTION2 must be replaced by valid section elements (global, domain or user)-->
<configuration includes="./other.xml">
     <SECTION1>
         <variable key="v1">value</variable>

         <property key="key1">value 1</property>
         <property key="key2">value 2</property>
     </SECTION1>

     <SECTION2>
         <property key="key1">value 1</property>
         <property key="key2">value 2</property>
     </SECTION2> 
 </configuration>

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 configuration element CAN specify a list of includes (comma-separated list of relative or absolute paths).

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 variable and property elements but MUST NOT contain more than one variable or property element using the same key.

Every variable element MUST define a "key" attribute.

The value of the variable is the text contents of the property element.

Every property element MUST define a "key" attribute.

The value of the property is the text contents of the property element.

Property elements CAN contain ${variableName} placeholders to use variables defined earlier.

Section elements must conform with one of the section types described below.

Section Type "Global"

The "global" section type defines properties that are valid globally (for the whole server):

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml configuration file with a global section -->
<configuration>
    <global>
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </global>
</configuration>

The "global" section type does not have any attributes and MUST not be declared more than once in a configuration file.

Section Type "Named Area"

WARNING: File-based scoped configuration as described here is deprecated in will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

The "area" section type defines properties that are valid for a certain named area.

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml configuration file with a domain section -->
<configuration>
    <area name="www">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </area>
</configuration>

The "area" section type MUST declare an "name" attribute holding the name of the area.

A configuration file MUST NOT contain more than one area section with the same "name" attribute.

Section Type "User"

WARNING: File-based scoped configuration as described here is deprecated in will not be supported in future versions. Please use dynamic configuration (stored in the database) instead. Dynamic configuration can be changed from the Admin Desk UI as well as via Web API.

The "user" section type defines properties that are valid for a certain authenticated user.

<?xml version="1.0" encoding="UTF-8"?>
<!-- example of an xml configuration file with a user section -->
<configuration>
    <user id="123456">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </user>
</configuration>

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.

Example XML Configuration File

Example of a valid xml configuration file. Property key must be valid keys (see Configuration Properties. for real-life files).

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <global>
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </global>

    <area name="www">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </area>

    <area name="ebanking">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </area>    


    <user id="12345">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </user>

    <user id="abcde">
        <property key="key1">value 1</property>
        <property key="key2">value 2</property>
    </user>    
</configuration>
  • deployonprem

results matching ""

    No results matching ""