Implementing a Lazy JDBC DAO

As I have created the SpacesCategoryDAO, I have been creating an CategoryDAO interface:

/**
 * Save and retrieve Categories.
 */
public interface CategoryDao {

    /**
     * After this is called, get with the return
     * value should always return an object
     * identical to the argument.
     */
    Long store(Category category);

    /**
     * Returns a Category with the argument id.
     */
    Category get(Long id);


    /**
     * Returns a subset of the subcategories of
     *  the category with the specified id.
     */
    Collection findByParentId(Long parentId, 
            int offset, int length);

    /**
     * Returns the count of subcategories of the
     * category with the specified id.
     */
    int countByParent(Long parentId);

    /** 
     * After this is called, the schema should
     * be created in the underlying data store
     *  (if appropriate).
     */
    void initialize();

    /**
     * After this is called, no previously
     * constructed object shall be returned from
     * get. */
    void clearSessionCache();

}

I will not cover implementing this interface for JDBC in detail, but I the downloadable source includes the source for JdbcCategoryDao. It is quite prosaic. I will use this interface to implement paged lazy loading in the final part of the article.

Paged Lazy Loading

I have showed that creating a lazily loaded collection is just as easy as creating a lazily loaded relationship. In order to make lazy loading work well, I have implemented a session cache for storing objects. This introduces a few issues with regard to performance: if we have too many objects in the cache, we can run out of memory. This is normally mostly an issue for one-to-really-many collections, and most object-relation mapping tools ignore it beyond providing a way to remove objects from the cache. This is to support what I would like to call one-to-very-very-many relationships.

There are several issues with one-to-very-very-many relationships. One problem that can be solved is that of memory consumption. In the systems I am currently working on, we have one-to-many relationships that can contain tens of thousands to a million objects. Loading all of these up when the first is needed might not be what you want. In order to fix this problem, I will use a strategy of paging: only a subset of the objects will be held in memory at the same time. For the point of illustration, I will use a page size of 5 (which is pointless in the real world, but it makes it easier to illustrate the technique).

public void testPagedObjects() {
    Category saved = categoryDao.get(largeCategory.getId());
    Collection savedChildren = saved.getSubcategories();
    Iterator iter = savedChildren.iterator();
    assertLoadedCount(0, largeCategory.getSubcategories());
    assertEquals("child[0].name",
        "subcategory 0",
        ((Category)iter.next()).getName());
    assertLoadedCount(5, largeCategory.getSubcategories());
}

In this code, largeCategory is a test Category object with 20 subcategories (initialized in the Test setUp). The method assertLoadedCount verifies that exactly the specified number of objects from the collection have been loaded.

private void assertLoadedCount(int expectedLoaded,
                               Collection subcategories) {
    int actuallyLoaded = 0;
    for (Iterator iter = subcategories.iterator(); iter.hasNext();) {
        Category element = (Category) iter.next();
        if (categoryDao.isLoaded(element.getId())) {
            actuallyLoaded++;
        }
    }
    assertEquals("loaded subcategories",
                 expectedLoaded, actuallyLoaded);
}

In order to support this test, I have expanded the CategoryDAO interface with the method boolean CategoryDAO.isLoaded(Category) to check whether an object has been inserted in the session cache. This method can also be used to improve the other lazy-loading tests.

Here's a paged implementation for the SpaceCategoryDAO:

protected Collection lazyFindByParentId(final Long parentId) {
    return new PagedLazyCollection(countByParent(parentId)) {
        public Collection getSubCollection(int offset, int pageSize) {
            return findByParentId(parentId, offset, pageSize);
        }
    };
}

I have introduced several new concepts. First, CategoryDAO now supports a countByParentId method, so we can implement java.util.Collection.size without loading all of the objects. Second, CategoryDAO.findByParentId has to be able to support paging. The implementation of these methods is trivial, and in the SpaceCategoryDAO doesn't really work. So instead, I will show you a typical JDBC implementation:

public int countByParent(Long parentId) {
    String sql = "SELECT count(*) FROM category WHERE parent = ?";
    return getJdbcTemplate().queryForInt(sql, new Object[] { parentId });
}

public Collection findByParentId(Long parentId, int offset, int length) {
    return getJdbcTemplate().query(
        "SELECT * FROM category WHERE parent = ? LIMIT ? OFFSET ?",
        new Object[] { parentId, new Integer(length), new Integer(offset) },
        new RowMapper() {
        // code to create a Category from a Recordset row omitted for brevity
        });
}

Finally, I have introduced a PagedLazyCollection class:

public abstract class PagedLazyCollection extends AbstractCollection {

    private class PagedLazyCollectionIterator implements Iterator {
        // ....
    }

    private final int size;

    public PagedLazyCollection(int size) {
        this.size = size;
    }

    public Iterator iterator() {
        return new PagedLazyCollectionIterator();
    }

    public int size() {
        return size;
    }

    public abstract Collection loadPage(int offset, int pageSize);

}

All the magic happens in the PagedLazyInterceptor:

private class PagedLazyCollectionIterator implements Iterator {

    private final int pageSize = 5;

    private int offset = 0;

    // Trick to avoid null checks
    private Collection currentCollecton = new ArrayList();

