Project

General

Profile

Wiki »

Guided Tour

Introduction

This documents how to explore the open source FWD technology using some sample projects. 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 development virtual machine 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 pre-release, so they are only available via a secure file transfer system. You will need an account to access that system. Contact fwd@goldencode.com to request access.

Secure Download Site

Since FWD v4 is pre-release, the code is only available from a secure file transfer system (xfer.goldencode.com) which has no anonymous access. If an account has not been provided to you, please contact fwd@goldencode.com to request access. You will need a userid and password for that system.

Access to the xfer.goldencode.com is exclusively through scp (secure copy) or sftp (secure ftp). ssh is not available. For details, please see:

Secure File Transfer System

The instructions below will use this "xfer" system. On Windows systems, Putty, WinSCP, FileZilla can all be used for this file transfer.

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.

Download the Virtual Machine

Please download the FWD development system which is pre-built as an Ubuntu 22.04 virtual machine. The virtual disk is in VirtualBox (.vdi) format. The scp command to download this is:

scp <userid>@xfer.goldencode.com:/opt/fwd/devvm/fwd_dev_machine_ubuntu_22.04_20220915.zip .

Substitute your secure file transfer userid in for <userid>. You can also use sftp to download the file.

This command will be available on any Linux system, but on Windows you will have to install an scp/sftp client as noted above.

The zip file is 19GB, so it will take some time to download. After it is downloaded, use unzip (or the equivalent) to extract the .vdi file. The result will be a 30GB file named fwd_v4_developer_machine_22.04.vdi.

Create the FWD Development System

VirtualBox is used to run this .vdi. If you use an alternative virtual machine host technology, you'll have to convert the .vdi into the proper format. These instructions assume that VirtualBox is installed and operational.

To create the FWD Development System virtual machine using VirtualBox:

  1. Launch VirtualBox and in the main menu choose Machine -> New... (please note: you cannot import this virtual disk, it is not an "appliance")
  2. Enter the name of the new virtual machine, for example "FWD Development System", choose the Type "Linux" and the Version "Ubuntu (64-bit)".
  3. On the next screen set the memory size to the recommended maximum. Move the memory size slider to the upper limit of the slider's green zone. At a minimum, set it to 4096MB and if you can, set the memory to 8192MB or more.
  4. Move to the next screen, choose the "Use an existing virtual hard disk file" option and use the file browser dialog to locate the downloaded FWD disk image.
  5. Choose the Create button, the virtual machine will be created.
  6. Make sure the new VM is selected and then open the settings dialog using Machine -> Settings.
    • Optionally, to enable the transfer of files to/from the VM, switch the the Shared Folders tab. Click on the + icon on the left to get to the Add Share dialog. From there, select the proper Folder Path (on the host machine) and select Auto Mount. Then click OK to add that share. When you boot the virtual machine, the auto-mounting will cause that shared folder to be available as /media/sf_<share_name>. FYI, you will need to use sudo to access those files because the auto-mount doesn't set the permissions for the fwd user.
    • For optimal performance increase the number of CPUs allocated to the created virtual machine. Switch to the System -> Processor tab increase the number of CPUs, set the recommended maximum, which is half the number of CPUs of the host system. You should not get into the red zone of the Processor slider, this would degrade the system performance. Confirm and close the settings dialog.
    • Save the changes by clicking OK.
  7. Start the virtual machine. For the best experience switch to full screen mode (main menu View -> Full-screen Mode). The system will start and automatically executes a login for the user 'fwd'.

The user for the system is fwd and the password is fwd. This same userid is enabled as a system administrator (using sudo).

Download and Setup FWD v4.0

FWD v4.0 is still being very actively modified. For this reason, at this time it is not being included by default in the virtual machine image. This means it needs to be downloaded and built.

Start the virtual machine and open a bash command shell. In the commands below, substitute your secure file transfer userid in for <userid>. Execute these commands:

bzr branch sftp://<userid>@xfer.goldencode.com/opt/fwd/trunk fwd
cd fwd
./gradlew core
cd

Some notes:

  • If the first access to sftp://<userid>@xfer.goldencode.com prompts you to accept the certificate for xfer, that is OK to do.
  • ./gradlew core
    • This step does a compilation of FWD (mostly Java and some native JNI code).
    • There are many warnings and javadoc errors. That is OK.

