Project

General

Profile

Quick Guided Tour

Introduction

This documents how to explore the open source FWD technology using some sample projects and Docker. The primary focus will show how test FWD as a solution to convert 4GL applications to Java. Rather than trying to add FWD onto your development system, a pre-existing Docker image is provided to make it easy to try the technology. Using the FWD Documentation, one can always add FWD to other systems later.

This guide will only work with the as-yet unreleased FWD v4.0. That FWD v4 code and the associated projects and support materials are provided at FWD v4.0.0 Early Access. Although some customers have this in production, FWD v4 is not Generally Available at this time.

Pull the Applicable Docker Image(s)

The Golden Code Docker Repository is located at https://hub.docker.com/repositories/goldencode. For this guided tour we have pre-built Hotel Docker images:
  • goldencode/hotel_gui_server:latest
  • goldencode/hotel_chui_server:latest

There are others for separate clients and PostGreSQL usage, but for this tour, these will suffice.

Pull them so that they are locally cached:

docker pull goldencode/hotel_gui_server:latest
docker pull goldencode/hotel_chui_server:latest

Try Hotel GUI

Prepare the Docker container hosting environment

On Ubuntu, open a bash command shell. Then use these commands:

cd ~
docker run --rm -it -v .:/tmp goldencode/hotel_gui_server:latest sh -c "unzip -q /home/fwd/repo/dist/hotel_gui_project_r*.zip -d /tmp/hotel_gui" 
cd hotel_gui
./docker/run_docker.sh

If you are on Windows, use these commands:

cd \
docker run --rm -it -v .:/tmp goldencode/hotel_gui_server:latest sh -c "unzip -q /home/fwd/repo/dist/hotel_gui_project_r*.zip -d /tmp/hotel_gui" 
cd hotel_gui\docker
run_docker_demo.cmd

Some notes:
  • These commands prepare your hosting environment so that the helpful script is available.
  • The database is stored in the container, and will not persist.

Run the "Virtual Desktop Mode" Web Client

  • Open Chrome or Firefox.
  • Load https://localhost:7443/gui
  • Use hotel and hotel (the demo includes SSO plug-in usage) for the "Username" and "Password".
  • The "virtual desktop" will appear, this is the actual converted 4GL code running in Java, you can "login" to the application using userid hotel and password hotel.
  • At this point it is just an ADM2 application (in Java on the server and with a pure html5/javascript browser client).

Run the "Embedded Mode" Web Client

  • Open Chrome or Firefox.
  • Load https://localhost:7443/embedded
  • Use hotel and hotel for the "Userid" and "Password".
  • The "embedded mode web application" will appear, most of this is just bespoke javascript web code but the rectangular iframe in the top left quadrant of the page is where actual converted 4GL screens are running in Java.
  • These are the ADM2 tabs without all the "chrome" or window decorations. You should recognize these same screens from the "virtual desktop" mode.
  • You will find there are many enhancements in this mode, including an enhanced browse widget; this includes dynamic layout, user defined sorting/filtering and export of the browse contents into Excel and PDF reports.
  • You will also find that the pure javascript parts of the screen are integrated with the 4GL parts, for example you can click on a cell in the Hotel Capacity section and it will select that date for the rest of the screen including the 4GL screen that is shown by the Available "tab".

Stop Hotel GUI

On Ubuntu, open a bash command shell. Then use these commands:

cd ~/hotel_gui
./docker/run_docker.sh -s

If you are on Windows, use these commands:

cd \hotel_gui
docker exec -it hotel_gui_server sh -c "(cd /opt/hotel/server; ./stop_server.sh -j hotel -c /opt/hotel/etc/server.xml; ./hold_session.sh -j hotel -r)"

Dive Deeper into Hotel GUI Setup

If you want to actually convert the Hotel GUI application, rather than utilize the pre-built Docker image, those steps are outlined here. Because in the previous section, the project files were retrieved from the Docker image, they can be used here.

Open a bash command shell. Execute these commands:

cd ~/hotel_gui
./prepare_json.sh -n < hotel.input.linux
./json_template.sh -d
./docker/build_docker.sh -l

Some notes:

  • ./prepare_json.sh -n < hotel.input.linux
    • This creates a json configuration file using the input from hotel.input.linux
  • ./json_template.sh -d
    • This creates the project files based upon the json configuration file. It also stores a json configuration file in ./deploy/server so that the directory can be generated from it.
  • ./docker/build_docker.sh -l
    • This converts (from 4GL to Java) and builds (javac and jar) the Hotel GUI sample application. The sample code is synched into the Docker container before the build, and the generated code is synched out of the container afterward.
    • The database being used is an embedded Java database called H2.
    • With some additional setup steps (for PostgreSQL) and some minor configuration changes in the project, PostgreSQL can be used instead. PostgreSQL 14 is part of the fwd_4.0_ubuntu_22.04_pg14 Docker image. Even so, I recommend starting with H2 since it is less work to get going.

This will create a Docker image locally.

Try Hotel ChUI

Prepare the Docker container hosting environment

On Ubuntu, open a bash command shell. Then use these commands:

cd ~
docker run --rm -it -v .:/tmp goldencode/hotel_chui_server:latest sh -c "unzip -q /home/fwd/repo/dist/hotel_chui_project_r*.zip -d /tmp/hotel_chui" 
cd hotel_chui
./docker/run_docker.sh

If you are on Windows, use these commands:

