Extending the NXRuntime package
===============================
                       
Author: Bogdan Stefanescu
Date: 2006/11/12


The OSGi package from NXRuntime (see NXRuntime: org.nuxeo.runtime.osgi) provides some abstract classes that helps you emulate an OSGi framework on host frameworks that are not OSGi compliant.

When using OSGI host frameworks like an Eclipse environment you don't need an OSGI adapter to correctly run your code. The OSGi environment is taking care of the bundle deployment.

Be aware that Nuxeo Runtime *is not* an OSGi framework. It is working on top of an OSGi framework.

As our first target for Nuxeo Runtime was JBoss which is not an OSGi compliant framework I wrote an OSGi adapter over JBoss microkernel. but this adapter is implementing only the OSGi features we currently need. And also the JBoss adapter is using the JBoss class loader logic that is not OSGi compliant.

But this is enough for us to be able to deploy a Nuxeo OSGi bundle on both JBoss or Eclipse. If you want to use OSGi functionalities not supported by the jboss adapter you need to contribute code that implement these functionalities.

Thus, not all the OSGi specs are emulated - only a small part. I will add more features as we will need them in future.

There is an abstract implementation of the OSGi adapter so you can reuse it when writing an adapter for a new host platform.

These generic classes are located in NXRuntime: org.nuxeo.runtime.osgi

Usually you may need to extend the abstract classes defined there. There are 2 examples you may follow:

- The JBoss adapter

- The test adapter - this one is used to be able to run JUnit tests that are dependent on NXRuntime features like components and extension points.

Here is a list with each class in the abstract OSGi adapter:

1. OSGiAdapter - is a simple OSGi framework manager - to be used on top of other frameworks.
It manages core OSGi functionalities like: bundles deployment, bundles life cycle, OSGi events - except class loading which is delegated to the underlying framework.
You may extend it.

2. AbstractBundle - the object describing a bundle. Must be implemented for each host platform.
Unimplemented methods are dealing especially with class loaders.

3. OSGiBundleContext - default implementation of the bundle context. It delegates almost everything to the AbstractBundle that creates the BundleContext
Not all methods are implemented.
Usually you don't need to extend this - if you need more features these should be integrated in this class.

4. BundleRegistry - handles bundle registration and life cycle.
It is not meant to be extended.

5. NullActivator - is a bundle activator that does nothing (used for bundles which don't define an activator).
It is not meant to be extended.

6. BundleIdGenerator - simple bundle ID store. It assigns an unique ID to each bundle and persists it between sessions.
It is not meant to be extended.

7. BundleRegistration - a bundle descriptors that is stored by the bundle registry for each bundle. Keeps info about dependencies state etc.
It is not meant to be extended.

8. OSGiComponentLoader - a bundle listener that scans the MANIFEST.MF entries and loads declared nxruntime components.
This listener is installed by the OSGiAdapter.
It is not meant to be extended.

9. OSGiRuntimeActivator - bundle activator to be used by NXRuntime or other implementations of the runtime (like NXJBossRuntime).
You may want to extend it.

10. OSGiRuntimeContext - a default RuntimeContext context implementation to be used in OSGi frameworks.
A runtime context is attached to a bundle and handles bundle registrations/unregistrations and bundle class loading.
You don't need to extend this. It delegates class loading to the attached OSGi bundle.

11. OSGiRuntimeService - this is the OSGi implementation of the runtime service. It starts and inits NXRuntime and provides access to main features to the runtime
This is the service you get on an OSGi platform when calling NXRuntime.getRuntime().
Usually, you don't need to extend it.

You can look in NXJBossRuntime to see how these classes are used and/or extended.

The idea is to use the default implementation provided by the core and plug them into the host framework (especially the host framework's class-loading mechanisms) by extending classes you want to adapt.

For example the NXJBossRuntime adapter defines these classes:

1. JBossBundle extends AbstractBundle => binds the bundle to the JBoss DeploymentInfo object. This way class loading is working correctly on jboss (even if it is not OSGi compatible).

2. JBossOSGiAdapter extends OSGiAdapter => adds methods to install bundles knowing the Jboss DeploymentInfo object.

3. JBossRuntimeActivator extends OSGiRuntimeActivator => customization of the runtime adapter used to perform specific jboss initialization.

4. BundleManifestReader - utility class to read bundle manifests.
