Guide

Build Highly Configurable

Applications on Payara Server
Using the Eclipse MicroProfile
Config API

The Payara® Platform - Production-Ready,

Cloud Native and Aggressively Compatible.
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Introduction
The goal of this guide is to help you as a Java developer make the most of the Eclipse MicroProfile
(EMP) Config API using the Payara Platform. The guide starts by looking at what Eclipse MicroProfile is,
the individual APIs that make up the EMP and finally takes a deeper look at the Config API. By the end
of this guide, you will be able to integrate EMP into your application and learn how to build highly
configurable applications on the Payara Platform.

What Do I Need to Use this Guide?

You will need a copy of the latest Payara Server full stream distribution to follow along this guide.
The sample code is built using Apache Maven and as such, any IDE that supports Maven is good
enough. You should also have a minimum of Java SE 8 installed on your computer.

For a video series about building highly configurable applications on Payara Server with MicroProfile
Config API, check out our YouTube Playlist:

https://www.youtube.com/playlist?list=PLFMhxiCgmMR8-3xnjEw4sbI_Xq-HVPii9

What is MicroProfile?
MicroProfile is an Eclipse Foundation led, community driven initiative. It’s a collection of abstract
specs that form a complete solution to developing cloud native, Java enterprise microservices.
The goal is to create a set of APIs that removes you from their implementations so you can create
highly portable microservices across vendors.

MicroProfile is built on top of Java EE 8 and as such borrows from the Java EE programming model.
The current release is version 3.0 and consists of 12 different specifications as shown below.
As abstract specifications, the various implementations are free to implement the base specs and
add custom features on top.

1
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

The Payara Platform is one of the popular implementations of the MicroProfile spec and it adds quite
a number of custom features on top of the base specs. This guide will walk you through the Payara
Platform implementation of the MicroProfile Config API.

Getting Started with MicroProfile

To get started with the MicroProfile API, you need to include it as a dependency in your project as
shown below.

With the MicroProfile API dependency in place, you have access to all the APIs of the project. In our
case, Payara Server will provide the implementation for us.

2
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

What is MicroProfile Config?

MicroProfile Config is an API that aims at simplifying application configuration in different
environments and from different sources without the need to redeploy or restart the application. An
application might need different port numbers for different requests, or certain features need to be
switched on or off based on certain configurations. The Config API aims at unifying and simplifying
application configurations such that it provides an aggregated view of the various configuration options.

Why MicroProfile Config?

There are 4 compelling reasons to give the MP Config API a try. They are:

Dynamic Config Values

The benefit of abstracting config values from an application is the ability to change the config values
without necessarily redeploying the application. With MP Config, you can have your updated config
values picked up in your application without having to redeploy.

Powerful Abstractions
The core of the MP Config API is the ConfigSource object. It’s an abstraction of any source of
configuration values. Given the almost infinite options available for storing config values, it’s good
to have the Config API abstract all config sources away into a config source that can be queried.
The developer can then get a set of well-defined methods to interact with the config source object.

3
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Easy DevOps
For every application, different data is required for development, testing and production. For
example, let’s say we are developing an e-commerce app using microservices. One of these services -
OrderService - needs to access data about clients from AccountService. AccountService is configured
to give three kinds of data - dev, testing, production - depending on the credentials one authenticates
with it. In developing OrderService, we’d want to use different credentials for the appropriate stage.
We can easily do that with the Config API. We set the three credentials in three different Config
sources (more about this later) with the same keys. Because the Config sources are placed in a
hierarchical order based on their ordinal values (don’t worry if you’re unfamiliar, we discuss this
below), we can put dev credentials in the lowest priority source with production being in the highest
priority source as shown below.

From the above image, we have the same values set in three different places. The source with
the highest number takes the top of the hierarchy. So in development, we could only have
the mp-config.properties file, in testing an ENVAR and in production, Systems Properties. Through
it all, your code would stay the same, but the values you get from the Config runtime will be different
depending on the config sources available. This can greatly enhance your software development
operations.

Good Base and Powerful Extensions

The MP Config consists of a good base that alone can get you quite far. But the goal of the entire
MP project is to encourage the community to innovate around it. And that is what you get with the
MP Config API. The Payara Platform has some very intuitive extensions1 built on the Config API that

1
https://docs.payara.fish/documentation/microprofile/config.html

4
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

completes it. For example, one of the config sources supported by Payara Server is Directory. In this
case, you define a directory in the server admin console as ConfigSource and any file in the directory
become a key value pair with the name of the file acting as key and content acting as value.

The simplest Config API use is shown below

