Liferay DXP’s System Settings application is convenient for making system-scoped configuration changes and setting default configurations for other scopes. But there’s another supported configuration approach: configuration files. You can use configuration files to transfer configurations from pre-production systems to production systems, or between any other Liferay DXP systems. Sometimes developers choose to distribute the default configuration for their applications via configuration file. Whatever the reason, configuration files are a straightforward way of configuring Liferay DXP.
Creating Configuration Files
System Settings provides an
Export
option that becomes available once you modify a configuration entry. Exporting
is the recommended way to create .config files: you download a .config file
containing the entry’s settings in a key=value format. Liferay DXP exports an
entry’s total available configuration keys and values, even if only one value
was changed. You can export a single configuration entry or the entire set of
modified configurations in Liferay DXP.
To avoid a file name conflict, name configuration files using a unique identifier. For example, the Journal Service entry, which backs Liferay’s Web Content capabilities, has this file name:
com.liferay.journal.configuration.JournalServiceConfiguration.config
Figure 1: The Web Content System Settings entry has the backend ID `com.liferay.journal.configuration.JournalServiceConfiguration`.
Configuration files use the .config property value format defined by the Apache
Felix Configuration Admin
framework.
The .cfg file format is common in OSGi environments, so Liferay DXP supports it,
but .config files are preferable. You can specify a property value’s type, and
have multi-valued properties. The syntax described below is for .config files.
Key/Value Syntax
The general syntax for all keys and values in a .config file is the same:
configurationName="value"
For single value configurations without special characters, that’s all there is to know. Settings with multiple values and certain characters require slight modifications.
Multi-Value Settings
Configuration entries can have properties that accept multiple values. For
example, a configuration property for specifying supported file extensions needs
more than one value. Here’s how to write a multi-value setting in a .config
file:
multiValueSetting=["Value 1","Value 2", ...]
Do not use a space character between values (after the comma). An errant space character can cause a failure to load the property.
Open the Web Content entry from System Settings and you’ll see what looks like multiple single value entries for Charactersblacklist:
Figure 2: The Web Content System Settings entry has many *Charactersblacklist* fields.
In the configuration file, this is really a single key with an array of comma-separated values:
charactersblacklist=["&","'","@","\\","]","}",":","\=",">","/","<","[","{","%","+","#","`","?","\"",";","*","~"]
Escaping Characters
Double quotes (") and equals signs (=) must be escaped in .config files.
Escaping is using another character to denote that a character shouldn’t be used
in its normal way. Since double quotes and equals signs are already used in
.config files, escaping them tells the framework not to read them the normal
way, but to pass them through as part of the value. Use a \ to escape
characters in the .config file:
charactersblacklist=["&","\"","\="]
This setting illustrates a multi-value setting with a regular, unescaped
character (&), and two escaped ones (\" and \=).
Along with the mandatory escaping of double quotes and equals characters, it’s beneficial to escape spaces inside values to avoid problems.
blacklistBundleSymbolicNames=["Liferay\ Marketplace","Liferay\ Sharepoint\ Connector"]
In the above example, a \ is used before each space character to ensure it’s
read and processed properly. If you don’t escape spaces yourself, the framework
adds the backslash for you after deployment.
Deploying a Configuration File
Once you have a configuration file, deploy it so Liferay DXP recognizes it and updates the targeted configuration values.
To deploy the .config file, place it in your
Liferay Home’s
osgi/configs folder. To change the configuration further, you can edit the
.config file directly or use System Settings.
Typed Values
The .config file format supports specifying the type of a configuration value
by inserting a special type marker character. Because Liferay DXP already knows
the correct type for each configuration property, the type characters are only
useful for informational purposes. For example, a configuration with a boolean
type has B just before the value to mark it as a boolean type:
addDefaultStructures=B"true"
If you see type markers in .config files, you can safely ignore them. The
example included above functions identically without the type marker:
addDefaultStructures="true"
Configuration Files and Clustering
In a clustered environment, each node needs the same configuration values for
each entry. For example, all nodes should use the same Blogs configuration
settings. To accomplish this, deploy a .config file to one node. Liferay DXP
uses an internal system that appies the change to all nodes in the cluster.
Factory Configurations
Configurations supporting multiple independent occurrences of the same configuration entry are called factory configurations.
If a service is meant to support factory configuration, its System Settings
entry has an Add button ().
Figure 3: If a System Settings entry has an Add button, it's suitable for factory configuration.
As with single-instance configurations, you can accomplish factory configuration in the System Settings interface (as described in the example above) or via configuration files. Once you determine you must write a factory configuration file. Name a standard single-instance configuration file like this:
my.service.ServiceConfiguration.config
If your service supports factory configuration, use Liferay’s convention
of calling the first instance of the configuration -default.config:
my.service.ServiceConfiguration-default.config
The next instance contains a unique subname (something other than default). It’s smart to use a descriptive name:
my.service.ServiceConfiguration-port9080.config
To follow the CXF Endpoints example described above, if Liferay’s developers had
shipped an initial CXF Endpoint .config file with Liferay DXP, it would have
been named
com.liferay.portal.remote.cxf.common.configuration.CXFEndpointPublisherConfiguration-default.config
Perhaps the -default.config configuration specifies a context path for REST
web services, and then you create another endpoint with a different context path
for SOAP web services. Your second configuration file could be named
com.liferay.portal.remote.cxf.common.configuration.CXFEndpointPublisherConfiguration-soap.config
Now a note of warning. In many cases, configuration files can be used to force a factory configuration scenario, but not all configurations are designed to be used this way. It’s best to stick to the intended use cases. Use System Settings as described above to determine if factory configuration is a good idea. If not, stick to the single occurrence mode of configuration (specifying only one configuration file for the service).