    private Iterator currentIterator = currentCollecton.iterator();

    public boolean hasNext() {
        boolean onLastPage = offset >= size;
        return currentIterator.hasNext() || !onLastPage;
    }

    public Object next() {
        if (!currentIterator.hasNext()) {
            nextIterator();
        }
        return currentIterator.next();
    }


    private void nextIterator() {
        currentCollecton = loadPage(offset, pageSize);
        offset += currentCollecton.size();
        this.currentIterator = currentCollecton.iterator();
    }

    public void remove() {
        throw new UnsupportedOperationException("remove not implemented");
    }

}

The interesting bit is in PagedLazyCollectionIterator.nextIterator, where we load the next page. This code should be sufficient to get the test to pass.

Unloading Pages

This code, as it stands, will not help much with preserving memory. Even though we wait with reading a page until it is needed, we never throw pages out again! Here's a test that illustrates the problem:

public void testPagedCollectionPagesOutUnusedObjects() {
    Category saved = categoryDao.get(largeCategory.getId());
    Collection savedChildren = saved.getSubcategories();
    Iterator iter = savedChildren.iterator();
    while (iter.hasNext()) iter.next();

    assertLoadedCount(5, largeCategory.getSubcategories());

}

This test will fail, as the whole set of subcategories of largeCategory will be loaded into the session cache at this point. In order to fix it, the Iterator has to be able to unload pages as well:

public abstract class PagedLazyCollection extends AbstractCollection {

    private class PagedLazyCollectionIterator implements Iterator {
        // ....

        private void nextIterator() {
            unloadPage(currentCollecton);
            // ....
        }

        // ...
    }
    
    public abstract void unloadPage(Collection collection);
}

So SpaceCategoryDAO.lazyFindByParentId has to be expanded to tell the collection how to unload objects:

protected Collection lazyFindByParentId(final Long parentId) {
    return new PagedLazyCollection(countByParent(parentId)) {
        public Collection loadPage(int offset, int pageSize) {
            return findByParentId(parentId, offset, pageSize);
        }
        public void unloadPage(Collection collection) {
            unloadFromSessionCache(collection);
        }
    };
}

SpaceCategoryDAO.unloadFromSessionCache could hardly be easier:

public void unloadFromSessionCache(Collection categories) {
    for (Iterator iter = categories.iterator(); iter.hasNext();) {
        Category element = (Category) iter.next();
        sessionCache.remove(element.getId());
    }
}

At this point, we have actually implemented a lazily loaded collection that pages objects in and out as we iterate over it. The amount of code needed is surprisingly small.

Limitations

The code as I have shown has several quite severe limitations. I will explain the strategy for solving these limitations, but if you want to see a full implementation, you have to nag me to write a follow-up article.

• Adding objects to the collection: If we add or remove objects from Category.getSubcategories, the changes will have inconsistent effects. First, the modification will not happen through the category at all, but only by modifying the parent category of the subcategories in question. This will be reflected when we search for new pages in the collection. If the modification changes something having to do with the paging, things will be bad. We might get the wrong objects in the next page. The simplest way to solve modifications to the collection involve introducing constraints. For example: if we could introduce an immutable listIndex field in the subcategory, we would know that all new subcategories will be added at the end.
• Removing objects from the collection: Supporting remove can be even simpler: just keep a collection of removed objects in memory, and skip these objects when iterating. Neither of these strategies will work perfectly in all situations. For example, if you have an operation that will remove most of the collection, keeping the removed objects in memory is not such a good idea. In the simple case, we can ignore this problem. In the not-so-simple cases, more research is needed.
• Reference integrity: If an object in a subcategory collection is also used from other places in the code, it will accidentally be thrown out of the session cache when the collection iterates over it. This is a bona fide bug, but it is actually not too hard to solve (use two types of session cache), and the code is pretty uninteresting, so I will leave that as an exercise for the reader, if you really need it. Or you can nag me to fix it for you.
• Intelligent iteration: There are several things we might want to do with the collection in order to use it better. For example, we really need to be able to skip when iterating. Sadly, neither Iterator nor ListIterator supports this. To avoid expanding the standard Java collection interfaces, I have not implemented my own skip method. Doing so is easy, though. Alternatively, we could implement lazy behavior in PagedLazyIterator.next.
• Sorting and subqueries: If you want to sort the subcategories or search for a subset of them, the current structure does not support this well. There are two good approaches to follow. The most straightforward approach is to just use custom methods on the DAO (like findByParentIdAndNameOrderedByName()) and return paged collections. In this case, we have abandoned the domain model. If you want to keep the domain model, you need to use something more intelligent than SQL to query your objects. Hibernate criteria or TopLink expressions provide object libraries for queries. Use decorators on top of the collection to modify the criteria or expressions.

Conclusion

Implementing a lazily loaded, rich domain model isn't just possible, it is practically feasible. Even really big collections can be dealt with. The simple case is surprisingly simple, and depending upon your requirements, even the complex cases are manageable.

In this article, I have showed how you can construct a lazily loaded domain model that will support reference integrity, collections, and paged loading of very large collections. This is surprisingly easy to do. So the question is: should we abandon third party object-relation mapping tools like Hibernate, TopLink, and JDO and just write our domain model ourselves?