Eclipse MicroProfile Config API

Provided version of the API: MicroProfile Config 2.0.1

Background

The Config API was created to allow for the modification of application configuration from outside the application without needing the application to be repackaged.

A full overview for the reasoning behind the API can be found in the Overview for the source code repository.

The complete specification is maintained in the same repository.

Config Sources

A ConfigSource is a definition of a source of configuration values that can be used by an application. In addition to the default ConfigSources outlined by the specification, the following are also supported ConfigSources:

Where multiple configuration properties exist, the property from a source with a higher ordinal number is preferred.

Source Ordinal Description

Source	Ordinal	Description
`directory`	90	Reads configuration properties from files in a specified directory. Each file name is the configuration property name and the contents of the file are the config property value. This config source can be used to read Kubernetes secrets files. You can find out more about directory config sources here: Directory Config Sources
`password`	105	Retrieves and stores config values in the password alias store. These will be available to all server instances in a domain.
`domain`	110	Retrieves and stores config values in the domain.xml as key values. These will then apply to all instances within a domain
`jndi`	115	Retrieves and stores config values within the JNDI tree. The property name being the dotted name path in the JNDI tree and the value being stored in the JNDI tree. These are modifiable by current admin console functionality.
`config`	120	Retrieves and stores config values at the level of the named configuration in the domain.xml; `server-config`, for example. MicroProfile Configuration property values will apply to all instances that use the Payara configuration specified.
`server`	130	Retrieves and stores config values at the level of the server in the domain.xml. Property values will only apply on the named server instance
`application`	140	Retrieves and stores config values at the level of the application. Property values will only be available for the specified application on all server instances it is deployed
`module`	150	Retrieves and stores config values at the level of an individual module within an application. Property values will only be available for the specified module on all server instances it is deployed
`cluster`	160	Retrieves and stores config values in the Hazelcast cluster as name value pairs. These will be available for all server instances that are members of the cluster.
`payara expression`	170	Reads configuration properties from a `payara-expression-config.properties` file. This should be stored in the same location as your `microprofile-config.properties` file This file can be used to reference properties containing variables which will be translated to their actual values upon retrieval. The property values should be in the format referenced here: Types of Variables
`cloud`	180	Reads configuration properties from various Cloud provider secret stores. You can find out more about our supported cloud config sources here: Cloud Config Sources
`jdbc`	190	Reads configuration properties from a specified database table. You can find out more about JDBC config sources here: JDBC Config Sources
`ldap`	200	Reads configuration properties from a specified LDAP directory. You can find out more about LDAP config sources here: LDAP Config Sources

directory

Reads configuration properties from files in a specified directory. Each file name is the configuration property name and the contents of the file are the config property value. This config source can be used to read Kubernetes secrets files. You can find out more about directory config sources here: Directory Config Sources

password

105

Retrieves and stores config values in the password alias store. These will be available to all server instances in a domain.

domain

110

Retrieves and stores config values in the domain.xml as key values. These will then apply to all instances within a domain

jndi

115

Retrieves and stores config values within the JNDI tree. The property name being the dotted name path in the JNDI tree and the value being stored in the JNDI tree. These are modifiable by current admin console functionality.

config

120

Retrieves and stores config values at the level of the named configuration in the domain.xml; server-config, for example. MicroProfile Configuration property values will apply to all instances that use the Payara configuration specified.

server

130

Retrieves and stores config values at the level of the server in the domain.xml. Property values will only apply on the named server instance

application

140

Retrieves and stores config values at the level of the application. Property values will only be available for the specified application on all server instances it is deployed

module

150

Retrieves and stores config values at the level of an individual module within an application. Property values will only be available for the specified module on all server instances it is deployed

cluster

160

Retrieves and stores config values in the Hazelcast cluster as name value pairs. These will be available for all server instances that are members of the cluster.

payara expression

170

Reads configuration properties from a payara-expression-config.properties file. This should be stored in the same location as your microprofile-config.properties file This file can be used to reference properties containing variables which will be translated to their actual values upon retrieval. The property values should be in the format referenced here: Types of Variables

cloud

180

Reads configuration properties from various Cloud provider secret stores. You can find out more about our supported cloud config sources here: Cloud Config Sources

jdbc

190

Reads configuration properties from a specified database table. You can find out more about JDBC config sources here: JDBC Config Sources

ldap

200

Reads configuration properties from a specified LDAP directory. You can find out more about LDAP config sources here: LDAP Config Sources

Converters

In addition to the standard converters specified by the API, Payara Platform’s implementation includes out-of-the-box converters for URL and InetAddress. These have @Priority of 1, the same as the default converters.

Payara Platform Configuration Properties

In addition to the standard configuration properties, Payara Server and Micro provide a number of out-of-the-box config properties you can use in your application to find information about the runtime environment.

Property Description

