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 code reuse as possible, Nuxeo developed a common component and packaging model that may be deployed and used on both of these platforms without any code change or repackaging. This model, the Nuxeo Runtime, was developed as the foundation for all Nuxeo components. The Nuxeo Runtime is not a standalone framework. It is, in short, a component model running on top of an existing platform that provides a common, platform-independent, model to underlie the components of an application. This architecture allows flexible and true componentization of applications.

In addition to the component model, the Nuxeo Runtime also defines a common model for packaging, the OSGi bundle model. At the lowest level, OSGi bundles are simply regular JARs containing an OSGi manifest file. OSGi technology is becoming more and more popular and is currently used by Eclipse, Geronimo, Glassfish, and Jonas as their runtime framework. Because of the component and packaging choices, applications based on Nuxeo Runtime can run on different platforms without modification and without having to care about the particulars of a deployment platform.

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 and most commonly components are registered using XML descriptor files.

Components can be declared as independent, top-level components - by using a standalone XML file in the bundle- or they can be declared at a finer granularity by programmatically registering sub-components within the bundle. To declare an top-level component, you need to create an XML description file, put it somewhere in the bundle, typically in the OSGI-INF directory, and specify the “Nuxeo-Component” header in the bundle manifest to load the component at bundle activation. For example, the manifest shown below has a reference to the XML file "helloworld-extension.xml" that declares a component.

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 components of the host platform. (This can often be accomplished using the Nuxeo component life cycle notifications.) The JBoss adapter for the Nuxeo Runtime, for example, is already doing this to adapt runtime components into JBoss "MBean services", and thus Nuxeo "components" are seamlessly integrated into the host platform. Since these components are understood by the host platform, we can leverage existing host platform functionaly, such as MBean service management on JBoss.

You should not be afraid by the “component model” denomination. The runtime component model does not limit your objects, nor imposing any extra rules on your development practices. You do not need to modify your existing objects to derive from some Nuxeo-supplied base class, nor implement some runtime interfaces in order to plug your objects into the component registry. Your objects that implement a "component" may be of any kind.

The only requirement is that to be a "component", your object must have a public constructor without arguments (the default constructor) so that it can be instantiated via newInstance method on the your object's Class object. The component model makes this a mild restriction, since it supplies other means for object initialization if you need to do complex actions at the time your object is created.

If you want to benefit from the extension points mechanism or to respond to component life cycle events like activation or deactivation, there are two options. You can either implement the Component interface if this is convenient for you, or define some methods with a particular signature so your object will be called by the runtime using Java reflection. See below for more details on this.

In conclusion, the component model offers substantial benefits with few requirements; the model primarily provides you the capability to register your components, extend others components, allow others to extend your componentns, and look up components. These functions work the same way on any platform supported by Nuxeo Runtime.

A component has three primary life cycle states:

A key innovation of the Nuxeo Runtime component model is the extension mechanism that enables components to extend one another.

We will begin with a demonstration of how this mechanism works: Imagine you have a component A, implemented in Java with class ImplA, that manages an action menu for the application. A wants to let other components contribute actions to the menu 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 name this point “actions”. Other components willing to contribute some actions to this "group effort" of a menu should use "actions" to indicate their contribution. (A component may declare any number of extension points and may contribute to any number of extensions to other components' extension points but we are using only point for this example.)

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

<?xml version="1.0"?>
<component name="A">
  <!-- A 'exposes' an extension point 'actions' that should be supplied with other components' MenuItem objects -->
  <implementation class="ImplA"/>	
  <extension-point name="actions">
    <object class="MenuItem"/>
  </extension-point>
  <!--A is 'contributing' a fragment of XML describing a 'doctype' to the extension point 'documentTypes' of B -->
  <extension target="B" point="documentTypes">
    <doctype name="File" extends="Document">
      <schema name="common"/>
      <schema name="file"/>
    </doctype>
  </extension
</component>

The content of an extension element is specific to the target extension point, such as the "doctype" in the example above. The extension element content is known only by the extension point. If a contribution to an extension point is made an the xml snippet is not correct from the standpoint of the component exposing the extension point, the result is unpredictable - generally, bad contributions will be ignored and some error will be logged. There is, for now, no mechanism of validating XML extensions like in Eclipse.

The Nuxeo Runtime provides an easy way to map XML extensions to real Java objects through an XML mapping mechanism called XMap. In the example above, the "doctype" can be thought of an object with a field called schema that contains a list of strings. Nuxeo supplies the XMap library to allow the XML fragment to automatically be transformed into a Java object with the fields correctly filled in. When not using XMap, extensions are returned as DOM elements and thus the component should itself perform the parsing of extension contributions.

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

XXX TODO ADD GRAPHIC

JBOSS permits its extensions to be packaged as SAR files, thus the Nuxeo Runtime provides a SAR package containing the Nuxeo Runtime and the JBoss OSGi adapter. This package is an OSGi bundle that acts as the OSGi system bundle. With the Nuxeo SAR in place inside JBoss, any packaging file format understood by JBoss (.sar, .jar, .ear, .war) or even a raw directory, will be treated as an OSGi bundle if it is found by JBoss and 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.