Designing your data model for use with MDAOG shouldn't be much different than normal. If you are going to be using automatically generated integer keys from sequences the sequence name should be in the form tablename_columnname_seq or you can use the Serial data type which creates a sequence of that form behind the scenes. Also it is a good idea to keep the keys on the top of your table definition.

Let's assume we're building a very simple application that manages books and their authors. We have an author table and a book table with a relationship between the two. The SQL to create those tables would look something like this:

It is a good idea to include comments on your tables and attributes. MDAOG will use those comments in the JavaDoc comments of the generated files. They have been omitted here for brevity.

Joining Tables

The quickest and easiest way to join 2 or more tables is to create a view in the database that represents the columns you would like returned and the criteria for joining those tables. WHen you run MDAOG you can select the views and MDAOG will create the DAO's and DTOs for accessing the view.

Generating Code with MDAOG

With our environment and database tables created we can focus on generating the DAO code. You can also view a Flash based demo on running MDAOG.

Obtaining MDAOG

You can download the MDAOG jar file or sources from here.

Save the jar files somewhere on your system.

Running MDAOG

MDAOG is packaged as an executable jar file. To start MDAOG use the following command from the directory where you saved mdaog.jar:

On Windows: java -cp [path to jdbcdriver jar];mdaog.jar net.sourceforge.mdaog.gui.DaoGenerator
On Unix/Linux: java -cp [path to jdbcdriver jar]:mdaog.jar net.sourceforge.mdaog.gui.DaoGenerator

If you don't have your JDBC driver jar in your classpath you have to enter it in the command line as done above.

MDAOG should then start. MDAOG is a Java Swing based application but it is set up to user your computer's System Look and Feel so it should closely resemble other applications on your system.

Setting up MDAOG to Generate

Before MDAOG can generate the source files it needs to have the following information entered into the following fields:

JDBC Driver: the canonical class name of the JDBC driver MDAOG should use. ex: org.postgresql.Driver
JDBC URL: the JDBC URL used to access the database you want MDAOG to generate files for. ex: jdbc:postgresql://localhost/mdaogtest
DB Username: the username required to log into your database
DB Password: the password required to log into your database
Package: the name of the package you want MDAOG to generate it's files in. ex: com.mycompany.mywebapp.data
Source Directory: path to save the generated source files to. You can choose to save the files in the same location as your web application source files or you can save it to a separate directory and manually compile and jar the DAO files and include it as a library when building your webapp. I usually use Netbeans for web applications and set my source directory to the source directory of my project folder. This way I can compile, debug, edit the generated code directly from my IDE. Also if I need to make changes to the data model, I don't have to worry about repackaging the DAO library. You can use the Browse button to select the directory/folder to save the files to. ex: C:\mdaogtest\src

Saving Project Settings

If you plan to make changes to your data model after you have generated the DAO files you should save your project settings. Go to the File menu and select Save and name the file. The file will be saved with a .properties extension and saved in the directory you choose.

Generating Sources

Now that we've set up the info MDAOG needs and saved the settings, we can have MDAOG generate the source code.

To do this select Generate DAO Sources from the Action menu.

MDAOG will now attempt to connect to the database via the JDBC settings you supplied. If all the settings were correct, it will pop up a window with two list boxes. The top list displays all the tables found in the database, the bottom all the views. Select the tables and views you'd like to generate files for and click on the Generate button.

MDAOG will now generate all the necessary Java source files for connecting to the database. Now is a good time to go through the generated code and get a feel for what it does.

Using the Generated Code

Now that MDAOG has generated the DAO code to access the database from your web application we'll go through the steps of using that code in a web application.

Web configuration

The code generated by MDAOG requires some settings in web.xml to function properly.

DataSource Configuration

The PostgreSQL code expects find a DataSource through a JNDI lookup for java:comp/env/jdbc/. The Data Source Name (dsn) is derived from the package settings. You can look at the jdbc/PostgresqlBase.java file to see the value MDAOG has assigned for this.

Either by editing your web.xml file directly or using the containers management interfaces you should create a JDBC DataSource with the appropriate dsn.

DaoFactoryImplementation

Since MDAOG should some day contain more than just the PostgreSQL DAO implementation, it is necessary to specify which DAO Implementation to use. You do this by creating an environment entry in your web.xml. Ex:

<env-entry>
  <env-entry-name>
    DaoFactoryImplementation
  </env-entry-name>
  <env-entry-value>
    com.mycompany.mywebapp.data.factory.PostgresqlDaoFactory
  </env-entry-value>
  <env-entry-type>
    java.lang.String
  </env-entry-type>
</env-entry>

When you call DaoFactory.getDaoFactory() it will return an instance of PostgresqlDaoFactory (or whatever is defined as DaoFactoryImplementation).

Using DAOs from Web Application

Below is an example of a simple Bean that can be used by a JSP page to display all the records in the authors table sorted by pen_name.

import com.mycompany.mywebapp.data.dao.*;
import com.mycompany.mywebapp.data.factory.*;
import com.mycompany.mywebapp.data.dto.*;
import com.mycompany.mywebapp.data.exception.*;

/**
 * Bean used for retriving authors for use by authors.jsp
 */
public class AuthorsPage {

    private Author[] authors;

    public AuthorsPage() {
        //get an instance of the DaoFactory
        DaoFactory daof = DaoFactory.getDaoFactory();

        //get an instance of AuthorDao
        AuthorDao adao = daof.getAuthorDao();

        //define that the results should be ordered by pen_name
        adao.setOrderByColumn(adao.COLUMN_PEN_NAME);

        try {
            //request all author records from AuthorDao
            authors = adao.findAll();
        } catch (AuthorDaoException e) {
            //handle exception
        }
    }

    public Author[] getAuthors() {
        return authors;
    }
}

Using the generated DAOs to insert an object can be performed as described in the following example:

import com.mycompany.mywebapp.data.dao.*;
import com.mycompany.mywebapp.data.factory.*;
import com.mycompany.mywebapp.data.dto.*;
import com.mycompany.mywebapp.data.exception.*;

/**
 * Inserts a new Author into the database
 */
public class AddAuthorPage {

    public void addAuthor(String firstName, String lastName,
            String middleInitial, String penName) {
        //get an instance of the DaoFactory
        DaoFactory daof = DaoFactory.getDaoFactory();

        //get an instance of AuthorDao
        AuthorDao adao = daof.getAuthorDao();

        //create a new Author DTO and PK
        Author author = new Author();
        AuthorPK pk = null;

        //set author attributes
        author.setFirstName(firstName);
        author.setLastName(lastName);
        author.setMiddleInitial(middleInitial);
        author.setPenName(penName);

        try {
            //insert the new DTO and retrieve the PK object
            pk = adao.insert(author);
        } catch (AuthorDaoException e) {
            //handle exception
        }
    }
}