JGuiGen ReadMe.html

JGuiGen - Java code that writes code
Generating "Elegant CRUD"

by
Hale Pringle Ed.D.
Vernon Singleton

Table of Contents
I. Introduction
II. Version and ToDo
III. History
IV. Getting Started - Obtaining the code and Menu options to generate an application
IVa. Getting Started - Linux Step by Step
IVb. Getting Started - Windows Step by Step
V. CREATING Edit Screens for your own Tables
VI. The CLASSPATH used by JGUIGEN
VII. JGuiGen - Accessibility and Internationalization
VIII. Logging and Error Handling
IX. Databases supported by JGuiGen
X. Using the Eclipse IDE and HSQL with JGuiGen
 XI. The XML ini file
 XII. JGuiGen Security and LDAP support
 XIII. The JGuiGen Java Code Generator
 XIV. Files & Jars used by JGuiGen
 XV. Java Web Start
XVI Linux considerations
XVII. Running the JUnit TestCases
XVIII. Replication - A General Purpose Replication System
XIX. Special Considerations for HSQL
XX. Special Considerations for MS SQL-SERVER
XXI. Special Considerations for Oracle (XE)
XXII. Special Considerations of PostgreSQL
XXIII. Special Considerations for MySQL
XXIV. Special Considerations for MS Access
XXV. A few notes on JGuiGen as Demo Swing Application Code
XXVI. A system for moving data from one Database to another
XXVII. A list of Tasks that programmers need to do in a Swing Application

I. Introduction


JGuiGen started of as an effort to create what we used to call "the usual" in xBase database development. Many developers found a need to take an existing table and create a very simple application that had the CRUD functionality. CRUD stands for Create, Read, Update, and Delete. There were several applications around that would allow you to point at a table and bingo you had "the usual." I found that in my java database work I often had need for "the usual." Even in very large projects, a considerable part of the effort went into creating applications to edit various tables. Current applications have evolved to where even "the usual" can be quite complex when it involves a SQL backend, users with different languages, etc.

JGuiGen is the result of my attempts to create a Java Usual. It is a system with six main parts.

  1. Data Dictionary - Table Documentation - A Data Dictionary system that queries the meta-data from an SQL database and fills a data_dict table with one row for each column in each table you are interested in. There is a GUI screen to add information about each column. The final step creates an HTML file that documents each table in the database in some detail.

  2. Useful Classes - There are a number of classes used in JGuiGen that may be useful in your applications. These are in the com.jguigen.standard folder and are described on the web site.

  3. Generated GUI Edit Applications - JGuiGen will generate an edit screen for a table in your database. It uses the data from the data dictionary table to create a screen that will view, search, add, edit and delete rows in your database. The generated code has the following pieces:
    • full CRUD functionality (insert, edit, view and delete) rows in a table
    • access to many swing visual classes (comboboxes, checkboxes, radio buttons, etc.) The developer uses the data_dictionary application to tell JGuiGen how to display each field on the edit screen.
    • Automatic use of special classes such as a pop-up calendar for hard to verify columns,
    • Immediate data verification and validation whenever possible (for example char fields can be given a limited length and a user will not be allowed to enter more characters than the given maximum length.)
    • Automatic (optional) generation of a table at the bottom of the edit screen which allow users to scroll and pick a new row to edit
    • Multi-user (automatically avoids having one user overwrite another user's changes),
    • User friendly (tools tips and helps automatically supplied),
    • Internationalized (I18N) - complete with a system to manage multi-language property files,
    • Accessible to the handicapped (A11Y),
    • Keyboard accessible without a mouse
    • Right-click pop-up menu with features like changing the language or the look and feel.
    • automatic creating of a duplicate row when desired (except for the id field)
    • Some tailoring of screen layout is allowed to help make the resulting application look and feel like the rest of your applications
    • Query-by-example visual query builder - with saved and reusable queries. This helps your user FIND rows in your database that they want to edit.
    • relatively simple to use user generated report system,
    • JUnit TestCases built in.
    • JGuiGen generates code that can be distributed using Java Web Start.
    • Automatic logging of activity and errors.
    • Automatic error handling and screens that show users what is going on.
    • Each entry screen "remembers" its last location and shape if a user resizes or moves the screen.
    • the resulting application runs without changes against at least six different SQL back-end databases.
    • the resulting application to run on Windows or *nix systems. While Java code always runs on different systems, code that reads and writes to system files must take into account differences between windows and *nix operating systems. JGuiGen does this.


  4. Swing Demonstration - The whole system is being used to demonstrate how swing components can be used in a real application. The application is documented and annotated on the web site in order to show one way that the many pieces involved in writing a database application can be put together.
    Here are some of the things that JGuiGen code demonstrates
    1. General Background items
      • Pluggable Look and Feel
      • Placement of window on screen and restoring when user next opens the window
      • Model versus non-modal windows
      • Running in Classes, Jars, and Java Web Start
      • Make your screen "garbage collectible" when it closes
      • Inherit from your own subclasses of Java classes
      • Do at least Model - View/Controller by using AbstractTableModel
      • Creating your own console for displaying SQL commands and errors
      • Interfacing JDBC and Swing Components - reliable updates and data integrity
      • Automatic fields such as date-row-last-changed or who-last-changed-row
      • JPanels inside JPanels
      • Cursor shape during long operations
      • Progress bar during long operations
      • Working with JPanel
      • Using a JTable in a GUI to select records
    2. Check that there are no unsaved changes before allowing window to close
    3. Border
    4. Internationalized code
    5. Accessible code
    6. Use a JTextField that does not allow too many characters to be entered
    7. Using a border to indicate required fields
    8. Making a field non-editable
    9. Placing tooltips on each components
    10. Forcing proper format of phone numbers - Cursor/Caret Placement in Component
    11. Hot Keys associated with JTextBoxes
    12. Loading data from SQL back end
    13. Replacing the Coffee Cup with your own image
    14. Changing the screen title

  5. A Java Code Generation System- The original version of JGuiGen basically used what amounts to print statements to generate each line of the java code being written. The current version reads lines from functioning java classes and does substitutions to create classes that are unique to your SQL tables.

  6. Data Replication System - as part of creating a business application with JGuiGen the need arose to create full blown gemeral data replication system. Since I built one of those some years ago I'm including in in the JGuiGen project.
CURRENT THOUGHTS/DIRECTIONS

When we create a Code Generator to we need some global guidelines. Here are ours.

  1. We must create code that works with databases. That is what JGuiGen is all about!
  2. We must use templates that are working code. We can tweak the working code until it has a new feature and when we generate a new class it will have this new feature.
  3. We must generate code that can be run be reflection. What we mean here is that we don't need to know all of the class names that we will be running at compile time. This enables data-driven applications to be built.
  4. We need to be able to generate rich GUI's that can include hand tweaking and hand-written code that we don't lose if we regenerate a class.
  5. We need to build GUI's that reflect reality - a developer might want to have a screen that contains fields from one table, other fields from related tables, other fields that summate yet other tables and buttons that navigate to places unknown.

We are getting close to meeting all of these goals. As a result of the Quick Create conversion we now have several new features

With the functionality JGuiGen already has. These additions cover Goals 1 through 4. Now we need to finish the 5th goal. Here are the steps we are working on.

  1. The first task is to get the Data_Dict Edit so that it compiles in Quick Create and keeps all of its current functionality - this will do most of the "Extra" class stuff described below.

  2. I have a whole new concept for the data_dict table. This table drives the GUI generation system. Historically there is a CHECK class that retrieves the meta-data from a SQL table and populates the data_dict table with one row for each column in the SQL table we are working with. We are going beyond this.
  3. The system will still start with a table in the SQL database and it will still go to the SQL database, retrieve the meta-data and populate itself from the actual SQL tables, but now it will center around a "class" and not a table. Hibernate and the Java Persistence API both use the concept of working with a POJO that is associated (persisted) to one primary table and you build a class around this. The ID of the POJO is the same as the ID of one row in one SQL table. In-other-words, the building block is an entity that is a class that is derived from one SQL table row. In order to go beyond that one SQL table is the data it contains, we need to expand what is put into our data_dict table. I am going to use two small tables in the example below so explain what we are doing. One is an employee table when an id number, an employee name (etc) and a department_id column that relates each employee to a one row in another table. This is the department table. JGuiGen's data_dict table is automatically populated with rows for each column in both of these tables. There is an employee/id row, an employee/name row, an employee/department_id row etc. There are also row from the department table such as department/id, department/name, etc.

    After the next set of updates when you look at all of the rows associated with a class you will see five types of rows in our data_dict table.

    1. a "class-level" row where we describe a whole class - we have these now. This row does not relate to one column in the originating SQL table. There would be an employee-class row and a department-class row using our examples. There might actually be several class rows that focus on the employee or department tables. If so there would be one class-level row for each of these classes.
    2. rows associated with a particular column in the main table this class is centered around (we have one set of these now). In the next generation there will be one set for each of the class-level rows described above. If there are two classes that focus on the department table there will be two sets of rows in the data_dict table.
    3. rows that describe derived transient visual components (textboxes, listboxes, comboboxes, etc that are sums, or counts, etc) that come from this table. These are not persisted since they don't really have a column to save them into. These might also be visual components (like a button) that lets the user navigate to s class in the application that has nothing to do with the current class/table. In this case we just need a way to tell JGuiGen to generate a button on the screen and attach a listener to it. We'll put the functionality (whatever it is) in manually. JGuiGen has a GUI for editing the data_dict table. This GUI will allow the developer to add these rows by clicking on an ADD button and indicating what type of transient field and visual component they want added to the generated GUI.
    4. rows that describe transient visual components that come from related (as in "relational database") tables. The rule here is that we need a table where we have a foreign key that relates to one current row in our primary table and we are dealing with a many-to-one situation. For example, we might have a department_id in an employee table, and what we want to see in the GUI is a combobox with the employee's department name. (We don't save the department name in the employee table, just the department_id number) (See our discussion of form-field-pickList elsewhere). The bottom line is that we will put a row into the data_dict table for the employee class that has classname = "employee" and a tablename = "department". This visual component will show up when we sort the visual components and when we edit what type of visual component we want. It will act just like it was a column in the employee table (except when it is populated and persisted.)
    5. last-but-not-least we have rows that are transient and derived, but the data come from tables other than our primary table and they don't meet the many-to-one condition required by the previous type of row. These again will usually be sums, totals, date-last-edited, status, etc. For example we might have a department table. The department table contains department head, address, phone number, etc. We also have an employee table which contains all of the employees. Several rows in this employee table "belong" to each department row in the department table. We would have a row in our data_dict table that has a classname = "department" and a tablename = "employee". We would have the SQL snippet that indicates how the visual component we will put on the GUI is to be filled and we might fill the visual component with a count-of-how-many-employees are in the department. This is a one-to-many situation where there isn't one row in the related table. In this case there are many but they are still related.

    Getting to this point requires several steps.

  4. The next task is to get the Data_Dictionary CHECK class so that it adds one set of rows to the data_dict table for each class we tell it we are going to associate with the table. (Talk about this.)
  5. Then I am going to allow us to add rows to the data_dict table that describe visual components that are not associated with a column in the table. In hibernate terms these are transient variables. We can use hibernate to populate these components with sums, counts, maxes, combo box links to another table, etc.
  6. Then I can see adding rows to data_dict that come from tables that belong to other tables where there is a foreign key that links them tightly to the main table.
  7. The last addition will be links to other tables - form-field-PickList and one-to-many we-own-these rows type screens (one bid to all of the bid-items that make up the bid)

  8. This brings us to adding hibernate. This is vital to the process since it handles a LOT of the behind the scene work which means that I don't have to do it.
    • automatic joins to multiple tables showing up as if they were one table in a JGuiGen edit screen.
    • automatic filling of visual components with data from other tables
    • automatic access to more back end databases (they handle differences in dialect, finding the new id numbers, finding the id of the row just added, etc.)
    • transactions
    • cascading data inserts, updates and deletes into secondary tables
    • caching
    • automatic collections taken from other sources (tables, XML, etc.)
    • blob, clobs, etc.
    • "respectability and main stream java" flavor instead of "out-in-our-own-world" or "Not-invented-here"
    • automatic updating table schema at remote sites.
    • when we have a foreign key we can treat two tables as if they were one and show all of their columns (that we want) in one GUI screen. Hibernate will handle getting the data, transactions, saving the data and inserting the data.
  9. I putting the JavaBeans into their own classes. I have naming questions
    • For example I18N and Codes Band use the same table with a discrimination column that contains "i18n" or "bank" I have already stared that we will have two sets of rows in the data_dict table so that we can using different rules for a column for each class. (A string might be a combobox in one class and an textbox in the other. OR one might be a major playing in one class and be marked "not-in-use" in the other.) Now how do I name these things.
    • Userlogdata has a whole set of fields that are just used for the SQLWhereclause query screens. There is a discriminator column that marks these rows as different from the "user" rows. Again - separate into another table or double-book and if double-booked how do I name the JavaBeans?
    • I can see having one JavaBean for an entire table and then secondary JavaBeans that describe the components that we build out of the main JavaBean (selected columns used in special ways, some columns ignored completely, etc).
  10. I can see adding a column to the data_dict for marking columns as foreign keys and indicating which table they are a foreign key to.
  11. Many-to-One - Form-Field-PickList - combobox and button - open a new JGuiGen screen. (perhaps with the table portion dominating the screen unless you click on EDIT. ) Have a PICK button. The combobox can be loaded with one "name" to start with (based on the current id the our table) when you click the down arrow in the combobox, hibernate populates the drop down and gives you more options. The main get-all-names call never happens unless you click the combobox drop-down.
  12. One-to-many - Sum/Count/Status/Date - Button - Click the button and open a new JGuiGen Screen. (I can see vertically split screens with a JGuiGen screen on left and a different JGuiGen screen on the right. Bid on the left, bid-items on the right.)

NOTE:I should note that as I read articles on programming I see places where authors explain at great length why it is not best practice to do some of the things I do in JGuiGen. Some of these I agree with (and have reasons for ignoring) and some I disagree with. You need to make your own decision.

II. Version - This is Version 1.08 06/28/2006

To Do

  1. See the previous section for current thoughts and directions.

  2. Add Data Replication to the system

  3. Switch data access to hibernate

  4. Work on Form - Field - Pick List. This concept allows our GUI to have a field that is taken from another table. Their is a button beside this field and clicking it opens an edit screen for the second table. For example you might have a combo box called customer. The list of avaiable customers for this combobox come from a table called customers. Clicking on an EDIT button beside the combobox opens an edit screen of the cusotmer table. You can edit data or add another customer.

  5. Change the data Javabeans so that they contain the lists used to feel JComboBoxes and JLists. Use the same format used by JSF. Make the data JavaBeans into a separate class.

  6. Make the generated applications run without access to the JGuiGen_I18n table and the Codes Bank table. Maybe do the same with the UserLogData table.

  7. Finish Code Validation (the Minimum/Maximum, field length) code in the generator.

  8. Modify JGuiGen so that it creates a web page CRUD editor (JSF) at the same time it creates a swing application.

  9. Clean up some of the code (make more things Private, etc.)

  10. Add Date Fields to the SQL Query Builder

  11. Get the Split Screen code working.

  12. Get a tree working

  13. Look at jgoodies code and see what we could use.

  14. Incorporate more of the snippets from the book Swing Hacks into JGuiGen (liquid buttons, status bar, different fonts, etc.)

  15. Handle blobs, clobs and other large fields

  16. Create some sort of working backup to activate from the main menu.

  17. Deal with moving the id column in the JTable

  18. Finish the code generator. We are taking most of the code from existing working java classes. I need to finish taking the parts of JBoundedText fields, jFormattedTextFields, etc. from an existing class instead of hard coded print statements.

