How to create a Spring-DM bundle project using Maven (and Eclipse...)

This quick guide will demonstrate how to set up Spring-DM project using Spring-DM Maven Archetype and configure it for Eclipse development.

The Spring-OSGi project supplies a maven archetype that will create a Spring bundle project for you all set up and ready to go.

mvn archetype:create   -DarchetypeGroupId=org.springframework.osgi   
-DarchetypeArtifactId=spring-osgi-bundle-archetype  
-DarchetypeVersion=<spring-dm version>   
-DgroupId=<your-project-groupId>  
-DartifactId=<your-project-artifactId> 
-Dversion=<your-project-version>

Example:

To create a new project open a console and navigate to the directory where you want to create project and simply type the following:

mvn archetype:create   -DarchetypeGroupId=org.springframework.osgi   
-DarchetypeArtifactId=spring-osgi-bundle-archetype  
-DarchetypeVersion=1.1.0   
-DgroupId=org.foo  
-DartifactId=org.foo.my-springdm-bundle 
-Dversion=0.1

Note: Make sure it is all typed as a single line. It's been formated here for readability.

The result of this is a directory org.foo.my-springdm-bundle which is a maven project that defines a public package org.foo, a private one org.foo.internal and two Spring configurations under src/main/resources/META-INF/spring/bundle-context.xml and src/main/resources/META-INF/spring/bundle-context-osgi.xml. The project is packaged as an OSGi bundle. The general rule: you define your interfaces in public package and implementations in private.

This project does not contain MANIFEST.MF file in META-INF directory - to generate one, navigate into the project's root directory and invoke the following commands:

mvn package

Now we'll use maven-bundle-plugin provided by Apache Felix (see more info here) which will generate MANIFEST.MF file inside of META-INF directory

mvn org.apache.felix:maven-bundle-plugin:manifest

You should now see the MANIFEST under META-INF folder.

Note: if you haven't already downloaded and installed the spring-osgi artifacts (by running 'mvn install' on the spring-osgi tree) you'll need to add an additional parameter to the above command: -DremoteRepositories=http://s3.amazonaws.com/maven.springframework.org/milestone. If this parameter does not work for you first time, see the additional instructions here.

Second Note: Snapshots version are available from: -DremoteRepositories=http://s3.amazonaws.com/maven.springframework.org/snapshot

Simply 'cd' into your newly created project directory and type 'mvn install' and you are good to go!

Generated Project features at-a-glance:

• Packaged as an OSGi bundle
• META-INF/MANIFEST.MF automatically generated
• src/main/java/<package> public package automatically exported
• src/main/java/<package>/internal private package
• src/main/resources/META-INF/spring/bundle-context.xml is a spring configuration file that defines the simple bean.
• src/main/resources/META-INF/spring/bundle-context-osgi.xml is a spring configuration file ready for you to add bean definitions from the osgi namespace (services, references etc.).
• .project, .classpath, and build.properties files created to enable use of this project directly inside eclipse as a PDE plugin project

To see the latest instructions, please read this section of the reference documentation.

Using the project inside of Eclipse

In order to use the project wihin inside of Eclipse IDE we need to perform two stepps:

1. Configure Workspace Build Path
2. Configure Eclipse artifacts (.project file etc.) so the project could be imported into the Workspace

Our generated bundle project contains .classpath file which points to varios JARs relative to M2_REPO variable. This variable should point to the root of your Maven repository - .m2/repository.

So, we need to configure Eclipse's Build Path to recognize M2_REPO variable. We can do it manually of course, but eclipse-maven-plugin has a nifty command that will do it for use.

mvn eclipse:configure-workspace -Declipse.workspace=<path to the workspace> 

Example:

mvn eclipse:configure-workspace -Declipse.workspace=/Users/kermit/eclipse/workspaces/myspringdm_workspace 

Now we are ready to configure our newly created project as Eclipse project. We are going to be using the same maven-eclipse-plugin.
Navigate to the project's root directory and execute the following command:

mvn eclipse:eclipse

This will generate required Eclipse artifacts (i.e., .project etc.) inside of your project structure.

Open up Eclipse and use "Import Existing project into the workspace" feature to import newly created Spring-DM project into the workspace.
That is all.

 

Using the archetype from within Eclipse

You can make it really easy to create a new Spring-OSGi bundle project from within eclipse by defining a new "External Tools" launch configuration. Open the "External Tools" configuration dialog, select the "Program" category and click "new". Refer to Eclipse documentation for more info on How to configure external tools

The "${string_prompt}" entries cause Eclipse to pop up a dialog asking you for a value when you run tool. You can also change the working directory to be something other than the workspace location (or even a ${folder_prompt} prompt if you like). This is the directory in which your new project will be created.

Now the creation of a new Spring-OSGi bundle project is as easy as click of a button

Note: the generated eclipse project depends on a number of the spring-osgi bundle projects that it expects to find installed in your workspace. See the instructions here for setting these additional projects up (one-time task).