Lines 1 and 2 use the @Inject and @ConfigProperty annotations on the String propertySource.
The @ConfigProperty2 annotation is from the MicroProfile Config API. It takes two parameters - name
and defaultValue. The name refers to the name or key to be used to identify the value from a given
source. In this case, the name is my.property.source, and the config runtime is going to iterate through
all available config sources in search of a key value pair that has the key set to my.property.source.

In this case, we have the value set in the default microprofile-config.properties file. This file is a nor-
mal text file that you put in the META-INF folder. Within it you create key value pairs as show below:

Line 1 is an example comment in the properties file. Lines 3 to 6 are all key value pairs where the
keys will be passed to the name parameter of @ConfigProperty to get the value.

For the developer, you have all the config sources automatically aggregated and iterated on your
behalf by the Config runtime. This is especially powerful in a microservices environment where you
will need to configure different things for different purposes.

2
https://is.gd/SuSzFW

5
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

The Config API is made up of 3 parts - the config source, converters and config value as shown below.

The Config Source

The config source is an abstraction over the source of a configuration. This source of configuration
could be a database, a properties file, system properties, environment variables and so on. The Config
API abstracts any source from which configuration values might be read into a ConfigSource3. There
cannot be a configuration without a config source. The API defines 3 config sources out of the box
from which it will search for configuration values by default. These 3 sources also have their default
ordinal values defined.

An ordinal value determines the position of a given config source in a hierarchy. It defines which
config source to take precedent in the event of a conflict in terms of config values. The config source
with a higher ordinal value has a higher precedent over a config source with a lower ordinal value.

As shown in the image above, System Properties has an ordinal value of 400, giving it the highest
priority over environment variables with an ordinal of 300 and the microprofile-config.properties
file with an ordinal of 100.

3
https://is.gd/BCgeHU

6
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

The Payara Built in Config Sources

Payara Server also comes with its own built-in config sources as shown in the image below:

From this image you can see some of the different config sources supported by Payara Server, namely
Domain, Application, Config, Module and Server. You can conveniently set key value pairs to any
of these sources right from the server admin interface as shown in the above image. Let’s briefly
examine what these sources are.

Domain - The Domain config source stores key value pairs in the domain.xml file and makes same
available for all applications deployed in that domain.

Application - This source constrains stored key value pairs to a selected application. Whatever key
value pairs will only be visible to the chosen application of all server instances.

Config - This source stores key value pairs at the level of a named configuration in the domain.xml
file. There are two named configurations that you can choose from the Payara Server admin - default
config and server config.

Module - This source stores key value pairs at the level of individual modules of an application.
Whatever key value you store in a module will only be available to the module alone.

7
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Server - This source stores key value pairs at the level of the named server in the domain.xml file.
Key value pairs will only be available on the named server instance.

You can set the ordinal values for all these config sources as shown below

As you can see, the Payara Server admin console is a convenient yet powerful tool you can use to
configure your MicroProfile Config key value pairs in a very fine grained manner. Aside from the
built-in config sources that comes with Payara Server, you can also create your own custom Config
Sources quite easily.

In addition to the above sources, the Payara Platform also supports the following config sources:

Directory - This source is perhaps the most powerful of all the sources. It treats file names as keys
and file content as value. So let’s say you configure a given directory such as /opt/my/config/source,
you can get the content of any file in this directory as config value when you pass in the file name as
key. For example /opt/my/config/source/api-key.txt is a file in the configured directory that contains
the key to an external API. We could easily get the value thus:

8
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Lines 2 uses the name of the file as the name of the key for our config value retrieval. The value of
the file will be injected into the String apiKey. The directory source can also be used to read secret
files in Kubernetes4. You can configure the path to the directory in the Payara Server admin console
as shown below.

4
https://kubernetes.io/docs/concepts/configuration/secret/#using-secrets-as-files-from-a-pod

9
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Password - This source stores config values in the Payara Server password alias store5. The password
alias you set becomes the key to the config runtime and the plain text password will be injected as
the config value. You can create password aliases in the Payara Server admin console as show below.

Once you create a password alias, you can use it as key to @ConfigProperty annotation as shown below.

Line 2 has the String ‘my-alias’ set as the name of the key to @ConfigProperty. That string is a pass-
word alias set using the Payara Server admin console. Running the above code, the config runtime
will inject the plain text, decrypted password into the field passwordAlias. Using the password config
source is another great way to deal with passwords and secrets on the Payara Platform through the
Config API. Password alias is available to all servers instances in a domain.

5
https://payara.gitbooks.io/payara-server/content/documentation/payara-server/password-aliases/

10
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

JNDI - This source stores config values in the JNDI6 tree and uses the dotted name path of the JNDI
tree. You can create custom JNDI resources using the Payara Server admin console as shown below.

Cluster - This config source uses the Payara Server Domain Data Grid (DDG7) to store config values as
key value pairs in memory. The config values stored in the DDG are available to all server instances
within a given Payara Domain.