III. History

-  6-20-2006 - Refoactored. Got rid of menu options to create a table. Now the Quick Create screen allows you to select a class and push one button. It generates, compiles, and runs the new class. You can edit Class level changes or column level changes. Close tha new screen and click the create button to generates, compile and run again.

4/20/2006 - Refactored and added Mark Tables Menu option (instead of editing XML file)

4/10/2006 - Separated the Edit Class Description into its own menu option. It was just a tab in the screen that mostly dealt with editing column data.

4/2/2006 - Finished the LDAP and encrypted password code. JGuiGen will now check a password against a hash stored in an LDAP store. It then unencrypts the database username and password needed to access the SQL backend.

3/28/2006 - The main code is now read from a template called /Template/MainSource.java. This is a working java class that has been annotated to supply the guts of the JGuiGen generated class.

1/23/2006 - Added ability to create a tabbed screen automatically.

 ;; 1/23/2006 - Refactored Data Dictionary Application into separate Sections.

 ;; 1/10/2006 - Added OracleXE to list of databases supported.

 ;; 1/4/2006 - Added MS SQL-SERVER to list of databases supported.

 ;; 1/2/2006 - Cleaned up and expanded the I18N code. For example it now automatically checks for duplicated prompts in the JGuiGen_i18n table.

12/20/2005 - When the scrolling table is filtered and a row is deleted, redisplay the scrolling table using the filter.

12/19/2005 - Enhanced the FIND utility (SQLWhereClause builder). Some tables never delete a row. Rows are just marked as "inactive." The query builder now lets you look at the inactive rows.

 ;; 4/29/2004 - added the ability to save queries and rerun them later.

Added a link to the JFreeReports system. You can take the JTable that is part of the normal edit screen, drag the columns around until you are happy and then print a report based upon your layout.

4/7/2004 - Modified the I18N routine. See the section on Internationalization.

Removed some of the code from the generated files. For example the code that actually builds the layout of the screen is now in its own class file. This is written the first time you generate an application. From then on it is not overwritten. This allows you to manually set up the screen the way you want and if you regenerate the application these changes are not lost.

Enhanced the Find routine.

Added a Duplicate current row, NEXT and PREVIOUS button to the pop-up menu.

When you save changes, these changes are reflected immediately in the JTable that displays the rows. This was done without re-reading all of the data and rebuilding the JTable.

Added an EXTRA button to each application. This button activates a separate class. The first time the application is generated this class is written out with dummy code. You can add functionality to this class and it will not be overwritten if the application is regenerated. You can change the name from "eXtra" using the I18N table edit described above.

Added another demo application to the sample application. This is an inventory edit screen that uses the extra button to merge table information into an HTML template. This template creates an ad for eBay. The Extra button also has an option that writes the necessary data out to a CSV formatted text file for import into eBay's Turbo Lister program. Using this system you can keep track of inventory, build ads to auction the inventory and automatically send the ads to Turbo Lister. Turbo Lister allows you to double check your work and upload the ads to eBay when you are ready for the auctions to start.

 ;; 10/7/2003 - Removed JGuiGenIni.xml, JGuiGen.Java, com/halepringle/src/UserLogData.Java, com/jguigen/standard/Model.java and com/jguigen/standard/DBMaster.java from the CVS repository and renamed them to *.javatemplate. ; These three files were added to the CVS repository. ; A setup.bat and a setup.sh file were also created.  The batch/script files copy the template files into their proper place.  The net result is that changes to the xml file, UserLogData.java,  JGuiGen.java, Model.java and DBMaster.java are not updated into the CVS repository.  Since these files are edited by each project in a unique way, this is desirable behavior. ; In order to commit a change to the repository so that every new project will have the change, the javatemplate files must be updated.

 ; 10/10/2003 - automated some steps that required cut and paste.  The steps automatically insert code into the XML file and the Model.java file as needed now.

IV. Getting Started - Obtaining the code and Menu options to generate an application

A. OBTAINING A COPY: 

Java Web Start - When I reactivate it you will be able to download an sample executable JGuiGen using Java Web Start (JAWS) on the SourceForge web site. Right now this is not functioning

The classes downloaded via JAWS will automatically unjar a copy of the necessary data base using Hypersonic SQL (hsqlhd on SourceForge.net).
It will also automatically unjar a copy of the XML file that contains setup information JGuiGen uses when an application starts up (JGuiGenIni.XML).

The XML file contains references to the JDBC Driver, the data base URL, the account to use to open the data base, etc.

There are currently URLS, Driver setups, etc. for six different backend SQL databases in the XML setup file (JGuiGenIni.xml). The set pointing to the 1) HSQL database is live. The xml properties pointing to the 2) MS Access, 3) PostgreSQL, 4) MS SQL-SERVER, 5) OracleXE, and 6) MySQL databases are commented out. You can edit the XML file and run the application against the other database types. See the sections below for information about running against PostgreSQL, SQL-SERVER, Oracle, mySQL and MS Access databases.

Full Copy -  You can copy down a full copy of JGuiGen from the HalePringle.com web site.  You will need to unzip the three files  ; There are more instructions below. 

SVN Repository on SourceForge-  You can obtain the most recent code from the SVN repository.  If you have installed subversion you can download a working copy of everything with the following command
svn checkout https://svn.sourceforge.net/svnroot/jguigen/JGuiGen/trunk jguigen
In this case the last word is the name of the folder that svn will create with this project installed. You can look at a video that walks through the steps at http://sourceforge.net/projects/jguigen or
http://vernon.is-a-geek.org/mediawiki/index.php/JGuiGen_Demo_with_Hale%27s_notes
Note: the PostgreSQL data base on my web site are not currently active. I will reactivate it upon request.

B. WHAT TO DO FIRST

Java Web Start (JAWS) - When you launch JGuiGen with JAWS the sample program runs automatically. (You will be asked to okay a certificate from Hale Pringle that is not verified. You will need to say it is okay for the system to download and run.)

Full Copy and SVN versions-  After you download and unzip the full copy.
run build.bat or ./build.sh
  This sets up a classpath and compiles the code.
Then run run.bat com.jguigen.standard.JGuiGen or ./run.sh com.jguigen.standard.JGuiGen to run the main application. You can run run.bat com.halepringle.src.JGuiGenDemo or ./run.sh com/halepringle/src/JGuiGenDemo to run a demonstration of what JGuiGen generates. There is more information below. I use the Eclipse IDE and there is a section below that describes running JGuiGen from this IDE. Other IDE are similar.

Edit JGuiGenIni.xml file - After you start you may want to use a text editor and edit the JGuiGenIni.xml file.  There is a list of users in this (you will see Hale, Vernon, and Tester already there.)  You may want to add your name to this list. ; If you don't modify the file, you can use any of the three names that are already there and the system will run using the HSQL tiny database system.

WHEN YOU FIRST RUN the JGuiGen.class- you will be asked to point to the path to the executable file that runs your browser of choice and your word processor/editor of choice. When one of the applications needs to show you something in HTML format it will invoke the file you point to. You will only need to do this once per machine.  Typical paths are shown in the prompt when you are asked to pick the path to your browser of choice.

Running the sample JGuiGen Application - The Main JGuiGen screen will come up. If you want to see what a generated screen looks like click on USERS --> View JGuiGenDemo. This will bring up a sample screen that has been generated by JGuiGen. This screen demonstrates virtually all of the special features that JGuiGen can generate. These are covered in some detail on the web site.

Creating a JGuiGen generated application You can click the Create button on the main JGuiGen screen. This will bring up what we call the Quick Create screen. Options in the Create Screen

  • COMBO BOX of tables- Pick a table to work with
  • CREATE - click on this button and a class is written, compiled and executes. You will see it immediately. You can use the other buttons on the Create screen to modify the data dictionary which was used to drive the creation of the class. Then you can close it and click the CREATE button again to see how you changes worked. From a command prompt use run src.[your classname] or ./run.sh src.[your class name] to run the class you just created.
  • REFRESH - See a list of tables in your SQL database and indicate which ones you are interested in working with. Runs the method that updates the data dictionary table with the current meta data from the SQL database you are using.

    The buttons on this screen are grouped. The first group are actions that will edit the entire class you just created.

  • CLASS - This is where you indicate things about the entire class you will generate. Click the HELP button for more information about the options available here.

  • ORDER - This button presents a screen that allows you to sort the columns in a table into an order that will be used in the generated GUI Edit screen.
  • OverWrite Table Model - This checkbox allows you to tell the system that you do not want the tablemodel class associated with the class you are generating overwritten.
  • OverWrite BuildLayout - This checkbox allows you to tell the system that you do not want the BuildLayout class associated with the class you are generating overwritten.

    • The second group of items is the Column Level edits. These allow you to modify things about one visual component in the GUI that is ued to edit one column in the SQL table.

  • Column - You can click on different rows in the JTable at the bottom of the screen and edit to add comments, notes, indicate which type of java class to use when editing this field (i.e. combobox), how the data should be validated, etc. Click the Help button for more instructions about the options available here.

  • Internationalization - This screen lets you modify the screen prompts for the application you just created.

  • Codes Bank - Some fields in the generated code will be edited using Visual components such as JLists, JComboboxes or radio buttons. The components need a place to find their data. The codes bank is where JGuiGen stores these values. Access to the Codes Bank table occurs in the Column Edit screen when you need it.

NOTE: ; If you using the version of JGuiGen that was downloaded by JAWS and you want to compile the generated code and try it yourself, you will need to do several things.

  1. Make sure the jars required by the project are in your CLASSPATH - see the classpath section below.
  2. CD to the folder where JAWS put the project.  JGuiGen will create a cd2JGuiGen.bat and cd2JGuiGen.sh file in your home folder to help since this folder is a LONG way down.  (Note: on Linux run the cd2JGuiGen.sh as   . ./cd2JGuiGen.sh - note the dot before the script name.)
  3. run the jawsUnjar.bat or jawsUnjar.sh.  This will pull the com.jguigen.standard folder and the properties files out of the jar that Java Web Start downloaded.
  4. compile  - javac com\halepringle\src\UserLogDataTableModel.java
  5. compile  -   javac com\halepringle\src\UserLogData.java
  6. run java com\halepringle\src\UserLogData   or JGuiGen
  7. You can also compile the UserLogDataAbstractTestCase.java file and the UserLogDataTest.java files and then run with java UserLogDataTest.
    8.


C. Running the samples already in the Jar file.
The third menu option in the main JGuiGen application (USERS) already has menu options to run UserLogData.class, JGuiGenDemo.class and an empty class called Tester. JGuiGenDemo is a JGuiGen generated screen that has been tweaked a little like a developer would normally do to create a production version of the code generated by JGuiGen.   When the project is shipped there is a dummy UserLogData class file included so that the JGuiGen file will compile.  You will overwrite this file if you generate your own UserLogData.java file.  


The final menu option under the second menu option lets you see the resource bundle file.

Linux - Step by Step

Notes are specific to Fedora Core 4 - adjustments may be necessary


