LDO Lightweight Data Objects SourceForge.net Logo
SourceForge Download Install Documentation Credits

Users' Guide

The LDO Wizard creates lightweight data object classes in Java that can be used by Java applications to access tables in SQL database. The lightweight data object code becomes a part of your application. No jar files need to be distributed with your application, and the impact on your application's footprint is similar to hand coded JDBC calls.

Starting the Application

Run the LDO Wizard by executing the LdoWizardWindow.rb file. If your Ruby installation has established file associations for Ruby just double click on the file. Otherwise, open a DOS window, navigate to the directory where you installed the LDO Wizard, and run the file with the command:

ruby LdoWizardWindow.rb

The application will display the main LDO Wizard window.

Entering Characteristics for the Data Object

To use the LDO Wizard you enter characteristics about the data object you want to create. The wizard uses your input to generate the appropriate Java code for the data object.

Setting the Class Characteristics

You set the characteristics of your generated Java class on the main window. The checkboxes for Insert, Update, Delete, and Get all provide you a way to specify the capabilities of the Java class. The main window text fields allow you to specify a Java package, a superclass name, a class name, and a table. The superclass name is optional. The table will be filled in from the SELECT statement if you don't enter a table name.

Inputing the Select Statement

The most critical input in describing the data object you want is the SELECT statement. The select statement identifies the database table and columns that will be included in the data object. You should create your SELECT statement using a database tools such as SQL Navigator. The SELECT statement needs to specify each column you want. Don't use "*" to get all column, the LDO Wizard requires you to be specific. Also, don't use the AS keyword or prefix the column names for joins. Normally when using LDO you should create views if you need to join more than one table. It is always possible to modify the code generated by the LDO Wizard to join table, but the initial SELECT statement cannot have a join. In addition to the columns you want, the SELECT statement should also have the FROM clause. However, no WHERE clause should be included. Adding WHERE clauses for different queries is a common modification to the code generated by the LDO Wizard, but again, this should not be in the initial select.

On of the reasons that you should use a database tool when preparing your select is that you can test it against your database. The LDO Wizard does not execute the SELECT statement before generating the Java code. Therefore, if your SELECT statement has errors your Java class will have problems accessing your database. When you have your SELECT statement with all the columns you want, with no WHERE clause, GROUP BYs or ORDER BYs, you can input it to the LDO Wizard using the Select Statement input dialog.

You access the Select Statement input dialog from the File menu. Choose the Input SQL menu item.

Setting the Data Characteristics

The Select Statement input dialog fills in the column and data type table with the columns specified in the SELECT statement. From the SELECT statement, the LDO Wizard does not know the data types of any of the columns, so they all default to String. You can then edit the data types to set the data types you want. Note that you do not have to specify the same data types as in the database. You can use String for columns that are NUMBER in the database, if you want String data in your data object. However, if you do so you could have problems if you try to insert or update the database with non-numeric data in the String fields.

To specify a column's data type, select its row in the table, then select the data type in the dropdown box. Multiple rows in the table can be selected and they will all get the same data type.

The column and data type table is also where you specify the keys for the table. Select the column or columns you want to be the key and check the Parm checkbox. As with data types, you don't actually have to use the key fields as specified in the database. However, the Java code generated by the LDO Wizard will provide a method that gets the data by the key fields. It will expect only one row to be returned. If more than one row is returned the data object will only give you the first one. Of course, you can always change the generated code to make it work the way you want. That is the intent of LDOs.

Generating the Java Code

Once you have all the characteristics and data types the way you want them, you can generate the Java code for your lightweight data objects. You access the generator from the File menu. Choose Generate Java Code. The code generator will first display a file dialog so you can specify the location where your Java code will be written. The dialog does not suggest a file name, so you have to enter it yourself. This is the result of a limitation of the vruby GUI toolkit, in a future version of the LDO Wizard this will be fixed. You must enter the file name the same as the class name or Java will give you compile errors. When you save the file name the generator will generator your Java class. It will also generate a template JUnit test class for your new data object class.

Using the Java Code

The lightweight data object Java classes generated by the LDO Wizard are intended to become a part of your application source code. You edit them just like any other Java code. All the LDO Wizard does is relieve you of the drudgery of creating all the standard code elements, so you can get on to the more interesting coding. Programmers most frequently create new methods based on the static get method that returns all rows. By adding a WHERE clause and filtering criteria you can retrieve only the rows you want. Your application can process the data objects, and update them one by one in the database if your application needs update capability.

The LDO data objects always need your application to provide a JDBC connection to access the database. In J2EE, the containers for servlets and EJBs generally have database connection pools. LDOs work well with connections from the connection pools. If you have a standalone application it must create the JDBC connection itself. The JUnit test code provides an example of creating a connection.

The LDO Wizard generates a JUnit test class for each LDO class it creates. The JUnit test classes inherit from BaseDOTest.java. A template of BaseDOTest.java is provided with the LDO Wizard. It is not complete, and must be edited and integrated into your project, but it provides a good starting place for developing unit tests for all your data objects. The developers of the LDO Wizard highly recommend using JUnit for all your Java code, expecially for lightweight data objects.