apache > ws.apache
Apache Muse
 

Apache Muse - Project Artifacts for OSGi

Overview

When Muse applications are deployed on top of OSGi, they must fit into the OSGi bundle model. The Muse framework includes an OSGi service that will manage all of the resources that you define in muse.xml. When the OSGi instance is started, it will load the Muse service, which will in turn read the muse.xml descriptor and initialize your resources.

Application Activator

The OSGi version of the sample project requires an Bundle Activator, which is generated by the tooling:

Application Activator - OSGi Bundle
package org.apache.muse.test.producer;

import org.apache.muse.core.platform.osgi.util.BundleRootHelper;
import org.osgi.framework.BundleActivator;
import org.osgi.framework.BundleContext;
import org.osgi.framework.Bundle;
import org.eclipse.core.runtime.FileLocator;

import java.io.File;
import java.util.Hashtable;
import java.util.Properties;

public class Activator implements BundleActivator {

     public void start(BundleContext context) throws Exception {
         String prop = System.getProperty("data.location");
         String dir = System.getProperty("user.dir");
         File root = null;
         if(prop == null){
             Bundle bundles[] = context.getBundles();
             for(int i=0;i<bundles.length;i++){
                 if("org.eclipse.equinox.common".equals(bundles[i].getSymbolicName())){
                     if(Bundle.ACTIVE != bundles[i].getState()){
                         //Allow the exception to propogate - we're no good without the location
                         bundles[i].start();
                     }
                     break;
                 }
             }
             root = new File(FileLocator.resolve(context.getBundle().getEntry("/")).getFile());
         } else if("USE_BUNDLE_DATA".equals(prop)){
             root = context.getDataFile(".");
         } else {
             root = new File(prop);
         }
         BundleRootHelper.registerRoot(context.getBundle(), root);
     }

     public void stop(BundleContext context) throws Exception {
     }

}
There are two things to note in the activator:

First, the data.location System property is used to allow the user to specify a particular location in the file system for storing logs and resource persistence information. The value will be interpreted as a File path, and used accordingly. If the value is "USE_BUNDLE_DATA", then the Bundle data location (as described in the OSGi specification) is used. If no value is provide for this property, the default is the root of the Bundle's install location. This location is determined using the FileLocator class, which is provided by the org.eclipse.equinox.common Bundle. The FileLocator is specific to Equinox, and is not part of other OSGi implementations.

Second, if no value is specified for the data.location property, the Bundle will attempt to ensure that the org.eclipse.equinox.common Bundle is active. This requirment is due to an implemntation detail within the FileLocator class, but the end result is that the org.eclipse.equinox.common must be active in order for your Bundle to execute. If an alternative mechanism is used to set your Bundle's root location, then the dependency on org.eclipse.equinox.common may be removed from the activator and the Manifest.

Users wishing to specify unique locations per Bundle, or to mix the location handling implementation between Bundles should change the Activator accordingly.

Application Layout

The OSGi version of the sample project is an OSGi Bundle with the following directory structure:

Application Layout - OSGi Bundle
/wsn-producer
    /META-INF
        /manifest.mf
    /OSGI-INF
        /muse.xml
    /router-entries
        /WsResource
            /resource-instance-1.xml
    /wsdl
        /WsResource.wsdl
        /WsResource.rmd
    /wsn-producer.jar

The nature of these files and directories is as follows:

  • /META-INF/manifest.mf - This is OSGi manifest for your bundle. Documentation of the OSGi manifest headers can be found at the OSGi Alliance website. However, the following merit special mention:

    • Require-Bundle - This header specifies the additional Bundles required in the OSGi runtime to allow your Bundle to run. These bundles are described below:
      • muse.osgi.core - the OSGi-specific bits of the Muse runtime.

      • muse.osgi.soa.axis2 - the Muse axis2 isolation layer

      • muse.osgi.soa.core - a generic SOA service definition layer that will allow bindings to other SOAP engines.

      • muse.core - the Muse runtime, packaged for OSGi.

      • muse.util.all - various Muse utilities, packaged for OSGi.

      • muse.wsa.soap - the Muse implementation of WS-Adressing, along with its spec-related artifacts.

      • muse.wsrf.api - the Muse interfaces for implementing WSRF, along with its spec-related artifacts.

      • muse.wsrf.impl - the default implementations of the WSRF capabilities.

      • muse.wsn.api - the Muse interfaces for implementing WSN, along with its spec-related artifacts.

      • muse.wsn.impl - the default implementations of the WSN capabilities.

      • org.eclipse.corona.soa.provider.Axis2 - a Bundle hosting an Axis2 instance, and implementing the service definition specified by muse.osgi.soa.core.

      • org.eclipse.equinox.http - A Bundle implementing the OSGi HTTP service, which is consumed by the.

      • org.eclipse.equinox.servlet.api - A Bundle exporting the javax.servlet and javax.servlet.http packages.

      • org.eclipse.osgi.services - the OSGi service interfaces, including the HTTP service interface definition.

      • org.eclipse.osgi.util - some OSGi utility services.

      • org.eclipse.osgi - the Eclipse Equinox implementation of OSGi.

      • org.eclipse.equinox.common - some Eclipse-specific extensions (including the FileLocator used in the Bundle Activator) to the OSGi runtime.

    • MUSE-CONFIG - This header specifies the location of the muse.xml file relative to the Bundle class path. The tooling ensures that the Bundle's root location is on the classpath; by convention the muse.xml is placed in the OSGI-INF directory, which appears under the Bundle root.

    • MUSE-CONTEXT - this header specifies the deployment context name for the Bundle's resources. This deployment context, along with the resource context from the muse.xml file, will appear resource address as http://host:port/deployment_context/services/resource_context.

  • /OSGI-INF/muse/muse.xml - This is the Muse deployment descriptor. It is read by Muse at initialization in order to load, configure, and support the resource types that you have implemented.

  • /OSGI-INF/wsdl - This directory holds the WSDL and related schema files for the resource type implemented in the sample. The WsResource.wsdl file is the WSDL for the sample resource type. The WsResource.rmd file contains MetaData descriptor for the resource described by WsResource.wsdl. For the OSGi deployment, the additional schema and WSDL files are superfluous and can be removed - they are supplied to the Muse runtime by their respective Bundles as described in the Require-Bundle section of the manifest.

Towards the end of the tutorial, you will learn how to build, deploy, and test this application with the help of Eclipse Equinox.


< Back      Next >