Thursday, April 22, 2010

ActiveJDBC the Basics

The title of this post has a class name in it...almost. The real class name is activejdbc.Base

This is an interesting class, in a sense that it is a completely static class (all methods static) and it is designed to wrap standard JDBC functionality in the most simple and succinct way humanly possible.
It allows to open a connection, query DB and close a connection in 3 lines of code - you have to write a half of page for this in any Java technology!
Here are some examples:
Base.open("oracle.jdbc.driver.OracleDriver", "jdbc:oracle:thin:@localhost:1521:xe", "usr", "pwd1");
List<Map> records = Base.findAll("select * from people");
//..iterate over list
Base.close();
As you can see, this exposes all SQL that is interesting to a developer and hides all the ungodliness of JDBC, including driver, connection, exceptions, etc.
I literally bent backwards (well almost:)) to make this code as clear as possible.
In the example above, the Base.open() opens a connection and attaches it to a thread. This allows any subsequent call consume it, while Base.close() closes the connection, obviously.
Another example:
List<Map> records = Base.findAll("select * from people where last_name = ? and name = ?", "Smith", "John");
I think this one is self-explanatory...and another one:
Base.find("select * from people", new RowListenerAdapter() {
            public void onNext(Map record) {
                System.out.println(record);
            }
        });
In the former examples, the entire result set (findAll()) was read into a list, but in some cases you will need to read millions of records and process them as in the stream (SAX - style of sorts).
The latter example achieves this goal, and you do not have to write a loop, the Base class takes care of it.

The Base class is not a super class to anything. It is just a utility that can be used externally and of course is used internally by the framework.

cheers,
igor

8 comments:

Red said...

Hey there. This looks like just the thing I was looking for. Any db persistence work I've done in the past couple of years has been with ActiveRecord. I'm now working on a Java project where I'd like quick and simple database access to some metadata and the idea of trying to use something like Hibernate is out of the question in my mind. I've stopped short of writing my own simple JDBC wrapper and came across ActiveJDBC. I'm ready to test this out yesterday! Any chance you have this up on some public repo yet?

Igor Polevoy said...

Red, thanks much for this posting and the interest; this means a lot to me. The few postings I published so far are just scratching the surface, since this is a full ORM implementation with many advanced features. However, it is not completely ready to be published yet and I'm working hard putting on finishing touches. I estimate that it will come out officially within four weeks from now. I hope you can wait.

thanks,
igor

david said...

Hi Igor;

This sounds like just what I'm looking for. Any chance I can get a link to the source?

Thanks

david[at]cheslow.net

Igor Polevoy said...

David, the sources have not been published yet, I'm in the process of preparations to open sourcing entire framework. I hope to do this within a few weeks time.

thanks,
igor

Blacktiger said...

So does the findAll method return a List>?

Igor Polevoy said...

blacktiger, I think it is clear that the Base.findAll(..) returns a list of maps - List<Map>, while Model.findAll(..) returns an instance of LazyList<T extends Model>.

The LazyList class allows for a DSL (described in another post) and has a delayed evaluation of queries, while List is just a plain old list of maps. The Base.findAll() implies that it will fetch an entire collection from DB and place it into a list.

I hope this explains it.

thanks,
igor

Blacktiger said...

Somehow my previous comment got messed up. I was trying to ask what the type of the Map is. Are the keys and values both Strings? Thanks.

Igor Polevoy said...

Blacktiger, the keys in the Map are all Strings and they correspond to columns in a table, except they are all lower case. The values are whatever was returned by the JDBC driver. This would be a JDBC Type corresponding to the column type. The value types would then be mapped to whatever types that a specific JDBC driver for a DB provides.

Hope this helps,
igor