JGUP

Overview

To run the bookstore example you will need to be familiar with Ant, Weblogic 8, and Oracle.

Generating source tree

This code generator tool creates Java code and database table DDL for persisting business objects, and their relationships, to an Oracle database. Your project Xml file details the database table for each business object and the Java Class to generate for dealing with that table. Simple CRUD functions (Create, Read, Update, Delete) are handled. The most common relationships between tables are also supported: one to one, one to many, an many to many. There are many approaches to organizing database tables to persist data, and map relations. This tool does not attempt to allow for all approaches; it generates tables that conform to a pattern. It also does not attempt to tackle persisting objects that inherit from other persistable objects.

Database tables

Each business object has at least one table with each row storing one instance of that object. The table is indexed by an unique artificial primary key generated from a sequence. If they are dependent objects (subtypes) they don't have their own unique key but have a foreign key that points up to their owner. When the table is the "many" in an "one to many" relationship it will have a foreign key that points to its "one". If it is part of a many to many relationship an extra xref table will be used for linking their primary keys.

Boostore Example ERD Diagram

In our bookstore example authors are business objects with their own primary keys. An author can write many titles (one to many). If the author has died they will have an obituary (one to one dependent). The bookstore has many ongoing sales promotions that include many titles (many to many).

The author table is indexed by an artificial primary key.

    create table author (
      author_id                      number(11) primary key,
      first_name                     varchar2(100),
      last_name                      varchar2(100)
    );
   

The Obituary table is dependent to one author so it does not have its own primary key- but shares it with its author

   create table obituary (
     birth_date                     date,
     deceased_date                  date,
     obituary_text                  Clob,
     author_id                      number(11) primary key,
     foreign key (author_id) references author (author_id)
   );   
   

Sale and Title have a many to many relationship so an extra xref table links them.

   create table sale_title_xref (
     sale_id                        number(10),
     title_id                       number(10),
     foreign key (sale_id) references sale ( sale_id ),
     foreign key (title_id) references title ( title_id ) 
   );  
   

Java Business Objects

The Java Business Objects encapsulates the jdbc code for persisting its properties to the db. New business objects can be created by calling the no-args constructor, calling the misc set() methods, and then calling store(). The store() method will return the primary key of the new business object. To reread the business object back from the db pass the primary key to its constructor. To update call the set() methods and store() again. The delete() method deletes the row from the table. If the object has other objects in dependent relationships with it then calling the store() method also calls the store() method on the dependent objects. Likewise calling the delete() method will cause delete() to be called in any dependent objects.

Here is a example from the bookstore of using a business object:

    
    Author author = new Author();  //Create a new Author  
    author.setFirstName("Issak");  //Set its properties
    author.setLastName("Asimov"); 
    long key = author.store();     //Insert to database

    //Find the author by key
    Author author = new Author(key);                              //Select the properties from the db 
    System.out.println("First Name=" + author.getFirstName() );   //Print them out 
    System.out.println("Last  Name=" + author.getLastName() ); 

    author.setFirstName("Issac");     //Lets change the name and save. 
    author.store();                   //This will do an update as the row exists already    

    author.delete();                  //Remove the row from the db table

 

If the business object has relationships to other business objects methods for accessing those objects will be generated. If the object is the "one" in a "one to many dependents" relationship then the getOthers() method will get a List of the dependent objects. If the object has a "one to one dependent" object then the getOther() method will return it. If two objects have a many to many relationship then they each will have a getOthers() method.

  List titles = author.getTitles();             //Get the many Titles written by this one Author

  if ( author.hasObituary() ) {                 //Does this Author have an obituary ?
    Obituary obituary = author.getObituary();   // then go get it.
  }
  List titles = Sale.getTitles();               //Get the many Titles included in one particular Sale   
  List sales  = Title.getSales();               //Get the many Sales that include this one Title
 

A manager class for listing authors will also be generated. Use the code below to get a List of all Author business objects on the database:

    AuthorManager authorManager = new AuthorManager();   
    List allAuthors = authorManager.findAuthors();
 

The source code for each business object class and it's manager is in the bookstoreProject/src/com/jdonohue/bookstore/model directory.

JGUP will generate code for a simple "plain vanilla" user interface shown below:

The "Project Overview" screen will show a list of business objects in this class.

Click on "Author" and list of all authors created will appear. The links: "Display, Edit, and Delete are self evident.

Clicking on edit, or "Add New" will bring up this screen.

It is expected that the JSP HTML be modified to fit in with the look and feel of the final website. The UI code JGUP generates conforms to the Model, View, Controller pattern. The business objects are the model, a servlet controls the UI, and the JSP is the view.

Servlets and JSP

A servlet will be generated for each business object. The servlet for the "Author" business object is AuthorController.java. This servlet works with three JSPs: AuthorList.jsp, AuthorEdit.jsp, and AuthorDisplay.jsp. The input parameter "?function=" determines what action the AuthorController servlet will perform. The functions are: list, add, edit, save, display, delete. The "list" function causes AuthorController to list all authors. The other functions work on individual "Authors" to add, edit, save, display, or delete them. The generated servlets are placed in the bookstoreProject/src/com/jdonohue/bookstore/servlet directory The JSPs are in bookstoreProject/jsp/objectview.

