Chapter 1. Prepare Eclipse/Spring-DM Environment


In this section we will create, configure and test Eclipse based Spring-DM Target Platform. First it is worth to mention that Spring-DM Target Platform comes with the distribution of Sring-IDE and Appendix C of Spring-DM Reference Manual provides details on how to configure Spring-DM Target Platform within the Eclipse PDE using Spring-IDE.

 

[Important]IMPORTANT
Please read FAQ distributed with Spring-DM distribution especially section 1.18 which talks about "strange" errors you might see when working with Eclipse and how to fix them.



Spring Source Tool Suite (STS) also comes with pre-configured Spring-DM Target Platform as well as set of Eclipse based Task Focused tutorials on how to configure and develop basic Spring-DM projects.

However, one of the goals of this tutorial is to showcase one of the main concepts behind OSGi™ where every platform could be customized and modified rather easily to fit whatever needs you might have, where the concept of being locked into configuration provided by the vendor is obsolete. In the course of this tutorial we are going to develop several applications. One of them is Spring MVC based application which requires our target Platform to be web-capable which means it requires bundles responsible for such functionality (e.g., Tomcat, Servlet API etc.) to be installed in the Target Platform, which is exactly what we are going to do in this section and that is why the knowlege of how to configure your own custom OSGi™ target platform is extremely important. It will also help use to prepare ourselves for future tasks, related to customization of our OSGi™ environment, as we might need to deal with upgrades and changes.

SpringSource OSGi™ repository already contains OSGi-fied bundles that could be used to customize your OSGi™ environment and it’s only growing. Knowing how to do it (bring new bundles into your OSGi™ Target Platform) is paramount.

The following steps would need to be performed to configure our Spring-DM target Platform and prepare our environment for development tasks.

  • Create Project Structure to host Target Platform
  • Define and execute Spring-DM Maven Configuration
  • Test target Platform
  • Define User Library (Class Path)

1.1. Prerequisite

In order to complete this tutorial make sure the following is installed and available:

Also, make sure your computer is connected to the internet (for Maven dependencies)

1.2. Create Project Structure to host Target Platform

In this section we will create and configure an empty project to be the host of our target platform. Doing it this way is convenient because we’ll be able to access our Target platform right from our workspace.

On the menu Click on: File -> New -> Project

New project wizard will open up

Select General -> Project and name it Spring-DM-Target-Platform


Next, Create new Folder in this project and call it target. When done you should have the following structure.

Now we need to configure our newly created target directory to be the root for our Target Platform

On the Eclipse menu bar click on: Window -> Preferences

Expend Plug-in Development -> Target Platform

In the Location field (at the top of the window), enter or browse to the absolute location of the target directory we’ve created earlier

Click on: Reload

You should see that our target platform is empty and it should be, since we don’t have a single bundle in it.

Click OK.

Now all we need to do is to install bundles which will define our target platform. We can obviously download and install these bundles manually (a very tedious process), so to make this process simpler and more consistent we’ll use Maven to do it for us. Copy the Maven pom.xml file to the root of your project. This file is located in SpringDM-Target-Platform directory of samples distribution

You should see the following structure:


[Important]IMPORTANT
Please pay attention to the comment provided in pom.xml file which asks you to modify the directory structure where you want the downloaded files to be copied (see below). It should point to the absolute path of your target directory you created earlier.


====================================================================================
<!-- IMPORTANT: Please modifty to fit your directory structure -->
<taget-platform.root>
C:\oleg\eclipse\workspace\Spring-DM-Target-Platform\target
</taget-platform.root>
. . . . . . . . . .
====================================================================================

You are ready for the next step.

1.3. Configure Maven using Eclipse External Tools

In this section we are going to configure Maven to assist us with creation of our custom web-enabled Spring-DM Target Platform. What this mean is that we are going to use Maven to download all required bundles and install them in the target directory which is already defined as the root for our target platform. Besides regular Spring-DM bundles we are going to download and install OSAGi-fied version of Tomcat and it's dependencies.

There are few Maven Eclipse plug-ins available which you can use at your will, however in order to keep this tutorial as much independent from any particular IDE as we can (even though it is based on Eclipse), we are not going to use any of the Maven Eclipse plug-ins. Instead we will use External Tools Configuration feature provided by Eclipse to simply point to your Maven installation (as if it was any other batch program). This way if someone prefers to execute Maven commands from the command shell, such switch would not be difficult to make.

Click on: External Tools (down arrow)-> Open External Tools

External Tools window will open up.

Right click on the Program -> New

