Les Hazlewood Where Les is More

Root Persistent Class for ORM Hierarchies (Hibernate, et. al.)

Ok, I'm about to divulge to the world one of my little programming gems - something I've used on every single project for almost the last 4 years now. It is very easily translated to any other OO language as well, especially C# for the .NET/Hibernate.NET folks.

I haven't been keeping it secret or anything, I guess I just never took the time to write it out for general public. So when someone reading my blog asked to see the source for it, I figured now is as good a time as any to write about it.

It is a root/base class from which all my persistent Classes extend. To put it another way, if I have Java instances that I need to store to a database through Hibernate or some other EIS API, every one of those instance Classes extend from this base class (either directly or indirectly in an OO hierarchy). Every entity in every persistent class hierarchy I've used in the last 4 years has it as its hierarchy root - it is versatile and resilient

Now, if you've used Hibernate much before, you'll realize this isn't the world's biggest secret - most people do something similar. Its a great idea. I'm just making mine available to the world in case there are those that haven't done something similar yet, or if those who have just want to see how I do things.

What is this class called? I call it Entity. In Object-Relational Mapping circles, the word Entity often comes up in the context of object persistence discussions - "Persistent Object", "Persistent Entity", "Base Persistent Object", etc. I personally think "Entity" is elegantly succinct, so I stuck with it.

Before going on to the code, I just want to clarify my Entity class a little bit. It is not an implementation of what many call the "Active Record design pattern". This means this base entity class doesn't know how to persist or delete itself via any save() or delete() methods.

I'm a firm believer in keeping persistence logic code out of my domain model to prevent the chance of polluting the rest of my application with those APIs (it goes beyond API pollution too - google the principal of "Low Coupling, High Cohesion" for more info). Anyway, and I relegate all such logic to DAO implementations and all of my domain classes remain nice and clean.

Ok, so now that point is settled, here's my oh-so-yummy-and-incredibly-useful Entity class:

import org.apache.commons.logging.Log;
import org.apache.commons.logging.LogFactory;

import java.io.Serializable;

/**
 * Root parent class for all persistent object entities.
 *
 * <strong>NOTE:</strong> Subclasses should <em>always</em> provide a unique
 * onEquals() and hashCode() implementation and these should not use
 * the id() property - i.e. always keep in mind the subclass' 'business keys'
 * when implementing those methods.
 *
 * @author Les Hazlewood
 */
public abstract class Entity implements Identifiable, Serializable, Cloneable {

    protected transient final Log log = LogFactory.getLog(getClass());

    /**
     * RDBMS Primary key, aka 'surrogate key'.  Long surrogate keys are best
     * for RDBMS performance (for many reasons that can't be expanded on here)
     * But, every single table should _always_ have a 'business key' - a unique
     * constraint across one or more columns that guarantee row duplicates will
     * never occur. Null value means the object hasn't been persisted to the RDBMS
     */
    protected Long id = null;

    /**
     * Used for optimistic locking to ensure two threads (even across different machines)
     * don't simultaneously overwrite entity state - not necessarily used by all subclasses.
     * Pretty much required if in a high-concurrency environment and/or if using distributed
     * caching in a cluster.   It (and its corresponding mutator methods) is not called
     * 'version' to prevent eliminating that name from subclasses should the business
     * domain naming conventions require it.  Also 'entityVersion' is self-documenting
     * and leaves little room for incorrect interpretation.
     */
    protected int entityVersion = -1;

    public Entity() {
    }

    public Long getId() {
        return this.id;
    }

    /**
     * Should <em>never</em> be called directly.  Only via Hibernate or other EIS framework, since
     * they get the ID from the RDBMS directly.
     *
     * This method can be removed entirely if the EIS framework supports setting the ID property
     * directly (e.g. through reflection).  Hibernate does support this, it is called 'property access'.
     */
    public void setId(Long id) {
        this.id = id;
    }

    public int getEntityVersion() {
        return this.entityVersion;
    }

