This post primarily reflects the environment in which [...]]]> This post is written for developers that are trying to deploy a .war file inside of an OSGi runtime environment.  I experienced a lot of pain along the way to making my solution work, so hopefully this will alleviate any pain that you might have.

The Scenario

This post primarily reflects the environment in which I am writing and deploying my application.  Here are the key points that led me up to my course of action:

• I use Maven to manage my project.
• I already had an existing web application .war that had no ‘knowledge’ of OSGi.
• I knew I would need to ‘OSGi-ify’ the .war and turn it into a bundle, since this is required by the OSGi 4.2 Enterprise specification
• Once I had the new OSGi-compatible .war, I would need to quickly and easily start it up in an OSGi environment to test it.

The Setup

Based on my above environment/needs, I decided on the following:

• Because I use maven and I have created plain (non-web) OSGi bundles with the Maven Bundle Plugin in the past, it would make sense for me to use it again to make my .war into a bundle.
• Again, because I use maven, I want to launch my ‘OSGi-ified’ .war in an OSGi environment directly from maven.  I didn’t want to do anything painful like manually copy and install the .war into an OSGi container installed elsewhere.  That would be a pain that would frustrate me and infringe on my productivity.The Maven Pax Plugin looked like it could easily start an OSGi runtime (Felix, Equinox, etc)  as well as provide the additional web support that is required to launch .war files.  So, I decided to give that a go.

The Solution

Step 1: Make your .war OSGi-compatible

This was actually pretty easy, but there were two major problems I encountered along the way that caused me hours of suffering.  May my pain be your salvation!

Using the maven-bundle-plugin, you essentially tell it to create a MANIFEST.MF file with OSGi entries, and then you tell the maven-war-plugin to use that generated file.  All it takes is adding the following two plugins to your war project’s <plugins> section:

<plugin>
  <artifactId>maven-war-plugin</artifactId>
  <configuration>
    <archive>
      <manifestFile>${project.build.outputDirectory}/META-INF/MANIFEST.MF</manifestFile>
    </archive>
  </configuration>
</plugin>
<!--
    Enable support for non-bundle packaging types
    See: http://felix.apache.org/site/apache-felix-maven-bundle-plugin-bnd.html
-->
<plugin>
  <groupId>org.apache.felix</groupId>
  <artifactId>maven-bundle-plugin</artifactId>
  <extensions>true</extensions>
  <executions>
    <execution>
      <id>bundle-manifest</id>
      <phase>process-classes</phase>
      <goals>
        <goal>manifest</goal>
      </goals>
      <configuration>
        <instructions>
          <Bundle-SymbolicName>CHANGEME</Bundle-SymbolicName>
          <Export-Package/>
          <Import-Package>javax.servlet,javax.servlet.http,javax.servlet.*,javax.servlet.jsp.*,javax.servlet.jsp.jstl.*</Import-Package>
          <DynamicImport-Package>javax.*, org.xml.sax, org.xml.sax.*, org.w3c.*</DynamicImport-Package>
          <Bundle-ClassPath>.,WEB-INF/classes</Bundle-ClassPath>
          <Embed-Directory>WEB-INF/lib</Embed-Directory>
          <Embed-Dependency>*;scope=compile|runtime</Embed-Dependency>
          <Embed-Transitive>true</Embed-Transitive>
          <Web-ContextPath>CHANGEME</Web-ContextPath>
          <Webapp-Context>CHANGEME</Webapp-Context>
        </instructions>
      </configuration>
    </execution>
  </executions>
  <configuration>
    <supportedProjectTypes>
      <supportedProjectType>jar</supportedProjectType>
      <supportedProjectType>bundle</supportedProjectType>
      <supportedProjectType>war</supportedProjectType>
    </supportedProjectTypes>
    <instructions>
      <!-- ... etc ... -->
    </instructions>
  </configuration>
</plugin>

Just remember to set the values appropriate to your application, namely those for the <Bundle-SymbolicName> and <Web-ContextPath> and <Webapp-Context> entries (we’ll discuss the latter two shortly).

