Platform Framework
R24 AMR | Min(s) read

Configuration Management

The purpose of the configuration web application is to manage properties and configurations stored in the database. It is protected by the basic authentication mechanism. To create the user with required privileges, see the « basic authentication » section matching your application server provider. This section provides details about the configuration properties and management of REST APIs for various aspects of property usage.

It allows interaction with TAFJ_CONFIGURATION table through the ConfigurationService EJB which is secured. It is made of two components:

Any change made to the runtime configuration requires an application re-start.

Configuration Service

The configuration service deals with all configuration operations:

  • Table creation
  • Configuration creation
  • Configuration copy from properties file or from database
  • Configuration loading
  • Configuration changes—properties change, addition and removal

If the configuration table does not exist on first configuration service invocation, it will be created automatically. If the requested configuration ID (-Dtafj.configuration) does not exist, it will be created with the system default values. It is also possible to make a configuration copy by using the REST API.

These configuration services provide views and entry points to the configuration table but do not reflect the state of the current runtime properties, which were loaded at application startup. 

Administration Console Runtime Properties

The administration console gives access to the runtime configuration. It can be accessed using the following URLs or from the main TAFJEE page under the configuration section.

http://localhost:8080/TAFJConfiguration/dashboard.xhtml

http://localhost:8080/TAFJEE/index.html

There is a reminder in the console header stating that it might not reflect the current runtime configuration.

The admin console provides only a view of the database entries. These entries may not be used by the runtime configuration in case of property overload, which means. System property -Dtemn.tafj.property=valueA takes precedence over temn.tafj.property=valueB as per its table definition.

In case of properties change without application restart, the database properties will not be synced with the current runtime properties.

The properties table header, gives information about the configuration ID and its version. The version is a timestamp, based on the last modification done to a property part of the configuration. The version is stored in the database in tafj.configuration.version internal property (not visible in the dashboard).

There is a main toolbar at configuration level, and one per property.

The main toolbar has three options:

You can use this option to apply changes made to configuration to database.

This option is disabled if there is no pending changes and requires confirmation.

In case of pending change the icon is enables and turned into a different color.

You can use this option to revert pending changes made to configuration or to synchronise the view with the current database table state.

A confirmation is required before discarding the pending changes.

You can use this option to create a new property in the configuration.

A confirmation is required to add the new property to the pending changes. A validation is done to ensure property key uniqueness within a configuration.

You need to define the key but can leave the value empty. However, properties with empty values are not loaded by the runtime.

When a property is modified or added, it is displayed in a different color to highlight that it is a pending change until modifications are applied to the database.

The property toolbar has three options:

You can use this option to display information about the property when available.

You can use this option to change the property value and the key is immutable.

A confirmation is required to add the modification to the pending changes.

You can use this option to remove a property.

A confirmation is required before adding the removed property from the pending changes.

The changes will be pending and not visible at the database level until Save modifications is executed.

Since changes are applied, the configuration version will be updated to the timestamp of the last modified property available in the database for this configuration ID. That is, new.property is the last property added to the configuration, hence the configuration version matches this property last modified date.

The system can load multiple configurations in development or test environments. This mode is useful to define a base configuration which could be overridden by specific configurations for some parameters, if any.

A multi-configuration is a coma separated list of configuration IDs ordered by priority, with the first one with the highest priority.

-Dtafj.configuration= specific,base

In case of multi-configuration, the administration console is modified to include a new column in the properties table to display the configuration ID to which the property is belongs to.

The following example shows a multi-configuration defined through the -Dtafj.configuration=TAFJTestMSSQLOverride,TAFJTestMSSQL parameter.

The TAFJTestMSSQLOverride defines the temn.tafj.default.appserver.name property, which take precedence at runtime on the same property defined in TAFJTestMSSQL.

When adding a new property, you need to select the target configuration ID from the dropdown list.

This configuration ID is immutable like the property key. The composite key (ConfigurationId-key) is unique to each property.

REST API – Properties and Configuration Management

When using the REST API, the changes are directly applied to the database. There is no pending changes state and no confirmation is required upon properties modification.

This service gives access only to the current configuration defined through -Dtafj.configuration system property. The base service URL is /TAFJConfiguration/resources/properties. The commands for various functionalities pertaining to the current properties are as follows:

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/properties \

@GET
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Get the current configuration set of properties, key value pair.
     * 
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when found.
     */

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/properties/temn.tafj.runtime.enable.logger.api \

@GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("{key}")
    /**
     * Get the current property value for the given key in current configuration.
     * 
     * @param key
     *            the property key
     * @return JsonObject {"key":key,"value":value}, Status OK - 200 when found,
     *         NOT_FOUND 404 when not property doesn't exist.
     */

