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!

“Free as in beer” is meant to signify a gratis, or no-cost (no money) distribution (but it is not necessarily free to do with [...]]]> I never understood this line when discussing Open-Source Software. Richard Stallman attempted to clarify the differences in Open-Source distribution models by saying “Free as in speach, not free as in beer”.

“Free as in beer” is meant to signify a gratis, or no-cost (no money) distribution (but it is not necessarily free to do with as you please), while “Free as in speach” is meant to represent freedom of use – with little or no restrictions.

When was the last time you received free beer?

And if you did receive a free beer, couldn’t you do with it as you pleased? Like drink it or maybe even give it to another friend because you know if you drink more, you’ll have no cognitive functions left to try and understand what the stupid phrase “Free as in speach, but not free as in beer” means?

I think we shud shtop wif fis analogie. It surtanly onli cnfsed me mur. Hiccup.

Wikipedia explains it well enough by saying Gratis vs Libre

See? Latin is still useful!

Hiccup.

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:

Anway, here’s what I [...]]]> Ok, I had a hell of a time trying to get this figured out. It seems like my Ingres 2006 install environment did not match the documentation on the ingres website, which looks to be docos for the older r3 product. This seriously sucked. C’mon guys – get the docos right.

Anway, here’s what I had to do.

I didn’t install this ingres instance, but I did realize that a process named ‘iijdbc’ was running. Apparently this is what allows jdbc to connect to an Ingres 2006 installation. We do not have Data Access Server running (iigdc).

When doing a process listing, this is what I get:

And here is the corresponding output from the ‘ingstatus’ command (corroborates the above, just less verbose):

So, given this starting point, here’s what I had to do:

As the ingres user, we had created a ‘cls’ database via the createdb command. Then we used accessdb to create the ‘cls’ user account inside ingres. Then we loaded the sql schema via accessdb.

So now, I had a cls user account and a schema with tables, but I couldn’t connect for the life of me over JDBC using Ingres 2006′s provided jdbc driver (found at $II_SYSTEM/ingres/lib/edbc.jar).

It turns out this is because Ingres uses Operating System user accounts for logging in over tcp. So, this meant I had to create a cls user as root:

and gave it a suitable password:

(this OS level password is then used for the JDBC connection later on).

Now that there is an OS user called ‘cls’ – exactly the same as my previously created Ingres database – I then had to let ingres know about this os user account and password:

(as root):

This command compiles and installs a program called ‘ingvalidpw’ that is not is not included in the standard Ingres2006 installation. This allows you to validate if a password is valid against an operating system user account known to Ingres.

Once that’s done, you’ll have to restart Ingres (as root):

To validate that Ingres password checking works, you should see that the Ingres env var II_SHADOW_PWD is set to the location of that compiled ingvalidpw executable:

In the list that is generated, you should see the II_SHADOW_PWD var set.

Now, you can verify that the username and password you would use for JDBC for your user will work:

If you see any value other than 0 returned, then the username/password entered doesn’t match the OS username/password. If you do see non-zero, then you can look in the $II_SYSTEM/ingres/files/iipwd/ingvalidpw.c file and see what the integer corresponds to find out what went wrong.

I then fired up DB Visualizer, pointed it to the edbc.jar file I specified earlier, and then used this url:

So, in my case it looked like this:

I clicked ‘test connection’ in DbVisualizer, and lo and behold! I was able to access all my tables!

I hope this is of use for someone – it took me close to 3 or 4 hours to get this working.

Here is the original Ingres forums thread that led me to my posting (you may need an Ingres account to access it, but its free):

http://opensource.ingres.com/projects/ingres/forum/30/121418044682?b_start:int=0#235464875124