Nuxeo Runtime

One of the main requirements of the “Nuxeo Core” component is to be deployable on both the JBoss and Eclipse platforms. To ease development and allow as much as code reuse, this requirement raised the need of a common component and packaging model that may be deployed and used on both of these platforms without any code change or repackaging.

To fulfill these needs, Nuxeo Runtime was developed as the foundation layer for all Nuxeo components. Nuxeo Runtime is not a standalone framework. It is, basically, a component model running on top of an existing platform and providing a common, platform-independent, model to power the applicative components of an application. It is our component architecture allowing flexible and true componentization of applications.

Besides its component model, Nuxeo Runtime also defines a common model for packaging. The adopted model is the OSGi bundle model. Actually, OSGi bundles are regular JARs containing an OSGi manifest file.

OSGi technology is more and more popular and is currently used by Eclipse, Geronimo and Jonas as their runtime framework.

This way, applications based on Nuxeo Runtime can run on different platforms without modifications by using an single component and packaging model - without having to care about platform specificity.

The main features provided by Nuxeo Runtime are:

Currently, Nuxeo Runtime adapters can provide the following OSGi features:

The following OSGi features are not supported (yet):

A definition from Wikipedia: “A software component is a system element offering a predefined service and able to communicate with other components”.

Components as defined by the Nuxeo model are logical units that may depend on and/or extend one another.

The Nuxeo Runtime is responsible for providing a common API to register, locate or extend components. Components are commonly registered using XML descriptor files.

Components can either be declared as subunits of an OSGi bundle or as independent components - as standalone XML files or programmatically registered components.

Components are commonly declared as part of an OSGi bundle through XML descriptors. To declare a component, you need to create an XML description file, put it somewhere in the bundle and specify the “Nuxeo-Component” header in the bundle manifest to load components at bundle activation.

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: HelloWorldExtension Plug-in
Bundle-SymbolicName: org.nuxeo.runtime.demo.HelloWorldExtension
Bundle-Version: 1.0.0
Bundle-Vendor: Nuxeo
Bundle-Localization: plugin
Require-Bundle: org.nuxeo.runtime.demo.HelloWorld
Nuxeo-Component: OSGI-INF/helloworld-extension.xml

The runtime implementation may adapt registered components to native components of the host platform. This can be done using the component life cycle notifications.

The JBoss runtime implementation is already doing this to adapt runtime components into JBoss MBean services.

This way, components may be seamlessly integrated into the host platform, thus leveraging the host platform functionalities (for example, MBean service management on JBoss)

You should not be afraid by the “component model” denomination. The runtime component model is not limiting in any way your objects nor imposing extra rules in the development. You don't need to modify your existing objects to derive or implement some runtime classes in order to plug them into the component registry. Objects implementing a component may be of any kind.

The only limitation is that component objects must have a public constructor without arguments (the default constructor) so that they can be instantiated via newInstance method on Class.

Anyway, if you want to benefit from the extension points mechanism or to respond to component life cycle events like activation or deactivation, then you should either implement the Component interface, or define some methods with a given signature in your object so that they will be called by using Java reflection. See below for more details on this.

In conclusion, the component model is not limiting your objects in any way, it only gives you the capability to register your components, extend and look them up in the same way on any platform supported by Nuxeo Runtime.

A component has 3 main life cycle states:

One of the most important feature of the component model is the extension mechanism that enable components to extend one another.

How does it work? Imagine you have a component A that manages an action menu for the application. It wants to let other components contribute actions in an easy and flexible way – for example by using XML files to describe these actions.

To be able to do this, component A should declare an extension point, let's say “actions”. This way other components willing to contribute some actions to the action menu managed by the component A can contribute these actions to the extension point “actions” exposed by the component A.

Obviously one component may declare any number of extension points and any number of extensions contributed to other components.

