Overview of Java runtime properties

An EGL-generated Java™ program uses a set of properties that provide information at runtime. Most of these Java runtime properties are set using build descriptor options, that you assign values to by editing the build descriptor part in the EGL Build Parts Editor.

Note: EGL-generated Java VGWebTransaction programs represent a special case. The determination of whether they run in a J2EE or non-J2EE environment depends on the setting of program property enableJ2EE. (The default value is NO.) If you are reading this topic because you are working with a VGWebTransaction program, do as follows whenever you read a reference to the build descriptor option j2ee: consider the value of program property enableJ2EE instead.

During generation, the build descriptor options' values are stored in the corresponding Java runtime properties, which are then listed in one of the following files:

If you are deploying your output in a J2EE environment, the properties are stored in the J2EE deployment descriptor.
If you are deploying your output in a non-J2EE environment, the properties are stored in a program properties file.
If you have set the j2ee build descriptor option to YES and have specified a directory for the genDirectory build descriptor option, then the Java runtime properties are stored in a J2EE environment file. A J2EE environment file is also created if you have set the j2ee build descriptor option to YES and have set the genProject build descriptor option to a non-J2EE project.

You can then go into either the J2EE deployment descriptor or the Java properties file, and edit any of the values of the runtime properties without having to generate your code again.

In order for EGL to use build descriptor options to create runtime properties, you must set the genProperties build descriptor option to either PROGRAM or GLOBAL.

Build descriptors and program properties

If you are generating Java runtime properties, they will be created and stored according to one of the following scenarios:

To generate Java runtime properties to the J2EE deployment descriptor, follow these steps:
1. Set the j2ee build descriptor option to YES.
2. Set the genProperties build descriptor option to PROGRAM or GLOBAL.
3. Generate your code into a J2EE project.
To generate properties into a J2EE environment file, follow these steps:
1. Set the j2ee build descriptor option to YES.
2. Set the genProperties build descriptor option to PROGRAM or GLOBAL.
3. Do either one of the following:
  - Generate into a directory, in which case you use the genDirectory build descriptor option rather than genProject; or
  - Generate into a non-J2EE project.
Note that the properties stored in the J2EE environment file will not be automatically updated when you generate.
To generate a program properties file, with the same name as the program being generated, follow these steps:
1. Set the j2ee build descriptor option to NO.
2. Set the genProperties build descriptor option to PROGRAM.
3. Do either one of the following:
  - Generate into a directory, in which case you use the genDirectory build descriptor option rather than genProject; or
  - Generate into a non-J2EE project.
To generate a program properties file named rununit.properties, follow these steps:
1. Set the j2ee build descriptor option to NO.
2. Set the genProperties build descriptor option to GLOBAL.
3. Do either one of the following:
  - Generate into a directory, in which case you use the genDirectory build descriptor option rather than genProject; or
  - Generate into a non-J2EE project.
To avoid generating properties, set genProperties to NO.

In a J2EE environment

If you are generating a Java program that will run in a J2EE environment, the Java runtime properties can be created in one of the following ways:

You can follow the steps in the first scenario in the previous section, to generate the Java runtime properties directly into a J2EE deployment descriptor. In this case, EGL overwrites properties that already exist and appends properties that do not exist. The generated Java program accesses the J2EE deployment descriptor at run time.
Alternatively, you can follow the steps in the second scenario of the previous section, to generate the runtime properties into a J2EE environment file. You can customize the properties in that file, then copy them into the J2EE deployment descriptor.
You can also follow the fifth scenario from the previous section, and set the genProperties build descriptor option to NO, to avoid generating the runtime properties at all. In this case, you must write any needed Java runtime properties by hand.

In a J2EE module, every program has the same runtime properties because all code in the module shares the same J2EE deployment descriptor.

For J2EE servers, properties are specified as env-entry tags in the web.xml file that is associated with the web project, as in these examples:

  <env-entry>
		  <env-entry-name>vgj.nls.code</env-entry-name>
    <env-entry-value>ENU</env-entry-value>
    <env-entry-type>java.lang.String</env-entry-type>
  </env-entry>

  <env-entry>
    <env-entry-name>vgj.nls.number.decimal</env-entry-name>
    <env-entry-value>.</env-entry-value>
    <env-entry-type>java.lang.String</env-entry-type>
  </env-entry>

In a non-J2EE environment

If you are generating a Java program that will run outside of a J2EE environment, you can set the genProperties build descriptor option to either PROGRAM or GLOBAL, which causes EGL to generate the runtime properties into a program properties file; or you can code the program properties file by hand. The program properties file provides the kind of information that is available in the deployment descriptor, but the format of the properties is different.

In a non-J2EE Java environment, runtime properties can be specified in any of several properties files, which are searched in this order:

user.properties
A file named as follows:
```
  programName.properties
```
where programName is the first program in the run unit.
rununit.properties

Using user.properties is appropriate when you specify properties that are specific to a user. EGL does not generate content for this file.

Using rununit.properties is especially appropriate when the first program of a run unit does not access a file or database, but calls programs that do. For example:

When generating the calling program, you can generate a program properties file named for the generated program, and the content might include no database- or file-related properties.
When you generate the called program, you can generate rununit.properties, and the content would be available for both programs.

None of the properties files are mandatory, and simple programs do not need any.

Rules for deploying non-J2EE code

At deployment time, the following rules apply:

The user properties file (user.properties, if present) is in the user home directory, as determined by the user.home Java system property.
The location of a program properties file (if present) depends on whether the program is in a package. The rules are best illustrated by example:
- If program P is in package x.y.z and is deployed to MyProject/src, the program properties file must be in MyProject/src/x/y/z
- If program P is not in a package and is deployed to MyProject/src, the program properties file (like the global properties file) must be in MyProject/src
In either case, MyProject/src must be in the classpath.
The global properties file (rununit.properties, if present) must be with the program, in a directory that is specified in the classpath.

If you generate output to a Java project, EGL places the properties files (other than user.properties) in the appropriate folders.

For details on accessing runtime properties in your EGL code, see the topics "getProperty()" and "Run unit" in the EGL Language Reference.