    /**
     * For the same reasons as the setId() method, this should only be called by a
     * framework and never directly.  Can be removed if the framework supports property access.
     */
    public void setEntityVersion(int entityVersion) {
        this.entityVersion = entityVersion;
    }

    /**
     * This method is declared final and does a lot of performance optimization:
     *
     * It delegates the actual "equals" check to subclasses via the onEquals method, but
     * it will only do so if the object for equality comparison is
     *
     * <ol>
     * <li>not the same memory location as the current object (fast sanity check)</li>
     * <li>of type Entity or one of its subclasses</li>
     * <li>Does not have the same id() property</li>
     * </ol>
     *
     * #3 is important:  this is because if two different entities have the ID property
     * already populated, then they have already been inserted in the database, and
     * because of unique constraints on the database (i.e. your 'business key'), you
     * can <em>guarantee</em> that the objects are not the same and there is no need
     * to incur attribute-based comparisons for equals() checks.
     *
     * This little technique is a massive performance improvement given the number of times
     * equals checks happen in most applications.
     */
    public final boolean equals(Object o) {
        if (o == this) {
            return true;
        }

        if (o instanceof Entity) {
            Entity e = (Entity) o;
            Long thisId = getId();
            Long otherId = e.getId();
            if (thisId != null && otherId != null) {
                return thisId.equals(otherId) &&
                        getClass().isAssignableFrom(e.getClass());
            } else {
                return onEquals(e);
            }
        }

        return false;
    }

    /**
     * Subclasses must do an equals comparison based on business keys here.
     */
    public abstract boolean onEquals(Entity e);

    public abstract int hashCode();

    /**
     * If children classes override they must always call super.clone() to get the object
     * with which they manipulate further to clone remaining attributes.  Never acquire
     * the cloned object directly via 'new' operator (this is true regardless of this Entity
     * class or not).
     */
    @Override
    @SuppressWarnings({"CloneDoesntDeclareCloneNotSupportedException"})
    public Object clone() {

        Entity e;
        try {
            e = (Entity) super.clone();
        } catch (CloneNotSupportedException neverHappens) {
            // Should _never_ happen since this class is Cloneable and
            // a direct subclass of Object
            throw new InternalError("Unable to clone object of type [" + getClass().getName() + "]");
        }

        e.setId(null);
        e.setEntityVersion(-1);
        return e;
    }

    /**
     * Returns a StringBuffer representing the toString function of the class implementation. This
     * should be overridden by all children classes using <tt>super.toStringBuffer()</tt> as the
     * base, adding properties to the returned StringBuffer.
     *
     * @return a <tt>StringBuffer</tt> reperesenting the <tt>toString</tt> value of this object.
     */
    public StringBuffer toStringBuffer() {
        StringBuffer sb = new StringBuffer();
        sb.append("id=").append(getId());
        return sb;
    }

    /**
     * Returns toStringBuffer().toString().  Declared as 'final' to require subclasses to override
     * the {@link #toStringBuffer()} method, a cleaner and better performing mechanism for toString();
     *
     * @return toStringBuffer().toString()
     */
    public final String toString() {
        return toStringBuffer().toString();
    }
}

You'll notice that the Entity class also implements Identifiable, which is nothing more than this:

/**
  * @author Les Hazlewood
  */
public interface Identifiable {
    Long getId();
}

This doesn't look too useful, but I have another interface that subclasses ('sub interfaces'?) it:

/**
  * @author Les Hazlewood
  */
public interface Referenceable extends Identifiable {
    String getLabel();
}

Referenceable is particularly useful in GUI/web code where you might want to present a list of options to the user, and the list-generation code only cares about IDs and readable strings to present to the user. For example, a drop-down/select box:

$referenceable.label

The list generation code doesn't care if the collection it is processing has User elements, or EmailAddress elements, or anything else. Ahh, the beauty of polymorphism

Anyway, I hope you find this Entity class as useful as I have - it is the staple by which I develop all of my domain models in Java.

Cheers,

Les

Configuration-hell remedy with Singleton injection – DON'T do it

