typed by Hans

This article describes the directory structure and command shell environment configuration I use on my development machine to help manage tools, source code and dependent libraries.

Directory Layout

On Windows I keep all my development tools and source code under c:\dev.  On Linux I use the same layout under $HOME/dev/

Inside the “dev” folder I have the following sub-directories:

…/dev

/tools - contains executable application, tools and utilities, like Eclipse, DbVisualizer, Tomcat, Maven, HSQLDB, etc.  I only place tools here that you can install manually simply by unzipping them (for example, Ecipse, Maven, Tomcat).  For the tools or applications don’t ship in a zip file but only come with installers (for example, Java, Oracle, TortoiseSVN) - I let these tools install to their default locations (for example, under “C:\Program Files” or  “/usr/local/”).

/lib - contains binary distributions of 3rd-party libraries and documentation, like GWT, JUnit, SpringFramework, Hibernate, etc.  These days this directory is actually pretty empty - since I now mostly rely on the Maven to download 3rd party libraries and store it in the local Maven repository.  However, it is still sometimes useful or necessary to have the documentation and examples handy.

/os - contains source code for 3rd-party Open Source libraries and tools.  I also use it as a sandbox for unpacking and executing 3rd party sample code.  The entries here are usually transient.

For example, on Windows I have:

    c:\dev\
            tools\
                    \apache-maven-2.0.9
                    \apache-tomcat-6.0.14
                    \eclipse-jee-ganymede-win32
                    …etc…
           lib\
                    \gwt-windows-1.4.62
                    \htmlunit-1.14
                    \spring-osgi-1.0.2
                    …etc…
           os\
                    \eclipse-equinox-SDK-3.3.2
                    \pax-samples
                    \servletbridge
                    …etc…

I also place my own source code projects directly under “dev”, for example:

    c:\dev\
            apps\
            spikes\
            voluble\
            …etc…

BTW, “spikes” is a nice “catch all” place for trying new things out before moving them into “real” projects. Even though “spikes” only contains throwaway or proof-of-concept code, I tend to commit the contents to a SVN repository. Some people use the term “sandbox” instead of “spikes”.

Shell Environment Configuration

To set up my environment variables I create a command file in the “dev” folder - usually called “setenv.cmd” on Winows and “setenv.sh” on Linux.  The file sets up the path, environment variables, and on Linux it also sets up aliases.

On Windows I find it far more convenient to manage the environment settings through a command file rather than going through the Control Panel (System > Advanced > User Profiles > Environment Variables) dialog.  It’s also very useful if to set your environment through batch files if you sometimes need to run a different versions of a tool (for example, if you use Java 6 for new projects but sometimes have to run Java 1.4 for legacy projects).

This is an example Windows setenv.cmd file:

SET JAVA_HOME=c:\Progra~1\Java\jdk1.5.0_14
SET ANT_HOME=C:\dev\tools\apache-ant-1.9.0
SET CATALINA_HOME=C:\dev\tools\apache-tomcat-6.0.14
SET MAVEN_OPTS=-Xmx512m
SET DERBY_HOME=C:\dev\tools\db-derby-10.3.2.1-bin
SET SPRING_OSGI_LIB=C:\dev\os\spring-osgi-1.0-rc2\lib

@echo off

SET PATH=%JAVA_HOME%\bin
SET PATH=%PATH%;C:\WINDOWS
SET PATH=%PATH%;C:\dev\tools\apache-maven-2.0.9\bin
SET PATH=%PATH%;C:\dev\tools\putty
SET PATH=%PATH%;C:\dev\tools\apache-ant-1.7.0\bin
SET PATH=%PATH%;C:\WINDOWS\system32
SET PATH=%PATH%;C:\dev\tools\bnd-0.0.238
SET PATH=%PATH%;C:\dev\tools\db-derby-10.3.2.1-bin\bin
SET PATH=%PATH%;C:\progra~1\Subversion\bin

echo on
echo PATH=%PATH%

Introduction

I have developed a small sample to demonstrate how to use Hibernate in OSGi with Spring Framework and Spring-DM.  The sample works in either Felix or Equinox. It builds with Maven 2 - the build process automatically downloads the Felix and Equinox jars so there is no need to install either framework separately.