cd \
docker run --rm -it -v .:/tmp goldencode/hotel_chui_server:latest sh -c "unzip -q /home/fwd/repo/dist/hotel_chui_project_r*.zip -d /tmp/hotel_chui" 
cd hotel_chui\docker
run_docker_demo.cmd

Some notes:
  • These commands prepare your hosting environment so that the helpful script is available.
  • The database is stored in the container, and will not persist.

Run the ChUI Web Client

  • Open Chrome or Firefox.
  • Load https://localhost:8443/chui
  • Use hotel and hotel (the demo includes SSO plug-in usage) for the "Username" and "Password".
  • The application login is userid hotel, password hotel.

Run the TTY (NCURSES) Client

You can run this via SSH to the Docker container, or open a bash shell directly in the container.

Connect to container via ssh:
You will need to start the ssh daemon, then connect to the port that is made available to the client. Open a bash command shell, then use these commands:

docker exec -it hotel_chui_server sh -c "sudo startssh" 
TERM=xterm ssh fwd@localhost -p 4202

The password is fwd, and you will be in the container. Then you can then run:
(cd /opt/hotel/client; ./client-terminal.sh)

Connect directly to the Docker container
Open a bash command shell, then use these commands:

cd ~/hotel_chui
./docker/run_docker.sh --chui

The application login is userid hotel, password hotel.

Some notes:

Alternatively, you can connect into the running container with ./docker/run_docker.sh --inspect. At that point, you have a bash shell and can perform:

cd /opt/hotel/client
./client-terminal.sh

Stop Hotel ChUI

On Ubuntu, open a bash command shell. Then use these commands:

cd ~/hotel_chui
./docker/run_docker.sh -s

If you are on Windows, use these commands:

cd \hotel_chui
docker exec -it hotel_chui_server sh -c "(cd /opt/hotel/server; ./stop_server.sh -j hotel -c /opt/hotel/etc/server.xml; ./hold_session.sh -j hotel -r)"

Dive Deeper into Hotel ChUI Setup

If you want to actually convert the Hotel ChUI application, rather than utilize the pre-built Docker image, those steps are outlined here. Because in the previous section, the project files were retrieved from the Docker image, they can be used here.

Open a bash command shell. Execute these commands:

cd ~/hotel_chui
./prepare_json.sh -n < hotel.input.linux
./json_template.sh -d
./docker/build_docker.sh -l

Some notes:

  • ./prepare_json.sh -n < hotel.input.linux
    • This creates a json configuration file using the input from hotel.input.linux
  • ./json_template.sh -d
    • This creates the project files based upon the json configuration file. It also stores a json configuration file in ./deploy/server so that the directory can be generated from it.
  • ./docker/build_docker.sh -l
    • This converts (from 4GL to Java) and builds (javac and jar) the Hotel GUI sample application. The sample code is synched into the Docker container before the build, and the generated code is synched out of the container afterward.
    • The database being used is an embedded Java database called H2.
    • With some additional setup steps (for PostgreSQL) and some minor configuration changes in the project, PostgreSQL can be used instead. PostgreSQL 14 is part of the fwd_4.0_ubuntu_22.04_pg14 Docker image. Even so, I recommend starting with H2 since it is less work to get going.

This will create a Docker image locally.

Code Analytics

Setup

Open a bash command shell. Then use these commands:

bzr co sftp://<userid>@xfer.goldencode.com/opt/fwd/hotel_gui hotel_reports
cd hotel_reports
./docker/build_docker.sh -l --reports
./docker/run_docker.sh -r . --reports

Some notes:

  • ./docker/build_docker.sh -l --reports
    • Parses the code into ASTs and then run the analytics/generate reports.
  • ./docker/run_docker.sh -r . --reports
  • Starts up the web application server which is used to access the results (see below). It will use the local repository, since the Docker image was not pushed.

Access the Reports

  • Open Chrome or Firefox.
  • Load https://localhost:9443
  • Login with userid admin and password hotel (you can just use the ESC key to bypass the password change prompt if you want to leave the password as is).

Next Steps

Get Help

Once you've gotten to this point, contact Golden Code (fwd@goldencode.com) to speak with an expert on the technology and to answer questions.

Redmine

All FWD project work is done on the Redmine system. This is the mechanism for bug reports, forums, feature requests, documentation and other interaction. If you do not already have an account, please use this link to create one:

https://proj.goldencode.com/account/register

DO NOT use your email address as your username. In Redmine the username is visible to the public, but the account also has an email address and that is not public. This ensures that your email can't be harvested by web crawlers.

Anything posted in the FWD project is public. This means it is visible via anonymous web browsing. We do prefer to put as much in that public project as possible, so that the work on FWD is in the open. Golden Code can create a private project for any sensitive discussions. Anything that really needs to be private can be done there.

Other Resources

  • FWD Documentation is the documentation for the technology.
  • Forums are a good place for questions/answers and discussions.
  • Sample Applications
    • The following have more details on the sample applications and their usage as a template for building your own conversion project. These pages are for slightly older versions of the samples. The newer sample versions that you have are a little different but the details are nearly the same.
    • The process noted above is simplified and leaves out much of the detail that can be found in those wiki pages.
  • 4GL Enhancements is the list of new 4GL features and capabiities that only exist in FWD (and not in OpenEdge). The documentation is not complete yet but you will get the idea of how much we have upgraded both the 4GL language itself as well as the runtime capabilities.

© 2004-2024 Golden Code Development Corporation. ALL RIGHTS RESERVED.