Doco Home Hints Home

Platypus Hints: Real World Process

The process of developing an app using Platypus portrayed in the tutorial is rather idealised. It assumes that each stage of the process is completed before the next is begun, and that each stage is completed without error.

In practice, we follow a different process. We work through the app workflow by workflow rather than stage by stage, and we do make some errors :-). We find that having complete HTML and the developers' configuration files are the most crucial parts of the process.

The following sections describe our experience in more detail. We start from the moment NewApp has been run: we should have a directory structure, Makefiles and HTML files (not marked up).

Getting Started

We generally proceed though the app workflow by workflow. Within a workflow, we start with the first PO, develop it for a while, then move onto the next PO in the workflow.

At the very beginning, we start with the Welcome page. (This may be several POs, making up a frameset page.) The Welcome page usually has little dynamic content, and is an easy kill.

Once we have selected a workflow, we check whether it needs any Commit POs. If it does, we add these to the system. Some hints on adding a PO are here.

Once we have selected a PO to work on:

Markup HTML
Some hints on marking up a PO are here.
Generate conf file
First, move the PO into the PO_CONF list in the Makefile.
Second, run make -s build_1.
Edit conf file
Some hints on editing a conf file are here.
What next?
At this stage, you can start on another PO, or carry on with this PO. The pro's and con's of each option are discussed below.
Generate presentation layer Java
First, move the PO into the PO_JAVA list in the Makefile run make -s build_2.
Second, run make -s build_2.
Generate business layer Java
To generate the business layer Java, run billabong. This is currently the best way to discover if your config files are correctly setup. Billabong will throw exceptions and die if there are problems. From experience, the FIELDPATH, DATAFROM and ACCESS fields in the IDS are the most frequent culprits.
Sanity check
So far, we haven't hand-edited anything generated from the developer's configuration. Before we do that, it's a really good idea to look through the generated Java and do a sanity check.
If something is missing, it will be much easier to change now than after hand-edits have been done. Trust me on this.
Edit Java
Some hints on editing a PO's java in the presentation layer are here.
Some hints on editing java in the business layer are here.
Compile Java
First, move the PO into the PO_CLASS list in the Makefile.
Second, run make -s build_3. This will compile Java in all three layers (and in the util/ directory). Depending on how you configure your server, you may need to run make -s jar.
Set up web server
Configure your webserver (or multiserver).
Run
Test the PO. We find testing is best done workflow by workflow. It's hard to fully test a PO until its workflow is ready to run. Our designs tend to have very little interaction between workflows, so once a workflow has been debugged, we find there are generally few system integration bugs at a higher level.

How far to take a PO

Once we've started on a PO, the question is: How far do we take the PO before we move onto the next PO?

We assume that testing will find some bugs, and cause some changes in the conf files or html. It may also cause changes which only affect the Java, but these are easily dealt with because they don't cause regeneration of the conf files or skeleton Java.

The main issues are:

Testing
It is difficult to test a PO in isolation. However, workflows can be tested in isolation.
This means that it is worthwhile to take a workflow to completion before moving to the next workflow, but we can't take a PO to completion until the other POs in the workflow are running.
Regenerating Files
Once a file has been generated, how difficult is it to regenerate if its precursor is changed?
If the HTML is changed, the Makefiles will regenerate the conf file in the view/ directory, and try to merge the new config into the existing config. If the existing config hasn't been hand-edited, it will do this perfectly. If it has been hand-edited, it will do a fairly good job, and require little hand-merging. However, the merging can be subtle (or forgotten), and cause problems.
If the conf file is changed, the Makefiles will generate a new skeleton manipulation file in the view/ directory. The new code must be merged into the hand-edited code by hand. This is tedious, but not particularly error prone.
Billabong does not operate on individual POs. It generates all the required files (including database table based files) at once, in the src/ directory. Changes to the developer's configuration after Billabong's output has been hand-edited causes pain.
This means that changes to the HTML and conf files after the Java code has been hand-edited are tedious and bug-prone. This is especially true if the changes affect the business layer.
Developer Focus (Presentation Layer)
As a developer, I (Guy Smith) have a limited breadth of focus. I like to focus on as small a module as possible, work it to completion, and then move on, hopefully never to return. I work mostly in the presentation layer. I find that the skeleton Java in the presentation layer is pretty close to the final code.
This means that once I've started on a PO, I like to take it as far as possible before moving to the next PO, but it doesn't greatly fuss me if I have to stop before hand-editing the Java in the presentation layer.
Developer Focus (Business/Data Layer)
I (Chris Ryan) often have to have a bigger picture than Guy since I work mostly in the business and data layers. Billabong has been created to generate all the BOs at once. This can be inconvenient after hand coding has started in the business area and a bug has been found in the presentation layer - often it's the config files. When a config file was changed requiring Billabong to be run, then I directed the output of Billabong to a temporary directory and cut'n'paste the new code as needed. The best advice I can give for the business layer developer is to ensure the config files are as close as possible to being correct before running Billabong.

I found that I used Squirt in an iterative process. As I went through BOs that required some query, I created the necessary SQL and QUERY section required and then re-ran Squirt. The stub code was then inserted into the correct BDO-BO file and the necessary linking call (and any data checking, conversions, etc) put into the PO-BO file.

The overall result is that we tend to proceed workflow by workflow. In a workflow, we take each PO as far as doing a sanity check on the presentation skeleton code. Once we've checked the developers configuration for the workflow, we rerun Billabong and take the workflow to completion.

Regenerating files

There are two aspects to merging the new code into the hand-edited code when one of the generated files has to be regenerated. First, the new code must be copied into the hand-edited code. Second, the newly copied code should be hand-edited.

Let me repeat that second point: Newly copied code should be hand-edited. This is easy to forget, and causes problems.

Note: Only one pass of the directories should be run in each invocation of make. After changes to the HTML files, invoke make with build_1. Then do the appropriate edits to the conf files before invoke make with build_2. Finally, do the appropriate edits to the conf files before invoking make again.

Changes to the HTML will cause the conf file to be regenerated. The Makefiles will try to merge the changes into the hand-edited conf files. Consider three cases:

No hand-edits
If there were no hand-edits, the file will be perfectly updated. The diffpatch script will not give any messages.
Patch succeeded
The diffpatch script will have only copied the new code in. Check whether the new code needs hand-edits.
Patch failed
The diffpatch script will tell you which hunks succeeded, which hunks failed, and where the failures are logged. You should check the failures, copy them into the hand-edited file, delete the logging file, then hand-edit both the hunks you hand-copied and the hunks patch succeeded in merging!

Changes to the conf file will cause the presentation layer skeleton to be regenerated, but will not automatically cause Billabong to be rerun.

Any new code created in the presentation layer skeleton must be copied into the hand-edited code, and any necessary hand-edits applied.

If the conf file changes affect the business layer, Billabong and possibly Squirt may need to be re-run. Squirt will only need to be re-run if a QUERY section has changed.

If you have to run Billabong and haven't done any hand edits in the business area, it's safe to direct the output to the business area and use the OVERWRITE parameter when invoking the billabong script.

If hand changes have been done in the business area, then life becomes more difficult. You must direct the output of Billabong to another directory and cut'n'paste the necessary changes into the affected BO files. If an IDS is changed, it can affect a number of BO files. For and IDS with DATAFROM set to DATABASE, the PO-BO may be affected, as will as possibly a BDO-BO - look at the table related to the ACCESS for the IDS to determine which one.