After you’ve added the plugins and changed the appropriate values, a normal maven build (e.g. mvn package or mvn install) will produce your OSGi-compatible .war!

But what you see is deceptively simple – there are two things that prevented me from deploying successfully for hours.  Make sure you avoid them:

Manifest Entries: <Web-ContextPath> or <Webapp-Context>?

Notice the two following lines in the maven-bundle-plugin‘s <instructions> element:

<Web-ContextPath>CHANGEME</Web-ContextPath>
<Webapp-Context>CHANGEME</Webapp-Context>

Doesn’t that look annoyingly repetitive to you?  Why do we need two?

Well, let’s cover what they are.  As you might have guessed by looking at either one individually, they specify the context path under which your web app will be accessible, for example http://localhost:8080/myContextPath.  If you don’t specify them, most OSGi web container implementations will default your context path to your .war’s Bundle-SymbolicName,  For example, servicing your webapp from http://localhost:8080/com.company.my.bundle.symbolicName.  That’s just plain ugly, so you really want to specify them to ensure your urls look sane.  But why are there two entries?

When I originally added the manifest entries, the only one I specified was the <Web-ContextPath> entry.  This is after all the correct Manifest entry as mandated by the OSGi 4.2 Web Applications Specification (Chapter 128 in the OSGi Compendium document).  I read the specification and added that entry accordingly.  All should work fine then, right?

Well, it would have if the Pax Web support used by the maven-pax-plugin used to launch the .war (covered below), was 100% OSGi 4.2 compliant.  It’s not.  I sat at my desk for hours, running various tests until 3:30 in the morning, swearing at myself that I couldn’t believe I was screwing things up, when all the documentation said it should be right!

Much to my early-morning chagrin, I discovered that the existing Pax Web support (0.7.2 at the time of this writing), does not yet understand the OSGi standard <Web-ContextPath> entry.  There is currently an outstanding Jira issue for them to fix this.  Until that is fixed, we’ll need to add both: the OSGi standard one to ensure it works in your standard OSGi deployment environment and the Pax Web-specific <Webapp-Context> one to make Pax happy while you’re testing with Maven.  When that Jira issue is fixed, you can remove it and keep the standard one.

But what if you don’t want to launch your .war using the maven-pax-plugin?  You can remove the non-standard entry, right?  

Well, not so fast – there are OSGi container distributions, such as Apache Karaf (which is the Felix OSGi runtime + a lot of nice enterprise features), that use the same exact Pax Web mechanism as their implementation to support .war deployments.  That means if you deploy your .war to Apache Karaf as your production environment, because Karaf uses the same Pax Web mechanisms, the non-standard <Webapp-Context> entry must still be specified.

Its safest to keep both entries and have them both reference a maven property that you can set once to avoid repeating yourself:

<properties>
    <web.contextPath>foo</web.contextPath>
    ...
</properties>

...
    <instructions>
        ...
        <Web-ContextPath>${web.contextPath}</Web-ContextPath>
        <Webapp-Context>${web.contextPath}</Webapp-Context>
    </instructions>
...

web.xml: use a <welcome-file-list>

Now that we got the Manifest entries out of the way, there’s one final issue that caused me grief: welcome files.

My web app has an index.jsp file at the root of the war file.  It is incredibly simple – all it does is redirect the user to a nice ‘home’ landing page:

<%@ page session="false" %>
<%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %>
<%-- Redirect to the home page --%>
<c:redirect url="/home/"/>

Trivial, right?

Well, my web.xml in my pre-OSGi .war did NOT have a <welcome-file-list> entry in it.  Tomcat and Jetty don’t care about this – they have a list of sensible defaults.  Because of that, I haven’t specified a welcome-file-list in years – I just didn’t think about it.

However, the  the OSGi war deployer mechanism I was using (Pax Web’s war extender) does require it.  It was not able to handle a request coming in to http://localhost:8080/myapp.  It didn’t know to automatically use the http://localhost:8080/myapp/index.jsp file.

