Virgo has been delivered with several sample applications used by many newbies creating their first OSGi running application. One of the flagships from the  Virgo sample pool of applications is the Greenpages application. This document refers to Greenpages deployment within  Eclipse development environment. Greenpages  has several issues preventing developers  from using from within Eclipse. Although most of the issues have been identified so far some of them cannot be solved within application itself but rather within environment. A new version of Greenpages might therefore not be a solution. Instead, this step-by-step guide will lead you around rocks and enable you to safely deploy Greenpages to a harbor – Virgo Tomcat server.

Introduction

The list of components required to follow this guideline:

  • Spring Tool Suite 3.1.0.RELEASE (STS) – based on
    • Eclipse Juno 4.2.1,
    • Java 1.7 and
    • m2e 1.2
  • Eclipse Virgo IDE 1.0.0
  • Virgo Tomcat Server 3.6.0.RELEASE

This guide assumes your intermediate level of  skills about the products referenced. Please refer to product manuals and Greenpages documentation in order  to set up products and follow the guide. Beside solving Greenpage application deployment issues the guide brings also following component upgrades:

  • EclipseLink will be upgraded to version 2.0.4
  • Java will be upgraded to version 1.7
  • Spring version will be upgraded  to 3.1

STEP 1: Importing Greenpages 2.5.0

Download and unzip greenpages-2.5.0.RELEASE.zip into temporary folder. Open STS and perform Import all Existing projects into Workspace from a temporary folder. Check option to copy projects into workspace. Convert all legacy Maven projects. Several error notifications pop up in the Problems view. They will be resolved during next steps.

STEP 2: Upgrading Projects to Java 1.7

Java sources and classes  will be migrated from  version 1.5 to 1.7.

NOTE: Projects could also be upgraded to Java 1.6. This final result has only been verified for migration to Java 1.7.

Open Greenpages.parent/pom.xml  and update source and target version numbers.

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-compiler-plugin</artifactId>
	<version>2.3.2</version>
	<configuration>
		<source>1.7</source>
		<target>1.7</target>
	</configuration>
</plugin>

Perform Java version upgrade Properties – Project Facets – Java  to 1.7  for  Greenpages.core, Greenpages.db, Greenpages.jpa and Greenpages.web.

Perform Maven-Update-Project from the context menu and select all the projects. Notice the significant reduction of errors in the Problems view.

In case of migration to Java 1.7, you will also need to update the Virgo runtime configuration. This extra task is required to override EclipseLink Bug 339388: Bytecode weaving has issues with JDK 7. Open Virgo Web Server configuration by Virgo Runtime at localhost – Overview – Open launch configuration and add VM argument -XX:-UseSplitVerifier.

STEP 3: Upgrading Spring Framework Version to 3.1.0

This step is necessary because of the Spring version gap between Greenpages 2.5.0 developed on Spring 3.0.5 and Virgo 3.6.0 distributed with Spring 3.1.0. The gap is resolved by upgrading Spring version in the application to 3.1.0.

Open Greenpages.parent/pom.xml and update version number to 3.1.0  for the following four dependencies:

<dependency>
	<groupId>org.springframework</groupId>
	<artifactId>org.springframework.spring-library</artifactId>
	<type>libd</type>
	<version>3.1.0.RELEASE</version>
	<scope>provided</scope>
</dependency>
<dependency>
	<groupId>org.springframework</groupId>
	<artifactId>org.springframework.test</artifactId>
	<version>3.1.0.RELEASE</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.springframework</groupId>
	<artifactId>org.springframework.instrument</artifactId>
	<version>3.1.0.RELEASE</version>
	<scope>test</scope>
</dependency>
<dependency>
	<groupId>org.springframework</groupId>
	<artifactId>org.springframework.aspects</artifactId>
	<version>3.1.0.RELEASE</version>
	<scope>test</scope>
</dependency>

STEP 4: Resolving Plexus-Archiver 2.1 Issue

The “org.codehaus.plexus.archiver.jar.Manifest.merge(org.codehaus.plexus.archiver.jar.Manifest)” error message appears because of the maven archiver plugin incompatibility with plexus-archiver-2.1.jar. This issue is thoroughly discussed in github as “sonatype / m2eclipse-extras issue #10”.

Open Greenpages-parent/pom.xml and downgrade the plugin version from 2.4  down to 2.3.2:

<plugin>
	<groupId>org.apache.maven.plugins</groupId>
	<artifactId>maven-jar-plugin</artifactId>
	<version>2.3.2</version>
	<configuration>
		<archive>
			<manifestFile>
			src/main/resources/META-INF/MANIFEST.MF
			</manifestFile>
		</archive>
	</configuration>