So, I just finished reading this blog post about Spring configuration advocating static getInstance() methods in some places in your code to reduce the amount of Spring xml config. Since I posted a reply on that blog, and the author would probably be inclined to moderate my entry and delete it because I directly oppose his position, I've reposted it here for the benefit of others to read.

THAT POST ADVOCATES POOR ARCHITECTURE. IGNORE IT.

If you're relatively new to the Spring framework, ignore the recommendations in that post entirely - you'll be saving yourself a _lot_ of pain in your software architecture.

Basically, here's my reply:

This is a really bad idea and is exactly what Spring pojo-based Dependency Injection was created to avoid - to replace the Service Locator pattern. What you're providing in a static getInstance() call is essentially a type-specific Service Locator.

Statics are evil - they're inherently non-OO and usually encourage poor programming practices, especially the proliferation of unnecessary functional programming in an OO language. They should only be used to overcome poor programming situations outside of your control - i.e. a tool to use in an extremely limited basis only when you can't use something else.

And although what you describe might make your life easier in the immediate sense, it significantly complicates it in other ways. How, for example, would you unit test your code properly without introducing dependencies not required for the test? Cleaner instance-level DI allows you do do things such as creating mock objects and anonymous inner classes for testing that is not possible with static singletons or where you would have to change a lot of code.

If you want to make your life easy, use autowiring - that's exactly why it was created. The new Spring 2.0 XML namespaces also simplify things greatly, reducing XML config. And, with IDEs like Eclipse and IntelliJ IDEA that actually can traverse, manage, and refactor the XML spring files for you, the "XML Hell" argument for using Static singletons, especially when your own code suffers greatly in flexibility, is not really an issue.

Bottom line - never let laziness dictate your software architecture (especially when similar alternatives like autowiring exist), and stick with the pragmatic, well-thought and proven truly Object-Oriented solution.

I just thought it important to raise the issue on this for anybody reading this blog entry, especially those relatively new to Spring. What is mentioned is _not_ a good idea for 99% of cases, and the less-experienced Spring folks shouldn't be led down a dangerous path. It could introduce really bad habits that would hurt you later on.

Consistent Cache Configuration: Spring, Hibernate, EhCache, Shiro, et. al.

Have you ever wanted to use caching in your Spring/Hibernate application beyond just supporting Hibernate's 2nd-level cache?

If you know what a Hibernate 2nd-level cache is, you really know how huge its performance benefits are. Wouldn't it be useful to utilize caching for other things in your application? Even if you don't explicitly use a caching API in your app, you still might already be using caching without knowing it - other open source frameworks in addition to Hibernate utilize caching internally for the same performance benefits.

This article explains how to achieve the following:

1) I know I'm going to utilize caching for Hibernate's 2nd-level cache, but I want to enable that same caching support to other libraries and frameworks that might need it. It would also nice to have if I ever need to use it in my own application code directly.

2) My application is Spring-configured, so I want to configure that caching support in Spring like everything else and then have all the frameworks/libraries, including Hibernate, to use these Spring-configured cache beans.

Unfortunately Hibernate makes this a pain to do.

Hibernate uses something called a CacheProvider to support its 2nd-level cache. A Hibernate SessionFactory uses a single CacheProvider to maintain/manage the individual Cache instances used by the 2nd-level cache.

Now here's the problem: This CacheProvider is instantiated by Hibernate based on text configuration properties specified to the SessionFactory. When the SessionFactory starts up, it reads these properties, finds the one called hibernate.cache.provider_class which specifies a fully-qualified class name of the CacheProvider implementation, and creates a new instance of that class via reflection. It then uses that instance from then on to manage the Cache instances it needs.

For existing spring configs, here is a simplified example (note the 2nd hibernate property):

Why is this a problem? Because you can't easily configure your CacheProvider instance yourself and then just tell the SessionFactory to use it. The SessionFactory interface and its default implementation do not have setter methods that would allow you to do so. This means you can't use Dependency-Injection to set the CacheProvider instance on the Hibernate SessionFactory in Spring or any other DI microcontainer.