6
https://www.oracle.com/technetwork/java/overview-142035.html
7
https://docs.payara.fish/documentation/payara-server/hazelcast/

11
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Custom Config Sources

You can also create custom config sources by implementing the org.eclipse.microprofile.config.spi.
ConfigSource interface as shown below.

Line 1 declares a class called MyCustomConfigSource that implements ConfigSource. The ConfigSource
interface has 5 methods, 2 of which have default implementations. Line 5 implements the getProp-
erties method. This method returns a Map<String, String> that is expected to contain all your key
value pairs. Line 10 implements the getValue method, which takes a String and returns a String.
This method is what will be queried on your behalf for value when you pass the key. Line 15 finally
implements the getName method which is expected to return the name of this ConfigSource.

One of the default methods in the ConfigSource interface is getOrdinal, which conditionally returns
an ordinal of 100. Remember an ordinal value determines the place of a config source in a hierarchy?
The Config API gives you the option of setting the ordinal of your custom config source - or even any
of the built in ones - by including a key value pair with the key set to config_ordinal and the value
set to an integer value.

12
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

You can implement your custom config source to fetch data from the database using JDBC as in the
example below.

Line 1 in the above code declares a class, MyDBConfigSource that implements ConfigSource. This time,
however, we implement a simple database retrieval of config values into the map PROPERTIES_MAP
declared on line 4. Lines 16 to 27 use the JDBC API to retrieve values from a table called MPCONFIG.
These values are then stored into the PROPERTIES_MAP which is finally returned on line 32. Line 36
implements the getValue method which simply checks whether the PROPERTIES_MAP contains the
key passed and returns the value or null if not. Line 44 implements the getOrdinal method. We want
this config source to have a custom config ordinal of 195 (could be any number though). This is a basic
example of implementing a database custom config source. Of course, the table would need to be pop-
ulated with values from some other source. But in this example, we assume that has already been done.

13
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

You are free to implement the ConfigSource interface any way you see fit. What matters is that once
it’s registered as a ConfigSource, it should be capable of returning values as long as a key match in
any of the configured config sources.

Once you’ve implemented the ConfigSource interface, you will need to register it. You do so by reg-
istering it with the fully qualified class name in the file /META-INF/services/org.eclipse.microprofile.
config.spi.ConfigSource as shown below

In the above image, we have registered our custom ConfigSource implementation by including the
fully qualified class name in the file. That is all you need to do to register a custom ConfigSource.

Converters
A converter is a mechanism for converting config values from the default String to their respective
Java types. The Config API provides the following converters with default Priority of 1 out of the box.

• boolean and java.lang.Boolean , values for true (case insensitive) “true”, “1”, “YES”, “Y”
“ON”. Any other value will be interpreted as false.
• byte and java.lang.Byte
• short and java.lang.Short
• int and java.lang.Integer

14
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

• long and java.lang.Long

• float and java.lang.Float, a dot ‘.’ is used to separate the fractional digits
• double and java.lang.Double, a dot ‘.’ is used to separate the fractional digits
• char and java.lang.Character
• java.lang.Class based on the result of Class.forName

For situations where no default or custom converter is available for a given Java type, a dynamic
converter is created automatically if:

• The target type has a public static T of(String) method, or

• The target type has a public static T valueOf(String) method, or
• The target type has a public Constructor with a String parameter, or
• The target type has a public static T parse(CharSequence) method

Besides the above, you can also create custom converters by implementing the org.eclipse.micro-
profile.config.spi.Converter interface as shown below

15
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

Line 1 declares a Java class called MyCustomConfigConverter that implements the Converter inter-
face. In the above example, we are converting from String to our custom Java type MyBoringPojo,
which we realize in the convert method of the interface. The MyBoringPojo bean is reproduced below.

After implementing the Converter interface, we need to register it. To do so, we include the fully
qualified class name of the implementation in the file /META-INF/services/org.eclipse.microprofile.
config.spi.Converter as shown below.

If your custom converter has a target type for which a default converter exists, your custom converter
will take precedent. You can also set the Priority of your custom converter using the @javax.annotation.
Priority annotation. A custom converter without an explicit @javax.annotation. Priority annotation
defaults to a priority of 100.

16
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

The Payara Platform provides built-in custom converters for URL and InetAddress with priority
of 1. This means you can directly request for URL based values without needing to write custom
converters. For example:

Line 1 uses the @Inject annotation in addition to the @ConfigProperty annotation to inject a URL
type into the field url. The value is derived from the properties file as shown below

This conversion to the Java type URL is being carried out by the Payara Server implementation of
the MicroProfile Config.

Config Value
The config value is the value returned by the Config API after querying the respective config sources
using the key we pass. There are 2 primary ways of requesting for config values. The first - and what
we’ve been seeing so far - is through injection. You annotate a given field with @javax.inject.Inject
and @org.eclipse.microprofile.config.inject.ConfigProperty.

The ConfigProperty annotation takes two parameters. The first is name, which is a String of the key to
the value you want. The second parameter is defaultValue, which is a value you pass to be defaulted
to in case the Config runtime fails to get a match using the key you pass to the name parameter.

The second means of getting a config value is through the programmatic method as shown below.

Line 1 invokes the getConfig() method on the ConfigProvider class to get an instance of the Config
object. This object has two twin methods for getting values from a config source. Line 2 invokes the
getOptionalValue() method on the Config object returned in the previous line to return an Optional

17
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

type. The type of the Optional object returned is determined from the type passed as the second
parameter to the getOptionalMethod() as shown on line 2. The first parameter is the name or key to
fetch the value with. This comes in handy in situations where you are not sure of the existence of a
given key value pair.

The converters are applied transparently to your config values. So for instance, I could have a field
of type BigDecimal and request for a config value as shown below.

The converters are applied transparently on your behalf. For example, you could make a request
as follows:

Lines 1 and 2 use the @Inject and @ConfigProperty annotations to request for config value for the field
type BigDecimal. Remember in config source where we have this value, in this case the mp-config.
properties file, the type is a simple String as shown below.

Line 1 declares the key value pair for my.very.big.number which we requested earlier. As you can see,
even though what we have in the properties file is a String, a dynamic converter was transparently
created and applied to the value for us, such that we ended up getting a BigDecimal type.

Payara Specific Configuration Properties

The Payara Platform comes with some handy configuration properties that you can use directly
in your applications to get information about the Payara Server instances you are running. These
properties are exposed as keys or names you can pass to the @ConfigProperty to get the needed
info. Some of the important ones are:

• payara.instance.type - This returns to type of the Payara Server runtime, whether a server
instance, embedded or micro.
• payara.domain.name - This returns the Payara domain name
• payara.instance.starttime - The start time of the server in System.currentTimeMillis
• payara.domain.installroot - The root directory in which the Payara Server is installed

18
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

As stated earlier, you can simply get the information using the above keys just as you would your
own config sources. The Payara Platform will take care of the config source for the Payara special
config properties.

Dynamic Config Values

The entire essence of using a config API is to be abstracted away from config sources and to not
necessarily redeploy your application when a config value changes in any of your config sources.
However, all the examples you’ve seen so far have just requested for config values into static fields.

There is a very simple way to get changed config values picked up in your live application without
redeploying or rebooting the server, though. Let’s see how.

Lines 1 and 2 declare the @Inject and @ConfigProperty annotations as usual. This this time around,
however, we field type annotated is the javax.inject.Provider with the type set to String. The Provider,
as the name implies, provides instances of objects. So in this case, it will provide objects of type
String. It has one method, get() which returns the typed instance. So any time you invoke the get()
method, a new String object is returned.

With myDynamicValue, anytime there is a change in any of our config sources that contains the data
with the key my.dynamic.value, we can invoke the get() method to get an instance of the updated
value. It’s that simple. Even though we have set the type of the Provider to String in this example,
you can set the type to just about any valid Java type as long as there is a Config converter available.

This is how easy it is to set up your code to retrieve updated values from your configures config
sources without having to redeploy or restart the server.

The Payara Platform Implements and Adds Features to the MicroProfile API
MicroProfile is a very compelling Eclipse Foundation led community effort aimed at increasing the pace
of innovation in enterprise Java software development. MicroProfile itself is an abstract spec, making
it possible for various vendors to implement the base spec and add other custom features on top.

The Payara Platform8 is a full Java EE (now Jakarta EE) implementation that also implements the
MP API and adds quite a number of features on top of it. This guide took you through the reason for

8
https://www.payara.fish/

19
 Build Highly Configurable Applications on Payara Server
Using the Eclipse MicroProfile Config API

and use of the MP Config API. We saw the various Payara Server custom features available to you
as a developer in addition to what the MP Config API gives you out of the box.

Should you need further support or need further info about using or transitioning your enterprise
Java workload to the Payara Platform, please don’t hesitate to get in touch with us.

Commercial support for the Payara Platform is available and provided directly by Payara’s engineers.

You can also keep in touch with on our social media platforms - Twitter, YouTube, GitHub.

  
[email protected] +44 207 754 0481 www.payara.fish

Payara Services Ltd 2016 All Rights Reserved. Registered in England and Wales; Registration Number 09998946
Registered Office: Malvern Hills Science Park, Geraldine Road, Malvern, United Kingdom, WR14 3SZ

20