Property	Description
`payara.instance.type`	The type of the runtime from `DAS`, `INSTANCE`, `EMBEDDED`, `MICRO`
`payara.instance.name`	The name of the instance e.g. `server`
`payara.instance.root`	The directory which is the root of the instance installation
`payara.domain.name`	The name of the Payara domain
`payara.domain.installroot`	The directory which is the root of the Payara software installation
`payara.config.dir`	The directory in which the server’s configuration files reside
`payara.instance.starttime`	The start time of the server in `System.currentTimeMillis`
`payara.instance.config.name`	The name of the configuration this server is using
`payara.instance.admin.port`	The administration port number of this instance
`payara.instance.admin.host`	The host IP address which the admin listener is listening on
`payara.instance.http.port`	The HTTP port for http-listener
`payara.instance.http.address`	The IP address the http listener is listening on
`payara.instance.http.enabled`	Whether the http listener is enabled
`payara.instance.https.port`	The HTTP port for https-listener
`payara.instance.https.address`	The IP address the https listener is listening on
`payara.instance.https.enabled`	Whether the https listener is enabled

payara.instance.type

The type of the runtime from DAS, INSTANCE, EMBEDDED, MICRO

payara.instance.name

The name of the instance e.g. server

payara.instance.root

The directory which is the root of the instance installation

payara.domain.name

The name of the Payara domain

payara.domain.installroot

The directory which is the root of the Payara software installation

payara.config.dir

The directory in which the server’s configuration files reside

payara.instance.starttime

The start time of the server in System.currentTimeMillis

payara.instance.config.name

The name of the configuration this server is using

payara.instance.admin.port

The administration port number of this instance

payara.instance.admin.host

The host IP address which the admin listener is listening on

payara.instance.http.port

The HTTP port for http-listener

payara.instance.http.address

The IP address the http listener is listening on

payara.instance.http.enabled

Whether the http listener is enabled

payara.instance.https.port

The HTTP port for https-listener

payara.instance.https.address

The IP address the https listener is listening on

payara.instance.https.enabled

Whether the https listener is enabled

Config Ordinal Configuration

Configuration variables ordinal values can be configured by using Admin Console or via the Asadmin CLI.

Using the Admin Console

To configure the ordinal value in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Config → Ordinal:

Set Config Ordinal

Using Asadmin Commands

A --source value of jndi is not supported for these asadmin commands yet. The JNDI ConfigSource does exist and is usable from the Config API, though.

`set-config-ordinal`

Usage: asadmin> set-config-ordinal --ordinal=<integer.value> --source=domain|config|server|application|module|cluster
Aim: Provides a way to set the ordinal for a given config source. Where multiple configuration properties exist, the property from a source with a higher ordinal number is preferred.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`ordinal`	The value of the ordinal to set. This must be a number greater than 1. A lower number ordinal means lower order of precedence.	-	yes
`source`	The value of the source to change. Must be one of: `domain`, `config`, `server`, `application`, `module`, `cluster`	-	yes
`target`	The target Payara config to apply the change to	server (the DAS)	no

ordinal

The value of the ordinal to set. This must be a number greater than 1. A lower number ordinal means lower order of precedence.

yes

source

The value of the source to change. Must be one of: domain, config, server, application, module, cluster

yes

target

The target Payara config to apply the change to

server (the DAS)

Example

asadmin> set-config-ordinal --ordinal=600 --source=application

`get-config-ordinal`

Usage: asadmin> get-config-ordinal --source=domain|config|server|application|module|cluster
Aim: Returns the ordinal value for the given ConfigSource type.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`source`	The ConfigSource to get the ordinal for. Must be one of: `domain`, `config`, `server`, `application`, `module`, `cluster`	-	yes

source

The ConfigSource to get the ordinal for. Must be one of: domain, config, server, application, module, cluster

yes

Example

asadmin> get-config-ordinal --source=cluster

Config Property Configuration

Configuration properties can be configured by using Admin Console or Asadmin commands.

Using the Admin Console

To configure the property in the Admin Console, go to Configuration → [instance-configuration (like server-config)] → MicroProfile → Config → Property:

Set Config Property

Using Asadmin Commands

`set-config-property`

Usage: asadmin> set-config-property --propertyName=<property.name> --propertyValue= <property.val> --source=domain|config|server|application|module|cluster --sourceName=<source.name> --moduleName=<module.name> --target=<target[default:server]>
Aim: Sets the given property name and value in one of the built-in config sources. The source is specified with --source and, where there is ambiguity, the --sourceName and --moduleName options can be used. For example, where the source is server, the --sourceName can be used to specify the name of the server where the config property is to be stored.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`propertyName`	The name of the configuration property to set	-	yes
`propertyValue`	The value of the configuration property to set	-	yes
`source`	The ConfigSource where the property is to be stored	-	yes
`sourceName`	The name of the ConfigSource when there may be ambiguity, for example a ConfigSource of type `application` must specify the name of the application. This property is required for sources of type: `config`, `server`, `application` or `module`	-	no
`moduleName`	The name of the module when the ConfigSource is of type `module`. When this is specified, the `sourceName` parameter must be provided and must have the name of the application where the module is deployed.	-	no
`target`	The target configuration where the command should be run	server (the DAS)	no