</plugin>

Perform Maven-Update-Project from the context menu for bundles Greenpages.core, Greenpages.db, Greenpages .jpa and Greenpages.web.

STEP 5: Resolving M2E Maven-Dependency-Plugin Issue

The “maven-dependency-plugin (goals “copy-dependencies”, “unpack”) is not supported by m2e issue explained in eclipse “M2E plugin execution not covered” article as well as Apache’s “OPENJPA/OPENJPA-2031”. The issue manifests as error messages in the Problems view and also in Properties-Maven-Lifecycle Mapping for bundle Greenpages.

Fortunately STS provides a quick-fix associated with “plugin execution not covered”. Select PAR Greenpages as a location to place ignore.

Consequently STS inserts the following plugin management definition into Greenpages/pom.xml:

<pluginManagement>
	<plugins>
<!--This plugin's configuration is used to store Eclipse m2e settings-->
<!-- It has no influence on the Maven build itself.-->
	<plugin>
		<groupId>org.eclipse.m2e</groupId>
		<artifactId>lifecycle-mapping</artifactId>
		<version>1.0.0</version>
		<configuration>
			<lifecycleMappingMetadata>
				<pluginExecutions>
					<pluginExecution>
						<pluginExecutionFilter>
							<groupId>
							org.apache.maven.plugins
							</groupId>
							<artifactId>
								maven-dependency-plugin
							</artifactId>
							<versionRange>
								[2.1,)
							</versionRange>
							<goals>
								<goal>
									copy-dependencies
								</goal>
							</goals>
						</pluginExecutionFilter>
						<action>
							<ignore></ignore>
						</action>
					</pluginExecution>
				</pluginExecutions>
			</lifecycleMappingMetadata>
		</configuration>
	</plugin>
</plugins>
</pluginManagement>

Now M2E will ignore the copy-dependencies instruction and we just got rid of another error.   However we will still be able t collect dependent bundles as we will build Greenpages with Maven .

STEP 6: Upgrading Eclipselink to version 2.4.0

This step is necessary because of the Spring version gap between Greenpages 2.5.0 – based on EclipseLink 1.0 and Virgo 3.6.0 – based on EclipseLink 2.0. The gap is resolved by upgrading EclipseLink to version 2.4.0.

Open Greenpages.parent/pom.xml  and insert a new property eclipselink.version into the <properties> section:

<eclipselink.version>2.4.0</eclipselink.version>

Next,  insert new repository into <repositories> section:

<repository>
	<id>EclipseLink</id>							<url>http://download.eclipse.org/rt/eclipselink/maven.repo</url>
</repository>

Insert new dependency into <dependencyManagement> section:

<dependency>
	<groupId>org.eclipse.persistence</groupId>
	<artifactId> org.eclipse.persistence.jpa</artifactId>
	<version>${eclipselink.version}</version>
	<scope>compile</scope>
</dependency>

Remove the three dependencies  from the same section:

<dependency>
	<groupId>javax.persistence</groupId>
	<artifactId>com.springsource.javax.persistence</artifactId>
<version>1.0.0</version>
	<scope>provided</scope>
</dependency>
<dependency>
<groupId>org.eclipse.persistence</groupId>
	<artifactId>com.springsource.org.eclipse.persistence</artifactId>
	<version>1.0.0</version>
	<scope>compile</scope>
</dependency>
<dependency>
	<groupId>org.eclipse.persistence</groupId>
	 <artifactId>com.springsource.org.eclipse.persistence.jpa</artifactId>
<version>1.0.0</version>
	<scope>compile</scope>
</dependency>

Open Greenpages.db/pom.xml and Greenpages.jpa/pom.xml and insert  dependencies  into <dependencies> section (both files):

<dependency>
	<groupId>org.eclipse.persistence</groupId>
	<artifactId> org.eclipse.persistence.jpa</artifactId>
</dependency>

Remove the three dependencies  from the same  section (both files):

<dependency>
	<groupId>javax.persistence</groupId>
	<artifactId>com.springsource.javax.persistence</artifactId>
</dependency>
<dependency>
	<groupId>org.eclipse.persistence</groupId>
	<artifactId>com.springsource.org.eclipse.persistence</artifactId>
</dependency>
<dependency>
	<groupId>org.eclipse.persistence</groupId>
	<artifactId>com.springsource.org.eclipse.persistence.jpa</artifactId>
</dependency>

Finally select Maven-Update-Project from the context menu and update bundles.