I. First we need to download a more current version of Java. The 1.4.2 version that comes with Fedora is not current enough to run JGuiGen.
1. Navigate to javasoft.com
The RedHat user forums indicate problems with Linux and Java 1.5. We have used it successfully. You can use it or you can go with 1.4_2_10
2. If you want 1.4.2_10, Search (Upper left corner Download 1.4.2_10

  • Download the SDK (System Developer Kit) or JDK (Java Developer Kit) as they are now calling it, not the Java Runtime Environment (JRE)
  • Accept Certificates (twice)
  • Click on Accept
  • Download Linux Development Kit 1.4.2_10
  • I pulled down SDK 1.4.2_10 and NetBeans bundle. This gave a very nice Installshield install
  • Editing ~home/.bash_profile
    added /opt/j2sdk1.4.2_10/bin: right after PATH= line became PATH=/opt/j2sdk1.4.2_10:
  • Preferences - On Linux java stores system preferences (backing stores) in two places
    1. java.util.prefs.systemRoot (/etc/.java/.systemPreferences)
    2. java.util.prefs.userRoot (/home/username/.java)

    We have tried to make sure that JGuiGen does not access the systemRoot preferences file. If by some chance this changes you can run the program once as the root user and the folders will be created.

    You will need to give your users read/write rights to these two places. JGuiGen saves things like the Look and Feel and Color Scheme that a user prefers in the UserRoot. It does not save anything (currently) in the systemRoot. On the other hand the folder must exist or you get an error that I cannot trap for. See http://www.allaboutbalance.com/disableprefs/ for more information about this "problem."

  • We will need to set some places in Eclipse in order to use this version.

II. If you want and Integrated Development Environment (IDE) you will need to download Eclipse

  • Download eclipse from eclipse.org (I found that the motif version worked better than the GTK version. Your mileage may vary. I am running the GTK version 1.3 and so far there are no problems)
  • Again the RedHat forums say copy down the executable NOT the RPM in executable
  • tar zxf eclipse-SDK-3.1.2-linux-motif.tar.gz or gunzip eclipse-SDK-3.1.2-linux-motif.tar.gz and tar xvf eclipse-SDK-3.1.2-linux-motif.tar
  • Right Click the desktop and add an application
    command is /Downloads/eclipse/eclipse
    icon is /Downloads/eclipse/icon.xpm
    workpath is /Downlods/eclipse

When it comes up make sure it says Eclipse 3.1 If it says Native Eclipse and has Fedora on the splash screen you are not running the new one.

NOTE: See the section on Eclipse below. There is one change in the Elcipse environment that you MUST make in order for Eclipse to run JGuiGen correctly.

III Download the source code

  • Best is to get the newest from sourceforge.net. Most of my Fedora boxes already had subversion loaded so the entire process involved typing one line
    svn checkout https://svn.sourceforge.net/svnroot/jguigen/JGuiGen/trunk jguigen
    This creates a folder called jguigen under your home (or wherever you were when you ran the file.) If you use this option you only need to unzip JGuiGenMisc.zip
  • You can also go to the sf.net/projects/jguigen web site and download the zip files containing the latest "released" copy of JGuiGen.
  • Unzip them.

IV Running Eclipse

  • Start up Eclipse 3.1

    I kill the Welcome Screen (red x on its tab)
    Click on Window --> Open Perspective --> Debug
    Now you will see two tabs in the upper right. You can switch back and forth.
    The Java Perspective has the nice tree for opening files
    The Debug Perspective allows you to "Terminate and Remove Threads" (Right click on a thread in the upper left and click on Terminate and Remove.
    You will need this because HSQL (the sample database in use) is truly single-user. If a thread hangs you can't open it again until that "user" goes away.
  • Click on File --> New -- Jave Project --> Next and enter JGuiGen change the "Open new project in Workspace" to "Create project from existing source" and browse for the folder you placed JGuiGen in. When I got to the JGuiGen folder I clicked on the ADD button to add that folder to my favorites list.
    The first time I did this I clicked on Finish at this point. It failed.
    The second time I chose Java Project under Java (not the top Java Project) and I clicked on Next instead of finish.
  • You will need to add the Java Run Time that we down loaded
    Click on Window Tab --> Preferences --> Installed JRE's I had to add /opt/j2sdk1.4.2_10 and put a check mark by it to make it live
  • NOTE: This is important. You MUST do it. Click on the JGuiGen at the top of the tree in the left hand panel in the Java Perspective. This opens the tree. Go down to the folder work and work.src. Right click each one and click on the CLASSPATH--> Remove option for each. If these folders are in your class path Elcipse will NOT be able to run classes you generates.
  • If I have forgotten to remove the ojdbc14.jar from the Build Path (again) You will see an error at the bottom of the screen that tells you that the jar is missing from the Build Path. Right click on the JGuiGen in the upper left of the Java Perspective. Click on Properties and Java Build Path Click the Libraries tab and remove the ojdbc14.jar. This is Oracle JDBC file and they won't let me send it unless I agree that I won't let people from foreign countries that the US doesn't like download it. I can't possibly stop them so there we are.
  • NOTE: You will need to add three more JARS to the BUILD PATH
    Right Click on JGuiGen Project (upper left in Java Perspective)
    Preferences --> JAVA Build Path --> External Jars --> Add
    add these two /opt/j2sdk1.4.2_10/lib/jce.jar
    /opt/j2sdk1.4.2_10/jre/lib/jsse.jar
    /opt/j2sdk1.4.2_10/lib/tools.jar
    - this is the compiler.
    Note: You will need to change the JRE and add these three external jar
    files every time you download a complete copy of the source. If you do not unzip JGuiGenMisc.zip you will not need to modify the class path again.
  • click on the little arrow beside the Yellow Arrow Pointing down Uncheck the "Warnings" now clicking on the Yellow Down Arrow takes you to the next error in the file.
Once it is happy it is going to build the whole project. Look in the lower right corner of the screen if you see a small progress bar with 10%, 20% that is what is going on. Sometimes it seems as if things have hung when in fact it building the project.

V. Running the Application in Eclipse

See the section about running JGuiGen in the Eclipse IDE for setup instructions.

Click on the plus beside the JGuiGen Package (upper left corner of Java Perspective

Click on the plus be Default Package

Double Click on JGuiGen.java
Click on arrow beside the green circle --> run --> as Java Application
One of the first steps should be run the JGuiGenDemo under the Users mens option.
You can then generate UserLogData using the options under Data Dictionary.
After the UserLogData files (model java code and main class java code) have been generated, you will need to right click on the JGuiGen Project in the upper left corner of the Eclipse Java Perspective. Choose "Refresh" and Eclipse will find the new java files in the com.halepringle.src folder. User projects choose "Build Project" or "Clear" to compile all of the new files. You can then run UserLogData on the Users menu option.

VI. Running from the command line

We have created two shell scripts ./build.sh and ./run.sh.

  • You will need to modify you system to include a JAVA_HOME environment variable before you can compile the code. JGuiGen requires access to the tools.jar that is supplied with the JDK; however java can't find the jar unless the JAVA_HOME is set.
  • Here's an example of how you might edit the userconfig.sh file: JAVA_HOME="/usr/local/j2sdk1.5.1" export JAVA_HOME

    or

    JAVA_HOME="/usr/java/j2sdk1.4.2_10" export JAVA_HOME

  • ./build.sh will compile the complete JGuiGen application.
  • ./runJGuiGen.sh to run the JGuiGen application (work/src is not in the classpath)
  • ./run.sh com/halepringle/src/JGuiGenDemo will run a Java Class generated by JGuiGen ./run.sh src.[yourClassName] will run a class you generate with JGuiGen.(This version includes work/src in the classpath.)

VI. Accessing HSQL database

  • Open a Terminal Window
  • chmod a+x runUtil.sh
  • ./runUtil.sh DatabaseManager
  • Fill in JGuiGen on second line
  • Change from "In Memory" to "Standalone"
  • Change the <> to JGuiGenDb
    note the Db on the last line The next time you can get JGuiGen from the list at the top of the screen and you won't have to reenter the Standalone and the database name
  • You can run SQL statements in the widow and click on Execute

Windows - Step by Step

Notes are specific to Windows 2000 Pro - adjustments may be necessary


I. First we need to download a fairly current version of Java.
Navigate to javasoft.com
You need to have a later version of 1.4_8 (or so) or Java 1.5. If you decide on 1.4.2_10 (the last version of 1.4, you will need to search for the download using the search area in the upper right corner of the screen.

  • Download the SDK (System Developer Kit) or JDK (Java Development Kit as they are calling it now) not the Java Runtime Environment (JRE).
  • Accept Certificates (twice)
  • Click on Accept
  • Download Java Development Kit 1.4.2_10 or Java Development Kit 1.5.?
  • The last time I pulled down a version it was the SDK 1.4.2_10 and NetBeans bundle. This gave a very nice Installshield install
  • Editing your path: You may need to go to Control Panel --> System --> Advanced --> Environment variables and change the PATH to point to your new version of Java.
  • You will also need to set a new System environment variable here called JAVA_HOME You set this variable equal to the root path where you installed java. For example if I type SET in a command prompt I see a list of environment variables. In this list is JAVA_HOME=c:\j2sdk1.4.2_10
  • We will need to set some places in Eclipse in order to use this version.

II. If you want an Integrated Development Environment (DE) you will need to download Eclipse

  • Download eclipse from eclipse.org
  • The version you download will be a zip file that you can unzip where ever you want eclipse to reside. There is nothing more to the install.
  • I usually right click the windows start button --> Explore and navigate to where I unzipped Eclipse. I find Eclipse.exe and right click on it. When I choose the "Send to --> Desktop (Shortcut button)" the system places a shortcut on my desktop.


When it comes up make sure it says Eclipse 3.1

III. Now we download the source code

  • Best is to get the newest from sourceforge.net. You will need to download a subversion client I used Tortisesvn from http://tortoisesvn.tigris.org/
    Tortisesvn merged into your windows explorer. Open the windows explorer and create a folder. Highlight the folder and right click. You should see a Tortisesvn Checkout option. Click on that and fill in the information. The "URL of Repository" is https://svn.sourceforge.net/svnroot/jguigen/JGuiGen/trunk Then "Checkout Directory" should already be filled in. The only other things that should be checked is the "HEAD Revision" checkbox. If you download a command line client the command will be
    svn checkout https://svn.sourceforge.net/svnroot/jguigen/JGuiGen/trunk jguigen
    This creates a folder called jguigen under your home (or wherever you were when you ran the file.) If you download using subversion you only need to unzip JGuiGenMisc.zip
  • Alternatively you can Go to www.halepringle.com --> JGuiGen (tab on left side) at the bottom of the screen download JGuiGenCode.zip, JGuiGenJars.zip and JGuiGenMisc.zip 5, 11 and 1 meg or thereabouts
  • Put these where you want them. I created a folder called JGuiGen under my JProjects folder and put them there.
  • Unzip them.

III Running Eclipse

See the section below for instructions on setting up JGuiGen in Eclipse.

  • Start up Eclipse 3.1

    I kill the Welcome Screen (red x on its tab)
    Click on Window --> Open Perspective --> Debug
    Now you will see two tabs in the upper right. You can switch back and forth.
    The Java Perspective has the nice tree for opening files
    The Debug Perspective allows you to "Terminate and Remove Threads" (Right click on a thread in the upper left and click on Terminate and Remove.
    You will need this because HSQL (the sample database in use) is truly single-user. If a thread hangs you can't open it again until that "user" goes away.
  • Click on File --> New -- Jave Project --> Next and enter JGuiGen change the "Open new project in Workspace" to "Create project from existing source" and browse for the folder you placed JGuiGen in.
  • You may need to add the Java Run Time that we down loaded
    Click on Window Tab --> Preferences --> Installed JRE's I had to add c:\j2sdk1.4.2_10 and put a check mark by it to make it live
  • NOTE: This is important. You MUST do it. Click on the JGuiGen at the top of the tree in the left hand panel in the Java Perspective. This opens the tree. Go down to the folder work and work.src. Right click each one and click on the CLASSPATH--> Remove option for each. If these folders are in your class path Elcipse will NOT be able to run classes you generate.
  • If I have forgotten to remove the ojdbc14.jar from the Build Path (again) You will see an error at the bottom of the screen that tells you that the jar is missing in the Build Path.
    Right click on the JGuiGen in the upper left of the Java Perspective. Click on Properties and Java Build Path
    Click the Libraries tab and remove the ojdbc14.jar. This is Oracle JDBC file and they won't let me send it unless I agree that I won't let people from foreign countries that the US doesn't like download it. I can't possibly stop them so there we are.

    You will also have to change the folder where Eclipse finds the /jre/lib/ext/jce.jar and the /lib/tools.jar

    Note: You will need to change the JRE and add these three external jar
    files every time you download a complete copy of the source. If you do not unzip the JGuiGenMisc.zip file you will not need to update the classpath.

  • click on the little arrow beside the Yellow Arrow Pointing down Uncheck the "Warnings" now clicking on the Yellow Down Arrow takes you to the next error in the file.
Once it is happy it is going to build the whole project. Look in the lower right corner of the screen if you see a small progress bar with 10%, 20% that is what is going on. Sometimes it seems as if things have hung when in fact it building the project.

IV Running the Application in Eclipse


  • Click on the plus beside the JGuiGen Package (upper left corner of Java Perspective

  • Click on the plus be Default Package

  • Double Click on JGuiGen.java
  • Click on arrow beside the green circle --> run --> as Java Application
  • One of the first steps should be run the JGuiGenDemo under the Users mens option.
    You can then generate UserLogData using the options under Data Dictionary.
  • After the UserLogData files (model java code and main class java code) have been generated, you will need to right click on the JGuiGen Project in the upper left corner of the Eclipse Java Perspective. Choose "Refresh" and Eclipse will find the new java files in the work.src folder. User projects choose "Build Project" or "Clear" to compile all of the new files. You can then run UserLogData on the Users menu option.
  • NOTE: Since we moved the generated classes out side the classpath, Eclipse will not compile them. This is not usually a problem becuase JGuiGen compiles them as part of the generation step. If you do make manual changes and want to compile them there are two ways. 1) Opea a command window and use the buildwork.bat file listed below. 2) Include the work and work.src folders in Eclipses classpath. Change the package for all the files in the work.src folder to work.src instead for src. Use Eclipse normally.

V. Running from the command line

We have created three batch files build.bat, run.bat. and buildwork.bat

  • build.bat will compile the complete JGuiGen application.
  • run.bat com.jguigen.standard.JGuiGen will run the JGuiGen application
  • buildwork.bat run compile just the folder where generated code is placed. This should already be done inside JGuiGen, but it you make manual changes you will need to use this compile.
  • run.bat com/halepringle/src/JGuiGenDemo will run a Java Class generated by JGuiGen run.bat src.[yourClassName] will run a class you generated with JGuiGen.

VI. Accessing HSQL database

  • Open a Command Window (Start button --> All Programs --> Accessories --> Command )
  • runUtil.bat DatabaseManager
  • fill in JGuiGen on second line
  • change from "In Memory" to "Standalone"
  • change the <> to JGuiGenDB
    note the DB on the last line The next time you can get JGuiGen from the list at the top of the screen and you won't have to reenter the Standalone and the database name
  • You can run SQL statements in the window and click on Execute

V. CREATING EDIT SCREENS USING JGUIGEN in your own projects

.

You will need to download the source code
After you have tried the sample in the Java Web Start folder, you are better off downloading the source and setting up your own project and running from there.  You can either download the three zip files or use the SVN repository on SourceForge.net.

The following steps are all described in more detail in the manual and on the web site but here is a brief overview of the steps involved in creating a real application. You will be able to skip a number of these steps when you run the samples and examples that come with JGuiGen.

  • Download the source to JGuiGen,
  • change the XML file to point to your database and add your users,
  • add the userlogdata, data_dict table and the JGuiGen_I18N table to your database,
  • populate the userlogdata, data_dict and JGuiGen_I18N tables (there are SQL Create-Table scripts and Java classes available to help you do this in the SQL folder under JGuiGen),
  • If you don't have a table you want to edit you will need to create one. There are sample "CREATE TABLE" scripts in the SQL folder of JGuiGen and this manual makes suggestions about database managers you can use for this task when it discusses the various databases.
  • Use the JGuiGen --> Create otion to create an application. ************************************
    NOTE: JGuiGen requires one special field to be identified and works best if three other fields are available.
    1. integer ID field. This field must have a check mark in the "Primary Key" box and should be the first column when the table is sorted. JGuiGen will mark the first column name that it sees with the format anything_id (the underscore id are the trigger characters.)
    2. a lastchangedate field - JGuiGen uses this to mark each row with the date/time the row was lasted updated. This is used to help avoid multi-user conflicts and for tracking down problems in your data base later. If JGuIGen finds a timestamp field with the name lastchangedate it will automatically mark this column to for this use.
    3. a lastchangedby field - JGuiGen will put the user name of the person who last updated each row. If JGuiGen finds a character field with the name lastchangedby it will mark this column for this use.
    4. a isremoved field. If you want rows to be marked as "removed" when the user asks to delete a row then you will need a column that is used to indicate that a row is removed. If JGuiGen finds a boolean or integer column named isremoved it will default the column for this use.

    You can override any of these default marking if they are not what you wanted.
    *****************************************
  • Generate the Application
  • edit/test/tweak the generated java code,
  • edit the Internationalization screens as necessary, and
  • merge the java code into your application. There are comments in the "main" method you generated that explain what should be copied into a menu listener to call the class you generated.

In normal development, I use the Eclipse (from eclipse.org) and run the DataDictionary application in com.jguigen.standard directly from the IDE and run the applications generated directly.

VI The CLASSPATH used by JGUIGEN:


JGuiGen uses a number of packages from other sources.  These will need to be in your CLASSPATH.  In Eclipse, I checkout the project and then Right Click on the Project --> properties.  One of the options is BUILD CLASSPATH.  I add them all by clicking the top one and shift-clicking the bottom onw in the "Add a Jar" option.

The jar files needed in the JGuiGen classpath are all located in a lib folder under the main JGuiGen folder. The build.sh, build.bat, run.sh and run.bat files all have code that automatically creates a classpath using the jars that are currently in the lib folder. In addition, after you have generated a class there in a YourClassName-manifest.mf file in the lib folder that contains one line that contains this class path if you need something to cut and paste from.

  • jdom.jar       - needed to read the JGuiGenIni.xml file
  • jh.jar            - java help system
  • pgjdbc2.jar - the JDBC 2.0 driver for PostgreSQL
  • xerces.jar     - the XML parser used to read JGuiGenIni.xml file
  • jaccess.jar    - part of the package used for making applications accessible (A11y).
  • jscroll-1.0.2.jar - a package for creating scrolling panels - not really used at the moment.
  • junit.jar         - the de facto testing facility for java.
  • jfcunit.jar      - an addition to junit - used for GUIs.
  • jakarta-regexp-1.2.jar - used by jfcunit
  • hsqldb.jar     - the JDBC driver, DatabaseManager application and files need to access a HSQL database.
  • mysql-connector-java-3.0.11-stable-bin.jar - JDBC driver for MySQL
  • bsh-1.2b6.jar - part of JFreeReports
  • gnujaxp.jar - part of JFreeReports
  • itext-1.00.jar - part of JFreeReports
  • jcommon-0.9.1a.jar - part of JFreeReports
  • jfreereport-0.8.4_8-all.jar - part of JFreeReports
  • pixie-0.8.1.jar - part of JFreeReports
  • poi-2.0-RC1-20031102.jar - part of JFreeReports
  • jtds-1.2.jar - JDBC driver for SQL-Server
  • wraplf.jar - a jar that allows anti-aliased fonts to be accessed
  • l2fprod-common-fontchooser.jar - a jar that contains the screen to choose fonts with
  • ojdbc14jar - JDBC driver for Oracle
  • /jre/lib/ext/jce.jar - a security jar from Sun
  • /jre/lib/ext/jsse.jar - a security jar from Sun
  • fscontext.jar - a reference application for creating an local LDAP
  • providerutil.jar - a reference application for creating an local LDAP

VII. JGuiGen - Accessibility and Internationalization

ACCESSIBILITY - A11y

See the manual for information about the many A11y features in JGuiGen generated applications.

For example:

  • Hot keys are available for most visual components and are internationalized.
  • The pop-up (right click) menu is keyboard accessible (Shift-ESC)
  • Clicking on column headers in the Scrolling table is keyboard accessible (CTRL-ENTER)
  • Resizing columns in the scrolling table is keyboard accessible (CTRL-UP_ARROW and CTRL-DOWN_ARROW)
  • Rearranging columns in the scrolling table is keyboard accessible (SHIFT-LEFT and SHIFT-RIGHT)
  • All visual components has the accessible names and descriptions set (for readers)
  • There is a magnifying glass available in the pop-up menu.
  • There is a supplemental screen that shows the A11y features of components under the mouse cursor.
  • and more...

INTERNATIONALIZATION - I18N

The system java uses to interationalize an application uses a text file for each language. These have an extension ".property" and are called properties files. Each of these files is made up of lines that contains prompts and values. For example title=TITLE SCREEN. Your application will look for the word "title" and replace it with the words "TITLE SCREEN". If you are running the application on a machine that is using a language other than English, the system automatically looks for a file containing prompts in your language. If the file exists it will contain exactly the same prompts as the English file. The values will be different in that they will be in your language.

Managing changes across several of these files is a nightmare. This problem is made even more difficult when working with a code generator like JGuiGen. Every time you regenerate the code you tend to overwrite any manual changes you made previously or you end up with properties files that do not contain the prompts for things you added during the new generation session.

JGuiGen now handles this problem by using a table to store the prompts and values. The table in the database is called JGuiGen_I18N. This table contains the information needed to create the properties files for up to 10 different translations of the prompts and error messages used in your project. Each row contains a prompt, a default value and the value you currently want placed in the properties file. It also contains the translations of the values for the foreign language properties files. There are three major advantages to this system.

  • One of the benefits of using a table this way is that there are over 300 prompts that are common to all applications generated by JGuiGen. Once these are translated the first time, they will be included in every application generated using JGuiGen from then on.
  • Another advantage is that you can make changes to the way you want prompts to appear in your application and if you regenerate the application they system will not overwrite your changes. There is an edit screen for this table. This screen can be called from the main JGuiGen screen that is used to launch the demo screens and the data dictionary edit screens.
  • The third advantages is that JGuiGen will automatically add rows to this table if you add something to your application that requires a new prompt, tooltip or error message. If you are not interested in internationalizing your application, this system will work automatically in the background and you will rarely need to look at it.

NOTE: You should NOT change the properties fields manually. They will be overwritten every time you generate a file using JGuiGen.

In order to use the internationalization system you will need to carry out three steps.

  • Run JGuiGen and choose Create --> I18N on the Create Screen.
  • Click on the FIND button and go to the classpath row. Click on "Not Used" and change it to "equal to". Fill in the next column with the name of the class you have generated (e.g. userlogdata). Click on the execute button. The scrolling table should now show just rows relevant to the class you are working with. You can also click on the AND/OR button on the classpath row and add a second criterion to your FIND string. You might look for a certain prompt or change the "not used" column to "LIKE" and enter a code such as %test$ in the value column. This would show you all prompts that contain the word "test".
  • Edit the "Current Value" row in the edit screen.
  • Click on the WRITE button (or when you exit the screen you will be asked if you want to write the properties files.) This recreates all of the properties files.
  • Overview of Internationalization Issues. Here is one list of the things you need to address for a truly internationalized application.
    1. date/time format - handled by JGuiGen_I18N table
    2. time zones - not really handled. I am not currently saving the time zone a date/time was entered in.
    3. calendar - am not sure - the popup can have different languages but is always Gregorian
    4. number format - floating point (0,000.00 vs 0.000,00 and -32 vs ?32) - handled by JGuiGen_I18N table
    5. currency format - handled by JGuiGen_i18n table
    6. collation (sorting) - handled by SQL queries
    7. character, word, line and sentence breaking - not handled except by default in textarea fields
    8. converting to lower or upper case - we can force upper case or lower case and this is done with a string taken from the JGuiGen_I18n table
    9. locale of UI (e.g. text in error messages, menus, dialogs, buttons, etc; images; audio; video; etc) - handled by JGuiGen_I18n table for text. Images and files are in folders like images. Spanish images are in images/es, Spanish_Mexican images are in images/ew_MX, etc.
    10. help files - handled the same way Images and files are handled. The system expects help files written in different languages.
    11. direction text is entered and displayed - should be handled by defaults.
    12. fonts - handled by java defaults and users can choose from available fonts.
    13. keyboard layout - not handled
    14. paper size (letter vs A4) - not handled other than OS defaults
    15. measurement (US vs metric) - not handled
    16. list separator (",") - not an issue that I can think of
    17. telephone (international access, country code, area code, outside line access, etc) - handled by JGuiGen_I18n table
    18. Format of Given and Family names - not handled. I did add titled borders so that you can explicitly mark what each field across a line contains. The developer could also hard code an if/else statement in the BuildLayout routine to change the order that items were presented based on the Locale
    19. Handling things like money where one user enters Euros and another enters Dollars - This is a corporate decision issue and is not handled by JGuiGen.

VIII. Logging and Error Handling  

One part of building applications that is often difficult is handling errors and support. JGuiGen and its generated applications come with a number of built in features to facilitate use and support.

First there is a second screen (that starts minimized) when JGuiGen or one of its applications starts. This screen has the icon LOG. You can see error messages and messages about how many rows where selected etc. on this screen. You or your users can also print this screen to communicate errors and problems.

When a problem occurs (or a warning occurs) a pop-up screen usually appears in the upper right hand corner of the users screen. This window indicates that there is something in the log screen that is probably worth looking at.

There are also some debugging and error messages that appear in the standard command window. If you are running JGuiGen using JAWS, there is a JAWS console that will contain these messages.

Finally there is a text file generated while JGuiGen is running. Developers or administrators can use these files to look for errors or to see who made certain changes. The files are called JGuiGen.txt.x where the "x" is replaced with 1, 2, 3, etc. They are written to the /Logs folder under the root folder for JGuiGen.

IX. Databases supported  

Currently there are six back-end databases supported by JGuiGen.
  • PostgreSQL - most of the development work was done with this full featured and very powerful open source SQL database engine. In addition to being able to link to the PostgreSQL server on my system, there are four small java files that (after you configure the XML file) will create and fill the two tables required to run the samples in JGuiGen. This allows you to install PostgreSQL and run the samples on your own system.

  • HSQL - the hsqldb project at SourceForge has created a very nice "small" SQL database. This database and its JDBC driver can be unzipped into a folder and at that point it is fully installed the JDBC driver can access it. For small systems and demonstration systems, this is ideal. HSQL scales up into multi- user and server versions as well.

  • MySQL - this is also a high end open source database package.

  • MS SQL SERVER (and Sybase?) - Microsoft's SQL Server is one of the large commercial databases heavily used in MS Shops. You can download a free (small) version called MSDE.

  • Oracle - the Oracle database system is one of the largest commercial databases available in the market. Testing was done using the OracleXE version which is a light version for developers and small businesses.

  • MS Access - Access is a well known and easy to use database system on Windows PCs. The database can be shipped to a PC, unzipped and it is ready to go. Unlike the HSQL database it requires the java ODBC-JDBC Bridge. This means that it cannot be used inside Java Web Start and we have not configured an ODBC driver for Linux yet. (There are commercial JDBC drivers for MS Access, but we haven't found an open source version yet.)

X Using Eclipse and HSQL with JGuiGen

  1. Opening the existing JGuiGen project after you download it.
    There must be a way to open an existing project in Eclipse, but I haven't found it. What I found is that if you create a new project, change from the default workspace and enter the path to the folder you unzipped JGuiGen into and enter the project name JGuiGen, Eclipse will recognize that there is an existing project and open it. This is not very intuitive, but it works.

  2. Eclipse Views or Perspectives.
    Eclipse has a number of "views" or "perspectives" that are different screens that have a combination of panels that facilitates a certain operation. I use the JAVA view and the DEBUG view extensively. In the newer versions of Eclipse you click on the Windows --> Perspectives menu option and click on the various available views to make them active in your project. From then on there will be tabs (usually in the upper right hand corner of the screen) that allow you to switch perspectives.

  3. Adding external jars to the Eclipse CLASSPATH
    Click on the JAVA perspective and you should see a panel with a tree with the word JGuiGen at the top. You may have to click on the plus sign to open this tree. Click on the tree to highlight it and then bring up the right-click menu. Choose Properties-->Java Build Path from this menu. Click on the Libraries tab. This is where the external jar go. There is a whole list of them elsewhere in this help file.

    NOTE: You will probably have to EDIT the various libraries to fix the PATH. The project I upload runs on the E: drive of a windows PC in a path that you probably won't have.

  4. IMPORTANTANT - The current version of JGuiGen will create an application, compile it, and run it. You can then change options in either the "Class" screen or the "Column" screen. You can then click on the "Create" button and JGuiGen will create the java files again, compile them again and run the new code. This is trickier than it sounds since Java caches classes that you load and there is virtually no way to purge this cache. This means that if the class you load is in your classpath, Java will also rerun the first version of the class you created. Here is how we get around that.

    1. In the Java Perspective open the JGuiGen tree in the left panel and find the "work" folder. Right click this and click on "classpath --> remove." Do the same for "work/src". The one disadvantage to this is that eclipse will not compile the java files in the work/src folder and doesn't tend to treat them as java files.

    2. I usually create a /src folder under my JGuiGen folder and copy the generated java files into this folder if I want to work with them in java. Note; You must erase these and restart Eclipse before you regenerate the class or the JVM that is running Eclipse will run the /src classes (which it has in cache) instead for the work/src classes you generate.

  5. What you will be editing
    In the JAVA perspective there are four paths in the tree that you will using.

    • default - this is right under the top level JGuiGen. It contains the java class files that are in the root folder of your project. This will contain the JGuiGen.java file and the various java files I use to populate tables in your databases.
    • com.jguigen.standard - I am using the Sun standard here of turning my web URL around and creating subdirectories that match. The "standard" directory contains class you might find useful and parts of JGuiGen that usually won't be editing. For example the DataDictionary and JGuiGen_I18N (internationalization) java and class files are in directory.
    • com.halepringle.src - this contains the files for the JGuiGen demos.
    • work.src - this contains the files JGuiGen generates. For example, after you generate the UserLogData application you will find the UserLogData.java files in this folder.

  6. Compiling the created java files
    By default (on Windows PCs) when you save a class file in Eclipse you automatically compile it. I spent some time looking for the "compile" button when I first started using Eclipse. Note that on Linux machines you have to activate this option. See the Linux Considerations portion of this help file.
    I use the Projects --> Build Project menu option regularly to compile all of the files that need updating.

    The files in the work.src folder will NOT be automatically compiled by Eclipse. I do one of two things. 1) run buildwork.bat from a command prompt or 2) add work and work.src back to the classpath and change the packages in each of the files to work.src. I don't use option 2 very often. or 3) I could creates a src folder under the JGuiGen folder and copy the generated files to this folder. They would run fine there.

  7. Warnings in Eclipse
    JGuiGen generates code that contains a lot of warnings. I have decided to live with this. For example I include the java libraries for all of the things the JGuiGen might generate. If you are not using certain features you will see a warning that an include is not necessary. Small yellow circles indicate warnings.

  8. Errors in Eclipse.
    Eclipse shows you that you have errors in your files using several visual clues. In the tree a class with a small red X beside it has errors. At the top of your edit screen there are tabs for each of the files you have open. Those with a red X have errors. (Those with an asterisk haven't been saved yet.) As you scroll up and down in a the java edit screen (either in the JAVA perspective or the DEBUG perspective) you will see a red X in the right hand margin beside lines that have errors. You can cursor over this X or over the code underlined in red to get a message about what Eclipse thinks is wrong.

    Down the right margin of the edit screen there are small red bars that tell you where in the whole java class Eclipse has detected errors. You can click on one of these bars to move the editor to that place in the file.

    There are several button at the top of the Edit screen that are worth looking into. One of these will take you to the next error in your file. Another takes you to the previous error. (There are also buttons to move to the last place you edited code - even if it is in a different class file. These are very useful.)

    When you SAVE a file, the red X that indicates the file has errors in it does not always go away even though there are no errors left in your java class. The Projects --> Build Project button almost always takes care of this. In the very rare cases that it does not you can exit Eclipse and restart it. So far this has always worked for me.

  9. Making sure the current session is completely closed for HSQL
    The single use hypersonic database (HSQL) that JGuiGen uses as a default (since it can be shipped with JAWS) is very sensitive to being SINGLE USER. This means that running a program in Eclipse that crashes, may leave the HSQL connection open. Click on the DEBUG perspective, highlight the threads area, right click and choose Terminate and Remove.

  10. Debugging
    Just above the Edit Screens in Eclipse there are two buttons that run applications. The green arrow runs applications "as Java Applications" or "as JUnit Applications" (and others). When you click the drop down part of the button you can choose "run as" --> Java Application and run the java class that is currently open. Most JGuigen classes have a MAIN method so that they can be run as Standalone files for testing. Once you have run a file using the drop down arrow, it is added to a list and this list appears when you activate the drop down. The last file you ran runs if you just click the arrow without the drop down.

    Beside the RUN button there is a green bug button. This is the "run as debug" button and it works just like the RUN button.

    If you right click on the margin beside an active line of code you get a pop-up menu that includes "Toggle breakpoint". When you first click it a blue circle appears in the left margin. This indicates a line that the application will stop running on when you are running in debug mode. There are several buttons available in the DEBUG view for stepping to the next line, stepping into a called class, etc. Note: If you have double clicked the tab containing the name of the file you are editing, Eclipse makes the EDIT panel full size for the Eclipse window. This is great for editing, but it hides the "Step over" and "Step into" buttons. You need to double click the tab again to reduce the size of the edit panel. The red square button allows you to terminate the running of the class at any time.

My 10 Favorite Eclipse Tips (From an Eclipse Presentation I made a few years ago)

  1. Enter a method or Java Function name followed by a period. Wait s couple of seconds and a list of all possible options appears. There are tooltips to show you what arguments the various functions take.
  2. Double click on an editor tab to have it grow to full screen. Double click again to have it shrink back.
  3. Double click on the yellow light bulb that appears beside a line with errors. You get a list of Quick-Fix options that Eclipse thinks will solve the problem. Click on one and Eclipse enters the code. For example. If you enter Date newDate = new Date(); Eclipse will flag an error with a light bulb. Double click the light bulb an it will tell that you need to import java.utils. Click on that option and Eclipse will write the import.
  4. You can drag Edit windows across the top of the screen to place them in a different order. You can also use the back arrow on the menu bar to jump to the last file you were editing.
  5. While debugging, Click on the window title of the Variable List and it expands to cover most of the screen. Click on a variable (especially an array, vector, JList etc.) and the values are displayed at the bottom of the screen.
  6. You can change the Windows Preferences to customize Eclipse. I change the color used to show matching braces to red since it shows up the best. I change the hot key for doing another FIND from ctrl-K to alt-F. This lets me use my left hand. I give up opening up the FIND menu at the top of the screen, but I rarely use that anyway and can use the mouse to open it. I also changed the action associated with hover over a variable during debug. I want to see the value of the variable. The default seems to be "show what kind of element the item is."
  7. Put the cursor on a brace, bracket, curly brace and press Alt-Shift-P. The cursor jumps to the matching brace, bracket, or curly brace. Double click beside a brace, bracket or curly brace and Eclipse will highlight the whole text enclosed in the braces, brackets or curly braces.
  8. Enter a property --> right click --> Create Getters and Setters. Boom - it is done.
  9. The refactoring stuff is awesome. You can change something and the change will ripple through all of your code.
  10. Enter //TODO xx and a task automatically is created with that xx as the task. Click on that task and the editor opens and jumps to the //TODO line.

XI The XML INI file

JGuiGen is driven by an XML file. The name of the file is JGuiGenIni.xml. The system looks for this XML file in several places.
  1. In a folder called C:\JGuiGen or /usr/home//jguigen.  You can change this by editing your copy of Model.java class used by all JGuiGen applications,
  2. In the folder the JGuiGen class is currently running from.
  3. Failing this, it looks for a jar called RMDatabases.jar. If this is found JGuiGen
  4. unjars the database and the XML file from the jar.
  5. If the RMDatabases.jar is not present it unjars one from the main JGuiGen.jar.  This one runs against the PostgreSQL database at my web site.

If the XML file has still not found, the system exits.

There are instructions in the XML file for editing it. You will need to edit this file to change which database you are using and where it is located.  The changed needed include the following:

  • The URL, JDBC Driver name, SQL account, password, and database type. These are required to access the SQL tables that JGuiGen will run off of.
  • The name and a short code for each table you are interested it.
  • The name of the users who should be able to access the system (this will change, but it is convenient for now.)
  • Other similar information about your system.

XII JGuiGen Security and LDAP Support

JGuiGen is designed to create a CRUD application that will edit a SQL backend database table. Creating such an application without regard to security doesn't make any sense. On the other hand Java is a quasi-interpreted language which makes securing the code difficult. Here are the solutions offered by JGuiGen.

Authentication - who can log in

  • Your call - first, you instantiate the Model class, then call
    Connection conn = Model.getConnection(username, password);,
    then call Model.setConnection(conn);
    You can optionally call Model.setUser("name of a user to record in tables"). If you don't make this call the user making changes will be recorded as "unknown".
    You get the database username and password and the username from your own code.
  • Trusted environment - don't worry about it. Place the user name and password required to access your database in the JGuiGenINI.xml file. Anyone can see it. After you instantiate Model, make a call to Model.getUser(). This will make a connection and pop up a Dialog screen with user names to select from. They are taken from a list in the JGuiGenIni.xml file. There are no passwords. A connection will be made using the information in the JGuiGenIni.xml file.
  • Stronger -In this case you do not put the database user name and password in the JGuiGenIni.xml file. You instantiate Model and make a call to model.getUser(). When the system notes that it can find the database, but doesn't have a user name and password to login with, it prompts your user with a fairly standard username/password screen. The password is hashed and that hash is compared with a hash stored in an LDAP system (a local file system is used if you do not have LDAP installed.) If the hashes match, the users password is used to decrypt a file containing the database user name and password. Local encrypted files are also decrypted to gain access to the LDAP in the first place and to determine the password used to encrypt selected fields in the table. See the Manual for more information about this system.

Note: At the time of this writing, the author does not actually have an LDAP system running. I am using JNDI which is Java's system for accessing multiple directory services with a standard set of calls. These calls should access Novel's NDS, Microsoft's Active Directory Service, various versions of LDAP - such as Open LDAP, etc. In this can I am using FSCONTEXT.jar which is a reference system provided by Sun to emulate LDAP. The information is being saved in a file called .bindings in the root directory where JGuiGen resides. While the user names are visible, the password information stored there is in hash form and it is VERY difficult to go from the exposed hash to the password that created that hash. These calls should work on a real LDAP or they may need some modification. I believe that they are close.

Note: The JGuiGenIni.xml file contains an entry for a shared path. This is a location where the encrypted text files are stored. This can be a shared network directory where IT can remove and add files at will or a local directory. If the shared path is "DEFAULT", the files will be in a System directory under the root location where JGuiGen resides.

Files: You will see the following files in the shared directory:

  • <username>-keystore.bin - this is a special encrypted value used with the person's password to encrypt the other files. This is part of Password Generated Encryption.
  • <username>-<databasetype>-DBUserPwd.encrypt - for example Hale-hsql-DBUserPwd.encrypt. This is the database user name and password used to access the HSQL database. The encryption is unique to the user Hale and is encrypted with Hale's keystore and his password.
  • <username>-<databasetype>-DBEncrypt-encrypt - for example Hale-hsql-DBEncrypt.encrypt. This is an encrypted version of the password used to encrypt individual fields in the hsql database.
  • <username>-fullRights-LDAP.encrypt - this is the name and password used to access the LDAP store. It indicates that the user Hale has the right to create new users. When the add-new-users screen is activated in JGuiGen all of the fields will be active. Of course - you must actually know an LDAP username and password to actually update the LDAP.
  • <username>-ChangePwOnly-LDAP.encrypt - If the user does not have a "fullRights" file, they should have the "ChangePwOnly" file. In the case they will be able to change their own password, but will not be able to change anything else. This encrypted file should contain a user name and password that gives just enough rights for a person to access their own password and (optionally) change it.

Authorization

Each screen has an option "Screen number." If this number is not -1 or 999, JGuiGen will query the Model file for the user's rights to this screen. This information either comes from the UserLogData table when the user log's in or you can manually set is with a call to Model.setScreenRights(ScreenNumber, rights). The rights code has the following format. In typical *nix fashion you add the rights you want the user to have together.
* 0 = view only
* 1 = add
* 2 = edit
* 3 = delete
* 7 = view, add, edit , delete
* 8 = do not even show screen
Note: The "Delete" rights are set when the application is generated. They may actually delete rows or they may mark them a "removed/inactive."

Encryption

JGuiGen has an option to encrypt individual fields in a table. The password is stored for each user when they are created. The password is encrypted and the user never see it. At the time of this writing I have not actually activated the encryption option. I will do so soon. The checkbox is in the Data Dictionary table and the Data Dictionary edit screen used to create JGuiGen Applications. My intent is to allow encryption of varchar fields only. In any case users will see the data while they are editing the table. The values will be decrypted on their way from the SQL table to the user edit screen and encrypted on their way back to the SQL table.

General

All of the classes used to secure JGuiGen are stored in the com.jguigen.secure folder. Debugging statements are surrounded with an if (DEBUG) {xx} statement so that they disappear from the resulting class file when DEBUG is set to false. To increase security you can remove the .java files from your system and even store these classes in an obsfucated jar.

HTTP Tunneling

JGuiGen ships with files from the Wrox book "Profession Java Security" which allow you to create an SSL encrypted tunnel between a user machine and a remote database. This ensures that data between the application and the database is difficult to "sniff" on the wire.

NOTE: I have not worked on these files at this time and hence don't know if they will work for us, but they should.

XIII The JGuiGen Code Generator

JGuiGen is code that writes code. When I started it was similar to Java Servelets. In a sevelet every line of HTML code is written out by the developer. This ends up with code that is very difficult to modify. The current version of JGUiGen is more like Java Server Pages. There is live java code mixed with merge codes.

First I take a working java program and mark it up. This becomes my template. The template always compiles and runs. This allows me to use an IDE to syntax check while I add features. It also allows me to compile and run the template until I get the results that I am looking for.

There are a few simple definitions and rules.

  1. Definition - Constant code - this is code that (with a few small substitutions) will be the same from one version of a given application to the next. Things in JGuiGen like buttons and their listeners are constant code. I have broken my application down into some 17 main sections.
  2. Variable Code - this is code that will differ dramatically based upon what type of SQL table columns we are dealing with. Dates will have pop-up calendars, while text fields will have very little "extra" code. There are some 20 Variable sections of code in JGuiGen.
  3. Line Markers - Lines that should be included in the generation process will have a comment at the end. When we call the merge process we tell it which line markers to look for.
  4. Merge Start and Stop codes - JGuiGen looks for certain codes in a line that tell it there are variables that should be merged. At present I use "_JGG_" to start and stop merge fields. This results in lines that javac understands even if they look a little odd to us. For example

    "public class _JGG_classname_JGG_ () { //MAINSOURCE"

    results in a line that compiles cleanly. JGuiGen would include this line if it is looking for the Line Marker "//MAINSOURCE" and could substitute the classname for _JGG_classname_JGG_.

  5. Special comments - JGuiGen looks for lines that start with "//+" these lines are ignored by the javac compiler, but are included in the final generated output. In the few cases where I cannot use a line in my template that needs to be in the generated output, I start it with //+.
For example:
//Example code for the JGuiGen Code Generator //MAIN
package Templates.stable;
//+package _JGG_packagename_JGG_              //MAIN
#import java.swing.utils;                     //MAIN
public class Tester() {
//+public class _JGG_classname_JGG_() {        //MAIN
System.out.println("Generated _JGG_classname_JGG_.java"); //MAIN
System.out.println("Hello World")             //MAIN
)                                             //MAIN
 When I use this code as a template lines 2 and 4 are not used (they don't have the //MAIN line marker) and lines 3 and 5 take their place. If we run this using the classname "Sample" and the package "com.halepringle.src" we get the following lines

//Example code for the JGuiGen Code Generator
package com.halepringle.src;
#import java.swing.utils;
public class Sample() {
System.out.println("Generated Sample.java");
System.out.println("Hello World")
)

Part of what I am working toward is to merge two types of templates as part of the generation process.

Type one - Constant code I have a large class (5000 plus) lines that will edit a SQL table. You have seen an example on the web site. This is what I call constant code even though there are elements in it (such as classname) that are variables.

TYPE 2 Variable code- Code that is specific to one type of Visual Component.

The current JGuiGen application has 20 different places in it that need java code to be generated that is specific to one SQL table and the columns that it contains. Most of these places involve Visual Components. For example: If I have a SQL table with the column lastname char(30) I would have the following places that this appears in my code:

DECLARE JBoundedTextFeild txtLastName = new JBoundedTextField(30);

INCLUDE IN AN ARRAY OF TABLE HEADERS ,"lastname"

INCLUDE ITS WIDTH IN AN ARRAY OF COLUMN WIDTHS ,75

CREATE A LOCAL INT THAT ACCESSES THE FIELD IN A JTABLE CLASSNAME_LASTNAME = 2;

INSTANTIATE txtLastName.setToolTip("_JGG_description_JGG_");
txtLastName.getAccessibility......
txtLastName.setName("last name");
etc.
LISTENER FOR VALIDATAION

CODE TO CHECK FOR ERRORS

CODE TO GET THIS FIELD OUT OF A SQL RESULTSET AND PUTS IT INTO A BEAN

tmpString = (String) rs.getString(tablename.LASTNAME);
if (tmpString = null) {tmpString = "";}
origDataBean.setLastName(tmpString);


CODE THAT TAKES IT FROM A BEAN AND PUTS IT INTO THE VISUAL COMPONENT
txtLastName.setText(origDataBeam.getLastName());


CODE THAT TAKES IT OUT OF THE VISUAL COMPONENT AND PUTS IT INTO A NEW BEAN
revisedDataBean.setLastName(txtLastName.value);


CODE THAT COMPARES THE TWO BEANS AND CREATES SQL STATEMENTS


classname_UPDATE_VARLIST += "lastname, ";
classname UPDATE_VALUELIST +=
"'"+revisedDataBean.getLastName()+"', ";
if (!{origBean.getLastName().equals(
revisedBean.get:astLastName())){
msg =+ "LastName changed":
classname_INSERLIST += "lastname = '"+
revisedBean.getLastName()+"', ";
changes++
}


Code is also needed to update a row in the JTABLE, special renders that might be needed for the JTable, etc. etc.


The bottom line is that all of this code is specific to a JBoundedTextField and will be extracted from a Java class file that is running code, but only has a couple of fields - one of which is a JBoundedTextField. The column name is this code will be _JGG_colname_JGG_ This will compile and run, but will be easy to find and substitute when I use the code in the merge. I'll have another class that contains all of the same code for a date, an integer, a regex field, etc.

Putting it together:

The final generated application will take all of the constant code and bits and pieces of the Variable definition files. If you have 30 char fields in your SQL table, it will have the same code 30 times, but with different column names substituted in the appropriate places. I haven't been really scoping this out as a generic tool, but I know that when I finish I will have enough pieces to fit into almost any running java code that I have worked with and turn it into a template.

XIV - Files and Jars used by JGuiGen

There are a number of special files and jars used by JGuiGen.  Here is a listing of some of the critical ones for developers.  The special classes provided for your use and used by JGuiGen applications are listed on the web site.  These are both provided through Java Web Start so that they are available to run the application and they are needed in your CLASSPATH when you develop using the JGuiGen system.  I use the Eclipse IDE and I need to Right Click on the Project name, choose Properties and choose BUILDPATH.  I then "add external libraries" and add all of these.

  •  hsqldb.jar - HSQL system.  This jar has the JDBC driver for the HSQL database, the Database Manager application for HSQL and other classes required to access and use an HSQL database.  
  • jaccess.jar - Accessibility (A11y) - This jar is required for use with   assistive technology extensions. These extensions are used to help handicapped users.

  • jakarta-regexp-1.2.jar - This regular expression system from the Jakarta project is used by jfcUnit.
  • jdom.jar - This is used to access the JGuiGenIni.xml file.
  • jh.jar - The JavaHelp jar is from Sun Microsystems (r) and contains the classes to access the JGuiGenHelp.jar
  • junit.jar - The classes required for JUnit testing.
  • jfcunit.jar- This is an extension of JUnit and is used for testing GUI code.
  • pgjdbc2.jar - The drivers to access PostgreSQL databases.
  • xerces.jar - The XML parser used to parse the JGuiGenIni.xml file.
  • mysql-connector-java-3.0.11-stable-bin.jar - JDBC driver for MySQL
  • bsh-1.2b6.jar - part of JFreeReports
  • gnujaxp.jar - part of JFreeReports
  • itext-1.00.jar - part of JFreeReports
  • jcommon-0.9.1a.jar - part of JFreeReports
  • jfreereport-0.8.4_8-all.jar - part of JFreeReports
  • pixie-0.8.1.jar - part of JFreeReports
  • poi-2.0-RC1-20031102.jar - part of JFreeReports
  • jts-1.2.jar - JDBC Driver for SQL-SERVER
  • ojdbc14.jar - JDBC Driver for Oracle
  • wraplf.jar - a jar that allows anti-aliased fonts to be accessed
  • l2fprod-common-fontchooser.jar - a jar that contains the screen to choose fonts with
  • /jre/lib/ext/jce.jar - a security jar from Sun
  • /jre/lib/ext/jsse.jar - a security jar from Sun
  • fscontext.jar - a reference application for creating an local LDAP
  • providerutil.jar - a reference application for creating an local LDAP
  • jscroll-1.0.2.jar - is needed for one of the com/halepringle/standard source files. It is not actually used by JGuiGen at this point.

In addition there are three jar files and some other files created by JGuiGen.  When these are downloaded by Java Web Start they will have the letters "RM" added to the front of each file.

  • Database.jar - The HSQL database and the MS Access database are shipped in this jar.  The files in the jar are unjarred on the target PC.
  •  JGuiGenHelp.jar - The help file is accessed directly from this jar.
  • JGuiGen.jar - The main application is shipped in this jar.
  • cd2JGuiGen.bat and cd2JGuiGen.sh - these batch and shell files are placed in your $HOMEDIR.  They will changed directories into the folder where Java Web Start installed JGuiGen.
  • jawsUnjar.bat and jawsUnjar.sh - These batch and shell files are placed in the folder where Java Web Start installed JGuiGen.  When it is run, the com\halepringle\standard\*.class files will be extracted from the JGuiGen jar.  A couple of properties files are also unjarred.   Once this has happened you should be able to compile java files that you create with the JGuiGen DataDictionary application.
  • JGuiGen.bat and JGuiGen.sh - These batch and shell files are placed in your $HOMEDIR.  In order to run JGuiGen with the MS Access database you must run with a regular java runtime engine.  These files call    java -jar <path >JGuiGen.jar.   If you edit the JGuiGenIni.xml file so that the JDBC Driver points at the MS Access database and run JGuiGen you will be using the MS Access database.  (Linux users - I haven't figured out the ODBC substitution to access the MS Access database yet so this will not work for you.) In either case the default database is Hypersonic (HSQL). This small SQL database is contained in a single jar file and is downloaded with JGuiGen.

 

Some of the other files shipped with the source code are as follows:

JGuiGen Files

Property files (I18N) - in the /conf folder

  •   JGuiGenModelRb.properties - the MODEL properties file
  •   JguigenmodelRb_en.properties - MODEL - English
  •   UserlogdataRb.properties - Userlogdata properties
  •   UsersLogDataRb_en.properties - Userlogdata - English
  •   UserlogdataRb_es.properties - UserLogdata - Spanish
  •  JGuigen_I18N.properties - JGuiGen_I18N - English

Template Files - in the Templates folder

  • ReportTemplate.xml - a the basic report used by JGuiGen to create new reports
  • LoginReport.xml - a sample report that comes with the JGuiGenDemo.
  • /Stable/*.java files - several template files used by JGuiGen to Generate code
Template Files - in the Templates/stable

  • MainSource.java - working java code used as a template for the classes you create.
  • MainSourceBuildLayout.java - working java code used as a template for the BuildLayout class that you create.
  • MainSourceTableModel.java - again working code used as a template
  • BoundedTextfield.java - working java code that contains the pieces needed when a BoundedTextfield component is used.
  • Other classes for other components (coming)
JGuiGen WORKING TOOLS
  • history.htm - shipped with JGuiGen - tells the user about changes in the current version of JGuiGen
  • build.bat/build.sh - compiles all of the code
  • run.bat/run.sh - runs the code
  • runJar.bat/runJar.sh - runs the jar in the separate drive and folder
    • Miscellaneous JGuiGen Files
    • JGuiGenIni.xml - the XML file that contains startup information that JGuiGen uses.
    • ReadMe.html - readme file for this project.

    FILES for POSTGRESQL DATABASE  
    • sq;/postgres_data_dict.sql - CREATE statement - used in  
      pg_admin II.
    • sql/postgres_userlogdata.sql - CREATE Statement
    • sql/postgres_JGuiGen_I18N.sql - CREATE Statement
    • PG Admin III (not provided) - use this to modify the databases directly.

    FILES for HSQL DATABASE

    • HSQL-Notes.txt - includes the CREATE statements used in the TransferTool
    • JGuiGenDb.script - part of the HSQL Standalone database
    • JGuiGenDb.data - part of the HSQL Standalone database
    • JGuiGenDb.properties - part of the HSQL Standalone database
    • /sql/Hsql-Data_Dict.sql - script to create the Data_Dict table.
    • /sql/Hsql-JGuiGen_I18n.sql - script to create the JGuiGen_I18n table.
    • /sql/Hsql-Tester.sql - sample script to create the Tester table.
    • /sql/Hsql-UserLogData.sql - script to create the UserLogData table.
    • runUtil.bat - run the Database Manager - Windows - type runUtil DatabaseManager to execute the manager.  Type runUtil Transfer to run the data transfer utility (transfer from one type of database to another.) See notes below for information on running the tools.
    • runUtil.sh - run the Database Manager - Linux   type ./runUtil.sh DatabaseManager to execute the manager.  Type ./runUtil.sh Transfer to run the data transfer utility (transfer from one type of database to another.) See notes below for information on running the tools.


    FILES for MS SQL-SERVER DATABASE

    The JDBC driver jar is the only file provided. You will need to down load MSDE or install a full SQL-SERVER you purchase from MS. See the section of MS SQL-SERVER to see a discussion of on open source management package you can download.

    • /sql/sqlserver-Data_Dict.sql - script to create the Data_Dict table.
    • /sql/sqlserver-JGuiGen_I18n.sql - script to create the JGuiGen_I18n table.
    • /sql/sqlserver-Tester.sql - sample script to create the Tester table.
    • /sql/sqlserver-UserLogData.sql - script to create the UserLogData table.

    FILES for Oracle (XE) DATABASE

    None of the Oracle files (including the JDBC drivers) are included in this download. Oracle requires a commitment to not ship their JDBC drivers to selected foreign countries and I cannot guarantee this. See the section on Oracle for information about where to download the file.

    • /sql/oracle-Data_Dict.sql - script to create the Data_Dict table.
    • /sql/oracle-JGuiGen_I18n.sql - script to create the JGuiGen_I18n table.
    • /sql/oracle-Tester.sql - sample script to create the Tester table.
    • /sql/oracle-UserLogData.sql - script to create the UserLogData table.

    FILES for MYSQL DATABASE

    • /sql/Mysql_data_dictionary.sql - includes the CREATE statement for creating data_dict table.
    • /sql/Mysql_JGuiGen_I18n - CREATE statement for creating the I18N table
    • /sql/Mysql_Tester.sql - script to create the Tester table
    • /sql/Mysql_userlogdata.sql - CREATE statement for creating the userlogdata table.

    FILES for MS ACCESS DATABASE

    • CreateAccessJGuiGen.java - includes the SQL CREATE statements.  NOTE, I had to do a lot of modification using the Access Table Designer after the CREATE statement was run.  I could not get things like DEFAULTS to work in the CREATE statement. I haven't been into this table for a while so its structure is out-of-date.
    • /sql/JGuiGen.mdb - the MS Access database
    • MS Access (not provided) - use this to modify the databases directly.

    XV. Java Web Start (JAWS)


     Java Web Start is part of java 1.4 and up. This system allows developers to put an full java application on a web site. Users click on a special link and JAWS will check to see if they are running the right version of Java, check to see if the current version of all the jar files in the system are already on the local PC and download those that are newer on the web site. In order for the jar files that are downloaded to be accessed, the developer must sign the jars with a certificate. The user must indicate that they accept the certificate before the jar will be allowed read/write access to the local PC. This verification only needs to be done once.

    Once the system has been downloaded, several files will be created and taken out of the jars.  If you use the DataDictionary --> Edit menu option and generate new files, they will exist on your system but you cannot run them from inside the JGuiGen application that Java Web Start downloads.  This application is compressed into a jar and the files you have created are not part of this jar.  Here are the steps to try out the files you create.

    1. CD to your $HOMEDIR and run cd2JGuigen.  This will put you into the folder where Java Web Start installed JGuiGen.  
    2. type unjar   - this will run a batch or shell file that removes the com\halepringle\standard\ classes from the jar.  On Linux use ./unjar.sh - you will need to run chmod a+x unjar.sh to make the script executable.
    3. cd to com/halepringle/src and edit the abstractTableModel file you created.  It will need to have several lines deleted from the top.  These lines are instructions about modifying the Model class.  This has already been done for the userlogdata class.
    4. cd back to the folder where JGuiGen.jar is and compile the abstractTableModel file - i.e. type javac com\halepringle\src\UserlogdataTableModel.java
    5. Compile the Userlogdata.java file - type javac com\halepringle\src\Userlogdata.java
    6. Run the Userlogdata class - type java com\halepringle\src\Userlogdata
          
      7.

    Obviously if you changed the name of the UserLogData.java file, you will need to make the changes to com\halepringle\standard\Model.java, recompile it and use your file name in steps 3, 4 and 5 in place of UserLogData.

    XVI. Linux Considerations
    • Shell Scripts - Each of the batch files mentioned above have corresponding shell scripts.  You will probably have to do a "chmod a+x   xxx.sh" on each of them to make them executable.
    • Special Directory - For the Java Web Start examples, the JGuiGen.Ini.xml file resides in the same folder with the jar files that Java Web Start downloads.   The more normal placement is in a special folder.  On Linux PC's this is a /usr/local/JGuiGen folder instead of a C:\JGuiGen folder used for windozs PC's.
    • Java and Java Web Start.   When you download the newest versions of java for Linux, there is no real install so they are not accessible when you type "java" or "javaws."  One way to make java accessible to your whole system is to create a   java.sh file in /etc/profile.d directory.  Do this work as super-user and make sure the version number of Java that you are installing is used in place of the 1.1.1_02 used in the sample below..  Here is an example
      •

               Warning: Be careful when editing /etc/profile.d/java.sh. 
                         You may not be able to run   Linux afterwards.
                 In this case, use the Red Hat Linux CD-ROM with boot: Linux rescue

    	[root]# vi /etc/profile.d/java.sh
    	export NPX_PLUGIN_PATH=/usr/java/j2sdk1.4.1_10/jre/plugin/i386/ns4/
    	export PATH=$PATH:/usr/java/j2sdk1.4.1_10/bin/:/usr/java/j2skd1.r.1_02/jre/javaws
    • Java Web Start - Note that the Howto's on the internet do not usually include the path to Java Web Start.  Also note that the version number is part of the path.  If you download a different version, you will need to adjust the path accordingly.   After you run ./java.sh, you should be able to type echo $PATH and see that java and java web start are in the path.  Typing java - version from any folder should run java and give you the version number of the jre being executed.
    • Eclipse - I use Eclipse as an IDE.  Two things I noticed about the Linux version and your mileage may definitely vary here.  First the motif version of Eclipse seemed to work better on RedHat 9 than the GTK version.  Second, the default setting for my windoze version compiled java files when I saved them.  The default on my Linux box did not.  Go to the Widows Menu --> preferences --> Workbench and make sure the "Perform build automatically on resource modification" checkbox is checked.  The way I noticed this was that errors would not go away after I saved a file.  Even lines that were now comments continued to be listed as errors.  See the Getting Started section for jars that need to included in the Java Build Path.
    • Test Directory - In order to use the toJar.sh and runJar.sh scripts you will need to create a "test" folder under your home folder.  I also used cvs to put the JGuiGen folder under my home folder.  These scripts expect to find it there.  Adjust them to suit your tastes.

    XVII. Running JUnit TestCase Suites

     Part of the generation process automatically creates a JUnit (and jfcUnit) test suite for each screen that is generated. These can be run from a command prompt as java where the ??? is the same name you gave the generated java class (e.g. UserLogData.java will have UserLogDataTest.java as its testCase.) These don't seem to run well as menu options inside a larger application.

    XVIII. Replication - A General Purpose Replication System

    Here is the document that describes the JGuiGen Replication system. JGReplication.html

    XIX. HSQL - Special Considerations.


    Managing the database - runUtil.bat and runUtil.sh are a batch file and a script that runs the DataBaseManager supplied with HSQL.  jawsRunUtil.bat and jawsRunUtil.sh are version that run in the folder that Java Web Start downloaded JGuiGen into.  Java Web Start automatically added "RM" to each jar, so the "jaws*" versions look for the hsqldb.jar to be named RMhsqldb.jar.

    You will need to open a command window, CD to the root folder where the project is running (This will be "interesting" for the Java Web Start versions - the path is under the C:\Program Files\ or your home folder, but it is a long way down.)

    Type jawsRunUtil DatabaseManager    or ./jawsRunUitl.sh DatabaseManager
    This will bring up a screen that lets you choose the type of HSQL database and point to the database you want to open.
    1. Choose "Standalone" from the top combobox
    2. Change to JGuiGen in the 3rd box (place the name after "jdbc:hsqldb:")
    3. Press OK.

    Database Access - a ready-to-run database is shipped with JGuiGen. NOTE: By default JGuiGen uses the Standalone version of the HSQL databases. This version will only allow ONE application at a time to access the database. You will need to make sure that there are no application threads in your IDE that are still attached before you can run the DatabaseManager. You must close it before you can run JGuiGen. (In Eclipse this means going to the debug view and highlighting a thread and pressing the button with a red square to kill the threads and then the stacked boxes button to remove them. You can also right click after you have left clicked on one of the thread and choose the "TERMINATE and REMOVE" or "TERMINATE and REMOVE ALL" options.

    Notes HSQL has a few quirks.
    • The VARCHAR fields do not return a column width when the metadata is queried. This causes problems. JGuiGen used CHAR fields here instead.If you really need VARCHAR, the system currently uses the width in the "default report width" field.  
    • When running the runUtil.bat or runUtil.sh DatabaseManager option there are a couple of quirks when creating tables.
      It seems to want the SQL key words in a specific order, i.e.
      to create a column called classname the following line in a CREATE table statement works: classname varchar(40) Default '' NOT NULL Putting the NOT NULL before the word Default does not seem to work. Boolean fields are designated with the column type of bit and their default is set with 'f' or 't'. It sometimes seems to have problems when you fill column with its default value. For example creating a column as a char(1) and giving it a default value of 'Y' seems to be a problem.
    • getColumns(null, null, tableName, null) requires an uppercase name. This should be taken care of already, but just in case I thought I'd let you know.
    • Date columns require dates to INSERTED and UPDATED using a very strict format. JGuiGen uses the SQL escaped date format which appears to work fine. There were a few places missed in JGuiGen, but I think we have them all now. (Escaped format = {ts 'yyyy-MM-dd HH:mm:ss'} {d 'yyyy-MM-dd'} and {t 'HH:mm:ss'}).
    • The SQL functions UPPER and LOWER are available. TRIM is not. You must use RTRIM and LTRIM.
    • HSQL has a system to auto-increment an INTEGER column. (Either do not insert the field or insert a NULL to a column marked as an IDENTITY column. There is no function to return the value just inserted. JGuiGen will use the contents of the "lastChangeBy" and "lastChangedDate" (if you identified them) and find the proper row. If you do not identify them, it looks for the highest row number. This would be a problem in a multi-user system where another user may have inserted a new row between the time you inserted yours and the time you queried. You can force an insert of any key if the key is not already in the table. This allows the JGuiGen TestCase to use a specific "testing id."
    • HSQL is case sensitive. Using UPPER (and you really need the RTRIM) will be necessary to run caseINsensitive queries.
    • HSQL converts TEXT columns in other system to VARCHAR. I changed them to LONGVARCHAR.

    XX. MS SQL-SERVER - Special Considerations.


    Database Management - Microsoft's SQL-SERVER comes in several brands and sizes. If you are using a full enterprise version you will have the Enterprise Manager. IF you use the small version (MSDE - Microsoft Data Engine), you will need a third party manager if you want a GUI front end. I have been using DbaMgr2K and DbaMgr. These are free and easily available on the web.
    The steps to get ready with DbaMgr2K are as follows:
    • Download and install
    • Run and choose your SQL-SERVER. You should see you local or your remote SQL-SERVER in a drop down list.
    • Add a new DataBase - in my case JGuiGen
    • Add a new user to the whole system. In my case I added Hale.
    • Open you new DataBase (JGuiGen) and add the User Hale to the database. Give the user lots of rights for testing purposes.
    • Click on Activities --> Query.
    • Paste SQL Create statements from the sql-server-UserLogData.sql file, and then execute it.
    • Do the same with the Table Create statements in the sql-server-JGuiGen-i18n.sql file and the sql-server-Data_Dict.sql file.
    case Insensitive
    JDBC Driver is open source and also works with Sybase. I haven't done the Sybase interface to JGuiGen yet.
    Setting the driver to attach to your SQL Server.
    jdbc:jtds:<server_type>://<server>[:<port>][/<database>][;<property>=<value>[;...]]
    where is one of either 'sqlserver' or 'sybase' (their meaning is quite obvious), is the port the database server is listening to (default is 1433 for SQL Server and 7100 for Sybase) and is the database name -- JDBC term: catalog -- (if not specified, the user's default database is used).
    When using the MSDE version of SQL-SERVER the default port is 1737.
    This works for me:
    url = "jdbc:jtds:sqlserver://localhost:1737/JGuiGen;tds=8.0";
    The set of properties supported by jTDS is listed in the jtds documentation at the Sourceforge site.
    More information is available at SourceForge project info: http://sourceforge.net/projects/jtds/

    There is no column type DATE in SQLSERVER, they are all DATETIME columns. If you are using a column where only the date is important you have to strip the time off manually.
    There is also no column type TIME in SQLSERVER, they are all DATETIME columns. If you are using a column where only the time is important you have to strip the date off manually.
    The timestamp data type is not SQL-92 standard. SQL-SERVER's timestamp is created automatically when a row is inserted and it has the data/time automatically inserted. It cannot be changed. This means that columns that used timestamp in other database systems must use datetime in SQLSERVER.

    sql = "Insert..."
    cnn.execute sql

    sql = "select @@identity"
    Set rs = cnn.Execute(sql, , adCmdText)

    If Not rs.EOF Then
    lngNewObjectID = rs.Fields(0)
    End if

    XXI. ORACLE - Special Considerations.


    Development and testing was done on the OracleXE version of Oracle. This is freely downloadable from http://otn.oracle.com. Since Oracle requires that I agree to never ship their database to certain foreign nationals, I do not include either the database or the JDBC drivers with JGuiGen. OracleXE can be installed on Windows or Linux and the ojdbc14.jar JDBC driver is installed when you install the database. Setup is every easy for both Windows and Linux. "ojdbc14.jar" is part of the OracleXE download or your can obtain the newest version from: http://www.oracle.com/technology. I believe the functions used by JGuiGen are available in version 8i forward. This has not been tested.

    Database Management -
    Oracle XE comes with an HTML database manager. You need to follow the instructions modify Internet Explorer, FireFox, etc. and make 127.0.0.1 respond as Localhost. I run mine as http://127.0.0.1:8080/htmldb/

    You can use this HTML based management system to add users (I added "Hale" and gave him DBA rights), and run SQL commands to create tables, test tables, etc.


    Database Access - In order to access an Oracle database you will need to carry out the following steps.

    1. Download and install an Oracle database. I used OracleXE from \\otn.oracle.com.
    2. Modify your browser to access the HTML database manager.
    3. Copy the ojdbc14.jar to your JGuiGen folder.
    4. Add ojdbc14.jar to you classpath (or the Build Class Path in Eclipse).
    5. Modify JGuiGenINI.xml to uncomment the Oracle section and modify the location of the database, the username and the password to access the database.
    6. Once you get the HTML database manager running.
      • Run the scripts in oracle-data_dict.sql file to create the data_dict table.
      • Run the scripts in the oracle-jguigen_i18n.sql file to create the jguigen_i18n table.
      • Run the scripts in the oracle-userlogdata.sql file to create the userlogdata table.
      • (Optionally) run the scripts in the oracle-qs_items.sql file to crate the qs_items table.
      • Uncomment the lines that access the Oracle JDBC driver, user name and password in fillDataDict.java class. Compile and run this class to fill the data into the Data_Dict table in your Oracle database.
      • Do the same with FillI18N.java and FillUserLogData.java
    7. Include the jars in your classpath or in the Eclipse Java Build Path.
    8. Run the JGuiGen Class from you command prompt or Eclipse.

    Notes on Oracle Specific issues     Here are some of the issues I ran into with Oracle that differed from other database back ends.
    • NOTE: When applications generated by JGuiGen in the com.halepringle.src folder are run directly (e.g. qs_itemsTst.java and userlogdata.java) they call the Model class and will not connect to the database. JguiGen and the Fill????.java classes have no problem. Since JGuiGen and qs_itemsTst are using exactly the same code in the Model.class I do not understand why this is happening.
    • The Biggest problem causes by Oracle was in updating data. Oracle treats '' (two quotes with no space between them) as a null when it does a table update or a table insert. This causes problems when updating columns that do not accept a null.
    • Could not create a database using the SQL Command option. The Object Browser allowed you to create tables, procedures, etc., but it did not offer an option to create a database.
    • You can only run one command (up to the semi-colon) at a time in the SQL Command option.
    • NOT NULL DEFAULT '' DID NOT WORK
      DEFAULT '' NOT NULL DID
    • There are no BOOLEAN, BIT, or TINYINT data types. I had to use SMALLINT for boolean columns.
    • I used TIMESTAMP(6) for the date columns.
    • VARCHAR columns should use VARCHAR2.
    • I had to change the column "comment" in JGUiGen_i18n to commentx - comment is a reserved word.
    • Oracle will only let me have one type LONG. LONG is depreciated, but it was the only memo field available. The other option was to use varchar2(????).
    • When the SQL command gets too long the HTML DB didn't give a result. I had to break long create tables into a "create table" and then an "alter table add".
    • Where inserting CHAR and VARCHAR columns, Oracle considers '' a null. Converted to ' ' (with a space).
    • After running a SQL Query to see rows from a table, the SAVE and RUN buttons are way over to the right. Scroll and scroll and you will find them.
    • Oracle uses a constraint for id columns. This is not an auto-increment field. You can insert duplicates if you hare not careful. One of the major issues JGuiGen tries to address is returning the ID of a row that was just inserted. Like PostgreSQL, with Oracle you can run a function that will give you the "NEXT ID" from a constrained column. You can then insert this value into the column as the new ID and return it to the calling class as the ID just created.
    • Oracle queries are case-sensitive. Since for my work most queries should not be case sensitive (I don't care if the name is Smith, SMITH, or SMith, I want them all when I ask for lastname = 'smith') JGuiGen creates it queries as upper(rtrim(lastname)) = 'SMITH'.

    XXII PostgreSQL - Special Considerations.


     Database Management - I have found PG Admin III to be a very robust and useful front-end for creating, querying and managing PostgreSQL databases. This is available from the postgresql.org web site and they have versions for Windows and Linux. You will need to download the postgresql ODBC driver and set up a DSN link to your database. PG Admin II also has good error messages that are useful when you are setting up access to a database on a remote machine.

    Database Access - There are two ways to access a PostgreSQL database. The first is to uncomment the section of the XML file that points to hale.homeip.net. This will give you access to a PostgreSQL server at my web site.

    Note: this service is subject to cancellation without notice and I do not guarantee 24/7 operation.

    If you have a copy of PostgreSQL running or if you install one, there are four java files shipped with the system. First you must modify the XML file to point to your database. Then you can use the SQL script in postgres_data_dict.sql in PG_ADMIN II to CREATE a data_dict table with the proper columns.  Next you can run postgres_FillDataDict.java. This will fill the table with data. You can do the same thing with postgres_I18N.sql, FillI18NData.java, postgres_UserLogData.sql and FillUserLogData.java. Now you should have access to your own PostgreSQL database.    

    Notes on SQL meta-data issues
    • Numeric columns return a column width of -1.
    • When you use a SQL CREATE statement to create a new table, the auto-increment field should just be called "serial."   For example CREATE table junk (junk_id serial, counter int4).   If you need to drop the table and create it again, you will either need to drop the automatically created sequence_id or change the word serial to something like dict_id int4 DEFAULT nextval('"data_dict_dict_id_seq"'::text) NOT NULL,      In the nextval function the "data_dict" portion is the table name, the "_dict_id" portion is the name of the auto-increment column and the "_seq" portion is a constant.
    • The "nextval" is a function that you can use to capture the next available auto- increment number. You can then insert this number in the table manually and know that it will be unique. Since you know the number it can be returned to calling application.  This is done automatically in JGuiGen generated applications.
    • Since you can insert any id number that is not already present, the JUnit TestCase can use a "testing id."  The default is ID = 1.  This can be changed in the JGuiGenIni.xml file.
    • When editing the data in the data_dict table that describes another table, a "lastChangedDate" column must be created and identified if you want JGuiGen generated code to avoid multi-user conflicts.
      •

    XXIII MySQL - Special Considerations.


    Database Management - There are several options on the MySQL web site, but I found that the MySQL Control Center is best for my uses. It is similar to the PG Admin III program and offers all of the functionality I need to query and update tables.

    Database Access - At this point in order to run this, you will need to have MySQL installed.  You need to carry out three steps.
    1. Ccreate the three tables (data_dict, userlogdata and JGuiGen_I18N) using the mysql_data_dict.sql, mysql_userlogdata.sql and mysql_jguigen_i18n.sql files.  You should run something like the MySQL Command Center, open the SQL window and paste the CREATE statements into the window and execute.

    2. Fill the tables with the three java files with the same names (plus the word "fill").   This means you will type    javac mysql_filldata_dict      and then      java mysql_filldata_dict  

    3. Edit the JGuiGenIni.xml file and uncomment the section that describes accessing mySQL tables.  You will need to point to the location of your database engine and put the username and password for your system into this file.    You will also need to comment out whatever driver that XML is currently using..

    Notes
    • MySQL SQL commands default to case insensitive (unless variable is char BINARY)
    • On-Line Reference - http://www.mysql.com/doc/en/Column_types.html
    • List of MySQL gotchas - http://sql-info.de/mysql/gotchas.html#1_1
    • Tablenames and paths default to the case sensitivity of your operating system. Windows = NO, *nix = YES
    • In order to obtain the last inserted ID, the following function was used:
      int newId = (int) ((com.mysql.jdbc.Statement) stmt).getLastInsertID();
    • Autoincrementing fiields are marked with the key word "auto-increment" in the SQL CREATE statement
    • MySQL does not have a type BOOLEAN. It does, but the field is a tinyint and takes 1's and 0's as true and false. This required a lot of rewriting. It is interesting that in SQL CREATE statements the default values for the TINYINT columns are given in quotes e.g. active tinyint(1) NOT NULL default '0' Most other database system give integer default values without quotes.
    • The SQL command like "Hale %" does not work on a char or var char since they are trimmed and hence there is never a space at the end of a column.
    • The SQL command upper ('hale') does not work because of the space after the key word upper.


    XXIV. MS Access - Special Considerations.
    Database Management - Use the MS Access application on windows PCs. This is one of the most complete and user friendly front ends out there for a database system. I'm not sure what you could use on a Linux PC.

    Database Access - At this point in order to run this, you will need to edit the JGuiGenIni.xml file and uncomment the section that describes accessing the JGuiGen.mdb file. You will need to comment out whatever driver that XML is current using.

    If your system returns an error code indicating that the MS Access ODBC driver cannot be found, you need to go to the Microsoft.com site and down load the Microsoft Data Access module. This is usually an exe file names MDAC_TYP.EXE. After you run this installation your system will have a number of ODBC drivers. You can check to see if this is needed by clicking on START --> SETTINGS --> ADMINISTRATIVE TOOLS - ODBC. If you click the ADD button and the MS Access Driver is available then you don't need to run MDAC_TYP.EXE. If the list is virtually empty you will need to download and run it.

    Notes
    • MS Access has an auto-increment feature for an INTEGER column. It is called a COUNTER during CREATE and an AutoNumber column in query designer.
    • MS Access does NOT allow us to force an insert even if the number you are trying to insert does not exist. This means that JGuiGen cannot use a "Testing id" when it inserts a row during the TestCase run.
    • MS Access is case-INsensitive during queries and doesn't recognize upper() lower() and trim().
    • JGuiGen has to read back the last record written after an INSERT to determine the id number that was auto-incremented. If the developer as included a "lastchangedate" field this is used to guarantee that the correct row is returned.

      Try bookmark code bookmark = rs.absolutePosition rs.Requery rs.absolutePosition = bookmark
    • Text columns return a width of 1,000,000 plus.
    • Column defaults are hard to add during CREATE statements. I had to go to the query designer and finish a lot of the conversion.
    • Numeric fields must use the type DECIMAL if there are to be decimals in the database. Several other data types (numeric, float, double) have a decimal value, but this is just for reporting purposes. The DECIMAL data type has property called SCALE which save how many decimals should be saved in the table.
    • Dates, Times and DateTimes all return SQL data types of 93 (TimeStamp). This required a change so that you could manually indicate that a column was to be a date only or a time only using the JGuiGen mask characteristic.
    • Logical fields are bit   and return 1 or 0..  Must be loaded as "true" or "false"
    • INTEGER return English SQL type of INTEGER (not int4 like PostgreSQL)
    • CHAR and TEXT columns default to "Cannot have zero length".  I changed this.

     

    XXV. A few notes on JGuiGen as Demo Swing Application Code

    One of the major reasons for building JGuiGen is to demonstrate and document one way to put Java code together into a full application. The help screens and documentation inside the code do a lot of this. In addition, one of the options when you generate code is to generate the code as an HTML file. When you do there are a series of links build that allow you to look at a list of areas inside the code and click on a link and jump straight to that section of the code. To demonstrate this, here are the 24 sections that JGuiGen has been divided into. There is a lot more to the code than these 24 sections, but they do separate the code into most of the major pieces that are requires to have a data entry screen with a JTable.

      SECTION markers are placed in every class that JGuiGen generates. They mark the various sections in the code where various Swing activities take place.

    • /** SECTION 1 - SETUP CONSTANTS and DECLARE VISUAL COMPONANTS */
      Example: Private String strVar;

    • /** SECTION 2 - START APPLICATION - ADD ATTRIBUTES TO INSTANTIAED VARIABLE & VISUAL COMPONANTS*/
      The main constructor. This is where the program starts running. The MODEL class is instantiated and things like looking up codes obtained from the XML file by the model class or obtaining internationalized strings and assigning labels, hot keys, etc. This cannot be done until the code is running because we get internationalized data with a method instead of the java default which crashes the program if a prompt is missing from the properties files. Example: lblScreen_Title.setText(model.getRbString(UserlogdataRb,"SCREEN_TITLE","userlogdata") Note: This method also adds the prompt to the JGuiGen_I18N table if it is missing from the userlogdata.properties file.

    • /** SECTION 3 - MORE SETUP OF COLUMN VARS - INCLUDING BUTTONS and LISTENERS */
      Set up listeners and add internationalized labels to buttons.

    • /** SECTION 4 - SETUP POPUP MENU */

    • /** SECTION 5 - MAIN DRIVER SECTION - DO THE WORK */
      Small section of code that actually calls for the BuildLayout, Get Data from a table, call for a JTable which uses the data and sets the screen visible.

    • /** SECTION 6 - CHECKS ALL FIELDS FOR ERRORS */
      When anything happens that will exit the current record, the currently visible data is checked first for errors. This includes 1) Changing rows in the JTable, 2) Starting a Find, 3) Closing the Window, 4) Executing an ADD, 5) Duplicating the current record, 6) Going to the next record, 7) Going to the Previous Record, or 8) Executing a Save

    • /** SECTION 7 - LIST Columns to call BuildLayout */
      Building the layout is done in its down class so that manually made changes will not be lost when the class is regenerated. It does mean that you must make additions or deletions manually. This requires that all of the fields to be used are passed into the BuildLayout() class.

    • /** SECTION 8 - Commented Column for BuildLayout */
      This set of fields is commented out and goes into the BuildLayout class. It is used see what has changed in order to make manual changes to the BuildLayout class.

    • /** SECTION 9 - ROWLAYOUT MANAGER - Build Rows */
      Java uses layout managers to determine where components go on a screen and how they handle screen resizing. JGuiGen uses a layout managers that deals one row at a time. All of the work takes place in a separate class (for example: UserLogDataBuildLayout()).

    • /** SECTION 10- CHECK FOR CHANGED FIELDS - SETUP UPDATE and INSERT STRINGS */
      Just like the routine that checks for errors, this routine is fired off anytime a screen of data would be left without saving changes. It builds the SQL strings needed to insert a new record or to update an existing record. It notifies the user that changes will be lost if a SAVE is not done and tells the user which fields changed.

      Example:
               tmpVarName is a String.
               tmpString is a String
               Model.QuoteReplacer() is a method
                 that makes single quotes into two single quotes for SQL
               newRowObj is a java bean with changed data
               vars_UserLogData is a String that contains a comma delimited list of variables to be
               ;    inserted in a SQL statement
               Values_UserLogData is a String that contains a comma delimited list of values to be used
               ;    in a SQL insert.
               rowObj is a Java Bean with the original data (before changes)
               change = in Integer which counts the number of changed records
               changeMsg is a String with a list of changed fields that a user can read
               update_UserLogData is a String containing Field=Value pairs for an SQL update call
          tmpVarName = "MiddleName";

          tmpString = model.QuoteReplacer(newRowObj.getMiddleName());
          vars_UserLogData = vars_UserLogData + "middleName, ";
        values_UserLogData = values_UserLogData + "'"+tmpString.trim()+"', ";>
          if (!(tmpString.trim().equals(model.QuoteReplacer(rowObj.getMiddleName()).trim()))){;
             changes++;
             changeMsg = changeMsg + "\n"+model.getRbString(UserLogDataRb,"change_description_MiddleName","UserLogData") + model.getRbString(UserLogDataRb," -Changed","UserLogData");
             update_UserLogData = update_UserLogData + "middleName = '"+tmpString.trim()+"', ";
          }

    • /** SECTION 11- GET CHANGED DATA FROM VISUAL COMPONANTS & BUILD NEWROWOBJ */
      JGuiGen uses tow Java Beans. Once contains the data before changes and the other contains the data after changes. This routine pulls the data from all visual components and builds a bean after changes are made.

    • /** SECTION 12- GETS DATA FROM DATABASE TABLE, FILLS VISUAL COMPONANTS and SETS UP JTABLE */
      main call to build the Java Bean before changes are made.

    • /** SECTION 13- GET RESULT SET FROM DATABASE and SETUP JTABLE RENDERERS, SORTER, ETC */
      Actually fire off the SQL Query and set up the JTable that will hold the resultset.

    • /** SECTION 14- GET DATA IN RESULTSET AND PUTS DATA INTO ROWOBJ */
      Routines that accessing one row of the result set and builds the Java Bean that holds the data as it looked before any changes are made.
      Example: utm = the instantiated tableModel class.
               idx_ is the row number
               utm.MIDDLENAME is a constant in the TableModel class with the column number

      tmpString = (String)(utm.getValueAt(idx_,utm.MIDDLENAME));
          if (tmpString == null) {tmpString = "";};
             tmpString = tmpString.trim();
          if (idx_ == 0){
             rowObj.setMiddleName(tmpString);
          }

    • /** SECTION 15- TAKE DATA FROM ROWOBJ AND PLACE IN VISUAL COMPONANTS */
      Fill the visual components with new data.
      Example: txtMiddleName.setText(rowObj.getMiddleName());

    • /** SECTION 16- UPDATE ONE ROW IN THE JTABLE WITH SAVED EDIT CHANGES */
      Change the values in the scrolling JTable to reflect saved changes in one row without having to re-query the whole results set. (Does not work with HSQL backend).
      Example: myModel = an Abstract Table model describing the JTable
               idx_ = index of the row in the JTable to update.
               UTM_MIDDLEWARE a constant in the UserLogData.Class that contains the column number that holds middlename in the JTable
               rowObj = a JavaBean containing the data.           myModel.setValueAt(rowObj.getMiddleName(),idx_,UTM_MIDDLENAME);

    • /** SECTION 17- CLEAR VISUAL COMPONANTS - PREPARE FOR ADD NEW ROW TO TABLE */
      Example: txtMiddleName.setText(" ");

    • /** SECTION 18- MISCELLANEOUS METHODS EG JTABLE MODEL & RENDERS, SCROLL SETTINS, SAVE SETTINS, PAINT VIUALS COMPONANTS TO PRINTER */
      Example: class MyTableModel extends AbstractTableModel {...

    • /** SECTION 19- BTNSAVE - DO INSERT or CHECK THAT ROW HASN'T CHANGED DURING EDIT AND IF OKAY DO UPDATE */
      This section calls to see if any variables have bad values (Errors)
      It then checks for any fields that have changed
      The routines that checks for changes also builds the strings needed for both a SQL Insert and a SQL update
      If the ID number is currently zero the utm.insertTable() method is called to insert a new row in the database table.
      If the ID number is not zero the system checks to see if the row in the database table still has the same date/time stamp in it that it had when the edit started. If not the update is aborted and the user is notified that a multiuser error occurred
      If the date/time is the same then a utm.updateTable() call is made to update the data is the database table.

    • /** SECTION 20- MAIN METHOD - USED TO RUN CLASS STANDALONE - RESTORES SCREEN SIZE & PLAF TO USER PREFERENCE */
      Almost all of the classes created by JGuiGen can be run in a standalone environment. This means that they need to have a MAIN() method in them.

    • /** SECTION 21- HANDLE CLOSING THE WINDOW (Calling program then sets to NULL) */
      Closes SQL resultset and SQL statement in the tablemodel, hides the frame and disposes of the frame. The calling program then sets the instantiated frame to null which frees up all of the memory it used.
    • /** SECTION 22- ABSTRACT TABLE MODEL IN A SEPARATE CLASS. */
      Each application JGuiGen Builds has a TableModel class that contains the calls that update and insert rows into the SQL backend.

    • /** SECTION 23- JUNIT TESTS IN TWO SEPARATE CLASSES */
      JGuiGen generates JUnit test files. These will 1) open the application (2) clear the fields 3) insert unique data into each field 4) save the data to the SQL table 5) close the application 6) Reopen the application 7) Query the SQL table for the row just inserted 8) Test every field to see if the data obtained from the query matches the data inserted in step 4.

    • /** SECTION 24- EXTRA CLASS TO RUN WHEN THE "EXTRA" BUTTON IS CLICKED. */
      Each application that JGuiGen generates has a button called EXTRA. (You change its name using the internationalization table). This comes with a dummy program that just pops up a message. You can replace this with your own code to do something real with your data.

      Example that shows the various places a single JTextField (bounded) appears in the code

    • Bounded Text Field Example - declare the field
    • Bounded Text Field Example - set ToolTips and Assistive Technology
    • Bounded Text Field Example - add to layout manager
    • Bounded Text Field Example - Test if data changed, set up update & insert strings
    • Bounded Text Field Example - Fill component from resultSet
    • Bounded Text Field Example - Reset hld value to value in component after save

      Example that show the various things done to the JFrame that holds this screen.

    • JxFrame Example - Includes for borders
    • JxFrame Example - JxFrame Declaration & Setting Title
    • JxFrame Example - Declaration of border variables
    • JxFrame Example - JxFrame Declaration for inside class
    • JxFrame Example - Pass JxFrame into class
    • JxFrame Example - Set Passed in JxFrame to a local field in class
    • JxFrame Example - Replace coffee cup icon on frame
    • JxFrame Example - setting the JxFrame border
    • JxFrame Example - Let user close the frame
    • JxFrame Example - JxFrame Windows Listener in Class - check if leaving class is okay
    • JxFrame Example - Example of passing frame into a JDialog
    • JxFrame Example - JxFrame Setup - size and location on screen
    • JxFrame Example - JxFrame Window Listener in main (set to null when done)
    XXVI. Here is a way to move data from one SQL database to another

    One of the common tasks when working with databases is to move data from one "system" to another. Here is one technique that can be used with JGuiGen.

    There is a java file called DumpGeneralTable.java in the SQL folder under JGuiGen. This program will a few thousands rows from one database or file system to another. Here are the steps I used for one small project.

    The DumpGeneralTable program connects to a database and reads all the rows in one table. It writes out a Java program that is mostly made up of INSERT statements that will write the data back into a another database table. This assumes you must have already created the empty table in the target database.
    This version of the program will add one unknown table into JGuiGen.
    Compile this program and then run it java DumpGeneralTable

    To Set this up you need to follow several steps

    1. Understand your original table. In my sample case I started with an Excel spreadsheet that needed to be in a database table. The first thing I had to do was save the Excel spredsheet using version 4.0 of Excel. My Visual Foxpro doesn't import the most current format.
    2. One I had a decent version of the spreadsheet I Ran VFP and clicked on File --> Inport (browse to the file, enter a file name)
    3. The next step involved renaming the columns to variable names other than A, B, C. Run VFP, cd to proper folder in the command window. use type modi stru in the command window. Rename the columns to names you want to use and then press the OK button.
    4. You can run VFP, cd to the proper folder, use <Filename> and Browse to see a scrolling table that contains your information. You can edit this table and the changes will be saved.
    5. The next step is to create an ODBC connection to the VFP DBF file. Click on the Windows Start Button --> Control Panel --> Administrative Tools --> ODBC. Then Click on the SYSTEM Tab and choose Visual Foxpro Driver. You will need to give it a name, description and browse for the file/path name of the DBF file you just created.
    6. Build a CREATE TABLE Script that will create a table that matches the source DBF table. You need to run this script in your target database so that the target table exists. If you have to run this several times you will need to DROP TABLE and run the CREATE screipt again. The JGuiGen SQL folder contains demo scripts for several different backend databases. You can use these as a starting place for your new table.
    7. Edit JGuiGenIni.xml file. There are four settings that are important
      • Remote settings - this will be the JDBC driver information and data base type for the target database
      • Local settings - this will be the JDBC-ODBC driver for the source table. You use the name you entered in the ODBC connection wizard on the JDBC-ODBC line. In my case the file name was AIC and the JDBC-ODBC driver name was <local_database_location>jdbc:odbc:AIC</local_database_location>
      • <source-move-file-name>zz</source-move-file-name> Enter the name of the dbf table you just created. Here is my line for a file called "drawinglistsample" <source_move_table>drawinglistsample</source_move_table>
      • <target-move-file-name> zz </target-move-file-name> Enter the name of the table in the target database. Again here was my line for a new file in my database called AIC <target_move_table>aic</target_move_table>

    8. Run the DumpGeneralTable by typing java DumpGeneralTable. It will create a java file names "Fill&ly;tableName> that you will need to compile and run. This file contains one insert command for each row in target table.
    Note; we use the database "types" to make conversion where necessary. For example some tables have true/false binary columns and some databases use 1/0 integer columns for true/false. Note: If running from PostgreSQL, search output file for the word "numeric" and change the "-1" column width to 5 and 8 Note: I don't know if the column type "bpchar" is used by other databases, so these may also need to be changed to something like "char"

    XXVII. A list of Tasks that programmers need to do in a Swing Application

    There are literally hundreds of things that a modern application is expected to do and Look and Feels that users expect from modern application. Here a some of those items and where you can see an example in JGuiGen generated code.

    Swing Task List