propertyName

The name of the configuration property to set

yes

propertyValue

The value of the configuration property to set

yes

source

The ConfigSource where the property is to be stored

yes

sourceName

The name of the ConfigSource when there may be ambiguity, for example a ConfigSource of type application must specify the name of the application. This property is required for sources of type: config, server, application or module

moduleName

The name of the module when the ConfigSource is of type module. When this is specified, the sourceName parameter must be provided and must have the name of the application where the module is deployed.

target

The target configuration where the command should be run

server (the DAS)

Example

asadmin> set-config-property
    --propertyName=JMSBrokerURL
    --propertyValue=my.jms.hostname
    --source=module
    --sourceName=myApplication
    --moduleName=myModule
    --target=myAppCluster

`delete-config-property`

Usage: asadmin> delete-config-property --propertyName=<property.name> --source=domain|config|server|application|module|cluster --sourceName=<source.name> --moduleName=<module.name> --target=<target[default:server]>
Aim: Deletes the given property name in one of the built-in config sources so that the property no longer exists. The source is specified with --source and, where there is ambiguity, the --sourceName and --moduleName options can be used. For example, where the source is server, the --sourceName can be used to specify the name of the server where the config property is to be stored. moduleName should only be used when the --source=module.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`propertyName`	The name of the configuration property to delete	-	yes
`source`	The ConfigSource where the property is stored	-	yes
`sourceName`	The name of the ConfigSource when there may be ambiguity, for example a `ConfigSource` of type `application` must specify the name of the application. This property is required for sources of type: `config`, `server`, `application` or `module`	-	no
`moduleName`	The name of the module when the ConfigSource is of type `module`. When this is specified, the `sourceName` parameter must be provided and must have the name of the application where the module is deployed.	-	no
`target`	The target configuration where the command should be run	server (the DAS)	no

propertyName

The name of the configuration property to delete

yes

source

The ConfigSource where the property is stored

yes

sourceName

The name of the ConfigSource when there may be ambiguity, for example a ConfigSource of type application must specify the name of the application. This property is required for sources of type: config, server, application or module

moduleName

target

The target configuration where the command should be run

server (the DAS)

Example

asadmin> delete-config-property
    --propertyName=JMSBrokerURL
    --source=module
    --sourceName=myApplication
    --moduleName=myModule
    --target=myAppCluster

`get-config-property`

Usage: asadmin> get-config-property --propertyName=<property.name> --source=domain|config|server|application|module|cluster --sourceName=<source.name> --moduleName=<module.name> --target=<target[default:server]>
Aim: Gets the value for the given property name in one of the built-in config sources. The source is specified with --source and, where there is ambiguity, the --sourceName and --moduleName options can be used. For example, where the source is server, the --sourceName can be used to specify the name of the server where the config property is to be stored.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`propertyName`	The name of the configuration property to get	-	yes
`source`	The ConfigSource where the property is stored	-	yes
`sourceName`	The name of the ConfigSource when there may be ambiguity, for example a `ConfigSource` of type `application` must specify the name of the application. This property is required for sources of type: `config`, `server`, `application` or `module`	-	no
`moduleName`	The name of the module when the ConfigSource is of type `module`. When this is specified, the `sourceName` parameter must be provided and must have the name of the application where the module is deployed.	-	no
`target`	The target configuration where the command should be run	server (the DAS)	no

propertyName

The name of the configuration property to get

yes

source

The ConfigSource where the property is stored

yes

sourceName

moduleName

target

The target configuration where the command should be run

server (the DAS)

Example

asadmin> get-config-property
    --propertyName=JMSBrokerURL
    --source=module
    --sourceName=myApplication
    --moduleName=myModule
    --target=myAppCluster

Config Cache Duration

The cache duration can be configured by using Asadmin commands. By default properties have a TTL (time to live) of 60 seconds. That means each individual property does not change for 60 seconds since it has been resolved before. Therefore it can take up to 60 seconds for changes made visible by a config source to become effective.

If properties were not resolved recently, the change can become visible faster than the cache duration or even immediately because some time already passed since they had been last resolved and cached.

Using Asadmin Commands

`set-config-cache`

Usage: asadmin> set-config-cache --duration=<duration.in.second> --target=<target[default:server]>
Aim: Sets the cache duration for the target instance(s). Any duration equal to or below zero disables the caching of MP config properties.

Command Options

Option Description Default Mandatory

Option	Description	Default	Mandatory
`duration`	Duration in seconds properties are cached	60	yes
`target`	The target configuration where the command should be run	server (the DAS)	no

duration

Duration in seconds properties are cached

yes

target

The target configuration where the command should be run

server (the DAS)

Example

Disable caching:

asadmin> set-config-cache
    --duration=0
    --target=myAppCluster

Set cache TTL (time to live) for properties to 30 seconds.

asadmin> set-config-cache
    --duration=30
    --target=myAppCluster