OSGi Service Platform Specification defines a container that supports and manages the all life cycle of specific Java application modules called bundles. Knopflerfish framework (KFF), Equinox/Eclipse framework and Oscar framework are a well known implementations of the OSGi Platform. The OSGi bundle can creates and runs services that are registered on the framework context and are became visible and accessible for the rest bundles of the framework.

The project goal is a creating a tool that allows bundles to watch and use a services running on remote OSGi framework by means of Java Remote Method Invocation (RMI). KFF has a SOAP connectivity kit for this but RMI approach has some advantages: simpler implementation, higher performance and easy using (you stay in Java standard environment only).

The RMI connection between two remote frameworks is supported by two bundles: RMIGate on server-side framework and RMIEntrant on client-side framework. Service intended to be remote and running on server-side framework is registered on this framework context. The service is also registered on remote framework by means of RMIGate connected to client framework RMIEntrant object. This service has to implement Remote interface (from RMI package) for that. After remote service was registered on client-side framework then other bundles of client framework can use the remote service in the same way as other local services and RMI nature of the service is hided for calling bundles.

The component diagram fig. 1 represents the main objects participated in communication between two OSGi frameworks. 1. Server-side framework has followed components:

• 1.1. RMIGate object is responsible for keeping of connection to one (or more) client-side remote OSGi framework.
• 1.2. HTTP downloader provides a code base for the RMI Classloader and using HTTP server for that.
• 1.3. HTTP Server is a service of 'HTTP Server' KFF bundle.
• 1.4. ServiceTracker watches the services that are registered as remote services.
• 1.5. RMIServiceTrackerCustomizer provides functionality to register and to unregister the services on client-side remote OSGi framework.
• 1.6. RMI Class Loader is a part of RMI package that loads classes of RMI objects from remote host by using HTTP connection.

2. Client-side framework has followed components :

• 2.1. RMIEntrant object 'enters' to remote OSGi framework through RMIGate in order to get access to remote services of that server-side framework.
• 2.2. ServiceTracker tracks only one service - remote service RMIGate of service-side framework.
• 2.3. RMI ServiceTrackerCustomizer executes operations corresponded with Service events from RMIGate.
• 2.4. HTTP downloader and RMI Class Loader is the same as above.

Suppose that both frameworks have an installed and started HTTP Server bundle. RMI Gate Bundle has to be installed and started first on server framework. The Bundle instantiates RMI Gate, Service Tracker with RMIServiceTrackerCustomizer and HTTP downloader objects, starts local RMI registry and registers RMI Gate object on this. HTTP downloader registers its context (code base for RMI Class Loader) on HTTP Server service. ServiceTracker keeps references to started RMI services. After that RMI Entrant bundle can be started on client framework. RMI Entrant adds itself to RMI Gate and then RMI ServiceTrackerCustomizer of RMI Gate invokes RMI Entrant and registers all servers� RMI services. RMI Entrant in its turn registers ones on Bundle context of client framework. Now any bundles from client framework can access remote RMI services from server framework. Detailed description of the bundles code presents below.

The new developed rmi package resides in com.ak.osgi.service package. It consists of:

• http includes StubDownloader class.
• remotefw contains the main interfaces: RMIGate and RMIEntrant.
• gate includes Activator class for RMIGate bundle and RemoteServer class implemented RMIGate interface.
• entrant includes Activator class for RMIClient bundle and Client class implemented RMIEntrant interface.
• interfaces package is a helper package that includes a few packages for RMI services. It is needed for dynamic importing of any new remote services packages into RMI Gate bundle.
• serviceimpl package is a container for a remote service packages. As an interface package, this one serves of dynamic importing packages of RMI services into RMI Gate bundle.

Class diagrams do not need a match of comments. Ones can help to understand source code of the bundles

The next sequence diagrams show the flow of operations and messages between the bundles.

Let�s talk a few words about rmiregistry. You do not need to run rmiregistry before starting of RMI Gate bundle. The bundle will try to run rmiregistry if the bundle could not detect it. But if you'd like run rmiregistry yourself it is OK - RMI Gate bundle detects it and will use already running instance of rmiregistry.

The bundles are developed and built by Eclipse. Below you can find description of Eclipse project for RMI Gate and RMI Entrant bundles. Project name is 'RMI_Framework'. Project consists of two folders Entrant and Gate with a few files and subfolders.

• Entrant/src folder contains source files of entrant package and property file named rmi.properties. rmi.properties keeps configuration information for the bundle. It is optional.
• Gate/src folder contains gate package source files and rmi.properties property file.
• Entrant/build.xml is Ant file for building Entrant bundle rmiclient.jar file.
• Gate/build.xml is Ant file for building Gate bundle rmigate.jar file.
• Entrant/bundle.manifest is manifest file for Entrant bundle jar.
• Gate/bundle.manifest is manifest file for Gate bundle jar
• build.xml is Ant file for building rmiclientinterfaces.jar file for the RMI interfaces. This jar file is needed for client framework to define interfaces for RMI Gate object and RMI services.
• build folder is target folder for builded jar files.

Let's look at manifest file for Gate bundle:
Manifest-Version: 1.0
Bundle-Name: RMI_GATE
Bundle-SymbolicName: RMI_GATE
Bundle-Version: 1.0
Bundle-Activator: com.ak.osgi.service.rmi.gate.Activator
Bundle-Category: test
Import-Package: org.osgi.framework,org.knopflerfish.service.log,org.osgi.service.http
DynamicImport-Package: com.ak.osgi.service.rmi.serviceimpl.*