STEP 7: Building Greenpages  PAR Gradually

Each of the Greenpages bundles depend on other OSGi bundles. Some of the bundles have been delivered as native Virgo bundles but others still need to be identified, downloaded and deployed together with the application. During the following steps all Greenpages bundles will be reworked and re-mapped to Virgo. To break down the complexity the application will be disassembled first and then gradually reassembled back to PAR project, one bundle after another. For each bundle the following procedure will be performed:

  1. Analyze bundle mapping to Virgo and perform any changes.
  2. Build bundle with Maven.
  3. Reactivate bundle in PAR Greenpages Maven files.
  4. Build PAR Greenpages with Maven to collect bundle dependencies.
  5. Deploy new bundle dependencies to Virgo user region.
  6. Target bundle to Virgo Runtime.
  7. Enable Bundle Classpath Container.
  8. Add bundle into PAR Greenpages MANIFEST.

Let’s start with disassembling the application.

Open PAR  Greenpages MANIFEST.MF. All bundles need to be removed. Please notice that the file contains false dependency names.

PAR editor 1

Remove all existing bundles .

Next, open PAR Greenpages/pom.xml and deactivate (comment) all dependent bundles: Greenpages.core, Greenpages.db, Greenpages.jpa and Greenpages.web.

Finally build Greenpages.parent with Maven. This will enable later Maven PAR  re-builds.

STEP 8: Mapping Greenpages.core to Virgo

First, open the file Greenpages.core/src/main/resources/META-INF /MANIFEST.MF. The Virgo Bundlor tool created a list of bundle dependencies relying on template.mf  file  and detailed bundle artifacts analysis. Only one package dependency, com.springframework.stereotype, can be found. Greenpages core  1

Build bundle with Maven, reactivate bundle in PAR’s pom.xml and build PAR with Maven.

Targeted Runtimes

Next , we need to map dependencies found in the MANIFEST.MF file to the already installed Virgo bundles. Eclipse environment and Virgo support us by presenting Bundle Dependencies Library.  In order to turn on this functionality we need to associate bundle with Virgo Runtime and enable Bundle Classpath Container using Virgo – Enable Bundle Classpath Container while Virgo server is stopped.

Now we can manually search for the package com.springframework.stereotype  and find it within bundle org.springframework.context_3.1.0.RELEASE.jar of the Bundle Dependencies container.

The bundle is actually located in ext folder of the Virgo Repository as it belongs to set of native bundles.  Note also that package version 3.1 falls within the requested interval [3.0, 3.5] defined in MANIFEST.MF.  No further actions related to this package is required.

Finally add he bundle into PAR Greenpages MANIFEST.

STEP 9: Mapping Greenpages.db to Virgo

Start in the same way as with Greenpages.core: open Dependencies tab in Greenpages.db/src/main/resources/META-INF /MANIFEST.MF.

Greenpages db 1

Build bundle with Maven, reactivate bundle in PAR’s pom.xml and build PAR with Maven.

Associate bundle with Virgo Runtime and turn on Bundle Dependencies container while Virgo server is stopped. Because bundle dependencies could not be identified within Virgo, Bundle Classpath Container remains empty and so not appearing in the package Explorer view.

Package javax.sql  is actually exported by  org.eclipse.osgi bundle which is a member of Virgo kernel  region. Unfortunately org.eclipse.osgi is not displayed within Bundle Classpath Container. Within JRE System Library the package is included in rt.jar.

Package org.apache.commons.dbcp could not be found in Virgo environment and we need to provide it for the application. We are alerted about the problem by an error message poping-up in the Problems view. Fortunately, Maven gives us a good support by collecting any direct and transitive dependencies. Reactivate bundle in PAR Greenpages pom.xml .  Build with Maven goal install on bundle Greenpages.db and PAR Greenpages.

Refresh and review new files appearing in Greenpages/target/par-provided container using Package Explorer:

com.springsource.freemarker-2.3.18.jar
com.springsource.org.apache.commons.dbcp-1.2.2.osgi.jar
com.springsource.org.apache.commons.pool-1.3.0.jar
com.springsource.org.h2-1.0.71.jar

As Maven ignores Virgo repository we need to manually determine bundles which are not installed in Virgo yet and copy those jars to Virgo’s usr repository.  Copy all files except com.springsource.org.h2-1.0.71.jar into Virgo’s usr repository. Later has issue which will be resolved during the next step.  Until then Greenpages.db  is not ready for deployment and consequently any remaining integration activities for this bundle should be suppressed.