This was equally as frustrating as the non-standard Manifest entry discussed above and further contributed to my hours-long “shoot me now, I hate OSGi” session – there were no error messages explaining why the request failed (terribly frustrating).  But I eventually figured it out by going through the arduous process of setting up an entirely separate ‘clean room’ .war project and trying different things from scratch.

I added the following XML snippet at the bottom of my web.xml file, and all was well again:

<web-app ...>
    ...
    <welcome-file-list>
        <welcome-file>index.jsp</welcome-file>
    </welcome-file-list>

</web-app>

Step 2: Launch your OSGi .war from Maven

Now that you have an OSGi-compatible .war, ideally you want to be able to launch it and test it immediately.  It would be a major pain to have to build your .war and manually copy it or install it into your OSGi deployment environment (e.g. Apache Karaf, Eclipse Virgo, Apache Geronimo, etc…).  We want instant gratification with no setup!!!

It’s the maven-pax-plugin to the rescue! (with the exception of the manifest entry and welcome-file-list complaints above)

Once you’ve completed both parts of step 1 above, the rest is smooth sailing.  Add the following plugin to your .war project’s <plugins> section:

<plugin>
    <groupId>org.ops4j</groupId>
    <artifactId>maven-pax-plugin</artifactId>
    <configuration>
        <provision>
            <param>--platform=felix</param>
            <param>--profiles=compendium,web,war</param>
        </provision>
    </configuration>
</plugin>

Notice that the first <param>, --platform=felix,  reflects my personal test environment.  You could specify --platform=equinox to use the Eclipse Equinox OSGi framework instead.  You could also specify other platforms as well.  See the maven-pax-plugin and Pax Runner documentation for more options.  You’ll naturally choose settings that will best reflect your production runtime environment.

The second <param> is what is important for testing .wars.  It specifies Pax Runner profiles that enable .wars to be deployed.  You can add other profiles as necessary, but those three are required for deploying .wars.

To run your web app, just execute the following:

mvn install pax:run

Super easy!

Success!

Once the two issues above were taken care of, and I could launch my new OSGi .war, it was accessible via http://localhost:8080/myapp and everything worked as expected.

But I hope this helps you, weary-eyed OSGi blog-searcher.  Good luck!

Whenever you see a class that implements an interface SomeName, and the name of that class is SomeNameImpl.

Guess what folks, EVERY implementation of an interface is an ‘Impl’. If you suffix ‘Impl’ at the [...]]]> Ok, I’m about to go on a rant, because I come across something regularly that really, really, REALLY irritates me:

Whenever you see a class that implements an interface SomeName, and the name of that class is SomeNameImpl.

Guess what folks, EVERY implementation of an interface is an ‘Impl’. If you suffix ‘Impl’ at the end of your class name, you’re being short sighted and portraying a potential lack of understanding of Interface-Driven Design: that you can have more than one implementation.

What if you ever create a new implementation? What if, when testing other components, you create a TestSomeName implementation or a MockSomeName implementation? Then the SomeNameImpl doesn’t make much sense anymore, does it? It could be a cause of confusion as to why you have more than one ‘Impl’, or, worse, perhaps it might make people think that you should only ever have one ‘Impl’.

Instead, if you need a default implementation, and can’t yet think of other cases where you might have other implementations, just call it DefaultSomeName. Then you’re telling the world, “Hey, this is our default implementation of this interface, and if any more ever are needed, we can create them, prefixed with a more meaningful name.”.

Yes, I’m an OO naming zealot, but you’d be surprised at how this little change, in conjunction with other ‘trivial’ changes, make code more readable, easy to understand, and most important, adaptable to change over time.

I haven’t been keeping it secret or anything, [...]]]> 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

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 [...]]]> 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!

Prior to the following approach, I used to have ‘default.data’ and [...]]]> 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…

PETTY REQUEST: The update required considerably more effort than the original as it now accounts for all valid [...]]]> 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:

