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