iSeries EGL

All things EGL for the iSeries / i5 / Power System

Archive for the ‘Application Startup’ Category

Application Startup Processing

leave a comment »

Introduction

This post illustrates the start-up processing phase of an arbitrary EGL based web application. The focus will be about how to incorporate some of the building blocks already presented which are used to help initialize the application.

The code to acquire the runtime environment variable is contained within runtimeEnvironment.jar. The code used to read the XML file is contained within appUtilities.jar.

Ask a member of the development team for these files so they can be included into your project.

Application Properties

Most web applications will have configurable program values stored in a file external to the application. The values are usually contained within an XML file. Shown below is an XML containing values for a comment, a version number and three values for an email address.

<?xml version="1.0" encoding="UTF-8" ?>
<!DOCTYPE properties SYSTEM "http://java.sun.com/dtd/properties.dtd">

<properties> 

    <comment>Configuration File</comment>

    <entry key="version">20120710.01.00</entry >

    <entry key="localhost.emailAddress">theDeveloper@theCorporateNetwork.com</entry >

    <entry key="TEST.emailAddress">theDeveloper@theCorporateNetwork.com</entry >

    <entry key="PROD.emailAddress">realDistributionList@theCorporateNetwork.com</entry >

</properties>

Fig.1 – A simple set of property values in an XML file.

 
The entries for <comment> and <entry key=”version”> is pretty much self-explanatory. The first is to hold a simple comment for the developer while the second contains a version number for the application.

The entries for <entry key=”localhost.emailAddress”>, <entry key=”TEST.emailAddress”> and <entry key=”PROD.emailAddress”> hold values reserved for one of the 3 possible servers in which the application will run. Each entry for email address is preceded with either ‘localhost’, ‘TEST’ or ‘PROD’ which represent the server running on the developer’s machine (i.e. 127.0.0.1, a.k.a ‘localhost’) the server assigned to the role of application testing (“TEST’) and the server assigned to the production role (‘PROD’).

In this situation, this approach of assigning application property values allows the developer to test the email application so that during the development-testing phase, emails will only be sent to the developer rather than a community of users. The same holds true for the TEST server. When the application is finally deployed to the production server the correct production-oriented email address is used.

By prefixing each property value with a server identifier, a unique value can be established for each server. This allows the application to pick up the correct value that has been assigned for the server in which the application is running. The only trick now is to get the application to determine which server it happens to be running on.
 

Placement of the Property File Within the EGL Project

As previously stated, the code used to read the XML file is contained within appUtilities.jar. As a consequence the XML file must be placed into a directory known to it, as shown below.

The ‘src/config’ folder must be placed as shown.


In addition, the XML file must be named ‘applicationConfig.xml’.
 

Determining The Server’s Role During Startup

Getting the right value during run-time rests upon the application’s ability to determine which server it happens to be running on. This is done by assigning an externally-defined value to each of the servers. To see how this is accomplished please refer to this post.

Once this value (‘TEST’ or ‘PROD’) has been established the application can read it which usually occurs at the very beginning when the application is first started.

The idea here is to read this value (‘TEST’ or ‘PROD’) and use it to append to the property name so that the retrieval process picks up the correct value which is then cached inside the application so that it can refer to it when needed. In this case, that would be when the application needs to send an email.

This post illustrates how to create EGL code to read the environment variable (EV) assigned to Tomcat’s JVM.
 

Reading Application Properties From The XML File

This section will illustrate how to create an External Type that is the interface to an external Java application.

The first thing to do is to create an EGL External Type so that the Java methods that are used to read the XML file can be called from the EGL Service program

Two functions have been crossed out from the list as they will not be discussed here.

package com.mig.jobmessages.externaltypes;

externalType ConfigurationCache type JavaObject{PackageName = "com.app.utilities.configuration"}
    
    static function getInstance() returns(ConfigurationCache);

    function setRuntimeEnvironment(runtimeEnvironment String in);    
    function getBaseProperties();
    function setPropertyTableEntry(propertyName String in, propertyValue String in );
    function cacheAppPropertyValues(listOfPropertyNames String[] in);
    function getPropertyTableEntry(propertyName String in )  returns (String);
    
end

