Defining Configuration Interfaces

Hard-coding configuration values directly into a component limits its flexibility. At the same time, traditional property files don’t integrate cleanly with the dynamic OSGi runtime. To solve this, Liferay leverages the OSGi Configuration Admin service. This service enables you to define configurations using annotated Java interfaces, which separates settings from the component code. Additionally, these annotations automatically generate a dynamic configuration UI in the Liferay Control Panel.

In this lesson, you’ll learn how to define a configuration interface using these annotations.

Configuration Interfaces

A configuration interface defines a component’s settings. Each method in the interface represents a configurable property.

Here’s an example interface:

@ExtendedObjectClassDefinition(
    category = "clarity",
    scope = ExtendedObjectClassDefinition.Scope.COMPANY
)
@Meta.OCD(
    id = "com.clarityvisionsolutions.insurance.benefits" +
       ".configuration.ClaimsConfiguration",
    localization = "content/Language",
    name = "claims-configuration"
)
public interface ClaimsConfiguration {
    @Meta.AD(
        deflt = "true",
        name = "enable-claims-processing",
        required = false
    )
    public boolean enableClaimsProcessing();
}

This interface defines a configuration with a single property, enableClaimsProcessing.

When it’s deployed to Liferay (with the claims-configuration and enable-claims-processing language keys), it appears in system settings:

The annotations used in this example describe the configuration metadata that Liferay uses to expose the configuration through the Control Panel.

Annotation: @ExtendedObjectClassDefinition

The @ExtendedObjectClassDefinition annotation is a Liferay extension that controls where the configuration appears in the Control Panel.

Here’s an example:

@ExtendedObjectClassDefinition(
    category = "clarity",
    scope = ExtendedObjectClassDefinition.Scope.COMPANY
)

The category value determines where the configuration appears in the settings menu (in this example, a clarity category). This helps organize related configurations when multiple modules are installed.

The scope value determines the configuration’s scope, which also determines which settings menu it uses. It may appear with these scopes:

• ExtendedObjectClassDefinition.Scope.SYSTEM: System Settings

• ExtendedObjectClassDefinition.Scope.COMPANY: Instance Settings

• ExtendedObjectClassDefinition.Scope.GROUP: Site Settings

Annotation: @Meta.OCD

The @Meta.OCD annotation defines the Object Class Definition, which represents the configuration itself.

It uses these attributes:

• id: The configuration’s PID.

• name: The configuration’s display name (usually a language key).

• description (optional): The description shown for the configuration (usually a language key).

In Liferay development, the configuration PID must match the fully qualified name of the configuration interface. This convention enables Liferay to associate configuration metadata with the correct interface. Here’s an example of a fully qualified class name that must be used as the PID:

com.clarityvisionsolutions.insurance.benefits.configuration.ClaimsConfiguration

Annotation: @Meta.AD

The @Meta.AD annotation defines an Attribute Definition. Each method with a @Meta.AD annotation becomes its own configurable property.

@Meta.AD(
    deflt = "true",
    name = "enable-claims-processing",
    required = false
)
public boolean enableClaimsProcessing();

These are the most common attributes for @Meta.AD annotations:

• deflt: The configuration property’s default value. The string value must match the method’s return type (e.g., "2" for a method returning int).

• required: Whether the property value must be provided to save the configuration.

• name: The configuration property’s display name (usually a language key).

• description (optional): The description shown for the configuration property (usually a language key).

Deploying Configuration Files

You can override the configuration interface’s property values by implementing the interface with a class that returns new values for each property method. However, it’s better to provide deployable configurations as .config files.

Liferay automatically applies .config files to their respective components when they’re added to this directory:

[LIFERAY_HOME]/osgi/configs

The file name must match the configuration’s PID, like this example:

com.liferay.frontend.js.web.internal.session.timeout.configuration.SessionTimeoutConfiguration.config

Values in the configuration file use property names matching their method names in the configuration interface. Set the values line by line, like this:

enableClaimsProcessing="true"

Deployable configuration files store configuration values alongside other deployment artifacts. Administrators often use them for these scenarios:

• Managing multiple environments.

• Deploying configurations as part of an automated process.

• Ensuring consistent configurations across a cluster.

You can change configurations through the Control Panel or with .config files, depending on your workflow.

Conclusion

Configuration interfaces define the settings that control a component’s behavior. Metadata annotations describe each property, and the values can be changed through the Control Panel or with .config files.

Next, you’ll practice creating a configuration interface for Clarity.