JXSE and Equinox Tutorial, Part 2

http://java.dzone.com/articles/jxse-and-equinox-tutorial-part-0

——————————————————————————————————————————————————————

Abstract

In the first post of this series, we covered the quickest way to get JXSE 2.7x working in Equinox and, with some considerations, probably other OSGI frameworks as well. The approach aimed to get the same functionality as you would get by using the jar file in a regular JAVA setting, but as I demonstrated, Equinox does have the benefit of allowing multiple JXSE instances to run simultaneously, which is a great benefit when developing JXSE applications.

In this second tutorial, we will cover some ways of improving the functionality by severing the dependency on the 4.2x version of Jetty (which has just released it's 9.0 version!) and we will introduce some basic tools to visualize the properties and functions of JXSE. This will improve the development cycle of JXSE applications even more.

NOTE: This tutorial will use a modified JXSE jar, which currently has only been sparsely tested. If you want to develop in a fail-safe environment, I would recommend that you stick to approach of adding the 2.7x and org.mortbay.jetty 4.2x jars to your plugin structure. If you are more adventurous or, even better, want to help to improve the tooling, then this post is for you!

Updating Jetty

The approach we covered earlier involves including a Jetty server for every JXSE bundle you want to deploy. The Jetty server is used for HTTP tunneling and basically starts a simple HTTP server with one servlet. If we want to optimize this approach when running multiple JXSE bundle projects, it would stand to reason that we run one server instance, which registers multiple servlets, which is basically the way that Jetty runs in most OSGI environments. Ideally we would utilize the http service for Equinox to register our servlets, but because every JXSE bundle needs to run on a different network port, registration of the servlets is a bit more involved.

The implication of breaking the dependency on the org.mortbay.jetty 4.2x jar (i.e. removing the jar-file from the lib directory and putting it in a separate bundle) is that the JXSE code has to be changed as well, and so we might just as well create a JXSE 2.7x bundle! This bundle will be a client for a declarative service that is offered by the Jetty plugin, and which allows registration of the specific servlets that JXSE uses. The necessary bundles can be found in the extended.zip, which offers functionality that extends the base porting of JXSE applications to Equinox. can be included in your target definition:

Download the zip-file and unpack it in the same target root as the other target plugins (e.g. C:ProjectsTargetExtended)
In the Eclipse IDE, select Window → Preferences → Plug-in Development → Target Platform, and select the active target we assembled in the previous posting
Press 'Edit' and 'Add' a new 'Directory' by selecting the appropriate controls. Browse to the folder where the unzipped files are located and add the folder to your target definition. Press 'Finish' to complete the Wizard

TIP: Extending a target definition with new directories can be a RSI-ridden chore. Luckily the 'Location' field stores previous entries, and so if you select one of these before pressing the 'Browse' button, you may win quite a few mouse-clicks

The target definition has been extended with a number of bundles, three of which are important for this part of the tutorial:

net.jxse (2.7.x)
org.mortbay.jetty (4.2.x)
org.eclipse.jetty.jxse.bridge (1.x.y)

I try to follow the convention to use the version of a jar-file when it is converted to OSGI, and from this it becomes evident that the first two bundles are basically the original jar-files that were deployed in part one of the tutorial. The only difference is that these bundles share their dependencies through a declarative service.

NOTE: Internally, the necessary modifications were performed with minimal impact of the code. To my knowledge, the core functionality should therefore not be affected. The major differences only come into play when multiple JXSE bundles are deployed simultaneously, which I consider to be new functionality anyway. When developing fail-safe applications, the two bundles should therefore be good to use, but keep a sharp eye on the HTTP logs to be certain!

With this, we can now modify the two JXSE Plugin project we developed in the previous post to work with these bundles. We will also use a different example from the book Practical JXTA II to make things more interesting. We will try to connect Edge_Anna with Rendezvous_Jack. Modify the two JXSE 2.7x Bundle Projects you made in the previous tutorial :

Remove the lib folder and the references to lib/jxse-2.7.jar and lib/org.mortbay.jetty.jar in the bundle classpath settings.
Solve the compiler errors by importing the necessary bundle dependencies in the 'imported packages' tab of the Manifest editor.
Include the org.mortbay.jettybundle (not the bridge!)

The resulting Manifest.MF file should look something like this:

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: Practical JXTA II: Anna the Edge Peer
Bundle-SymbolicName: net.practical.jxta.decoupled.anna
Bundle-Version: 1.0.0.v20130816
Bundle-Activator: net.practical.jxta.decoupled.anna.Activator
Bundle-Vendor: MyCompany
Bundle-RequiredExecutionEnvironment: JavaSE-1.7
Bundle-ActivationPolicy: lazy
Bundle-ClassPath: .
Import-Package: net.jxta,
net.jxta.document,
net.jxta.endpoint,
net.jxta.exception,
net.jxta.id,
net.jxta.peer,
net.jxta.peergroup,
net.jxta.platform,
net.jxta.rendezvous,
org.osgi.framework;version="1.7.0"

We can now copy Edge_Anna.java and Rendezvous_Jack.javafrom the folder B_Exploring_Connectivity_Issuesfrom the examples that are covered by Practical JXTA II as replacement for the previous examples. Last we need to make a slight adjustment to the Activators in order to ensure concurrency:

import java.util.concurrent.Executors;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;

public class Activator implements BundleActivator, Runnable {

private static Activator activator;
private ExecutorService executor;

  static Activator getDefault() {
    return activator;
  }

  public void start(BundleContext bundleContext) throws Exception {
    activator = this;
    executor = Executors.newSingleThreadExecutor();
    executor.execute(this);
  }

  public void stop(BundleContext bundleContext) throws Exception {
    if( !executor.isShutdown() && !executor.isTerminated())
      executor.shutdown();
    Activator.context = null;
  }

  @Override
  public void run() {
    Edge_Anna.main(null);
  }
}

When the bundles are added to your run configuration, you will see that the various pop-up messages are spawned as the two bundles are activated. But hidden deep in the log messages, you will also find that a -if all went well:

INFO: Jetty Server for JXTA found!

And, a bit later:

INFO: Line 679 net.jxta.impl.peergroup.GenericPeerGroup.loadModule()
Loaded privileged module : Reference Implementation of the HTTP Message Transport
(net.jxta.impl.endpoint.servlethttp.ServletHttpTransport)

As Rendezvous_Jack is starting up HTTP transport. If this doesn't seem to happen, then the most likely reason is that the org.mortbay.jettybundle has not started (type 'ss' in the Eclipse console for the status of the bundles). You can also check if the declarative services that forge the connection between the two bundles have started correctly by typing in the OSGI console:

'attendees': this should return (at least)
osgi> attendees
net.jxse.petitioner.ServerStarterPetitioner
org.mortbay.jetty.provider.ServerProvider
'matched': this should return:
osgi> matched
net.jxse.petitioner.ServerStarterPetitioner is matched with:
org.mortbay.jetty.provider.ServerProvider

The bundles use a light-weight wrapper around OSGI's standard declarative services called a secure broker (org.eclipselabs.osgi.ds.broker) to make the connection. This bundle is also provided by the target addition that was downloaded .One of the added functions are three console commands to check the connections (the third one is 'waiting'). The first command lists the (broker) services that are registered, the second one which services are matched with one another. Above you can see that the bunle net.jxseis connected with the bundle org.mortbay.jetty. If these commands are not recognized, it means that the broker plugin is not activated yet.

Integration with Jetty 6 to Jetty 8 (inclusive)

If you are a bit more adventurous, you may want to try the Jetty Bridge that has also been included in the additions to the target. This bundle requires the org.eclipse.jetty bundles from 6.0.0 to 8.9.9, which are often shipped with certain Eclipse distributions. Simply deactivate the org.mortbay.jettybundle and activate org.eclipse.jetty.jxse.bridge. (and Jetty, of course). If all is well, you should see the same behavior as previously, but now more recent versions of Jetty can be used.

NOTE: Please consider that I have only tested this option with Jetty 8, and not extensively. The sources are available on eclipselabs, so a Jetty expert (JXTA knowledge is hardly required) may be able to improve the current code considerably!

Enabling JXSE Tools for Eclipse

The previous examples probably have made clear that pop-up messages and log messages are not going to be very helpful when developing multiple JXSE Bundle projects simultaneously. Although this is work in progress (and probably will always be so), a start has been made to develop JXSE tools that can be used in an Eclipse IDE. I hope to add more posts to this tutorial as functionality becomes available, but here we can begin by demonstrating what needs to be done at minimum to make your JXSE Bundle Projects visible to the tools.

In order to enable the Eclipse tooling, a new target is needed which replaces equinox with an Eclipse version (which, of course, includes an Equinox version). As we have ample experience with target definition management by now, I will just list the three directories that are needed to get things up and running

An Eclipse version. You can opt to copy the Kepler installation to the target environment (recommended), or use the
${eclipse-home} option as location (quickest)
the core JXSE bundles that were downloaded for the previous post
The extended JXSE bundles that were downloaded for the first part of this tutorial

Next we need to create a new Eclipse application ( File → New → Plugin Project). Select the option that the 'plug-in is targeted to run with' an Eclipse version, and (in the second tab) that we will develop a Rich Client application. Clicking 'Finish' will generate a bare-bones Eclipse RCP. We will include one perspective to the RCP by hardcoding it in the ApplicationWorkbenchAdvisor:

package org.{my-company}.jxse.ui;

import org.eclipse.ui.application.IWorkbenchWindowConfigurer;
import org.eclipse.ui.application.WorkbenchAdvisor;
import org.eclipse.ui.application.WorkbenchWindowAdvisor;

public class ApplicationWorkbenchAdvisor extends WorkbenchAdvisor {

  private static final String PERSPECTIVE_ID = "org.eclipse.jxse.perspective";

  @Override
  public WorkbenchWindowAdvisor createWorkbenchWindowAdvisor(
         IWorkbenchWindowConfigurer configurer) {
    return new ApplicationWorkbenchWindowAdvisor(configurer);
  }

  @Override
  public String getInitialWindowPerspectiveId() {
    return PERSPECTIVE_ID;
  } 
}

Next, remove the Tools.java file from the JXSE bundles and rename the faulty imports in the JXSE bundles to 'net.osgi.jxse.compatibility.Tools'. We also need to make some changes to the code from Practical JXTA II:

Make the class that run the examples extend net.osgi.jxse.compatibility.AbstractExampleContext
Include addModule( MyNetworkManager) after it has been instantiated;

NOTE: The static method addModule registers JXTA modules (NetworkManager, the various services, and so on) to the JXSEContext, by wrapping them in a IJxseComponent instance. In fact, the Jxse service context accepts any object; it manily serves to create a tree structure of provided modules (objects) with the NetworkManager as primary child. The NetworkConfigurator is also represented internally as a IJxseComponent, but the service context already takes care of this when the NetworkManager is registered.

Last, a new launch configuration is needed for an 'Eclipse Application'. Select the 'Run an Application' option in the first tab, and select the application you just created. The workspace plugins that are needed should include the application, and the two JXSE Bundle projects 'Jack the Rendezvous' and 'Anna the Edge'. Add the 'Required Bundles', and ensure that the following bundles are included:

org.eclipse.equinox.console
The three org.apache.felix.gogobundles
org.eclipselabs.osgi.ds.broker
org.mortbay.jetty or org.eclipse.jetty.jxse.bridge
net.osgi.jxse.compatibility
org.eclipselabs.jxse.ui

Validate the configuration and 'add Required Bundles' if necessary. If no problems have been detected, you can launch the application. If all went well, you should see the two JXSE bundles start up as they did previously, but instead of the somewhat outdated pop-up boxes from JAVA Swing, the more flashy alternatives from Eclipse's SWT packages should pop up. Also a basic Eclipse application should become visible with some views which are currently empty. The more observant developers will probably spot the

WARNING:
This bundle is not a valid JXSE Bundle. A JXSE-INF directory is required.

Ignore this warning for now. It will become more important in the next part of this series.

We are almost there! Stop the run configuration, and make the following modifications to the JXSE Bundle projects:

Create a new component definition (File → New→ …) and select as the parent folder <your.bundle.name>/OSGI-INF, and name jxse.xml (or another name of your choosing). This will create a folder OSGI-INFunder the root of your JXSE bundles and add the file.

When the component editor opens, fill in the details as follows:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="<your.bundle.name>.service">
<implementation class="<your.bundle.name>.service.OsgiComponent"/>
<reference bind="setAttendeeService" cardinality="1..1" interface="org.eclipselabs.osgi.ds.broker.IAttendeeService" name="IAttendeeService" policy="static" unbind="unsetAttendeeService"/>
</scr:component>

After the component definition is completed, the required OsgiComponent.java needs to be present in the designated package. This class should look as follows:

<?xml version="1.0" encoding="UTF-8"?>
<scr:component xmlns:scr="http://www.osgi.org/xmlns/scr/v1.1.0" name="<your.bundle.name>.service">
<implementation class="<your.bundle.name>.service.OsgiComponent"/>
<reference bind="setAttendeeService" cardinality="1..1" interface="org.eclipselabs.osgi.ds.broker.IAttendeeService" name="IAttendeeService" policy="static" unbind="unsetAttendeeService"/>
</scr:component>

Include the following line in the Manifest-MF file:

Service-Component: OSGI-INF/jxse.xml

The OsgiComponent is very simple:

package <your.bundle.name>;
 
import net.osgi.jxse.service.core.JxseDSComponent;
import <your.bundle.name>.Activator;
 
public class OsgiComponent extends JxseDSComponent {
 
public OsgiComponent() {
super( Activator.getDefault());
}
}

Modify the Activator as follows:

package <your.bundle.name>;
 
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
 
public class Activator extends AbstractJxseBundleActivator{
 
private static Activator activator;
 
static Activator getDefault() {
return activator;
}
 
public void start(BundleContext bundleContext) throws Exception {
activator = this;
}
 
public void stop(BundleContext bundleContext) throws Exception {
activator = null;
}
 
@Override
public IJxseServiceContext<NetworkManager> createContext(){
return new Edge_Anna();
}
}

As you can see, the Activator has become much simpler, as the superclass it derives from does most of the work. All that needs to be done is to tell the activator which IJxseServiceContextis required, and these rest is taken care of. The OsgiComponentextracts the context from the Activator and offers it as a declarative service.

If the changes compile without problems, you can launch the application, and if all went well, you should now see both JXSE bundles become visible in the navigator at the left-hand side of the GUI. Clicking these should show you the NetworkManager, NetworkConfiguratorand the NetPeerGroup, while their properties are displayed in the properties editor.

NOTE: Currently not all the functionality works flawlessly (as it is an incubator project), but you can set some properties without problems. I am however not sure how JXSE responds to dynamically changing them, so I recommend to use the PropertyViewer for viewing only.

Securing your JXSE Bundle

When deploying your bundle in a production environment, you have to consider that the declarative service opens up means for 'rogue bundles' to listen to the creation and deployment of your JXSE bundle. As this poses a security risk, it is advised to disable the declarative service before deployment in real-world settings. You can either remove the Service-Component entry in the manifest file in order to achieve this. In the next tutorial I will cover a different way of securing the declarative service.

Conclusion

This tutorial has demonstrated some improvements on the results of the previous posting, and has opened up a way to view the content of the JXSE Bundles. So far, the main focus has been to modify existing code in order to get it working in Eclipse / Equinox. The next post will concentrate on building a JXSE bundle from scratch, and mixed-method approaches.