Converting the Application Using Docker¶

Converting the Application Using Docker

Introduction¶

After Analytics have been reviewed, and it is determined to proceed with application conversion, this section will show you how to run a Conversion. Before executing these steps, you MUST have run Conversion Project Setup Using Docker. A Conversion will take you from source code and schema all the way to a running environment. The build process can either clean all intermediate artifacts off, or leave them in place. If they are cleaned (using the clean target), you will rebuild fully. This can be called a Full Conversion. If you do not clean, this can be called an Incremental Conversion, because only those procedures which have changes will be re-converted.

In most development situations, a Full Conversion will be performed once, and then as changes and fixes are made to the code, Incremental Conversions will be performed. The incremental conversions are much faster to regenerate the end results, since only the changed files and dependencies are re-built.

In the below sections, archives are used to help transport changes from a build location on a development or build system, to a system that might be used for testing or deployment. They are also used as input in the generation of Docker images. This allows for the de-coupling of the converting and building of the code from the generation of the Docker image.

Note: The same conversion project directory cannot be used simultaneously for both Analytics and Conversion. Instead, you must duplicate the setup to create two independent project directories if Analytics and Conversion are needed simultaneously.

Full Conversion¶

This should be executed from a Docker bash shell opened under fbash.sh (described here).

cd ~/projects/<project_name>
ln -s /opt/fwd p2j
ant deployapp archive

Ensure you are in the project's directory and then run ant passing the deployapp and archive targets. This build will generate archive (ZIP) files in the ./distribution directory, which can be used to build the Docker images in later steps, if desired. See Build Docker Images for those instructions.

The deployapp target can be broken down into:

clean - Remove all clean.build, clean.convert, clean.dist files. This ensures all procedures are converted.
convert - Convert the 4GL source code to Java source code, using a pattern as input.
jar - Compiles and Jars the converted application Java source code. Does NOT convert or deploy.
deployapp.prepare - Deploys the generated jars for the application (not FWD) by copying them to the location expected by the runtime scripts.

The archive target creates each of the archives as outlined in the following section. This is detailed from the Hotel GUI sample, but is can be any nomenclature desired, including none.

Archive Names¶

The archive files are generated so that creation of runtime Docker images and the runtime setup can be transported to a location other than where the build takes place. When the archive task runs from the build.xml, there will be 5 ZIP files generated. The archive.prepare task attempts to gather information about the environment using a script named setup_version.sh and build the names of the files to match the environment of the build. The format of the filenames is ${projname}_<zipfile>_${app_rev}_${fwd_branch}-${fwd_rev}_${app_date}.zip where <zipfile> is:

Name	Archive Contents
deploy	The application jars and other files required for deployment on other systems.
debug	The artifacts helpful for debugging.
incremental	The artifacts necessary for an incremental build.
dumps	The dumps for testing.
runtime	The application jars only required for deployment on other systems.

The rest of the name is built from various runtime values, or retrieved from the version.properties file. The app_rev is the bzr revno value from the project's Bazaar repository. The fwd_branch and fwd_rev are retrieved from the FWD jar file (p2j.jar) using java -jar <p2j_jar_file>. The app_date is the current time in the format %(%Y%m%d) (yyyymmdd) with a letter appended, starting with 'a'.

An example of the content of the distribution/ folder for Hotel GUI sample is:

-rwxr-xr-x 1 rfb rfb 11379479 Nov 19 16:16 hotel_gui_debug_416_trunk-16279_20251119a.zip
-rwxr-xr-x 1 rfb rfb 12456542 Nov 19 16:16 hotel_gui_deploy_416_trunk-16279_20251119a.zip
-rwxr-xr-x 1 rfb rfb     9455 Nov 19 16:16 hotel_gui_dumps_416_trunk-16279_20251119a.zip
-rwxr-xr-x 1 rfb rfb 22304119 Nov 19 16:16 hotel_gui_incremental_416_trunk-16279_20251119a.zip
-rwxr-xr-x 1 rfb rfb 12188032 Nov 19 16:16 hotel_gui_runtime_416_trunk-16279_20251119a.zip

For your application, this would be information specific to how you want to identify the application. The archive. tasks create the names in build.xml.

Incremental Conversion¶

This is the "normal" conversion process. You've used your favorite editor and IDE to make changes to the code in the ~/projects/<project_name>/abl directory, and now it is time to build. The fbash.sh will find it, and convert it.

Pre-requisites¶

In order to perform an incremental conversion, all the artifacts from a full conversion need to be available. If you are working on the same system where the full conversion has taken place, you simply need to update the files in the ./abl directory structure. See Conversion Project Setup Using Docker for where the source files are located under the ./abl directory structure.

If you are not working on the system where the full conversion took place, it may be possible to re-create the build environment to the point of being able to perform an incremental conversion by performing steps using the archive zip files and source code.

For your personal project:

Start with the configuration project in place.
Place source code and schemata, as you left off from Conversion Project Setup Using Docker
Unzip archives generated from the original build over the new project. These would be the result of the archive target, and would be located in the ./distribution directory. Unzip from project unzip -oq ./distribution/<archive> -d .:
1. The deploy archive
2. The incremental archive
3. The debug archive (option for the conversion, but required to debug java source)
Update the necessary files in the ./abl directory structure.

For the Hotel GUI sample:

Checking out the project and performing bootstrap_conversion.sh. See Automated Setup for details.
Unzip archives generated from the original build over the new project. These would be the result of the archive target, and would be located in the ./distribution directory. Unzip from project unzip -oq ./distribution/<archive> -d .:
1. The deploy archive
2. The incremental archive
3. The debug archive (option for the conversion, but required to debug java source)
Update the necessary files in the ./abl directory structure.

You are now ready to convert only those changed 4GL files.

Perform the Incremental Conversion¶

From fbash.sh run the ant command, similar to the full conversion, but passing different targets so that the clean target is not executed.

cd ~/projects/<project_name>
ln -s /opt/fwd p2j
ant convert jar archive

The conversion should find all the files that require re-conversion, including dependencies (such as if an include file being modified, all the including procedures will be converted. The resultant archive files will be placed in ./distribution. It is important to know which version of FWD was used for the original conversion, so as to make sure that a compatible version is used for the incremental conversion. A best practice is to use the exact same version. This is another reason to use a naming convention for the build directory.

If necessary, the Docker images can be recreated, and the 4GL code updates should be available. See Build Docker Images for those instructions.

WARNING - a FWD release may not be compatible with existing conversions. In these cases, a full conversion will be mandatory.

FWD Runtime Updates¶

Most changes to FWD only involve the runtime and do not require re-conversion of the project. To incorporate the updates, you can update the FWD branch you are using by following the branch update steps in Docker Development Environment Setup and the FWD branch will be ready for use in runtime (as well as conversion).

Non Source-Code Updates¶

If there are situations where deployment files are updated which are not involved in the conversion, and the archives are to be regenerated, simply update the files and perform the archive task again:

cd ~/projects/<project_name>
ant archive

The archive files in the ./distribution directory will be updated, and ready for the next step, either building the Docker images or simply running the application.

Project

General

Profile

FWD

Wiki