Since I’m responsible for a lot of web 2.0 / enterprise software products, I wanted to find a framework and/or suite that I could leverage [...]]]> While attempting to quench my thirst for the latest and greatest software that would make my life easiser, I went ‘a searchin’ on the net to find frameworks and technologies.

Since I’m responsible for a lot of web 2.0 / enterprise software products, I wanted to find a framework and/or suite that I could leverage to cut my development time down. One of my biggest criteria in determining what is valuable is that of intuitiveness. I want things to make sense to me. Granted, this is a purely subjective statement, but I’ve found that what makes sense to me makes sense to most of the people in my field.

So, what makes sense to me? Object Oriented design.

I’m talking about pure OO – everything is an Object, objects communicate with other objects via messages, interface-driven design, abstraction, polymorphism, etc.

Well, since I’m a Java guy, I knew that I was at a dead end, since Java isn’t purely OO (ints and booleans are not objects, they’re “primitives”). But I love Java, and Java 1.5 helped a little bit with its auto boxing/unboxing feature, but that’s not perfect. Yes its verbose, and yes the compile/build/deploy cycle is cumbersome, but its strong type safety finds a heckuva lot of errors. When you’re in a team environment, thats a huge safety net. And, when you throw in frameworks like Spring, Hibernate and JUnit, I do still find myself very happy and productive. With their support, I can churn out a lot of functionality very fast in Java. But Java has its quirks, and to be honest, the strict typing thing ties your hands in a lot of ways.

What I was looking for was the next revolution. Something huge. Something that would drop my development time literally in half. I’m not kidding…something that would realistically reduce my coding/testing/rollout time 50% or more. Concretely.

So, I started searching for “OO-like” scripting languages to complement my Java knowledge. I came across Ruby (thanks to the hype surrounding Rails – which is very cool), Jython, Python, BeanShell, Groovy, JavaScript, and some others. Being a CS guy and actively involved in the open-source/cutting-edge world of software, I’m no stranger to all of these languages at some level. I put in probably a good week or so researching what would be best for me. I did want something that could leverage the massive amount of libraries available to Java too. Spring, Hibernate, etc, are so far ahead of the framework game, I don’t want to relinquish their power by leaving them behind.
Here’s what I’ve decided:

• I don’t really like Ruby all that much. The syntax is a little too cryptic which can introduce ugly code that’s hard to read (Python anyone?). But more so, its slow as hell. Rails is a great concept, but I’m not sure that Ruby is the best choice for such a framework. There is already a massive flame war about why Ruby is great or sucks, but I’m not going to get into that here. Suffice it to say its not right for me. It doesn’t leverage Java, so that means its out, even if its better than sliced bread.
• I don’t like Jython or Python – not ‘pure’ enough for me. Yes, they can adhere to the OO paradigm, but they allow a ton of functional programming. This makes code too sloppy for my taste. Jython is cool in that it can leverage Java, but it can’t win out due to the code readability thing.
• BeanShell is cool and is really just interpreted Java. But Java/BeanShell doesn’t do everything I want. I want closures!
• JavaScript – supports closures and is very powerful. I can’t remember where I found a benchmark test, but JavaScript on Rhino beat out all the other scripting languages that I mention here in speed. This accounts for a lot actually. However, I don’t really like programming in JavaScript. Its such a pain to debug, and consistent browser support doesn’t exist (thanks IE!). I actually find myself making JS code look more like Java to make it more readable. Again, I say Java is a little on the verbose side, but dang its easy to read. This is a huge thing for me. Code readability is ultra important, and thats why I abandon a lot of scripting languages (Jython and Python and Perl are so flexible, there are like 3 to 5 ways to do anything – very frustrating when trying to read code written by someone else.)
• Groovy supports everything I want. The syntax is very similar to Java, at least, similar enough to be able to learn the differences in a single day. It also supports everything in Java. That means I can leverage the amazing amount of functionality already written in Java (Spring, Hibernate, Ant, etc). Its not quite as fast as Rhino/JS, but it does have a decent support base over at CodeHaus. Then I found Grails.

