JDBM Tutorial - 2

Equipped with JDBM, we have a simple persistent layer for ToDoTasks without a large footprint; the entire JDBM library, jdbm.jar is an 88K jar file and you can find it on the JDBM site.

Table Presentation Matters
People have come to expect applications with table components to make their table views sortable by clicking on the header columns of the table. It takes some by surprise to find that the Swing toolkit has no built in functionality to support this easily. The oddest part of this is that Sun actually give people table sorting in plain sight. The Sun JavaDocs point to the extensive Sun Java tutorials online. If you follow the JTable links you get to a tutorial which eventually mentions, amongst lots of [Pending] comments in the text, the TableSorter

class which you can find at http://java.sun.com/docs/books/tutorial/uiswing/components/example-1dot4/TableSorter.java.
Now the TableSorter is a decorator model which can wrap an existing TableModel and add all the sorting functionality without changing the underlying TableModel. It doesn't store the contents of the table; it just does the bare minimum to work out how to sort the contents and map calls through to the wrapped model. In ToDoTasks, we have the TasksModel which is a simple view on the Tasks class with no sorting. In the TasksFrame class, once we have created the GUI, we call the Controller to get the TasksModel and then set that as the JTable model.

        TasksModel tasksModel;
        ...
        tasksModel=controller.getTasksModel();
        tasksTable.setModel(tasksModel);

To incorporate the TableSorter, we first need to wrap the the TaskModel in a TableSorter and then set the sorter as the JTable model like so:

        TasksModel tasksModel;
        TableSorter sorter;
        ...
        tasksModel=controller.getTasksModel();
        sorter=new TableSorter(tasksModel);
        tasksTable.setModel(sorter);

We keep a handle on the sorter as there's one thing more to do, hand the sorter the JTable's table header so it can step through it and add in mouse event listeners to make the headings trigger sorting behaviour:

        sorter.setTableHeader(tasksTable.getTableHeader());

And that's it. You now have a JTable which supports clicking on a heading to toggle between no sorting, ascending order and descending order. It also supports a secondary column for sorting by pressing control and clicking on the headings. Yes, it was that simple, and leaves you wondering why TableSorter isn't an official part of Swing.

We'll wrap up this article with a tip for more rapid prototyping. You can find yourself burning time handling enumerations when presenting them in a table, translating from an enum value to a string and vice versa. In ToDoTasks, the task priority is represented as a Java 5.0 enum in Priority.java, like so:

        enum Priority {
            NONE(0),LOW(1),MEDIUM(2),HIGH(3),CRITICAL(4);
            Priority(int priority) { this.priority=priority; }
            final int priority;
        }

Now, to quickly make that appear in the table, with names, you could write a custom cell renderer for the table which translated the enum value. Because enums are proper objects now, we can tell the JTable to use its defaults to render the value, and what is displayed is not the numerical value, but the name of the enum value.

To allow for editing of the value, again, we could write a custom CellEditor to do the work. But it's the matter of 3 lines of code to make the editor a drop down with all the enum values. To get all the values of an enum, you can call its values method. This returns an array in the order the enum values were declared. Once we've created our JTable in TasksFrame, we can create a DefaultCellEditor with a JComboBox.

        DefaultCellEditor priorityEditor=new DefaultCellEditor(
            new JComboBox(Priority.values()));

We initialise the JComboBox with the array from Priority's values. For usability's sake, we set the CellEditor to need two clicks to start editing the cell:

        priorityEditor.setClickCountToStart(2);

If we had left it at one click, it would very hard to select a row using that cell because it will immediately show a combobox menu to change it. The last step is to tell the table that whenever it sees a Priority value in a cell to use our new editor:

        tasksTable.setDefaultEditor(Priority.class,priorityEditor);

We now have a combobox editor which shows the enum's names as they appear in the code; a useful timesaver when you are prototyping.

---

tutorial-jdbm-1/2

JDBM Tutorial - 1

In the first of a series of tutorials that will end in a working application, we look at a simple persistence mechanism, and a grid for displaying data. In this series of tutorials, we're going to be showing how to enhance a simple application from a basic GUI to a full web enabled client and server. Our example application is ToDoTasks, a simple work tracking program. Each task has a name, notes, a priority, a percentage completed and when completed, the date it was complete.

In the ToDoTasks application, this is all displayed in a TasksFrame which has a JTable control, with a separate JTextArea for the notes. Underneath the hood, a class which implements the Tasks interface manages a collection of Task instances and generates TasksEvents when changes are made to it. A TasksModel listens to these TasksEvents and makes the Tasks' contents available to be rendered by the JTable which is created in TasksFrame. Finally, orchestrating these classes is a Controller class which creates the Tasks, TasksModel and TasksFrame.

Before we move on to expanding ToDoTasks, we're going to look at two elements of the application; persistence and presentation.

JDBM - When you absolutely don't need a database. There are times when all you need for an application is a simple manageable way to persist objects and even an embedded SQL database like HSQLDB or Derby/JavaDB is just a little too much for what you need. It's for situations like this that JDBM exists. JDBM at its simplest lets you store objects with a 'long' value for a record id. There are no database queries, just a simple find method to pull back an object by its record id. Of course it's not easy to work with just these record ids; for example, when an application starts up, how will it know which record ids represent what data. To get around this, JDBM has the ability for you to create named objects, where a name maps to a record id, so you can look up and retrieve record ids for 'important' records in the JDBM store.