The all entries of the file are usual except 'DynamicImport-Package'. The entry define a list of packages that will be scanned by package administrator of OSGi framework in run-time when class of this packages need to be loaded. Reason for this feature is : Gate bundle can not know when it starts what rmi services will register on framework after that. So Gate bundle have to have ability dynamically find and load classes of rmi services from other bundle that installed and started after RMIGate. If rmi services classes reside in com.ak.osgi.service.rmi.serviceimpl packages (which were defined for dynamic import) they are always visible for Gate bundle.

Bundles are built by running Ant files build.xml. Build files for all project bundle have the same structure. It consists of a few targets :

Init

The target creates working folders for class compiling and jar generating.

Compile

Running java compiler

jar

Building jar file of bundle that includes packages, manifest and properties files.

Wipe

Clean up disk space

You need only change KFF property that has to point to location of KFF installation folder in your development workstation (Linux or Windows depends on condition tag). It presumes that Eclipse projects 'RMI_Framework' and 'RMI_services' (see below) reside in the same Eclipse workspace.

Now it is time to test connection between client and server framework. Eclipse project named 'RMI_services' represents two demo RMI services and bundle that calls the services. Services 'Demo1' and 'Demo2' are running on server framework and bundle 'caller' is running on client framework. Install and start 'Demo1' and 'Demo2' bundles on server-side framework. Start 'RMI_Gate' bundle or refresh its packages if it is already running. After that install 'Caller' bundle on client framework and start RMI_Entrant if not yet. Now start 'Caller' bundle and get in output window a response from remote services 'Demo1' and 'Demo2'

RMI Gateway is a simple combination of RMI Gate and RMI Entrant. After RMI starts it create two objects RMIGate and RMIClient. RMIGate is waiting for incomming connections one or more remote client framework and RMIClient is trying to connect to remote framework as a client. Symmetrical RMI Gateway makes easer of configuration and maintenance of remote framework's connection. More detail description is comming in next project.

Equinox deployment of RMI Gateway bundle little bit differ from above KFF. First the system and bundle properties resides in %INSTALL-DIR%/eclipse/plugins/configuration/config.ini. For example deployment of client requires following properties :
osgi.parentClassloader=app
org.osgi.service.http.port=8880
# RMI bundle properties (Client)
local.rmi.registry.port=1299
remote.rmi.registry.port=1199
remote.rmi.registry.host=localhost
For server deployment :
osgi.parentClassloader=app
org.osgi.service.http.port=8980
# RMI bundle properties (Client)
local.rmi.registry.port=1199
remote.rmi.registry.port=1299
remote.rmi.registry.host=localhost
To run Equinox framework execute this script :
cd %INSTALL-DIR%/eclipse/plugins
%JAVA_HOME%\java -cp %RMI-BUNDLE-DIR%/rmiclientinterfaces.jar;org.eclipse.osgi_3.2.0.v20060328.jar org.eclipse.core.runtime.adaptor.EclipseStarter -install %INSTALL-DIR%\eclipse\plugins -console
Before install and run RMIGateway bundle you have to install the folowing bundles:
org.eclipse.osgi.services_3.1.100.v20060109
org.eclipse.equinox.servlet.api_1.0.0.v20060206
org.eclipse.equinox.log_1.0.0.v20060206
org.eclipse.equinox.http_1.0.0.v20060317
org.eclipse.equinox.common_3.2.0.v20060329


The system properties resides in %INSTALL-DIR%/lib/system.properties and bundle properties in %INSTALL-DIR%/lib/bundle.properties. For example deployment of client requires following properties :
-- system.properties :
# RMI bundle properties (Client)
local.rmi.registry.port=1499
remote.rmi.registry.port=1199
remote.rmi.registry.host=localhost
-- bundle.properties :
org.osgi.service.http.port=8880
For server deployment :
-- system.properties :
# RMI bundle properties (Server)
local.rmi.registry.port=1199
remote.rmi.registry.port=1499
remote.rmi.registry.host=localhost
-- bundle.properties :
org.osgi.service.http.port=8980
To run Oscar framework execute this script :
cd %INSTALL-DIR%
%JAVA_HOME%\bin\java -cp lib\oscar.jar;%RMI-BUNDLE-DIR%\rmiclientinterfaces.jar org.ungoverned.oscar.Main
Before install and run RMIGateway bundle you have to install the folowing bundles:
file:bundle/shell.jar
file:bundle/tablelayout.jar
file:bundle/shellgui.jar
file:bundle/shellplugin.jar
file:bundle/bundlerepository.jar
file:bundle/http.jar
file:bundle/servlet.jar
file:bundle/log.jar
file:bundle/logger.jar
file:bundle/osgi-util.jar


Do not forget to change configuration properties files of the downloaded jars (see installation instructions above). Better way is set this properties as system (using -D... or props.args)

Future enhancement of RMI bundles :

• Extend RMI bundle functionality to allow the bundle remote access to some methods from remote framework BundleContext (Not to all for security reason). (Done and will be applayed for remote terminal for OSGi FW management with RMI protocol connection. Comming soon)