Wicket Osgi Extension

User Guide

Wicket Osgi Extension: User Guide

Table of Contents
1. Introduction ................................................................................................................... 2. Quickstart ...................................................................................................................... Configuring Wicket Application .................................................................................... Defining extension points ............................................................................................ Building plugins ......................................................................................................... Defining plugins ................................................................................................. Creating plugable pages ....................................................................................... Creating Plugable Extensions ................................................................................ 1 2 2 3 4 4 4 5

iii

List of Figures
1.1. Big Picture .................................................................................................................. 1

iv

Chapter 1. Introduction
Wicket Osgi Extension is a library that gives developer the capability to create plugin enabled wicket applications. Classic OSGI philosophy (everything is a bundle) propagated by the OSGI Alliance doesn't fit the JavaEE world and architecture of existing application servers. Thereby the idea behind this library is to reuse existing JavaEE infrastructure by starting an osgi container (e.g. Apache Felix) embedded in the classic wicket web application. This will give developers the possibility to extend existing wicket applications with plugins (osgi bundles) that contain additional pages or components and get seamlessly integrated into the existing frontend.

Figure 1.1. Big Picture

Chapter 2. Quickstart
Configuring Wicket Application
Download the latest version of the wicket-osgi-extension and add it as a library to your project. Also add other required libraries such as Apache Wicket and Apache Felix. For maven users: To get the wicket-osgi-extension artifact add the following repository and dependency declarations to your POM-File

<repositories> <repository> <id>googlecode</id> <url>http://wicket-osgi-extension.googlecode.com/svn/m2-repo/releases/</url> </repository> </repositories> <dependency> <groupId>net.javaforge.wicket.osgi</groupId> <artifactId>wicket-osgi-extension</artifactId> <version>WICKET-OSGI-EXTENSION-VERSION</version> </dependency>>

Create the main wicket application class by extending the OsgiWebApplication class (instead of the usual WebApplication).

public class MyApplication extends OsgiWebApplication { ... }

If necessary overwrite the doInit() method provided by the OsgiWebApplication by adding custom osgi container configuration parameter. Notice that Wicket's default initialization method init() is declared final in the OsgiWebApplication and its functionality is provided by the new doInit() . The following example demonstrates how to configure the embedded osgi container and how to set appropriate properties.

public class MyApplication extends OsgiWebApplication { @Override protected void doInit() {

Quickstart

// specifies the osgi bundles directory getOsgiSettings().setOsgiBundlesDirectory("plugins"); // export the host application packages to the bundles getOsgiSettings().setExportedPackages("com.mycompany.web"); // specifies bundles always started on application startup getOsgiSettings().setAutostartBundles( "org.apache.felix.fileinstall-1.0.0.jar", "org.apache.felix.shell-1.2.0.jar", "org.apache.felix.shell.tui-1.2.0.jar"); } ... }

One of the most interesting lines in the example above is the "osgi bundles directory" property. It specifies the filesystem directory where the osgi container should search for the bundles. Default value for it is System.getProperty("java.io.tmpdir") + "/bundles" . Put the fileinstall bundle (see http://felix.apache.org/site/apache-felix-file-install.html ) created by the Apache Felix project into the applications bundles directory. Also put other additional bundles (e.g. shell console ) which you want to be autostarted at the startup of the embedded osgi container. IO: wohin Make sure to register them by adding them to the setAutoStartBundles(...) method. This is all that has to be done to complete the configuration. Your are now able to define the extension points and the plugin development.

Defining extension points

By using the following markup in your page-template, the target to be replaced by the rendered componenttrees of registered plugins will be defined. In case, that no plugin is registered for the provided id, no markup will be generated by this tag. Defining an extension point is pretty simple. Use an extension-point wicket tag introduced by the wicket-osgi-extension like in the example below and you are done.

..... <wicket:extension-point id="com.mycompany.extension.foo" /> .....

For creating extensions that can contribute to the extension point definition see the section called Creating Plugable Extensions .

Quickstart

Building plugins
Defining plugins
Plugins are osgi bundles that follow some conventions introduced by the wicket-osgi-extension . One of the most important convention concerns the bundle's activator. It should extend the OsgiWicketActivator class and implement the abstract doStart(BundleContext ctx) and doStop(BundleContext ctx) methods.

public class MyActivator extends OsgiWicketActivator { @Override protected void doStart(BundleContext context) throws Exception { ... // implement bundle's start logic here } @Override protected void doStop(BundleContext context) throws Exception { ... // implement bundle's stop logic here } }

Don't forget to specify your plugin's activator in the bundle's MANIFEST.MF like this:

.... Bundle-Activator: com.mycompany.foo.MyActivator ....

Creating plugable pages

First create a page as you would do it for a "classic" wicket application: by defining the page class and the corresponding html-template. Next register the page with the osgi container. This is done by using one of the mountXXX(..) methods provided by the OsgiWicketActivator. The following example demonstrates how to mount a bookmarkable page Foo.class under the name foo .

@Override protected void doStart(BundleContext ctx) throws Exception { mountBookmarkablePage(ctx, "foo", FooPage.class); }

Quickstart

To unmount the page (typically while stopping the bundle) use the activator's unmount(..) method.

@Override protected void doStop(BundleContext ctx) throws Exception { unmount(ctx, "foo"); }

Creating Plugable Extensions

Creating plugable extensions is a two-step process: Definition of an extension point within some wicket components html markup. This serves as a placeholder which will be dynamically replaced at runtime by the extensions provided by the plugins. Definition of the extension and the assignment to one or more extension points.

Defining an Extension Point

The HTML markup snippet shown below demonstrates how to define the extension point with the unique identifier: com.mycompany.extensionpoints.EXTEND_ME.

<wicket:extension-point id="com.mycompany.extensionpoints.EXTEND_ME" />

Defining an Extension
Next, we will define an extension containing a simple label and commitingIO: ??? to the extension point com.mycompany.extensionpoints.E1. The first step is to write an extension class and create the corresponding HTML markup for it.

public class SimpleExtension extends Extension { public SimpleExtension(String id) { super(id); add(new Label("inner-label", "Hello world!!")); } }

<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"

Quickstart

"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" xmlns:wicket="http://wicket.apache.org" > <wicket:panel> <span wicket:id="inner-label"/> </wicket:panel> </html>

The final step is to register the extension in your plugins activator by associating it with the id of the extension point.

@Override protected void doStart(BundleContext context) throws Exception { ..... registerExtension(context, "com.mycompany.extensionpoints.EXTEND_ME", SimpleExtension.class); }