Download Latest Code and Setup Hotel GUI

Open a bash command shell. In the commands below, substitute your secure file transfer userid in for <userid>. Execute these commands:

bzr branch sftp://<userid>@xfer.goldencode.com/opt/fwd/hotel_gui
cd ../hotel_gui
ln -s ../fwd/ p2j
./prepare_hotel.sh
ant deploy.all
./install_spawner.sh

Some notes:

  • ant deploy.all
    • This converts (from 4GL to Java) and builds (javac and jar) the Hotel GUI sample application.
    • It also does an import of the database so that the application can be executed.
    • 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 9.4 is installed on the virtual machine already. Even so, I recommend starting with H2 since it is less work to get going.
  • ./install_spawner.sh
    • You will be prompted for your sudo password. Type "fwd" and then ENTER. This is needed to install the "spawner" for the web client which is part of the build command in this case. The prompt looks like this: 
                  [sudo] password for fwd:
            > Task :ant-native
            [ant:echo]

Try Hotel GUI

Start the Server

Open a bash command shell. Then use these commands:

cd ~/hotel_gui/deploy/server/
./server.sh

Run the "Virtual Desktop Mode" Web Client

  • Open Chrome or Firefox inside the Ubuntu virtual machine.
  • Load https://localhost:7443/gui (or use the FWD GUI Web Client bookmark).
  • Use fwd and fwd (the main Ubuntu account) 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 inside the Ubuntu virtual machine.
  • Load https://localhost:7443/embedded (or use the FWD Embedded Web Client bookmark).
  • 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".

Run the Swing Client

Open a bash command shell. Then use these commands:

cd ~/hotel_gui/deploy/client/
./client.sh

This is the same ADM2 application, but running in Java using the desktop Swing client.

Setup Hotel ChUI

Open a bash command shell. In the commands below, substitute your secure file transfer userid in for <userid>. Then execute these commands:

cd
bzr branch sftp://<userid>@xfer.goldencode.com/opt/fwd/hotel_chui
cd hotel_chui
ln -s ../fwd/ p2j
./prepare_hotel.sh
ant deploy.all
./install_spawner.sh
  • ant deploy.all
    • This converts (from 4GL to Java) and builds (javac and jar) the Hotel ChUI sample application.
    • It also does an import of the database so that the application can be executed.
    • 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 9.4 is installed on the virtual machine already. Even so, I recommend starting with H2 since it is less work to get going.
  • ./install_spawner.sh
    • You will be prompted for your sudo password. Type "fwd" and then ENTER. This is needed to install the "spawner" for the web client which is part of the build command in this case. The prompt looks like this: 
                  [sudo] password for fwd:
            > Task :ant-native
            [ant:echo]

Try Hotel ChUI

Start the Server

Open a bash command shell. Then use these commands:

cd ~/hotel_chui/deploy/server/
./server.sh -i1

Run the ChUI Web Client

  • Open Chrome or Firefox inside the Ubuntu virtual machine.
  • Load https://localhost:8443/chui (or use the FWD ChUI Web Client bookmark).
  • Use fwd and fwd (the main Ubuntu account) for the "Username" and "Password".
  • The application login is userid hotel, password hotel.

Run the TTY (NCURSES) Client

Open a bash command shell. Then use these commands:

cd ~/hotel_chui/deploy/client/
./client-terminal.sh -i1

The application login is userid hotel, password hotel.

Run the Swing Client

Open a bash command shell. Then use these commands:

cd ~/hotel_chui/deploy/client/
./client-swing.sh -i1

The application login is userid hotel, password hotel.

Code Analytics

Setup

Open a bash command shell. Then use these commands:

cd
bzr branch hotel_gui/ hotel_reports
cd hotel_reports/
ln -s ../fwd/ p2j
ant rpt
cd deploy/server/
./report.sh

Notes:

  • The ant rpt will parse the code into ASTs and then run the analytics/generate reports.
  • The ./report.sh starts up the web application server which is used to access the results (see below).

Access the Reports

  • Open Chrome or Firefox inside the Ubuntu virtual machine.
  • Load https://localhost:9443 (or use the FWD Analytics bookmark).
  • 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

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

Other Resources:

  • FWD Documentation is the docmentation 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-2021 Golden Code Development Corporation. ALL RIGHTS RESERVED.