Fig.2 – An EGL External Type used to read property values in an XML file.

 

Each entry following the ‘externalType’ entry represents methods to be used in this process. Each of these are described below.

  • static function getInstance() returns(ConfigurationCache);
    This function is used to get an instance of the Java class called ConfigurationCache. It is the program that handles all of the I/O to the XML file holding the application’s configuration values.
  •  

  • function setRuntimeEnvironment(runtimeEnvironment String in);
    Once an instance of ConfigurationCache is obtained use this method to inform it about the runtime environment in which it is running. This value is used to enable ConfigurationCache to read the correct set of values assigned for each server role.
  •  

  • function getBaseProperties();
    This function gets properties that have been identified as basic properties common to all applications. Examples of these are shown here:

    <entry key=”localhost.log4jConfigFileLocation”>C:\Desk\AppDevEGL\JobMessages\JobMessagesProject\src\config\log4j.xml</entry>
     

    <entry key=”localhost.log4jLogFileDirectory”>C:\Desk\AppDevEGL\JobMessages\JobMessagesProject\WebContent\logs\</entry>
     

    <entry key=”localhost.daysBeforeLogFilesDeleted”>10</entry>
     
  •  

  • function setPropertyTableEntry(propertyName String in, propertyValue String in );
    This function allows the developer to set an arbitrary name-value pair into the cache, however this function makes no sense in an EGL setting.
  •  

  • function cacheAppPropertyValues(listOfPropertyNames String[] in);
    This function is best explained with by the set of code that appears below. It shows the creation of a dynamic array that is used to hold 5 entries, each of which is a named property. In this case, the dynamic array of names will be used to hold just two values i.e. ‘version’ and ’emailAddress’ which are referenced using constants defined elsewhere in the program. (See the XML at the beginning of this post to see the entries for ‘version’ and ’emailAddress’.)
     
    The idea is to ‘push’ the names of each property into the array and then pass the array of values to the function cacheAppPropertyValues(listOfPropertyNames String[] in); that reads and caches them. When control is returned to the caller, calls to the next function (presented below) will retrieve each individual value for the name specified on the function’s parameter.

        //Get the runtime environment value from the server using RuntimeEnvironment 
        rte RuntimeEnvironment = new RuntimeEnvironment();
        runtimeEnvironment string  = rte.getRuntimeEnvironment();
    
        //Initialize the dynamic list of property names and the size. Set index 'p' to zero.
        listOfPropertyNames string[5] {maxsize = 5} ;
        p int = 0;
        
        //Increment index and add the property name to the list.
        p=p+1; listOfPropertyNames[p] = CommonLibrary.CONST_VERSION;
        p=p+1; listOfPropertyNames[p] = runtimeEnvironment+"."+CommonLibrary.CONST_EMAIL_ADDRESS;
           //... add more here when needed. 
     
        //Get an instance of the Configuration Cache and pass the runtimeEnvironment variable.
        configCache ConfigurationCache = ConfigurationCache.getInstance();
        configCache.setRuntimeEnvironment(runtimeEnvironment);
    
        //Read the properties in the list into the Cache. The values of each will be retrieved next.
        configCache.cacheAppPropertyValues(listOfPropertyNames);
    

    Fig.3 – This code goes into the Service program called on startup.

     

  • function getPropertyTableEntry(propertyName String in ) returns (String);
    This function retrieves the value of the property specified by the passed parameter. Retrieval is dependent upon the preceding step that caches the property value. See the function cacheAppPropertyValues(listOfPropertyNames String[] in);, above.

        //Retrieve and store the value into EGL program variables. 
        configDataRecord.version         = configCache.getPropertyTableEntry(CommonLibrary.CONST_VERSION ); 
        configDataRecord.emailAddress    = configCache.getPropertyTableEntry(CommonLibrary.CONST_EMAIL_ADDRESS);
    

    Fig.4 –

     

Summary

This post showed how to set up an EGL External Type to describe the interface to Java methods that allows access to discrete data elements residing in an external XML file. The nature of the values contained within the XML file are used to control program behavior that must differ across multiple server environments. The solution presented prevents the need for the program to be modified each time it is deployed to a new environment.

Written by iseriesadmin

July 12, 2012 at 2:41 pm