TableOfContents

Introduction

[http://wiki.ops4j.org/confluence/display/ops4j/Pax Pax] is a project to develop tools for OSGi bundles. Pax-Construct, which is a part of Pax project, is a tool to create, build, manage and deploy OSGi bundles. The basic idea is that instead of writing all pom.xml files manually, generate those using simple shell commands.

Sample Projects

Create New Spring-OSGi Project

• Install Pax-Construct - Essentially, Pax-Construct is a collection of scripts, so you can install this by uncompress the zip file somewhere on your local disk space, and set the path to the directory. For example, if you unzip the pax-construct version 1.3 to PAX_HOME, you need to set the path to:

PAX_HOME/pax-construct-1.3/bin

• Create Project - You can run the following shell script to create a sample Spring-OSGi project named project1.

##############################################
# Template for Spring-OSGi projects #
##############################################

# (1) Create Project "project1"
pax-create-project -g org.cytoscape -a project1
cd project1

# (2) Add SpringSource Enterprise Bundle Repositories
pax-add-repository -i com.springsource.repository.bundles.release -u http://repository.springsource.com/maven/bundles/release
pax-add-repository -i com.springsource.repository.bundles.external -u http://repository.springsource.com/maven/bundles/external

# (3) Import required bundles
pax-import-bundle -g org.springframework.osgi -a org.springframework.osgi.extender -v 1.1.0 -- -DimportTransitive -DwidenScope

# (4) Create bundles
pax-create-bundle -p org.cytoscape.helloservice1 -- -Djunit
pax-create-bundle -p org.cytoscape.helloservice2 -- -Dspring=2.5.5 -Djunit
pax-create-bundle -p org.cytoscape.helloserviceuser -- -Dspring=2.5.5 -Djunit

# (5) Build and run the project
mvn clean install pax:provision

Details

1. pax-create-project command creates a new OSGi project in the current working directory. By -g option, you can specify group id of this project.

2. In general, you CANNOT use existing library files (jar files registered at the maven central repository) as OSGi bundle. There are two options to solve this problem:

   • Wrap existing jar files by pax-wrap-jar command

   • Use OSGi bundle repository instead of maven central repository

   In this example, I used the second option. pax-add-repository command adds an additional maven repository location to the pom file. SpringSource manages a maven repository [http://www.springsource.com/repository/app/ SpringSource Enterprise Bundle Repository], which is a repository of OSGi bundles. All library files in this repository are wrapped as OSGi bundles.

3. pax-import-bundle command automatically generates <dependency> statement in the project pom file. In this example, bundles required to run [http://www.springframework.org/osgi Spring Dynamic Modules] are imported.

4. This section contains the actual statements to generate templates for your bundles. pax-create-bundle commands generates minimal set of files to start writing OSGi bundle. If you do not specify the option, a simple bundle with BundleActivator and an OSGi service will be created. If -Dspring option is specified, an example Spring Bean and XML files to setup Spring-based OSGi services will be created.

5. Pax is also available as maven plugin. Anytime after you build the bundles by mvn clean install command, you can run your bundles by mvn pax:provision. This command automatically setup [http://felix.apache.org/site/index.html Apache Felix] to run your bundles.

After you run the script, you will see the prompt (if not, hit enter). Type ps and you can check the current status of the bundles:

-> ps
START LEVEL 6
   ID   State         Level  Name
[   0] [Active     ] [    0] System Bundle (1.0.4)
[   1] [Active     ] [    5] Spring DM Extender (1.1.0)
[   2] [Active     ] [    5] Apache Commons Logging (1.1.1)
[   3] [Active     ] [    5] Spring Beans (2.5.5.A)
[   4] [Active     ] [    5] Spring Context (2.5.5.A)
[   5] [Active     ] [    5] Spring Core (2.5.5.A)
[   6] [Active     ] [    5] Spring DM Core (1.1.0)
[   7] [Active     ] [    5] AOP Appliance API (1.0.0)
[   8] [Active     ] [    5] Spring AOP (2.5.5.A)
[   9] [Active     ] [    5] Spring DM IO (1.1.0)
[  10] [Active     ] [    5] org.cytoscape.helloservice1 (1.0.0.SNAPSHOT)
[  11] [Active     ] [    5] org.cytoscape.helloservice2 (1.0.0.SNAPSHOT)
[  12] [Active     ] [    5] org.cytoscape.helloserviceuser (1.0.0.SNAPSHOT)
[  13] [Active     ] [    1] osgi.compendium (4.0.1)
[  14] [Active     ] [    1] Apache Felix Shell Service (1.0.1)
[  15] [Active     ] [    1] Apache Felix Shell TUI (1.0.1)

At this point, all bundles you have created by the script are running and they are assigned IDs (13, 14, and 15). Type services 10:

-> services 10

org.cytoscape.helloservice1 (10) provides:
------------------------------------------
objectClass = org.cytoscape.helloservice1.ExampleService
service.id = 23

services command in the Felix shell shows a list of services running now. The example above shows an OSGi service named ExampleService is successfully registered at the OSGi service repository.

Now you are ready to write your code for the bundles. If you use Eclipse, use

mvn pax:eclipse

and then import the project from File --> Import. You need to choose Maven Project for project type. The project looks like the following:

attachment:eclipseproject1.png

Create New Plugin in Cytoscape 3 Project

Since Cytoscape 3 SVN trunk is build as PAX project, you do not need to create new project. You can add your plugin as a new bundle(s).

1. Install latest version of Maven
2. Checkout Cytoscape 3 trunk from SVN
3. cd to the Cytoscape 3 project directory
4. Check Cytoscape 3 compiles in your environment:

    mvn clean install pax:provision

5. If OK, quit and run this script:

   #######################################################################
   # Create new Spring DM bundle in Cytoscape 3 directory  #
   #######################################################################
   
   # Add SpringSource Enterprise Bundle Repositories
   pax-add-repository -i com.springsource.repository.bundles.release -u http://repository.springsource.com/maven/bundles/release
   pax-add-repository -i com.springsource.repository.bundles.external -u http://repository.springsource.com/maven/bundles/external
   
   # Import required bundles
   pax-import-bundle -g org.springframework.osgi -a org.springframework.osgi.extender -v 1.1.0 -- -DimportTransitive -DwidenScope
   
   # Create new plugin as a bundle
   pax-create-bundle -n helloPlugin -p org.cytoscape.helloPlugin -- -Dspring=2.5.5 -Djunit

6. cd to the new plugin directory (in this example, helloPlugin)

7. Edit osgi.bnd

   -----------------------------------------------------------------
   # Use this file to add customized Bnd instructions for the bundle
   #-----------------------------------------------------------------
   Export-Package: org.cytoscape.helloPlugin

8. Edit src/main/java/org/cytoscape/helloPlugin/internal/ExampleBeanImpl.java

   public class ExampleBeanImpl
       implements ExampleBean
   {
   
       public ExampleBeanImpl() {
         System.out.println("======================= Hello OSGi and Spring! ====================");
       }   
   
       public boolean isABean()
       {
           return true;
       }
   }

9. mvn clean install

10. Back to Cytoscape 3 home directory

11. Type mvn pax:provision

12. You will see something like this(情報 will be shown in your OS language):

    情報: No outstanding OSGi service dependencies, completing initialization for OsgiBundleXmlApplicationContext(bundle=cytoscape.core.helloPlugin, config=osgibundle:/META-INF/spring/*.xml)
    2008/07/18 9:54:28 org.springframework.beans.factory.support.DefaultListableBeanFactory preInstantiateSingletons
    情報: Pre-instantiating singletons in org.springframework.beans.factory.support.DefaultListableBeanFactory@dee91: defining beans [myExampleBean]; root of factory hierarchy
    ======================= Hello OSGi and Spring! ====================
    2008/07/18 9:54:28 org.springframework.osgi.context.support.AbstractOsgiBundleApplicationContext publishContextAsOsgiServiceIfNecessary
    情報: Publishing application context as OSGi service with properties {org.springframework.context.service.name=cytoscape.core.helloPlugin, Bundle-SymbolicName=cytoscape.core.helloPlugin, Bundle-Version=1.0.0.SNAPSHOT}

-- KeiichiroOno DateTime(2008-07-08T22:20:36Z)