You can find ToDoTasks JDBM implementation in JDBMTasksImpl.java. To use JDBM, we need to create a JDBM RecordManager, which you can get from the RecordManagerFactory giving it a file name as a parameter which will serve as the base name for the two files JDBM creates;

     RecordManager recman;
     ...
     recman=RecordManagerFactory.createRecordManager("tasks");

Storing a new object is simply a matter of calling the RecordManager insert method which will return the record id for retrieving the stored object. Setting a name for this record is done by calling the RecordManager's setNamedObject method with a name and the record id you want associated with that name. For example, from the Tasks generateTaskId method:

     Long generatedTaskId;
     ...
     generatedTaskId=new Long(1000L);
     recid=recman.insert(generatedTaskId);
     recman.setNamedObject("nextid",recid);

This stores a Long and creates a name, "nextid" associated with the record id returned by the insert. To retrieve an object from the store if you have the record id to hand, then the RecordManager fetch method will retrieve it;

   generatedTaskId=(Long)recman.fetch(recid);

If you don't have the record id to hand and it's a named object, you can get the record id with RecordManager's getNamedObject. This will return either the record id or 0 if the named object doesn't exist. You can use that attribute to determine whether you need to initialise the store. Back in Tasks generateTaskId we have an example of that:

     Long generatedTaskId;
     long recid=recman.getNamedObject("nextid");
     if(recid==0) {
        // There is no existing nextid; we create it
        generatedTaskId=new Long(1000L);
        recid=recman.insert(generatedTaskId);
        recman.setNamedObject("nextid",recid);
     } else {
       // We have an existing nextid; get the record
       generatedTaskId=(Long)recman.fetch(recid);
     }

Updating a record is a call to RecordManager's update method, which takes the record id and an object and replaces whatever is there with that object. Note that you can put a completely different class in the update and JDBM won't complain, it just sees things as serializable objects. This is good if you are persisting classes with a common subclass or interface but can lead to ClassCastExceptions if you don't manage it carefully.
When you've completed your updates or persisting new records, you need to commit the changes, using the RecordManager's commit method which completes the JDBM transaction. You can also use the rollback method to roll back changes to the last commit, but there are caveats to using that which we'll get back to. Here's the rest of generateTaskId which updates the stored task id:

   generatedTaskId++;
   recman.update(recid,generatedTaskId);
   recman.commit();

Now, you could use just this part of the JDBM API to manage a lot of persistence, but there are two classes you can use which make JDBM much more useful, HTree and BTree. The HTree gives JDBM a simple persistent hash tree into which you can put() and get() keyed values but lacks ordering or size semantics. The BTree is a more scalable and manageable tree, with ordering and size semantics and the ability to browse the tree. We use the BTree in the Tasks class to store the Task instances. To create a BTree, we call a static method, createInstance, in BTree, giving it a record manager and a Comparator instance to allow it to compare keys. JDBM comes with a set of Comparators for Long, String and ByteArray; as our key is a Long, we can use the LongComparator:

   BTree tasktable;
   ...
   tasktable=BTree.createInstance(recman,new LongComparator());

Now we have a BTree instance, we can use the setNamedObject() method to save a reference to the record; the BTree keeps a reference to its own record id in the JDBM store which we can get using the getRecid() method.

   recman.setNamedObject("tasktable",tasktable.getRecid());

To retrieve an existing BTree, we can now look it up using getNamedObject(), but to recreate the BTree instance, we use the static load() method of BTree. load() takes the record manager and record id as parameters and returns a BTree instance.

   long recid=recman.getNamedObject("tasktable");
   ...
   tasktable=BTree.load(recman,recid);

Working with the BTree is simple; we can use its insert method to add records:

   Task toDoTask=new Task();
   ...
   tasktable.insert(l,toDoTask,false);

The boolean parameter at the end sets whether the insert should replace the record if the key already exists. Here, we are inserting a new record, so it's set to false. The insert() method actually returns an object, which would be the value of the existing key. To retrieve a key's value, we use the find() method; in DBMTaskImpl.java we find:

   public Task getTask(Long id) throws IOException {
    return (Task)tasktable.find(id);
   }

To navigate around the tree, there is the TupleBrowser which we can obtain from the BTree using the browse() method which returns a TupleBrowser positioned at the start of the tree's keys. If you give browse() a key, it will position at just before that key in the tree, and if you give it a null as a key, it will position at the end; in JDBMTasksImpl.java we use this in the getTaskIds() which needs to return an array of all the keys in order, so we browse from the start;

   TupleBrowser tupleBrowser=tasktable.browse();

Once we have a TupleBrowser, we need to create a Tuple to hold key/value pairs:

   Tuple tuple=new Tuple();

The TupleBrowser takes this tuple as a parameter when we call the TupleBrowser getNext() or getPrevious() methods. Both methods return a boolean, true if a Tuple has been retrieved, false if not. So to iterate through all the key/value pairs we can call getNext() till it returns false:

   while(tupleBrowser.getNext(tuple)) {
      Long key=(Long)tuple.getKey();
      ...
   }

With the TupleBrowser we can navigate around the tree easily. If you make structural changes to the tree though, the TupleBrowser will become inconsistent and you should get a fresh instance of it. As mentioned earlier, there's a catch using BTree and HTrees and JDBM rollback, namely that rollback invalidates BTrees and HTrees in memory so if you do rollback, you need to reload any tree instances.


JDBM Tutorial - 1/2

---