I found Grails and it was like the heavens opening and angels singing “AAAAaaaaawh”. Its already based on Spring/Hibernate (my pairing of choice on almost all projects), and does exactly what I want.

You see, I think the OO world will return to behavior AND state in the same Class within 5 years, as OO intends. AOP makes this ability possible. Because of distributed systems and the complexities of state management, users of OO languages like Java/C++/C# etc. have split their programming paradigm. We usually write business logic in classes as functions and pass in an object POJO that contains state and nothing else. Why can’t they be the same?

Distributed systems threw a wrench into that concept. If I passed an object from one VM to another, I couldn’t guarantee that the object transferred would work correctly in VM1 as it would in VM2. Thats why folks created “state-only” objects, and let the behavior reside elsewhere in “Manager” or “Service” stateless components. I think AOP allows us to move back to what OO is meant to be – state and behavior together.

Grails helps move in that direction. Where I used to have a Book domain model object, and a BookManager service object which in turned used a BookDAO object to do persistence logic, I can have all 3 in one Class with grails:

When using Grails, you don’t even have to write that last findByTitle call in your Groovy class. Grails automatically interprets that method call as a hibernate call if it doesn’t exist in your class, and essentially creates and executes the implementation dynamically, during runtime on your behalf. Pretty sweet magic going on there.

(It still rubs me the wrong way a little propagating queries up to such a high level in the code – instead of using a DAO for example – but there is nothing that prevents me from using DAOs should I choose to do so, and that discussion is worth a new post entirely. Suffice it to say doing this gets you up and running _very_ fast, and you could always implement a DAO strategy very easily if time and costs allow).

Anyway, this is a huge step in the right direction – logic and state in the same entity. Brilliant! (mmm…Guinness)

So, I started thinking.

Groovy/Grails are doing things that have been around for years. Smalltalk has type-safety. It has interpreted support (highlight a chunk of code and click “doit!”, and it evaluates). It even has closures (called blocks). AND – here’s the kicker – it is truly pure OO – everything is an object. Numbers, booleans, even the compiler itself – are all represented as instances of a class. Even null is an object (called ‘nil’, it is the only instance of the UndefinedObject class).

So, this leaves me a little frustrated. I’ve come full circle from C to Java to all these new fangled scripting langauges, all the way back to Smalltalk. Its like we CS idiots just keep reinventing the wheel when Smalltalk has had all this stuff all along! I learned Smalltalk back in college at Georgia Tech, and I have to be honest, I didn’t like it that much. We used an open-source variant called Squeak, and it was slower than molasses, it had a poorly documented API, and the IDE sucked (it looks much better now, 5 years later).

But the language itself was awesome. It made sense to me as a fledgling CS student (Java did too, so I guess that doesn’t say much). But I’ve heard of stories of 8 year olds learning Squeak in a couple days (I think Disney did some learning research with it). It took CS students in a university an entire semester to really learn Java. It takes even longer to fully understand C and C++, because you have to know the intracacies of pointer and memory management.

So, again, I’m like “what the hell!?!?”. Squeak’s VM, compiler, and IDE are written in its own language. I’ve even heard of folks modifying live code in production without restarting anything. Are you kidding me? Thats just freaking amazing. Why the heck have we reinvented the wheel like 30 times?

Smalltalk was written in the late 1970′s by Xerox Parc. It had a VM back then. How revolutionary! When CS was just a fledgeling concept and departments were one or two rooms in a Mathematics school, they were already on to the concepts of virtual machines, garbage collection, OO abstraction, design by contract, etc, etc. Holy crap those guys were smart.

So, why isn’t everyone using Smalltalk today instead of Java or C#?

The answer is Smalltalk’s price in the early days. Unfortunately, IBM and other Smalltalk vendors charged an arm and a leg for a single developer license. I think the average around 1985 was about $3000 per developer. That was a lot of money back then, and is even too expensive for today’s market when the best IDE‘s are free or inexpensive. That, and open-source was not even close to being on the radar in the late 1970′s.