Project XML File UI field settings

Below is an excerpt of a the definition of the last name of the Author business object. The non user interface tags have been omitted.

This example will put onto the edit form an input box of size 30 with the label "Last Name:".
Like this:

The field will be validated both in Javascript and in the servlet. The field can't be left blank, and it must be between 1 and 30 alphabetic characters.

The <label> tag specifies the label to use for this field in the user interface. The <length> tag gives the length of the <input type="text"> box in the form.

The two <promptValidation> tags defines conditions that must be met before the user can save the record. The <regExp> tag defines the regular expression to compare the user input to, and the <message> tag has the message to display if an error is detected. The errorWhen="match/notMatch" specifies if the error is when the regular expression matches the user input or when it fails to match.

If you want to validate both in JavaScript (before form post) and in the Java servlet (after form post)- then specify: javaScriptValidation="yes" and servletValidation="yes" If the regular expression is more complex and is expressed differently in Java and JavaScript- then use two different <promptValidation> tags each one with "yes" only given for either javaScriptValidation or servletValidation.

If a <property> tag includes a <treatAs>GregorianCalendar</treatAs> tag it will be show in the JSP as a date selector like this:
See the Sale business object for an example.

The <isObjectDisplayProperty> tag marks that property as the one to use to describe the object when it is referenced from an associated business object. In our bookstore example the Author's lastName <property> includes the <isObjectDisplayProperty> tag. The title screens will therefore display the last name of the author who wrote them.

You can add a The <dontDisplay> tag if you don't want this property to be displayed in the UI. Use this when the web site administrator's will be able to see and edit the field (authorEdit.jsp) but the end users should not see this field (authorDisplay.jsp and authorList.jsp).

JUnit test cases will be generated for each of the business objects to test their database persistence. An Ant task for running each JUnit test will also be generated in build.xml.

The test data to use for each property of the business object are specified in the <testData> and <testDataUpdated> tags. The business object will be created using the data in the <testData> tag. It will then be updated with the data in the <testDataUpdated> tag and then deleted. At each step we use "assert" methods to validate that the data was persisted to the database correctly.

Below is an example from the bookstore project. The tags irrelevant to JUnit testing tags have been omitted. The Ant task "testAuthor" calls AuthorTestCase. AuthorTestCase extends TestCase and will test adding a new author, editing it, and deleting it. The Author business object has two fields firstName and lastName.

A new author will be saved to the database with a first name of John and a last name of Smith. We then read it back again and assert what the first and last names should be. We then edit it, changing John to Jane and Smith to Doe, and save it again. Again we read it back and check the data. Finally we delete it. Watch the log file "comm.jdonohue.bookstore.log" to see the test happening.

Each test case will also test persisting any objects it depends on. The authorTestCase will test persisting Obituary objects to the database, and the Title object will test Author, Publisher, Category, and Category objects.

AppContext Overview

Database connection, logging, and simple configuration services are provided by an application context singleton: AppContext. This singleton is globally available to all classes by calling AppContext.getInstance(). When AppContext.getInstance() is called for the first time the singleton will determine if it is running under WebLogic or from the command line, and prepare an appropriate database connection service.

Here is some pseudo code that shows the uses of AppContext.

    AppContext appContext = AppContext.getInstance();                    //Get a handle to AppContext.

    //Logging
    Logger logger = appContext.getLogger("com.abc.myproject.MyClass");   //Get a hanlde to our JDK 1.4 logging 
    logger.finest("This is a log message from MyClass");                 //Log the severe error message

    //Get a configuration parameter from the database "CONFIG" table.
    String myParam = appContext.getParameter("lines_per_page");          //Get misc config parameter from db 
 
    Statement stmt = null;
    ResultSet rset = null;
    Connection conn = null;
    try {
      conn = appContext.getConnection();                                 //Get a DB connection 
      stmt = conn.createStatement();
      rset = stmt.executeQuery("select * from dual");
      if ( rset.next() )  { ... do something }
    }
    catch (Exception exp) {
      logger.severe("MyClass, Exception: " + exp);                       //Log the severe error message
    }
    finally { 
      appContext.closeAllDB(conn,stmt,rset);                      //Have AppContext close the db Connection,
    }                                                                    //ResultSet and Statement
 

  

The source for the AppContext class and associated classes are in the bookstoreProject/src/com/jdonohue/bookstore/appcontext directory.

Be aware that some commenters maintain that using a singleton to provide global access to services is the wrong approach. Instead they advocate newer strategies using "Inversion of control". See the PicoContainer and Spring projects.

AppContext and Database I/O

Example of using AppContext JDBC utility methods.

    Statement stmt = null;
    ResultSet rset = null;
    Connection conn = null;
    try {
      conn = appContext.getConnection();                    //Get a DB connection 
      stmt = conn.createStatement();
      rset = stmt.executeQuery("select * from dual");
      if ( rset.next() )  { ... do something }
    }
    catch (Exception exp) {
      logger.severe("MyClass, Exception: " + exp);          //Log the severe error message
    }
    finally { 
      appContext.closeAllDB(conn,stmt,rset);                //Have AppContext close the db Connection,
    }                                                       //ResultSet and Statement
  