This is a problem for me too. The scenario that prompted this article happens to me quite a bit - I use Hibernate plus other libraries that benefit from caching. My own open-source project, Apache Shiro, can use caching to greatly speed up security checks. When I use Hibernate and Shiro in the same application, I want both frameworks to use the same underlying cache infrastructure. And although Shiro supports DI for its cache support, Hibernate does not, which means I have to jump through hoops to get Hibernate to play nice.

Where does Ehcache come in to this? Well, Ehcache is one of the more well-known and stable open-source caching solution for enterprise applications. It is stable and has a long history, it is extremely efficient with goodies like smart multi-threading under the hood, and now with Ehcache 1.3+, supports multicast distributed caching in a cluster - a huge benefit in enterprise apps. Basically, for open-source options, it is one of the best you can get. Cheers to Greg Luck for creating and supporting this great library (Another wonderful Open Source alternative is TerraCotta, take a look at that too).

So, in this particular example, I'm using EhCache but I also want to use it not just for Hibernate, but for Shiro and everything else that could use a Cache. And until now, I've been using Ehcache as Hibernate's cache provider using the aforementioned text property. Hibernate would create an instance of EhCacheProvider and use it internally. Basically this EhCacheProvider implementation is a wrapper around EhCache's own API of a CacheManager.

The CacheManager is really what I want to configure in Spring. Typically it is good practice and much easier to specify a single CacheManager for an application, which uses a single ehcache.xml file for all configuration. Then you can use this one ehcache.xml file for your Hibernate cache configuration, as well as for any other library that would use EhCache under the hood.

So, since you can't inject a CacheManager into Hibernate's SessionFactory, how do you do this in Spring?

Well, Since Hibernate instantiates the CacheProvider itself, and we can't inject anything, our only option left is via static memory. Blech, I know - I don't like statics any more than you do, but don't worry - it is _only_ used as a mechanism to make Hibernate play nice and its never used anywhere else in your config or application code.

*Note that static memory will only allow a single CacheManager to be used across the entire VM, so if you need more than one Hibernate SessionFactory, each with its own separate cache configs, you'll need to do more trickery (maybe 2 static fields? one per SessionFactory? You'll know more about your app than I do, so I'll leave how to do that to you. But you can use this the following technique and expand on it for your environment).

Let's get to the code, its only one class. You'll create your own CacheProvider implementation to statically reference a CacheManager instance. The CacheManager instance will be configured in Spring, and we'll get to that in a bit. Here's the CacheProvider implementation:

Ok, now that you have this class, what do you do with it? Well the first thing is to change your hibernate.cache.provider_class value to now be com.leshazlewood.hibernate.ExternalEhCacheProvider in your Hibernate SessionFactory bean definition. Then you want to define your CacheManager instance as a bean in your Spring config. Next you want to tell this CacheProvider implementation to use that instance when Hibernate needs to use caching functions.

We do that via a cool little Spring trick - by using the MethodInvokingFactoryBean. Basically this bean will call a static method at application startup with specified method arguments. Its a handy little tool that we can use to statically call the setter method that makes the CacheProvider work:

So the above spring config says: At application startup, create the CacheManager instance named 'ehcacheCacheManager' and then inject it into the ExternalEhCacheProvider via that class's 'setCacheManager' static method.

But are we finished?

Well, not quite. We have one piece of cleanup work to do.

The experienced Spring folks will recognize that there can possibly be a race condition with our Hibernate SessionFactory and CacheManager/CacheProvider definitions. Yes, our Spring-configured CacheManager instance will be created and injected into the ExternalEhCacheProvider class correctly, and our Hibernate SessionFactory bean instance will be created correctly. But, what if the Hibernate SessionFactory tries to use a ExternalEhCacheProvider instance before it is ready to be used? (i.e. before the static CacheManager property has been injected?)

To prevent this race condition and guarantee that the ExternalEhCacheProvider's internal CacheManager instance is set so it is available when the Hibernate SessionFactory needs it, we use the spring bean 'depends-on' attribute in our SessionFactory definition:

So, although our Hibernate SessionFactory bean doesn't actually use the CacheManager as a property - otherwise this whole article would be pointless - we force it to wait until the cacheProviderCacheManagerInjector bean has done its work before we allow it to initialize.

We make the 'depends-on' attribute point to this injector (MethodInvokingFactoryBean) instance specifically (as opposed to the ehcacheCacheManager bean) because we care that it is not only created, but also injected too.

There. Now we're done.

Now when the Hibernate SessionFactory bean starts up and creates its hibernate.cache.provider_class instance, we can rest assured that it will access our Spring-configured CacheManager.

And, you'll be able to use that same Spring-configured 'ehcacheCacheManager' bean and inject it into Shiro, or any other framework that supports simple Dependency Injection. Because this bean is an application singleton and uses a single config file, now all of your caching config across the entire application is easily manged from the same location - very convenient.

Have fun!

Spring Application Bootstrap Data

When you install an application for the first time, many times you want 'bootstrap' data to exist before the application is used for the very first time. Here's a simple but easy technique to get bootstrap data inserted into your application upon first startup.

Prior to the following approach, I used to have 'default.data' and 'sample.data' tasks in my ant scripts that either ran SQL manually, or started up a separate Spring ApplicationContext and inserted data explicitly. You had to run it manually from ant, which 1) required that ant be installed and 2) that you had the project checked out on the box that you were installing data to. Many production and QA environments didn't meet this criteria, and even if they did, it is still cumbersome and isn't as nice as an 'automatic' solution.

My newer automatic solution moves this type of data insertion logic into the actual application, where it is better managed and tested. There is another benefit too though: Since I use Hibernate and JCR as the EIS-tier APIs, it is far easier to insert data via these standard APIs than to do so via raw SQL. This is because you can write all of your initial data objects and graphs with Java or Groovy POJOs, utilizing the benefits of powerful IDE coding features, and let the Hibernate and JCR frameworks insert all the data with dependencies for you: a massive time saver.

So, here's a simple way to do this:

You create a POJO that will execute at application startup automatically after its dependencies have been injected. Here's an example:

The key to this code working as a POJO in your normal application configuration is due to two things:

1. The insertBootstrapData() method is wrapped in the TransactionTemplate. If anything goes wrong during the execution of that method, it will be rolled back and the database remains in a consistent state
2. The first bit of code in insertBootstrapData() checks to see if a well-known entity already exists in the database. If it does, you can assume that the bootstrap data has already been inserted, and return quietly.

You can create other 'Bootstrap Beans' like this to do other things as well. The above one initialized RDBMS data. You can have another one that initializes your JCR repository. Or another that checks against a license store to ensure that the application installed is allowed to be installed. All sorts of things...

Java Email Address class

UPDATE: This Java class was updated on February 1st, 2008 to account for domain literals and quoted strings such as "John Smith" <john.smith@somewhere.com>. It is now effectively the only complete and semantically correct email validator for Java.

PETTY REQUEST: The update required considerably more effort than the original as it now accounts for all valid RFC parsing conditions. Because of this, and that this page is easily my most visited, I'd appreciate it if you could show your appreciation by hooking a brother up and clicking on some ads. It helps pay for my hosting. Thanks!

I'm writing a new open source CMS (Community Management System) based entirely on the Spring Framework and Hibernate.

This CMS will take many cues from Drupal and other PHP based CMS systems, but be far more flexible, have fantastic OO and design pattern architectures and be a benefit to the Java Enterprise software community. I've decided to abandon JSR-168 support - I want a much cleaner, easier to implement, OO-based and typesafe "plugin" support framework - which I'm working on now. Suffice it to say I'm not a fan of JSR-168, but that's a whole 'nuther post.

Anyway, In this CMS, I'm using time-honored OO classes I've used on many many projects. One such is the EmailAddress class that I've referenced in earlier posts in this blog for email address validation. I've gotten some good feedback on this class, so I thought I'd just post the whole thing in case anyone wants to benefit from it (instead of just using code chunks I've posted before).

Here it is: