Liferay DXP uses Felix File Install to monitor file system folders for new/updated configuration files, and the Felix OSGi implementation of Configuration Admin to let you use files to configure module service components.
To learn how to work with configuration files, first review Understanding System Configuration Files.
Configuration File Formats
There are two different configuration file formats:
.cfg: An older, simple format that only supports string values as properties..config: A format that supports strings, type information, and other non-string values in its properties.
Although Liferay DXP supports both formats, we recommend .config files
for their flexibility. Since .cfg file lacks type information, if you want to
store anything but a String, you’ll need a properties utility class that casts
the Strings to their proper types (and you must carefully document properties
that aren’t Strings). Since .config files can include type information, using
them eliminates this need. The articles below provide a detailed explanation of
these file formats, including their syntax:
- Understanding System Configuration Files
- Configuration file (
.config) syntax - Properties file(
.cfg) syntax
Naming Configuration Files
Before you create a configuration file, you should determine whether multiple instances of the component can be created, or if the component is intended to be a singleton. Follow these steps to make that determination:
-
Deploy the component’s module if you haven’t done so already.
-
In Liferay DXP’s UI, go to Control Panel → Configuration → System Settings.
-
Find the component’s settings by searching or browsing for the component.
-
If the component’s settings page has a section called Configuration Entries, you can create multiple instances of the component configured however you like. Otherwise, you should treat the component as a singleton.
Figure 1: You can create multiple instances of components whose System Settings page has a *Configuration Entries* section.
All configuration file names must start with the component’s PID (PID stands
for persistent identity) and end with .config or .cfg.
For example, this class uses Declarative Services to define a component:
package com;
@Component
class Foo {}
The component’s PID is com.Foo. All the component’s configuration files must
start with the PID com.Foo.
For each non-singleton component instance you want to create or update with a
configuration, you must use a uniquely named configuration file that starts with
the component’s PID and ends with .config or .cfg. Creating configurations
for multiple component instances requires that the configuration files use
different subnames. A subname is the part of a configuration file name after
the PID and before the suffix .config or .cfg. Here’s the configuration file
name pattern for non-singleton components:
[PID]-[subname1].config[PID]-[subname2].config- etc.
For example, you could configure two different instances of the component
com.Foo by using configuration files with these names:
com.Foo-one.configcom.Foo-two.config
Each configuration file creates and/or updates an instance of the component that matches the PID. The subname is arbitrary–it doesn’t have to match a specific component instance. This means you can use whatever subname you like. For example, these configuration files are just as valid as the two above:
com.Foo-puppies.configcom.Foo-kitties.config
Using the subname default, however, is Liferay DXP’s convention for configuring
a component’s first instance. The file name pattern is therefore:
[PID]-default.config
A singleton component’s configuration file must also start with [PID] and end
with .config or .cfg. Here’s the common pattern used for singleton component
configuration file names:
[PID].config
When you’re done creating a configuration file, you can deploy it.
Resolving Configuration File Deployment Failures
The following IOException hints that the configuration file has a syntax
issue:
Failed to install artifact: [path to .config or .cfg file]
java.io.IOException: Unexpected token 78; expected: 61 (line=0, pos=107)
To resolve this, fix the configuration file’s syntax.
Great! Now you know how to configure module components using configuration files.