So, just as Smalltalk was starting to hit the mainstream among companies that could afford it, Sun Microsystems came in in 1995 and blew up the world with a FREE developer toolkit and with marketing techniques that piggybacked the hype of the newly popular internet. Smalltalk never had a chance. Hobbyists would never pay for something so expensive, so they adopted Java, and the rest was history.

Sucks for us. Don’t get me wrong, I absolutely love Java. But I think I could love Smalltalk even more given proper community support and adoption (and a good IDE – I would much rather have an Idea or Eclipse environment than what Squeak has, even with Squeak’s improvements).

Unfortunately, I’m not sure Smalltalk can recover. Java and .NET are the really only heavy hitters out there for enterprise development. Does Smalltalk/Squeak have an ORM tool as powerful and sophistacted as Hibernate? What about application frameworks like Spring, Tapestry, Struts, etc.? I would assume so since the language has been around a lot longer than Java, but I haven’t heard of them. I would love for an experienced Smalltalker to point them to me.

So I conclude discouraged and disheveled, because the coolest language out there, the one that has been around for 30 years, and has had ALL of the feature that the most modern languages are just now starting to support – not many of us use it. There is not enough industry adoption. There is not enough of a marketing machine out there. Even IBM, an early Smalltalk supporter (VisualAge Smalltalk), has ditched most of its offerings for Java.

I love Java. I really do. I just wish Smalltalk had a heavy hitter like Sun behind it. Until then, I look to Java, Groovy and Grails, which are much more likely to catch the eye of today’s developers. Too bad we’re just now able to do things that Smalltalk has been able to do for more than 20 years.

I end this post disgusted. I’m going to get a Guinness…

PETTY REQUEST: The update required considerably more effort than the original as it now accounts for all valid RFC [...]]]> UPDATE: This article 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!

In Object-Oriented design, I’m a firm believer in modeling things in they way they truly exist (in as much is possible given abstraction and time restrictions). So, whenver I design a system’s domain model, I create Classes that represent entities as they exist in real life. That being said, I’ve accrued a nice library of Classes that I reuse in a lot of projects.

For example, I don’t save or reference an email address as a String: strings as objects don’t tell me anything about the email address itself, like if its valid, if its bouncing, if it has been verified by the user with which it is associated, etc, etc. As such, I have created an EmailAddress class to represent this information. Doing this is a small example of the beauty of OO over functional programming.

Anyway, I was a little lax in the past in my validation logic. This time on my last project, I was determined to get things right once and for all.

I googled quite a while for the Right Way to validate an email address. In my opinion, there is only one Right Way – the RFC 2822 way. This is the standard after all.

I never came across anything I was happy with. All the responses seemed to be perl or php variant regular experessions or some horribly convoluted text string nearly impossible to decipher. I was disappointed to see so many interpretations of a standard. I mean, c’mon people, its written in pure black and white!!!

I guess the old addage “If you want something done right, you’ve got to do it yourself” resonated in my head this time. I actually took the time out to read the RFC (something I hadn’t done in a long while, probably since college).

After reading the RFC, I translated the grammar into usable, *readable* source code that now resides in my EmailAddress class, and I’ve included it below for the benefit of anyone that wishes to use it. It is written in Java, but the same code could be replicated in C# or PHP or whatever. Just keep it clean!

N.B: Look at the to the first two constants, ALLOW_DOMAIN_LITERALS and ALLOW_QUOTED_IDENTIFIERS – enable or disable them as you see fit for your application.

Anyway, the above java code allows you to do things like the following.

In the EmailAddress class, you can have a method:

Then you can write validation logic wherever you want (hopefully in a dedicated Validator ):

Better yet, if you want to see if any email address instance is valid, the EmailAddress class has the following method that you can use for ‘pure’ OO ‘messaging’ (i.e. a method invoked on an object is a ‘message’ from the calling object to the target object):

which enables you to do checks this way (this is ‘pure’ OO):

Happy validating!