Components may declare extension points and extension contributions using a simple XML syntax like the following:

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.core.schema.TypeService">
  <implementation class="org.nuxeo.ecm.core.schema.TypeService"/>	
  <extension-point name="doctype">
    <object class="org.nuxeo.ecm.core.schema.DocumentTypeDescriptor"/>
  </extension-point>
  <extension-point name="schema">
    object class="org.nuxeo.ecm.core.schema.SchemaBindingDescriptor"/>
  </extension-point>	  
  <extension target="org.nuxeo.ecm.core.schema.TypeService" point="doctype">
    <doctype name="File" extends="Document">
      <schema name="common"/>
      <schema name="file"/>
    </doctype>
  </extension
</component>

You can see here a component declaring two extension points and contributing an extension to its own doctype extension point.

The content of an extension element is specific to the target extension point. The extension element content is known only by the extension point. How are handled extensions not conforming to the extension point schema is unpredictable – generally they will be ignored and some errors will be logged. There is, for now, no mechanism of validating XML extensions like in Eclipse.

But Nuxeo Runtime provides an easy way to map XML extensions to real Java objects through an XML mapping mechanism called XMap. You can see that each extension point in the example above is specifying an object tag. This means the content of the XML extension should be mapped through XMap to an object instance of this type. When no object tag is specified, extensions are returned as DOM elements and thus the component should perform itself the DOM parsing of extension contributions.

For details on the XML mapping, see the XMap documentation and/or the JavaDoc.

XXX TODO ADD GRAPHIC

Nuxeo Runtime provides a SAR package containing the Runtime and the JBoss OSGi adapter. This package is an OSGi bundle that acts as the OSGi system bundle.

Any package (directory, .sar, .jar, .ear, .war or any other JBoss-supported archive) will be treated as an OSGi bundle if it contains a valid OSGi manifest. In order for these bundles to be deployed, you need to have NXRuntime.sar already deployed in JBoss.

Besides the OSGi adapter and the auto-registration of components through bundle manifest, the JBoss adapter adds the capability to deploy runtime components as XML files located outside OSGi bundles through the JBoss deployment mechanism. This feature can be useful to register components that provide extensions to other components that can be described by plain XML without any code dependency.

Example of a plain XML component that contributes new document types:

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.core.CoreExtensions">
  <extension target="org.nuxeo.ecm.core.schema.TypeService" point="doctype">
    <doctype name="File" extends="Document">
      <schema name="common"/>
      <schema name="file"/>
    </doctype>
    <doctype name="Folder" extends="Document">
      <schema name="common"/>
      <facet name="Folderish"/>
    </doctype>
    <doctype name="Workspace" extends="Document">
      <schema name="common"/>
      <facet name="Folderish"/>
    </doctype>
    <doctype name="Domain" extends="Document">
      <schema name="common"/>
      <facet name="Folderish"/>
    </doctype>
  </extension>
</component>
      

The NXRuntime.sar library offers two JMX services:

For Eclipse, a NXRuntime.jar bundle is provided. Since Eclipse is OSGi-compliant, Nuxeo Runtime will not install any adapter (so it is not intervening on the bundle deployment).

When running on OSGi platforms, the main role of the runtime is to register components declared inside OSGi bundles (as seen previously through their manifest).

Because Eclipse is not starting automatically OSGi bundles (it starts them only on demand or on class loading), you need to update Eclipse's config.ini and configure it to start Nuxeo Runtime (i.e. org.nuxeo.runtime) when Eclipse starts:

osgi.bundles=org.eclipse.equinox.common@2:start, org.eclipse.update.configurator@3:start, org.eclipse.core.runtime@start,org.nuxeo.runtime@start

Components may be created either from XML descriptor files, or programatically.

In order to register components you always need a runtime context.

// load the component XML file given its location relative to the bundle root
URL url = context.getLocalResource(“OSGI-INF/MyComponent.xml”);
if (url != null) {
    context.deploy(url);
}