AppContext abstracts the details of getting a JDBC Connection object. When the appContext.getConnection() method is called it will return a Connection object from the WebLogic DataSource if it's running under WebLogic. If it is running from the command lines AppContext.getConnection() will login to the database separately for each connection. This shields the classes requiring database connections from the details of their runtime environment. They can be run from WebLogic or a command line JUnit test without any changes.

When running from under WebLogic the AppContext constructor will instantiate a WeblogicContext object for getting the connections to the database. The code generated in WeblogicContext will ask Weblogic to get the data source named: "DataSource". In the bookstore example the bookstore.xml file defines the project name like so:

Therefore the generated code in WeblogicContext will ask for "bookstoreDataSource". This data source and a corresponding connection pool should be set up in the WebLogic Console to point at the test database. This same login information should be set in the file config.properties. This file is by JGUP to login to the database to create the project's table's and also for JUnit command line testing (see below).

When running from the command line the AppContext constructor will instantiate a CommandLineContext object for getting the connections to the database. CommandLineContext will look for a local file: config.properties to get the database login information
The file config.properties file looks like this:

       connectString=jdbc:oracle:thin:@localhost:1521:testdb
       user=scott 
       password=tiger 
      

This file is directly under the project's home directory and should be checked in along with the rest of the source tree.

Your code is still responsible for closing any Connection, Statement, ResultSet, or PreparedStatments you use. The appContext.closeAllDB() method has overload versions that accept any combination of these JDBC objects. Before trying to close the object the closeAllDB() method will test it for null. You should put the closeAllDB() inside a finally { } block to avoid connection leaks.

     closeAllDB(Connection conn) 
     closeAllDB(Statement stmt) 
     closeAllDB(ResultSet rset) 
     closeAllDB(Statement stmt, ResultSet rset) 
     closeAllDB(Connection conn, Statement stmt) 
     closeAllDB(Connection conn, Statement stmt, ResultSet rset) 
  

AppContext and Logging

AppContext also provides easy access to and control of logging. The logging used is the logging package java.util.logging introduced in JDK 1.4 (log4J and Commons logging are not supported). The generated code gives each model object has its own logger and log file. In the bookstore example their would be a individual log files for the Author, Title, and other model objects.
Here is an example from the Author class.

    Logger logger = appContext.getLogger("com.jdonohue.bookstore.Author");
    logger.finest("This is a log message from the Author Class");               
   

The logging level can be changed on the fly from the application console. Information on each logger, its logging level, file, and rotation is stored in a database table: APPLCIATION_LOGS.
The DDL for this table is below:

  CREATE TABLE APPLICATION_LOGS (
    LOGGER_NAME            VARCHAR2(250 BYTE)     NOT NULL,
    LOG_FILE               VARCHAR2(250 BYTE),
    LOGGING_LEVEL          VARCHAR2(10 BYTE),
    ROTATE_LOG_FILE_AT     NUMBER(10),
    LOG_FILES_IN_ROTATION  NUMBER(5)
  )

This information is read at start up. If you wanted to change where a log file was written to you would change the value in the LOG_FILE column. This table is created and populated as part of the JGUP project code generation.

AppContext and Configuration

AppContext also provides access to configuration name/value pairs stored on the CONFIG database table. The DDL for this table follows:

  CREATE TABLE CONFIG (
    NAME   VARCHAR2(250 BYTE)                     NOT NULL,
    VALUE  VARCHAR2(4000 BYTE)
  )
  

ApplicationConsole

The application console is a administrator's web page for viewing log files and setting configuration parameters. It included in the generated project and is password protected.

The logging level, from Finest to Severe, can be set and will take effect immediately.
From the console you can access the log files. You can ask for a certain number of lines from the start or end; the lines will appear in a pop-up windows. You can also download the entire log file.
Each configuration parameter on the CONFIG table can be reset.
If your application is running on multiple nodes in a WebLogic cluster there will be a separate application console for each node. You will have to login to each application console when checking log files, setting logging level, or adjusting config parameters. The application console login password defaults to "admin". It's stored on the CONFIG table.

The JSPs for the console are in bookstoreProject/jsp/admin/console and the servlets are in bookstoreProject/src/com/jdonohue/bookstore/servlet/admin/console.

Acknowledgements and License

This tool makes use of or includes several JAR libraries. They are listed below:

Velocity	velocity-1.3.1.jar
	velocity-dep-1.3.1.jar
	velocity.license
Jdom	jdom.jar
	jdom.license
JUnit	junit.jar
Jasper JSP Compilier	jasper-compiler.jar
	jasper-runtime.jar

JGUP License

The JGUP tool is licensed under the GNU GPL. This covers enchancements to the tool itself not the code that is generated by it. The code you use JGUP to generate is your property and your responsibility.

Questions or Comments to: