Articles

Home

Getting Started With S2AP, Eclipse, and Maven

This guide walks through Eclipse setup for working with SpringSource Application Platform bundle projects. The easiest way to manage these projects is with Maven 2, and a plugin that integrates Maven project functionality into Eclipse.

At the end of this guide, you'll have a working Eclipse installation that can be used to create multiple OSGi bundle projects. You will be able to run unit tests inside or outside of the container, start up the S2AP server within Eclipse, and debug your bundle code while it runs in-container.

I do assume that you have a working knowledge of Eclipse. Maven experience is helpful but not required.

Revision History

May 30, 2008

First draft

May 31, 2008

Added Starting the Server and Running Unit Tests the First Time.

Eclipse Setup

Basic Installation

Download Eclipse 3.3.0, using the "Eclipse IDE for JavaEE Developers" configuration from the official download site. Unpack it somewhere useful. If you've already got Eclipse installed, you can use your existing installation, but you might need to add some features from the Web Tools Project.

Using the Eclipse update manager, add the following remote update sites:

  1. Maven for Eclipse: http://q4e.googlecode.com/svn/trunk/updatesite/
  2. Subclipse 1.2: http://subclipse.tigris.org/update_1.2.x
  3. SpringSource Application Platform Tools: http://static.springsource.com/projects/sts-ap/update/

Select all features from these update sites.

Project Definition

Creating a bundle project

I've found it helpful to create a new workspace, separate from my existing ones. I mainly did this because OSGi projects will create a lot of top-level entries in the workspace, so it felt too cluttered to have all of them in my default workspace.

  1. Make sure you're in either the Java perspective or the JavaEE perspective.
  2. In an Explorer or Package Explorer view, right-click and select New | Project...
  3. Select "Maven 2 Project Creation Wizard"
  4. Use a project name like "com.example.feature.tier", where feature describes the service and tier describes this bundle's purpose: domain, persist, web, webservice, etc.
  5. Leave "Create new project in workspace" selected.
  6. Click "Next"
  7. Be sure that "Select a maven archetype to use" is selected.
  8. Select the archetype "spring-osgi-bundle-archetype [1.0.2]"
  9. Click "Finish"

The new bundle will be created as a top-level project. You should check it in to Subversion before you do anything else. Select "Team | Share Project...". Go through the wizard, using the SVN repository and the correct URL.

The project model was created with a bunch of default repositories enabled. We need to swap some of these out for the SpringSource Bundle Repository. Open pom.xml and locate the start of the "repositories" section. Add the following lines, right under the open tag:

<repository>
	<id>com.springsource.repository.bundles.release</id>
	<name>SpringSource Enterprise Bundle Repository - SpringSource Bundle Releases</name>
	<url>http://repository.springsource.com/maven/bundles/release</url>
</repository>
	
<repository>
	<id>com.springsource.repository.bundles.external</id>
	<name>SpringSource Enterprise Bundle Repository - External Bundle Releases</name>
	<url>http://repository.springsource.com/maven/bundles/external</url>
</repository>

<repository>
	<id>com.springsource.repository.libraries.release</id>
	<name>SpringSource Enterprise Bundle Repository - SpringSource Library Releases</name>
	<url>http://repository.springsource.com/maven/libraries/release</url>
</repository>
	
<repository>
	<id>com.springsource.repository.libraries.external</id>
	<name>SpringSource Enterprise Bundle Repository - External Library Releases</name>
	<url>http://repository.springsource.com/maven/libraries/external</url>
</repository>

I got the definition for these repository entries came from the SpringSource Enterprise Bundle Repository FAQ.

Running Unit Tests the First Time

Whenever I see a bunch of generated files and code, I want to make sure they work before I do anything with them. In this case, you'll have some generated unit tests.

To run these tests for the first time, right-click the project and select "Run As | JUnit Test". The unit tests run very quickly, about one second for me.

There are three unit tests created by the Maven project archetype:

  1. BeanImplTest: Instantiates one object and calls a method on it.
  2. BeanIntegrationTest: Loads a Spring configuration, gets a bean from it (the same class as BeanImplTest uses) and calls a method on it.
  3. BeanOsgiIntegrationTest: Loads a Spring configuration, using OSGi bundles. Asserts that the bundle configuration was loaded correctly.

This last unit test leaves a mess behind. It creates a directory called eclipse_config, with a bunch of bundle zip files in it. (I think it's a local copy of the bundle repository, or at least enough of the bundle repository to resolve all dependencies in loading the bundle being tested.) This directory and its children will cause spurious checkin events and make it look like your working copy is out of sync with version control. (The first time you run unit tests, you will probably have to refresh your explorer view in order to see the new directory.)

To avoid version control noise, you can tell Subversion to ignore the eclipse_config directory. Right-click eclipse_config and select "Team | Add to svn:ignore...". Leave "Resource(s) by name" selected and click OK.

Adding JUnit

You'll probably want JUnit available for testing in each bundle project. Open up pom.xml and all the following, right under the comment that says "test scoped dependencies":

    <dependency>
    	<groupId>org.junit</groupId>
    	<artifactId>com.springsource.org.junit</artifactId>
    	<version>4.4.0</version>
    	<scope>test</scope>
    </dependency>

As soon as you save pom.xml, Eclipse will download the new dependencies and update the bundle project's classpath.

Adding Dependencies

Instead of adding JAR files directly into your bundle project, it's better to add dependency declarations to your pom.xml file. To find out the right form for the dependency, you can go to the SpringSource Enterprise Bundle Repository and search for the bundle or library you need.

For example, suppose I need to use the Servlet API. Instead of downloading somebody's implementation of servlet-api.jar, I go to the repository and search for "javax.servlet" I get these results:

Bundles that contain the search text in their name

I really want to see which bundles have that package, so I click "bundles" and see:

Bundles that export a package containing the search test

That shows me which bundles export the package javax.servlet. Any of these will probably suffice, but I'm going to be safe and use the Java Servlet API, version 2.5.0. Clicking that link shows me details about the bundle, including the correct Maven dependency snippet.

<dependency>
	<groupId>javax.servlet</groupId>
	<artifactId>com.springsource.javax.servlet</artifactId>
	<version>2.5.0</version>
</dependency>

Copy that from the web page and paste it into pom.xml, in the dependencies section. Once again, Eclipse will immediately download the bundle files when you save the POM.

Fetching Sources

The Maven extension also has a nice workaround for a deficiency in Eclipse: downloading source JARs and linking them to the classpath entries. Right-click on the bundle project and select Maven 2 | Fetch Source JARs. Maven will download the sources and connect them so you can browse directly from your calling code into the definition.

You will need to do this every time you add a new dependency in pom.xml.

Starting the Server

Switch over to the "Java EE" perspective. One of the views in the bottom of the window will be "Servers". This is where you can tell Eclipse how to start S2AP for remote debugging. S2AP will run as a separate process, but with automatic redeployment of code and debugging directly within Eclipse. (Not just debugging, either. The Eclipse profiling tools work this way, too.)

The first step is to define a server configuration to Eclipse. In the "Servers" view, right-click and select "New | Server" This server will be local, so leave "localhost" as the server's host name. Expand SpringSource and select "SpringSource AP v1.0 Server". Click finish.

The new server dialog

The server view now shows your new server configuration. From here, you can start the server up, either with the view's toolbar buttons, or by right-clicking the server definition itself. Start it up now.

The servers view now shows the new local server

The console view shows the server's short and sweet startup sequence. At this point, you've got the SpringSource Application Platform running from Eclipse, but it's just sitting there with nothing to do. Still, even though you haven't deployed any code, there are a couple of interesting things you can do.

First things first, pull up http://localhost:8080/ to view the splash page. This is a war file application that comes with Spring. The last line in the console log tells you that S2AP is deploying platform.admin.splash-1.0.0.beta5.war (or whichever version you're running.) Follow the "Admin Console" link in the upper left to get a look at the deployed applications.

By the way, the default admin account is "admin", with password "springsource". Please don't go into production without changing this!

In addition to the web interface, the Equinox server underneath S2AP also has a remote console interface listening on port 2401. Try telnetting to it.

The console interface, with help contents displayed

I'm not sure what to do with all that stuff yet, but it looks pretty cool. As an example, Dave Syer has a blog post where he uses the admin console to kick off batch jobs.

One warning about the console: if you type "exit", thinking you're disconnecting from the console... well, you aren't. Exit tells the server to shut down. I'm sure this will make for more than one "ohnosecond" with production application administrators.

Credits

I cobbled most of this together from various blog entries and some judicious experimentation. Many thanks to Dave Syer and Adrian Colyer, in particular.

To Do

As I cross more bridges, I'll fill in more material here. Off the top of my head, I can think of several areas that need more detail:

  • Initial Subversion checkin
  • Manifest editing
  • Handling inter-project dependencies
  • Scripted builds (i.e., in a CI server)
  • Parent projects and Eclipse interactions