Starting Hibernate in OSGi with the normal Hibernate SessionFactory would allow you to use Hibernate in OSGi - but that would not address the dynamic behavior that an OSGi system is capable of. This sample demonstrates how a Hibernate SessionFactory can be updated dynamically in an OSGi environment. You can dynamically add and remove entity classes to the Hibernate configuration by stopping and starting bundles that contribute clasess to the Hibernate configuration.

This implementation contains a small Swing UI which allows you to see which entity classes are present in the Hibernate configuration. The Swing UI also allows you to issue rudimentary SQL and HQL queries.

The solution is based on this OSGi and Hibernate blog entry by Peter Kriens. The design uses an entry in the manifest file to declaratively add classes to a Hibernate session using an extender model.

Get the code

To get the source code for the hibernate sample, use SVN:

svn checkout http://voluble.googlecode.com/svn/trunk/osgi-samples/hibernate/ osgi-hibernate-sample

Run the code

Run “mvn install” in the new osgi-hibernate-sample folder and see all projects build successfully.

The 2nd last project that builds is “integration-tests”, which uses Spring DM to run an integration test suite in an OSGi container. The integration tests are run against an in-process HSQLDB server.

Continue Reading »

This is a quick and practical task-based introduction to OSGi. We avoid any in depth discussion about the purpose or benefits of OSGi or even the tools referenced in this article. Many high level introductions on the technology are available; for examples, please see the webcasts at Eclipse. There’s also a good webcast on the OSGi efforts at Weblogic.

With OSGi it’s possible to run multiple versions of the same classes in the same container. We’ll start from scratch and build services that demonstrate this ability.

I used Apache Felix as an OSGi container. The other two well known open source OSGi container implementations are Equinox and Knopflerfish. Apache Felix actually seems to be the least popular of the three - I wanted to get some experience using the underdog!

Our immediate focus is to create and deploy applications in an OSGi server. We’ll do the following:

• First we’ll set up a simple OSGi deployment environment.
• We’ll create a simple OSGi bundle that will export classes and a service, making it available to other bundles. We’ll call this Bundle A, version 1. We’ll install and start the bundle in an OSGi container.
• To demonstrate the power of OSGi, we’ll create a second version of the same bundle and install it alongside the first version. We’ll call this Bundle A, version 2. This will demonstrate OSGi technology’s ability to seamlessly manage multiple versions of the same classes at the same time, even though the class and package names of both versions will be identical.
• We’ll create another set of bundles which will import and use the classes and service exported by the first set of bundles. We’ll call them Bundle B, versions 1 and 2. Bundle A, versions 1 and 2 will export services which will be imported by Bundle B versions 1 and 2 respectively. This will demonstrate OSGi technology’s ability to dynamically manage modularized applications.

We will use Spring Dynamic Modules for OSGi(tm) 1.0 (with dependencies), Apache Felix 1.0.3, Apache Felix Maven Bundle Plugin 1.2.0, Apache Maven 2.0.8 and Java 1.5.14. Please refer to the individual project websites for more information and background on these projects. We are avoiding discussion of these tools as we are only focusing on accomplishing the tasks outlined above.

I used Windows XP to create this tutorial. When writing the development and deployment steps it seems much easier and less error prone to reference full path names, rather than relative names. For example, I prefer referencing c:\dev\tools\felix-1.0.3, rather than “your Felix home directory”. You will notice I use the following directory structure for my development environment.

   c:\dev\
                  lib\   (Libraries)
                              \spring-framework-2.5.1
                              \spring-osgi-1.0
                              …etc…
                  tools\   (Executable tools)
                              \felix-1.0.3
                              \maven-2.0.7
                              …etc…

You can change the steps in the tutorial to match your environment, or copy the environment I lay out here. If you use a different layout, simply substitute path references to match your environment. For example, substitute “c:\dev\tools\felix-1.0.3” with whatever you chose for “your Felix home directory”.

To start out I’ll detail where to get the components to build the OSGi deployment environment. I will then use a command file, “setenv.cmd”, to configure my environment variables and system path when operating from a Windows command prompt. I’ll provide a sample “setenv.cmd” file.
Continue Reading »