STEP 10: Resolving H2 Driver Loading Issue

There is a problem “Cannot load JDBC driver” while deploying application to Virgo described in Eclipse Bug 368781. A valid workaround is to create a new plug project from existing H2 driver jar.  Start with deactivating dependencies on existing driver  from Greenpages,, Greenpages.db, Greenpages.jpa and Greenpages.web pom.xml files 

<!-- DEACTIVATED 		<dependency>
	<groupId>com.h2database</groupId>
	<artifactId>com.springsource.org.h2</artifactId>
</dependency> -->

Continue with deactivating dependency in  dependencManagement of Greenpages.parent/pom.xml:

<!--  DEACTIVATED		<dependency>
	<groupId>com.h2database</groupId>
	<artifactId>com.springsource.org.h2</artifactId>
	<version>1.0.71</version>
        <scope>compile</scope>
</dependency>  -->

New plugin 1

Now a new Plug-in from Existing JAR Archives project needs to be created. JAR file com.springsource.org.h2-1.0.71.jar can be found in target/par-provided container of the Greenpages.db.

New plugin 2

Mavenize the project by performing Configure-Convert to Maven Project from the context menu.

New plugin 3Open the Greenpages.h2/pom.xml and select project’s parent Greenpages.parent. Next, update the relative path in the Parent section. Finally perform Maven-Update-Project from the context menu and select Greenpages.h2 project.

Convert the project to faceted form by Properties – Project Facets -Convert to faceted form. Tick the EclipseRT Virgo Server checkbox.

After the project has been created edit its MANIFEST.MF file. Remove JAVASE-1.7 execution environment. Ignore the warning message.

Configure Java Build Path from the Greenpages.h2 project Properties. Create four java source folders:

greenpages.h2/src/main/java
greenpages.h2/src/main/resources
greenpages.h2/src/test/java
greenpages.h2/src/test/resources

Move META-INF from bundle root container into into src/main/resources.

In the root of the bundle create a new template.mf file and populate it manually.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: GreenPages H2
Bundle-SymbolicName: greenpages.h2
Bundle-Vendor: SpringSource
Bundle-Version: 0.0.1
Export-Template: org.h2.*;version="1.0.72",
 org.h2.command.*;version="1.0.72",
 org.h2.server.*;version="1.0.72",
 org.h2.store.*;version="1.0.72"

Still within template.mf : export all org.h2.* packages and perform Virgo-Run generation of MANIFEST.MF File from the project’s context menu.

Associate bundle with Virgo Runtime: Properties – Targeted Runtimes – Virgo Runtime.

Build with Maven goal install for  bundles Greenpages.h2.

Insert the following new dependency into Greenpages, Greenpages.db, Greenpages.jpa and Greenpages.web.

<dependency>
	<groupId>org.eclipse.virgo</groupId>
	<artifactId>greenpages.h2</artifactId>
	<version>0.0.1-SNAPSHOT</version>
</dependency>

Replace org.h2 [1.0.71] with org.h2 [1.0.72] in template.mf  file for bundle Greenpages.db. We have delivered a brand new version number to the packages within new bundle Greenpages.h2 in order to avoid any collision with other applications relying to the standard 1.0.71 H2 driver.

Build with Maven with goal install on bundle Greenpages.db and PAR Greenpages.

Add bundles Greenpages.h2  and Greenpages.db into PAR’s Greenpages MANIFEST.

STEP 11: Mapping Greenpages.jpa to Virgo

An upgrade of EclipseLink has already been completed some steps ago. Now we can build bundle with Maven, reactivate bundle in PAR’s POM and build PAR with Maven. Several new dependent bundles are collected in PAR’s target\par-provided container:

javax.persistence-2.0.4.v201112161009.jar
org.eclipse.persistence.antlr-3.2.0.v201206041011.jar
org.eclipse.persistence.asm-3.3.1.v201206041142.jar
org.eclipse.persistence.core-2.4.0.jar
org.eclipse.persistence.jpa.jpql-2.4.0.jar
org.eclipse.persistence.jpa-2.4.0.jar

Copy all files except javax.persistence-2.0.4.v201112161009.jar to Virgo usr repository. Later is Virgo native bundle and already installed in Virgo’s ext repository. Associate bundle with Virgo Runtime and enable Bundle Classpath Container using Virgo – Enable Bundle Classpath Container while Virgo server is stopped.

Open Dependencies for Greenpages.jpa/template.mf and perform several changes:

Greenpages jpa 1

Upgrade package javax.persistence  to version [2.0.4,2.0.4].

