Skip to main content

ConfigServlet Guide

Overview​

ConfigServlet provides a way to manage web-server-host specific properties/settings (via OS environment variables and template config files), so allowing the same physical Temenos Explorer WAR file to be deployed (unamended) to different target environments (test, production, etc) where the applicable values for those properties/settings differ.

Note that, providing the <url-pattern> within the <servlet-mapping> for each ConfigServlet-related <servlet> definitions (in TemenosExplorer/public/WEB-INF/web.xml) are defined to match the web-app-root-relative path for the original (i.e. non template version) of the relevant config file, this mechanism is transparent to any existing TemenosExplorer HTML pages linking in that original config file (which means that no changes to those references pages are required in order to enable this mechanism).

In addition to serving the token-substituted content of the relevant template config file, each ConfigServlet instance also provides access to a diagnostic HTML "status" page summarising the effective values for referenced environment variables, the template config file content before / after substitution, etc). The URL to request the (text/html) status page is the same as that to access the token substituted (html/javascript) content, but with /status appended as the servlet path.

Key files​

The TemenosExplorer/public folder (which is manually zipped in order to create a WAR file) includes the following runtime content relating to ConfigServlet:

  • template config files:

    • TA_config.SAAS.configservlet-template.js (adapted from TA_config.SAAS.js)
    • plugins/CSA/CSA_config.SAAS.configservlet-template.js (adapted from CSAConfig.SASS.js)

    The environment-variable token types recognised by ConfigServlet are covered below here.

  • WEB-INF/web.xml:

    As supplied includes (separate) commented-out ConfigServlet-related <servlet> and <servlet-mapping> pairs for each of the 2 template config files named above.

    Further <servlet> and <servlet-mapping> pairs (one per new .configservlet-template.js file) may be freely added as needed, however.

    The ConfigServlet-related web.xml entries are are covered in further detail below here.

  • WEB-INF/status.html:

    This template used internally by ConfigServlet to generate the HTML page returned when the suffix: /status is included (as the servlet path) on the end of the URL for a particular config file.

  • WEB-INF/lib/configservlet.jar:

    This contains the compiled .class files for com.temenos.servlet.config.ConfigServlet and its supporting classes.

    (The corresponding .java source files, an ant build.xml file and a README.txt file explaining how to use that to create an updated configservlet.jar, should that be necessary, are located in the JavaServlets/ConfigServlet directory).

Template config files: environment-variable token types​

ConfigServlet recognizes the following token types:

  • @{env:XXXXX} or @{env!:XXXXX}: denotes a reference to a mandatory environment variable named XXXXX

    In the case where the (mandatory) environment variable is found to be undefined, this is flagged as an error both:

    • in the logging output by the relevant ConfigServlet instance's init() method

    • in the html "status" page returned by the servlet when /status is present on the end of the url for the relevant config file

    ...and the referencing token is left unsubstituted in the text/javascript response returned by the servlet for the url of the relevant config file.

  • @{env?:XXXXX}: denotes a reference to an optional environment variable named XXXXX

    In the case where the (optional) environment variable is found to be undefined, rather than being reported as an error, the token is simply replaced with an empty string in the text/javascript response returned by Config servlet for the relevant config file.

TemenosExplorer/public/WEB-INF/web.xml entries​

As noted above, the supplied version of this file includes commented-out ConfigServlet-related entries for the .configservlet-template.js variants of 2 original configuration files (TA_config.SAAS.js and CSAConfig.SASS.js).

The purpose of this section is to explain how such entries work (so that you'll know both (a) how to fine tune the existing ones and/or (b) add further entries for other config file templates should the need arise).

  • Each instance of com.temenos.servlet.config.ConfigServlet is responsible for serving (a) the token-substituted content, and (when invoked via url ending with /status) (b) the HTML summarizing its initialization for a single template configuration file.

    On initialization, each instance deduces the (deployed) location of the relevant template config file from the value made available to that instance via a servlet init-param named: webAppRootRelativeConfigFilePath.

  • In the web.xml, for each template configuration file to be handled by a ConfigServlet instance, it is therefore necessary to define both:

    • a) a <servlet< tag containing the following sub-tags:

      • <servlet-name>XXXXX</servlet-name>

        ...where XXXXX is a logical name (unique within this web.xml) for this particular servlet instance (used later to associate the corresponding <servlet-mapping> with this particular instance)

      • <servlet-class>com.temenos.servlet.config.ConfigServlet</servlet-class>

      • <init-param:> containing the following sub-tags:

        • <param-name>webAppRootRelativeConfigFilePath</param-name>

        • <param-value>XXXXX</param-value>

          ...where XXXXX is the sub-path to the relevant template config file (relative to source-tree sub-directory: TemenosExplorer/public).

          TIP: To avoid potential problems if/when the WAR file is deployed to web-containers on hosts running unix-flavoured operating systems:

          • Use / as the path separator character (which works fine in Windows host environments too)

          • Use the exact case (Windows file sytem is case insensitive, unix-flavoured ones are not)

      • <load-on-startup>XXXXX</load-on-startup> (optional, but recommended)

        ...where XXXXX is a positive integer number (traditionally >= *1000 to ensure that any servlets internal to the web-container are initialized first) indicating:

        • a) that the servlet's init() method is to be called on server start-up (meaning that any initialization problems will be evident on completion of server start-up) - rather than waiting for the servlet to be accessed for the first time

        • b) when (relative to the initialization of other servlets that include a valid value for this tag) that initialization is to occur

    • b) a corresponding <servlet-mapping> tag with sub-tags as follows:

      • <servlet-name>XXXXX</servlet-name>

        ...where XXXXX matches the value of the sub-tag of the same name within the corresponding <servlet;> tag

      • <url-pattern>XXXXX</url-pattern>

        ...where XXXXX is the /-separated, web-app-root-relative URL sub-path to the (non template) config file (as referenced in referencing Temenos Explorer HTML pages) - suffixed /* on the end to allow for the optional /status suffix on URLs requesting the HTML status page (vs. the token-substituted template-config-file content)

Summary​

In order to enable / use ConfigServlet to serve environment-variable-based values for the 2 config files already catered for via the commented-out entries in TemenosExplorer/public/WEB-INF/web.xml, the steps required (prior creating the WAR file by zipping TemenosExplorer/public) are as follows:

  • uncomment the ConfigServlet-related **<servlet>** and **<servlet-mapping>** entries in that file

  • on each host environment where the WAR file is to be deployed, ensure that appropriate values are defined for each of the environment variables referenced via the tokens in template config files: TemenosExplorer/public/TA_config.SAAS.configservlet-template.js and TemenosExplorer/public/plugins/CSA/CSA_config.SAAS.configservlet-template.js

The additional/alternative steps required to use ConfigServlet to do the same for different/additional config files are (for each such config file):

  • create a new config template file (by copying the original config *.js file to one with the same name and extension: .configservlet-template.js)

  • edit that new config template file, replace relevant values with appropriate environment-variable reference tokens as described above here

  • update TemenosExplorer/public/WEB-INF/web.xml to include (i) a suitable (ConfigServlet) <servlet>; definition (to define a named servlet instance for that file) and (ii) an <servlet-mapping> associated with that new <servlet>; instance as described above here