A blog about Java, Eclipse, OSGi

Google+ Followers

Translate

Oct 31, 2012

This rather long post analyses four solutions to the problem of using data sources,
and more in general JNDI in Virgo, the 4th being the one I recommend
and decided to use, which consists in leveraging Tomcat's built-in JNDI provider in Eclipse Virgo Server for Apache Tomcat.

If you are not interested in the reasons why I
dropped the first three, jump directly to the fourth.

Even if the post is mostly focused on JDBC data sources, once Tomcat JNDI provider is exposed to the application it can be used for any type of resource, not only data sources.

Most of the credits for this solution go to my colleague Stefano Malimpensa.

1. JDBC data sources in OSGi

The most correct approach to obtain a JDBC data source in a pure OSGi enterprise application consists in using the OSGi JDBC Service (see the official OSGi JDBC specification). In Virgo, that means using Gemini DBAccess.

However, in my humble opinion Gemini DBAccess is not an optimal solution for a number of reasons:

Gemini DBAccess is currently available
only for Derby, and to use a different database you need to write your own implementation. Not a big issue but some extra effort anyway.

When using DBAccess with Gemini JPA you need configure
connection parameters in each bundle's persistence.xml. I find this inconvenient because it is necessary to repackage the bundles every time the
connection parameters change, and due to the modular nature of OSGi one complex application may include several bundles with persistence units.

If DBAccess is used without GeminiJPA, DBAccess will
provide only a data source factory, and it will be the responsibility of your code to
instantiate and configure the data source (e.g. pass in user name, password etc). In such case you would need to support a
configuration file to let system administrators easily change
connnection parameters, which is again extra effort.

DBAccess requires the
OSGi registry, which means it would not work with legacy code or third
party libraries written for J2EE.

As the name implies, Gemini DBAccess is tailored to data base
resources. If you want a single, unified approach for looking up any type
of resource, then it's not a good fit for you.

2. Full JNDI in OSGi

There is no configuration console, nor a configuration file: the only way you can bind resources in the JNDI namespace is programmatically. This implies a lot of boring initialisation code, and you probably need to support a
configuration file to let system administrators easily change configuration parameters, which is again extra effort.

Gemini Naming requires the
OSGi registry, which means it would not work with legacy code or third
party libraries written for J2EE.

3. Local JNDI declared inside a Web App

Virgo supports JNDI lookups for data sources inside a Web App. To achieve this you have to:

Include in the Web application the JDBC driver(s) and the pool implementation (e.g. Apache DBCP or Tomcat JDBC) as jars in your WEB-INF/lib folder

Configure web.xml to list the usual JNDI resource-refs

Include a Tomcat context.xml file in the Web App and configure it as explained here and here

The above will work for JDBC data sources but has the following draw backs:

You must include the JDBC driver and pool in every Web App of yours. This means that each Web App will have its own pool, even if they connect to the same database, and that you must repackage the WAR if you need to update the JDBC driver

JNDI lookup will work only in a thread originated by a HTTP request. This means that application bundles that are not WARs will not be able to obtain the data source via a JNDI lookup, unless their code is executed by a thread started by the Web container. In fact, the JNDI lookup will fail from threads created by Equinox: this is for example the case of code that observes OSGi framework lifecycle events (BundleListener) and need access the database when a bundle is installed or uninstalled.

In my case the main show stopper to this solution is the thread issue described above, because my application must access the database (and therefore the data source) from threads that are not always started by the Web container. If you are interested in the historical roots of this apparently strange limitation, I recommend reading this post by Neil Bartlett.

Please note that this solution will make the global JNDI namespace available, disabling the Web App java:comp/env context. In order words, you cannot use the java:comp/env prefix in your JNDI lookups. This should be an acceptable limitation, given that the java:comp/env prefix in any case would work only within a Web App and not from a plain OSGi bundle.

In order to use the Tomcat JNDI registry for data sources in Virgo the following mandatory steps are required:

Create a bundle fragment for Catalina to extend Virgo's Tomcat with connection pooling support. The Virgo distribution contains in fact a stripped down version of Tomcat that removes the libraries required for JDBC pooling. Luckily enough, you can create a fragment to contribute the libraries back to Catalina. You just need to make sure that your fragments are placed in the bundle repository folder, not in pickup.

Create a bundle fragment for Catalina to make the required JDBC driver(s) available to the server and the application

All the above fragments are a convenient method for extending Tomcat/Catalina to use third party libraries whose Java packages were not originally imported by the Virgo bundles. For further details refer to this post by Glyn Normington, the project lead of Virgo. If you are working with Virgo his personal blog is a must read!

1. The pool bundle fragment

Here is a sample for Apache DBCP. The MANIFEST.MF below is added to the DBCP JAR, that's why there is no Bundle-Classpath.
Mind the fragment host header.

The first, GlobalJNDILifecycleListener, is a GlobalResourcesLifecycleListener subclass that downcasts the server instance to get the global JNDI context and that registers in the JVM NamingManager a custom InitialContextFactoryBuilder which wraps the JNDI context obtained from Tomcat.

Other options are of course possible, including doing everything in the custom implementation of InitialContextFactoryBuilder without subclassing the listener, but whatever approach you adopt, it is important to make sure that the invocation to NamingManager.setInitialContextFactoryBuilder occurs only once in the life of a Virgo server instance, because the method will fail and raise a runtime exception if it is called more than once.