curl --request DELETE \
  --url http://localhost:8080/TAFJConfiguration/resources/properties/temn.tafj.runtime.enable.logger.api \

@DELETE
    @Path("{key}")
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Remove a property from the current configuration for a given key.
     * 
     * @param key
     *            the property key, not blank
     * @return Response 204 - NO_CONTENT when successfully removed.
     *         INTERNAL_SERVER_ERROR - 500 for invalid key. NOT_FOUND 404 when
     *         not property doesn't exist.
     */ 

curl --request PUT \
  --url 		 \
  --header 'authorization: Basic dGFmajp0YWZqITIwMTY=' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'postman-token: 402c9e43-4911-fa4c-4f33-1a51994b07b6' \
  --data 'key=temn.tafj.runtime.enable.logger.api&value=false'

@PUT
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Add a new property or modify an existing property value for a given key in
     * current configuration.
     * @param key
     *            the property key, not blank
     * @param value
     *            the property value, can be blank
     * @return JsonObject {"key":key,"value":value}- Status OK - 200 when
     *         successfully added or modified. INTERNAL_SERVER_ERROR - 500 for
     *         invalid key.
     */

This service gives access to any existing configuration and allows creating new configurations by copy using the URL /TAFJConfiguration/resources/configuration. The commands for various functionalities pertaining to any configuration are as follows:

Dtafj.home must be defined as a system property and the properties file identified by its name must exist under tafj.home/conf.

curl --request POST \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/filecopy \
  --header 'authorization: Basic dGFmajp0YWZqITIwMTY=' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'postman-token: 24124927-4576-7223-684c-44c4812660c9' \
  --data 'source=TAFJTestOracle&destination=fromTAFJTestOracle'

@POST
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/filecopy")
    /**
     * Create a new JDBC configuration by cloning the provided properties file
     * identified by its name.
     * 
     * @param source
     *            the properties file name which must be present under
     *            tafj.home/conf.
     * @param destination
     *            the configuration ID which will be used to store the JDBC
     *            configuration.
     * 
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when source is found and successfully copied to
     *         destination. INTERNAL_SERVER_ERROR - 500 when properties source
     *         doesn't exist or is empty.
     */

The source configuration identified by its configuration id, must exist in the configuration table.

curl --request POST \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/databasecopy \
  --header 'authorization: Basic dGFmajp0YWZqITIwMTY=' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'postman-token: 24124927-4576-7223-684c-44c4812660c9' \
  --data 'source=fromTAFJTestOracle'&destination=newFromTAFJTestOracle'

@POST
    @Produces(MediaType.APPLICATION_JSON)
    @Path("/databasecopy")
    /**
     * Create a new JDBC configuration by cloning the provided properties file
     * identified by its name.
     * 
     * @param source
     *            the properties file name which must be present under
     *            tafj.home/conf.
     * @param destination
     *            the configuration ID which will be used to store the JDBC
     *            configuration.
     * 
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when source is found and successfully copied to
     *         destination. INTERNAL_SERVER_ERROR - 500 when properties source
     *         doesn't exist or is empty.
     */    

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/TAFJTestMSSQL \

    @GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("{configurationid}")
    /**
     * Get the configuration for the given configuration id, set of properties,
     * key value pair.
     * 
     * @param configurationid
     *            the configuration id
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when found, NOT_FOUND 404 when configuration
     *         doesn't exist.
     */

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/ TAFJTestMSSQL/temn.tafj.runtime.enable.logger.api \

@GET
    @Produces(MediaType.APPLICATION_JSON)
    @Path("{configurationid}/{key}")
    /**
     * Get the property value for the given configuration id and key.
     * 
     * @param configurationid
     *            the configuration id
     * @param key
     *            the property key
     * @return JsonObject {"key":key,"value":value}, Status OK - 200 when found,
     *         NOT_FOUND 404 when not property doesn't exist.
     */

curl --request DELETE \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/TAFJTestMSSQL/temn.tafj.runtime.enable.logger.api \

@DELETE
    @Path("{configurationid}/{key}")
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Remove a property for the given configuration and key.
     * 
     * @param configurationid
     *            the configuration id
     * @param key
     *            the property key, not blank
     * @return Response 204 - NO_CONTENT when successfully removed.
     *         INTERNAL_SERVER_ERROR - 500 for invalid key. NOT_FOUND 404 when
     *         not property doesn't exist.
     */

PUT http://localhost:8080/TAFJConfiguration/resources/configuration/a.configuration.id with key and value parameters.

curl --request PUT \
  --url http://localhost:8080/TAFJConfiguration/resources/configuration/TAFJTestMSSQL / \
  --header 'authorization: Basic dGFmajp0YWZqITIwMTY=' \
  --header 'cache-control: no-cache' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --header 'postman-token: 402c9e43-4911-fa4c-4f33-1a51994b07b6' \
  --data 'key=temn.tafj.runtime.enable.logger.api&value=false'

@PUT
    @Produces(MediaType.APPLICATION_JSON)
    @Path("{configurationid}")
    /**
     * Add a new property or modify an existing property value to the given
     * configuration id for a given key.
     * 
     * @param configurationid
     *            the configuration id
     * @param key
     *            the property key, not blank
     * @param value
     *            the property value, can be blank
     * @return JsonObject {"key":key,"value":value}- Status OK - 200 when
     *         successfully added or modified. INTERNAL_SERVER_ERROR - 500 for
     *         invalid key.
     */

For multi-configuration, Dtafj.configuration=TAFJTestMSSQLOverride,TAFJTestMSSQL

The same services are available with the configuration ID added as a prefix to the property key to make a composite key.

CompositeKey=ConfigurationId-key 

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/properties \

Response: 

{
    "configurationId": "TAFJTestMSSQLOverride,TAFJTestMSSQL",
    "properties": [
        {
            "key": "TAFJTestMSSQL-temn.tafj.runtime.ud.encoding",
            "value": "UTF-8"
        },
….
{
            "key": "TAFJTestMSSQLOverride-temn.tafj.default.appserver.name",
            "value": "WEBLO"
        },

You need to use the composite key to access, modify or delete a property from a multi-configuration.

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/properties/TAFJTestMSSQLOverride-temn.tafj.default.appserver.name \

Response: 

{
    "key": "TAFJTestMSSQLOverride-temn.tafj.default.appserver.name",
    "value": "WEBLO"
}

curl --request PUT \
  --url http://localhost:8080/TAFJConfiguration/resources/properties \
  --data 'key=TAFJTestMSSQLOverride-temn.tafj.default.appserver.name&value=WEBLO'

Response: 

{
    "key": "TAFJTestMSSQLOverride-temn.tafj.default.appserver.name",
    "value": "WEBLO"
}

curl --request DELETE \
  --url http://localhost:8080/TAFJConfiguration/resources/properties/TAFJTestMSSQLOverride-temn.tafj.default.appserver.name \

Current Runtime Properties and Configuration Viewer

An extension to the configuration web application is available to get a view on the runtime configuration state. This view may not be synced with the configuration table state, since this reflects the configuration state at the time of the application start.

It allows accessing the runtime properties key, value pairs through a console (JSF), which is a GUI based application or a REST API, which is a JAXRS based application.

The runtime properties view gives an overview to the runtime configuration. It can be accessed from the URL http://localhost:8080/TAFJConfiguration/runtime.xhtml or from the main TAFJEE page under the diagnostic section (http://localhost:8080/TAFJEE/index.html).

The view is similar to the administration console, except that it does not provide any edition capabilities. As the system properties are part of the runtime configuration, the filtering option is available to refine the selection of interest properties.

This service gives read-only access to the current runtime properties and is similar in its usage to the configuration API. The base service URL is /TAFJConfiguration/resources/runtime, that is, http://localhost:8080/TAFJConfiguration/resources/runtime. The commands for various functionalities pertaining to the runtime properties are as follows:

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/runtime \

@GET
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Get the current runtime set of properties, key value pair.
     * 
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when found.
     */

The above command produces the complete set of properties loaded by the runtime (system properties and tafj properties).

{
    "configurationId": "TAFJTestMSSQL",
    "properties": [
        {
            "key": "temn.tafj.runtime.local",
            "value": "en_US"
        },
        {
            "key": "file.encoding.pkg",
            "value": "sun.io"
        },
        {
            "key": "java.home",
            "value": "C:\\development\\3rdParty\\jdk\\java-11-openjdk-11.0.16.1.1-1"
        },
        {
            "key": "java.net.preferIPv4Stack",
            "value": "true"
        },
…

curl --request GET \
  --url http://localhost:8080/TAFJConfiguration/resources/runtime/tafj \

@GET
    @Produces(MediaType.APPLICATION_JSON)
    /**
     * Get the current runtime set of properties with key matching the filter
     * parameter, key value pair.
     * 
     * @return JsonObject
     *         {"configurationId":id,"properties":[{"key":key,"value":value},...]}
     *         - Status OK - 200 when found - NOT_FOUND 404 when no properties
     *         are matching the filter
     */

The above command produces the set of properties containing the string tafj in their key.

{
    "configurationId": "TAFJTestMSSQL",
    "properties": [
        {
            "key": "temn.tafj.runtime.local",
            "value": "en_US"
        },
        {
            "key": "tafj.configuration",
            "value": "TAFJTestMSSQL"
        },
        …

Copyright © 2020- Temenos Headquarters SA

Contact Us

knowledge@temenos.com

Published on :
Monday, May 27, 2024 5:10:21 PM IST