Using Yank as a MySQL Persistence Layer in Your Java Application

Yank is a lightweight JDBC persistence layer API for any type of Java application. Looking at the JavaDocs, we can see that it only has a grand total of 4 classes. I love APIs like this because I can dig into the JavaDocs and very quickly understand the design and structure, making it a snap to get up and running with working code. Yank makes it easy to interact with JDBC databases in a structured, organized, and clean-cut approach. If you don't use a persistence layer like this, you quickly find that your database querying code becomes an unmanageable mess.

The Basic Idea

Each table in your database has a corresponding Java object. The object has private fields with names and data types that match the column names of your table. In other words, the Bean is a Java object that is a one-to-one mapping of a single row in your table.

The next thing you need is a Data Access Object, or DAO, for the Bean. In this class, you create methods for interacting with the table. In each method, with only a few lines of code, you create the specific SQL query you want and use the com.xeiam.yank.DBProxy to handle the query for you.

The advantage of this is that your code for interacting with the database is all wrapped up in just two very simple classes for each table in your database - a POJO and a DAO. And because the actual nitty-gritty details of handling database connections and results sets in handled for you in com.xeiam.yank.DBProxy, you don't have to worry about coding that yourself. It saves time and prevents errors.

An Example

In order to make the relationship between a table, the Bean, and the DAO absolutely clear, I will walk through an example.

Step 0: Create a Database. We'll call the database "Yank", which matches the jdbc URL in step 4 exactly. How you create the database may be different than how I do it, but here's what I did at the command line:

$ /usr/local/mysql/bin/mysql -u root -p
mysql$ create database Yank;
mysql$ show databases;
mysql$ exit;

Step 1: Create a table. I'll be using similar code to the Yank example code for this. In MySQL create a database called 'Yank' and add the following table called 'Books' to it:

CREATE TABLE `Books` (
`TITLE` varchar(42) DEFAULT NULL,
`AUTHOR` varchar(42) DEFAULT NULL,
`PRICE` double DEFAULT NULL
) ENGINE=MyISAM DEFAULT CHARSET=utf8;

Step 2: Create a Bean for the table. First, add the fields corresponding to the column names. The names MUST match, although case doesn't matter. Finally add getters and setters for all the fields. In Eclipse, these can be easily auto generated.

package com.xeiam.yank.demo;

/**
 * A class used to represent rows in the BOOKS table 

 * Note: class member naming tip: data type and name must match SQL table!

 * Note: DBUtils uses reflection to match column names to class member names. 

 * Class members are matched to columns based on several factors:
 * 
 * 
set* methods that match the table's cloumn names (i.e. title <--> setTitle()). The name comparison is case insensitive.
 * 
The columns are matched to the object's class members
 * 
If the conversion fails (i.e. the property was an int and the column was a Timestamp) an SQLException is thrown.
 * 
 * 
 * @author timmolter
 */
public class Book {

  private String title;
  private String author;
  private double price;

  /** Pro-tip: In Eclipse, generate all getters and setters after defining class fields: Right-click --> Source --> Generate Getters and Setters... */

  public String getTitle() {

    return title;
  }

  public void setTitle(String title) {

    this.title = title;
  }

  public String getAuthor() {

    return author;
  }

  public void setAuthor(String author) {

    this.author = author;
  }

  public double getPrice() {

    return price;
  }

  public void setPrice(double price) {

    this.price = price;
  }

  /** Pro-tip: In Eclipse, generate a toString() method for a class: Right-click --> Source --> Generate toString()... */

  @Override
  public String toString() {

    return "Book [title=" + title + ", author=" + author + ", price=" + price + "]";
  }

}

Step 3: Create a DAO class. I'll add two methods to it - one for inserting a Book and one for selecting all the books in the table.

package com.xeiam.yank.demo;

import java.util.List;

import com.xeiam.yank.DBProxy;

/**
 * DAO (Data Access Object) Class for BOOKS table. 

 * This is where you create your own methods for SQL interaction with a database table.

 * Each table in your database should have it's own DAO Class.

 * 
 * @author timmolter
 */
public class BooksDAO {

  public static int insertBook(Book book) {

    Object[] params = new Object[] { book.getTitle(), book.getAuthor(), book.getPrice() };
    String SQL = "INSERT INTO BOOKS  (TITLE, AUTHOR, PRICE) VALUES (?, ?, ?)";
    return DBProxy.executeSQL("myconnectionpoolname", SQL, params);
  }

  public static List selectAllBooks() {

    String SQL = "SELECT * FROM BOOKS";
    return DBProxy.queryObjectListSQL("myconnectionpoolname", SQL, Book.class, null);
  }
}

Step 4: Use your new persistence layer in your code. For demonstration purposes, I'll create a simple class that calls the two methods in the DAO and prints out the results. In this class, first define the connection properties. The Yank API needs to know how to connect to your database: which JDBC driver, which table, which user, and the password, and how many Connections in the connection pool. For the last four properties, the word 'local' corresponds to the name of the connection pool. Notice in the DAO class that the DBProxy method calls are passed 'local' as the first parameter. This feature allows you to have multiple Connection pools in your application if you want.

import com.xeiam.yank.DBConnectionManager;

public class BooksExample {

    public static void main(String[] args) {

        Properties props = new Properties();
        props.setProperty("driverclassname", "com.mysql.jdbc.Driver");
        props.setProperty("local.url", "jdbc:mysql://localhost:3306/Yank");
        props.setProperty("local.user", "root");
        props.setProperty("local.password", "");
        props.setProperty("local.maxconn", "5");

        DBConnectionManager.INSTANCE.init(props);

        // Insert Book
        Book book = new Book();
        book.setTitle("Cryptonomicon");
        book.setAuthor("Neal Stephenson");
        book.setPrice(23.99);
        BooksDAO.insertBook(book);

        // Select All Books
        List allBooks = BooksDAO.selectAllBooks();
        for (Book book1 : allBooks) {
            System.out.println(book1.toString());
        }

        DBConnectionManager.INSTANCE.release();
    }
}

Here's the output:

Book [title=Cryptonomicon, author=Neal Stephenson, price=23.99]

Piece of Cake!!!

Additional Information

As you can see, it is really easy to use Yank to push and pull data into and out of a database from your Java application. On the Yank example page, you can see a few more advanced capabilities as well. You can set up your database connection information in a properties file rather than directly in your Java code if you want. You can also keep all you SQL statements in a single properties file and access them using the DBProxy.*SQLKey() methods. In addition to the insert and select statements shown above, you can query in anyway you want: update, insert ignore, replace, batch query, etc.

Yank has 3 dependencies, so in order to integrate Yank into your application you'll need not only the Yank jar on your classpath, but also these:
Apache Commons DBUtils
Simple Logging Facade for Java (SLF4J)
MySQL Connector/J

And remember, this will work with any type of database that has a JDBC driver, such as PostgreSQL. You would just have to add the appropriate JDBC driver to your classpath, and modify the connection properties appropriately.