Add package javax.persistence.criteria [2.0.4,2.0.4].

Remove bundles com.springsource.org.eclipse.persistence[1.0.0.,1.0.0] and com.springsource.org.eclipse.persistence.jpa[1.0.0.,1.0.0].

Add following  import bundles:
org.eclipse.persitence.jpa[2.4.0.v20120608-r11652, 2.4.0.v20120608-r11652],
org.eclipse.persistence.core [2.4.0.v20120608-r11652, 2.4.0.v20120608-r11652]
org.eclipse.persistence.jpa.jpql [2.0.0.v20120608-r11652,2.0.0.v20120608-r11652]
org.eclipse.persistence.asm [3.3.1.v201206041142,3.3.1.v201206041142]
org.eclipse.persistence.antlr[3.2.0.v201206041011,3.2.0.v201206041011]

Propagate changes to bundles MANIFEST.MF by performing Virgo – Run Generation of MANIFEST.MF File.  Add bundle into PAR Greenpages MANIFEST.

STEP 12: Mapping Greenpages.web to Virgo

Build bundle with Maven, reactivate bundle in PAR Greenpages pom.xml and build PAR Greenpages with Maven.

Greenpages.web project has been delivered with Dynamic Web Module project nature. This nature for some reason prevents  module to be delivered within greenpages-2.5.0.RELEASE-synthetic.context therefore it has to be removed. Due to another Eclipse issue (NPE) it cannot be removed using Properties – Project Facets  dialog. Fortunately you can use a workaround. Open file greenpages.web/.settings/org.eclipse.wst.common.project.facet.core.xml  found  in Navigator view. Remove the line  <installed facet=”jst.web” version=”2.5″/>. The final outlook of the file follows:

<?xml version="1.0" encoding="UTF-8"?>
<faceted-project>
  <runtime name="Virgo Runtime"/>
  <installed facet="org.eclipse.virgo.server.bundle" version="1.0"/>
  <installed facet="jst.java" version="1.7"/>
</faceted-project>

Open template.mf and MANIFEST.MF files,  remove the  import library org.springframework.spring  [3.0,3,1) and add org.springframework.spring [3.1.0.RELEASE, 3.1.0.RELEASE].

Version to Match

Update the  upper boundary from 3.1 to 3.5 for each of the eight packages org.springframework.*:

Associate bundle with Virgo Runtime and enable Bundle Classpath Container using Virgo – Enable Bundle Classpath Container while Virgo server is stopped.

Add bundle into PAR Greenpages MANIFEST.

STEP13: Summarizing Changes to PAR Greenpages

Folder target\par-provided is populated with the following jars:

com.springsource.freemarker-2.3.18.jar
com.springsource.org.apache.commons.dbcp-1.2.2.osgi.jar
com.springsource.org.apache.commons.pool-1.3.0.jar
javax.persistence-2.0.4.v201112161009.jar
org.eclipse.persistence.antlr-3.2.0.v201206041011.jar
org.eclipse.persistence.asm-3.3.1.v201206041142.jar
org.eclipse.persistence.core-2.4.0.jar
org.eclipse.persistence.jpa.jpql-2.4.0.jar
org.eclipse.persistence.jpa-2.4.0.jar
com.springsource.org.h2-1.0.71.jar

All files except org.eclipse.persistence.jpa-2.4.0.jar and com.springsource.org.h2-1.0.71.jar have already been copied to Virgo’s usr repository. Former is part of the original Virgo kernel region and later has been replaced with bundle Greenpages.h2.

PAR  Greenpages MANIFEST.MF should look like this:

Greenpages 1

STEP 14: Resolving Virgo PAR Republishing Issue

By default Virgo server is configured to automatically refresh bundles, PARs and plans. This automatic refresh appears even without any project modification from developer. Unfortunately there is an issue with PAR and plan refresh:

 Cannot refresh par 'greenpages' version '2.5.0.RELEASE' as refresh of par artifacts is not supported.

In order to avoid recurring republishing you need to turn off automatic republishing.

Virgo 1

Conclusion

Application has been re-assembled and can now be deployed to Virgo. Do not forget to start up the  H2 database first. Use application compliant version, 1.0.71, of the database driver to avoid database access conflicts from the Greenpages application.

You can override all but the last two steps by simply downloading the final version of  Greenpages.zip. You might still need to download the original sample file for H2 database and documentation.

This guide is based on several workarounds for known bugs discovered by many developers. However, to successfully deploy Greenpages one had to collect all the solutions in a structured guide. Thanks to any of these contributors who paved many parts of the journey.