Manifest-Version: 1.0
Bundle-ManifestVersion: 2
Bundle-Name: HelloWorldExtension Plug-in
Bundle-SymbolicName: org.nuxeo.runtime.demo.HelloWorldExtension
Bundle-Version: 1.0.0
Bundle-Vendor: Nuxeo
Bundle-Localization: plugin
Require-Bundle: org.nuxeo.runtime.demo.HelloWorld
Nuxeo-Component: OSGI-INF/MyComponent.xml, OSGI-INF/MySecondComponent.xml

// retrieve the current bundle
Bundle bundle = ...
RegistrationInfoImpl ri = new RegistrationInfoImpl();
// create a context associated to the current bundle
ri.context = new OSGiRuntimeContext(bundle); 
ri.name = new ComponentName(“my.component”);
// set the class name of the component to register
ri.implementation= “org.nuxeo.runtime.example.MyComponent”;
// register the component
Framework.getRuntime().getComponentManager().register(ri);

In this section we will describe the most important elements composing an XML component descriptor.

You can inspect the XMap annotations on the class org.nuxeo.runtime.model.impl.RegistrationInfoImpl to find all elements that may compose an XML component descriptor.

A complete component descriptor may look like this:

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.core.schema.TypeService">
    <implementation class="org.nuxeo.ecm.core.schema.TypeService"/>

    <require>org.nuxeo.ecm.core.api.ServerService</require>
    <require>org.nuxeo.ecm.core.repository.RepositoryService</require>

    <property name="author">Bogdan Stefanescu</property>
    <property name="description">The component description ...</property>

    <extension-point name="doctype">
        <object class="org.nuxeo.ecm.core.schema.DocumentTypeDescriptor"/>
    </extension-point>
    <extension-point name="schema">
        <object class="org.nuxeo.ecm.core.schema.SchemaBindingDescriptor"/>
    </extension-point>

    <extension target="org.nuxeo.ecm.core.api.ServerService"
               point="clientFactory">
        <factory class="org.nuxeo.ecm.core.api.impl.LocalClientFactory"/>
    </extension>
    <extension target="org.nuxeo.ecm.core.schema.TypeService" point="schema">
        <schema name="common" src="schema/common.xsd"/>
        <schema name="core-types" src="schema/core-types.xsd"/>
        <schema name="file" src="schema/file.xsd"/>
    </extension>
</component>

Each component is defined inside its own file. As you can see the root element is component. This element has a required attribute name. Apart this, all other sub-elements are optional.

Here is a list with all supported sub-elements:

org.nuxeo.runtime.test.NXRuntimeTestCase is a base class to write JUnit tests for Nuxeo Runtime applications. It sets up the Nuxeo Runtime environment (in the setUp method) and provides methods to control bundle and resources loading. It is designed to behave in the same manner in Maven and Eclipse situations. Therefore resources must be accessed in a way that does not depend on the actual ordering of classpath.

public class TestBookTitleService extends NXRuntimeTestCase {

    private BookTitleService service;

    private static final String OSGI_BUNDLE_NAME = "org.nuxeo.project.sample";

    private static final String OSGI_TEST_BUNDLE = "org.nuxeo.project.sample.tests";

    public void setUp() throws Exception {
        super.setUp();
        // deployment of the whole nuxeo-project sample bundle
        deployBundle(OSGI_BUNDLE_NAME);

        service = Framework.getService(BookTitleService.class);
    }

    public void testServiceContribution() throws Exception {
        // Lookup is ensured simply by making the 'test' sub-hierarchy a
        // bundle of its own, with a MANIFEST file
        deployContrib(OSGI_TEST_BUNDLE, "sample-booktitle-test.xml");
        assertEquals("FOOBAR Test", service.correctTitle("foobar"));
    }

}

While working on an integration test, it is always worthwhile to prescribe clearly what is to be tested: either API calls to services provided by other modules, consistency with configuration provided by other modules, default configuration for the module being tested. This is especially important for the non-regression aspect of the testing and the cost of maintaining the tests.

The use-cases discussed below require basic knowledge of the Nuxeo ECM framework. Implicitely, it is somehow assumed that the tested code has to interact with one service. In case of multiple target services, one would have to choose a pattern for each of them.