Manage Configurations window will open up

Enter the following in the corresponding fields:

Name:Create-SpringDM-Target-Platform

Location: Browse to the location of your Maven installation and point to mvn.bat (or it's equivalent on Linux/MAC based platforms) file

Working Directory: Browse Workspace and point to the root of our Spring-M-Target-Platform project

Arguments:package

Click: Apply -> Run

This will run Maven configuration which will download and copy all the bundles into our target directory. Time for this step depends on how much bundles and their dependencies you have in your local Maven repository.

Once completed you should see successful Maven build:

====================================================================================
. . . . . . . . . .
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
. . . . . . . . . .
====================================================================================

Right click on the target directory and select Refresh

You should see all the bundles there:

On the Eclipse menu bar select: Window -> Preferences

Expend: Plug-in Development -> Target Platform (as we did few steps before) and click on Reload.

You should see that or target platform was populated with downloaded bundles.

Click OK

You are ready for the next step

1.4. Test Spring-DM target Platform

In this section we’ll create Launch Configuration for our newly created Target Platform and test it by starting it.

Click on: Run-Dialog (down arrow)-> Open Run Dialog

New Launch configuration window will open up

 

Right click on OSGi Framework -> New and enter Spring-DM-TP in the Name field:

 

 

Make sure Target Platform is selected 

 

Now we have to make sure that our Web Extender bundle starts  after our Tomcat and other related bundles. We need this because Web Extender depends on some of the packages exported by those bundles and we want to make sure they are available when it starts. 

To do that we'll adjust the Start Level of the web extender bundle. Default Start Level is 4 (as you can see from the screen shot below), which means we'll have to make our web extender bundle's start level 5.

Select org.springframework.bundle.osgi.web.extender and increase the start level to 5 (see below)



The last thing we want to do is set osgi.clean System property to true. Eclipse Equinox OSGi platform does state caching between the runs which is not a good thing during the active development. Setting this property to true which will allow our Target Platform to start clean every time.

 

Clik on Arguments tab and add this argument to the VM Arguments -Dosgi.clean=true



Click: Apply (to save configuration for future use) -> Run

 

You should see the following output in your console:

====================================================================================
osgi>log4j:WARN No appenders could be found for logger 
		(org.springframework.osgi.web.tomcat.internal.Activator).
log4j:WARN Please initialize the log4j system properly.
====================================================================================

Your Target Platform platform started successfully. (We’ll fix the Log4J warning message later)

Type ss (short status) in the console and you should see that all bundles (except for org.springframework.bundle.osgi.test) are in the ACTIVE state.

====================================================================================
osgi>log4j:WARN No appenders could be found for logger 
 (org.springframework.osgi.web.tomcat.internal.Activator).
log4j:WARN Please initialize the log4j system properly.
ss

Framework is launched.

id State Bundle
0 ACTIVE system.bundle_3.2.2.R32x_v20070118
1 ACTIVE org.springframework.bundle.spring.context.support_2.5.5
2 ACTIVE com.springsource.junit_3.8.2
3 ACTIVE jcl104.over.slf4j_1.4.3
4 ACTIVE org.springframework.osgi.jasper.osgi_5.5.23.SNAPSHOT
5 ACTIVE org.springframework.bundle.spring.beans_2.5.5
6 ACTIVE org.springframework.osgi.commons-el.osgi_1.0.0.SNAPSHOT
7 ACTIVE org.springframework.osgi.catalina.start.osgi_1.0.0.SNAPSHOT
8 ACTIVE org.springframework.bundle.osgi.io_1.1.0.rc1
. . . . . . . . . . .
====================================================================================

That is it for now. We can shut down our Target Platform.

1.5. Create Spring-DM User Library

One last step we should perform is to prepare Sring-DM library for our class path to be conveniently exported when developing non-plug-in based projects  (i.e., Spring-DM Integration Test project) against our Target Platform. We can of course define required JARs manually, but it would be simpler and more elegant if we were to expose our Target Platform as User Library configured via Eclipse.

To do that on the Eclipse menu bar select Window -> Preferences

When Preferences window will open up, expend Java -> Build Path -> User Libraries

Click on New (Right top corner)

When New User Library window opens up enter SPRING_DM_1.1 in User Library name:

Click OK

Now we are ready to add our bundles (JARs) to this library

Click on Add JARs and browse to the target directory we created earlier. When there select all JARs

You should see that all JARs were imported into our library:

Click OK

We’re done. Our Spring-DM library was created and ready to be used to develop Spring-DM projects.