Developer Documentation

This page information that would be useful to those that are interested in modifying or extending the functionality of MDAOG. It's a good idea to read and understand this page before attempting to make changes to MDAOG.

Obtaining the Source Files via CVS

The source files for the project are available via anonymous cvs access to the SourceForge cvs repository. To obtain the source, use the following cvs commands:

cvs -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mdaog login

Check out the mdaog module

cvs -z3 -d:pserver:anonymous@cvs.sourceforge.net:/cvsroot/mdaog co -P mdaog

Using Netbeans to Develop MDAOG

The Netbeans IDE is a good, open source Java IDE. You can set up Netbeans to obtain the sources from the cvs repository and build and test MDAOG.

Instructions for using Netbeans to develop MDAOG can be found here.

Background/Design Goals

The code for MDAOG started out as a test class to see what kind of metadata I could extract from the database that grew into a utility that could generate the DAO source files. When it was working I slapped on a GUI to make running it easier. The design and coding of MDAOG happened on the spot as was necessary. More emphasis was placed on architecting the generated code rather than the application that was generating it. Things could probably be a lot better, especially the Swing code. It's pretty simple and it works.

The code is generated using simple string manipulation. There are some templating engines out there that could have been used but in this case I felt it would be a lot simpler to not deal with them. I wanted very little or no dependence on any other external libraries. This makes it easy for others to use and modify. The only requirement for running the application will be the MDAOG jar file and the JDBC driver.

The development was done with Netbeans 4.0 and 4.1. The structure of the source code and build scripts reflect that. Netbeans uses Apache Ant build scripts that work without Netbeans as long as you have Ant to build the project.

The source files are organized in three main packages that separate the main classes, output classes and gui classes. The best way to understand the MDAOG source code is to review it or the API documentation (JavaDoc output).

GUI Info

Swing programming is not my strongest area. There are probably some better way of doing things in the GUI code but I managed to get it to work almost like I wanted it to. Things like the progress bars I had some difficulty with and I'm not sure that it's right but it works. This is one area I'm sure could use improvement by someone that has more experience with Swing.

Ideally it would be nicer to also build a Netbeans or Eclipse plug in front ends so that MDAOG can benefit from being part of a larger IDE. That would make development of the web application a little more streamlined.

Generated Code

The most important aspect of the application is the structure of the code that is generated. MDAOG Generates Java code that conforms to the DAO Design Pattern. Right now, it only generates JDBC DAO classes for communicating with a PostgreSQL Database but it is possible to add functionality to MDAOG that will generate DAO objects for other JDBC databases, JDO, EJB, XML, LDAP, etc. if someone wants to build that functionality in.

MDAOG creates 5 packages that contain the generated files. The packages are:

dao: contains the Data Access Object Interfaces.
dto: contains the Data Transfer Objects and Primary Key (PK) objects for each DAO.
exception: contains the DAO Exceptions.
factory: contains the abstract DaoFactory class and it's subclasses. (In the case of MDAOG, PostgresqlDaoFactory.)
jdbc: contains the DAO implementation for accessing a PostgreSQL database via JDBC. There isn't very much PostgreSQL specific in these generated files except that it expects the database to support sequences and transactions which is why jdbc was chosen as the name.

Editing the Generated Code

The quickest, straight-forward way I could think of to allow users to add their own methods to DAO classes was to create a DAOBase that contains the generated and the DAO which extends the DAOBase. When MDAOG runs, it will overwrite the DAOBase files. If the DAO files exist it does nothing, if they don't it creates them. This also allows them to override methods if they choose to change the behavior.

DAO Methods

MDAOG generates methods to insert, update, delete, select and count records in the table. The best way to understand the generated source files is to look at the generated source or to create JavaDoc files from the generated sources as they are fairly well documented. As a heads up, this is what you can expect to find in the generated DAOBase files.

setOrderByColumn(String column): allows the user to set which column to order the results by.
setOrderByColumn(String column, boolean descending): same as above except it allows the user to specify if the results should be ordered descending
setOrderByColumns(String[][] columns): allows the user to select more than one column to order by and whether to order it descending or not
setLimit(Integer limit): allows the user to specify the maximum number of records returned
setOffset(Integer offset): allows the user to specify how many records into the result set the data should start to be returned
insert: inserts the specified DTO into the table. Depending on which insert method is called determines if the primary key has been specified or if the database should be allowed to create it.
update(pk, dto): updates the record specified by the Primary Key object with the values in the DTO object
delete(pk): deletes the record specified by the Primary Key object
findByPrimaryKey: returns a DTO that matches the primary key parameters specified. The primary key parameters can be passed as a PK object or as individual parameters
findAll(): returns all the records in the table or all the records between the offset and limit if specified
findByForeignKeyTable: selects all records that match the PK object of the Foreign Table
findWhereColumnEquals: returns all records where the specified column matches the supplied parameter
findByWhere: allows the user to supply their own Where string and pass an array of parameters to be sent to the PreparedStatment object
count...: returns the number of records that fit a certain criteria. The same methods that are available for find are available for count so I won't list them all

Project News

MDAOG 0.5.3a Released

MDAOG's first reported bug was (hopefully) fixed :) Also support for bigserial datatypes has been added. The generated DAO code will recognize bigserial as a java Long and will go fetch the sequence value on inserts.

MDAOG 0.5.2 Released

This new version of MDAOG adds methods to the DTO objects to allow you to easily duplicate them or test for equality. The ability to specify the DataSource name used by the webapp has also been added. Previously if you wanted to make changes to the DSN you had to modify the PostgreSQLFactory.

MDAOG 0.5.1 Alpha

A few changes to the GUI were made based on some recommendations as well as some code changes and rebuilding the package to be compatible with older JVMs

MDAOG 0.5 Alpha Available for Download

The first Alpha Release of MDAOG is available for download. This build allows you to connecto to a PostgreSQL database through MDAOG's Swing GUI and generate DAO source files for accessing the database in your Java web applications. Though it is an Alpha release, the generated code is of high quality and fairly well tested.

MDAOG Java DAO Generator Project

The MDAOG Java DAO Code Generator Project is coming to SourceForge. The project home page is up with a bit of information to give you an idea about what it's all about. Jar files and source code will be available soon. If you're interested in the project please leave a comment.

Hosted on: