onecx-parameters

Installation

If you want to use this extension, you need to add the org.tkit.onecx.quarkus:onecx-parameters extension first to your build file.

For instance, with Maven, add the following dependency to your POM file:

<dependency>
    <groupId>org.tkit.onecx.quarkus</groupId>
    <artifactId>onecx-parameters</artifactId>
    <version>2.0.0</version>
</dependency>

Usage

Parameter client

Assuming you have Parameters running on localhost:8088 you should add the following properties to your application.properties and fill in the values for url.

onecx.parameters.service.client.url=http://localhost:8088/api

Once you have configured the properties, you can start using a Parameters-client.

@ApplicationScoped
public class TestService {

    @Inject
    ParametersService parameters;

    public boolean isTest() {
        return parameters.getValue("key", String.class, "DEFAULT_VALUE");
    }
}

@Parameter

By using the @Parameter annotation there is a shortcut to inject value of the parameter.

@ApplicationScoped
public class TestService {

    @Parameter(name = "param-name-1")
    Instance<Variant> param1;

    @Parameter(name = "param-name-2")
    Instance<String> param2;

    @Parameter(name = "param-name-3")
    Instance<MyCustomJsonModel> param3;

}

@Parameter should only be used with the Instance<?> type.

History

By default, the client will send history of used parameters to the backend. History contains count of usage of the parameter in the interval configure by the onecx.parameters.history.update-schedule property.

Cache

To avoid to many calls the client will use local cache for parameters. To disable the local cache you can use this property onecx.parameters.cache.enabled. The local cache is updated via the scheduler and schedule time is configurable with onecx.parameters.cache.update-schedule property.

You can update cache at start of the application onecx.parameters.cache.update-at-start and control if the application should not start if there is error to update cache at the start onecx.parameters.cache.failed-at-start.

Multi-tenancy

To disable or enable multi-tenancy you can use this property onecx.parameters.tenant.enabled. To resolve the tenant the ApplicationContext will be used.

For background job like cache update you need to implement @org.tkit.onecx.quarkus.parameter.tenant.TenantResolver and create ApplicationContext for each cache update.

Metrics

Micrometer metrics are support by the client library. By default, there are

  • parameter usage count onecx_parameters_item_total

  • update parameters background job counter with response codes onecx_parameters_update_total

  • send history background job counter with response codes onecx_parameters_history_total

Value configuration priority

You retrieve either the value from the…​

  1. Backend parameter service.

  2. Project application.properties See: Quarkus configuration reference guide

  3. Source code default value.

in this respective order.

Configuration

Configuration property fixed at build time - All other configuration properties are overridable at runtime

Configuration property

Type

Default

onecx.parameters.build.metrics.enabled

Whether a metrics is enabled in case the micrometer or micro-profile metrics extension is present.

Environment variable: ONECX_PARAMETERS_BUILD_METRICS_ENABLED

boolean

true

onecx.parameters.service.client.url

Parameters client URL configuration. This property is alias for rest-client generated configuration property quarkus.rest-client.onecx_parameter.url

Environment variable: ONECX_PARAMETERS_SERVICE_CLIENT_URL

string

http://onecx-parameter-svc:8080

onecx.parameters.service.client.v1

Parameters client version V1. Client v1 is deprecated and will be removed at some point in the future.

Environment variable: ONECX_PARAMETERS_SERVICE_CLIENT_V1

boolean

false

onecx.parameters.enabled

If set to true, the application will attempt to look up the configuration from Parameter service

Environment variable: ONECX_PARAMETERS_ENABLED

boolean

true

onecx.parameters.throw-update-exception

Throw update exception when parameters are loaded from backend.

Environment variable: ONECX_PARAMETERS_THROW_UPDATE_EXCEPTION

boolean

false

onecx.parameters.cache.enabled

Enable or disable client cache.

Environment variable: ONECX_PARAMETERS_CACHE_ENABLED

boolean

true

onecx.parameters.cache.update-schedule

Update parameter scheduler configuration in milliseconds.

Environment variable: ONECX_PARAMETERS_CACHE_UPDATE_SCHEDULE

long

900000

onecx.parameters.cache.update-at-start

Pull parameters during start phase

Environment variable: ONECX_PARAMETERS_CACHE_UPDATE_AT_START

boolean

false

onecx.parameters.cache.failed-at-start

Does not start the microservices if an error occurs while retrieving the parameters during the startup phase.

Environment variable: ONECX_PARAMETERS_CACHE_FAILED_AT_START

boolean

false

onecx.parameters.product-name

Product name.

Environment variable: ONECX_PARAMETERS_PRODUCT_NAME

string

required

onecx.parameters.application-id

Parameters application ID.

Environment variable: ONECX_PARAMETERS_APPLICATION_ID

string

${quarkus.application.name}

onecx.parameters.instance-id

Instance ID

Environment variable: ONECX_PARAMETERS_INSTANCE_ID

string

onecx.parameters.history.enabled

If set to true, the application will send history information to the parameter management.

Environment variable: ONECX_PARAMETERS_HISTORY_ENABLED

boolean

true

onecx.parameters.history.update-schedule

Update history scheduler configuration in milliseconds.

Environment variable: ONECX_PARAMETERS_HISTORY_UPDATE_SCHEDULE

long

900000

onecx.parameters.items."parameters"

Parameters configuration

Environment variable: ONECX_PARAMETERS_ITEMS__PARAMETERS_

Map<String,String>

onecx.parameters.tenant.enabled

Enable or disable multi-tenancy.

Environment variable: ONECX_PARAMETERS_TENANT_ENABLED

boolean

true