General Overview

When we started building Nuxeo EP, we defined several goals to achieve. Because these goals have a structural impact on Nuxeo EP platform it is important to understand them: it helps understanding the logic behind the platform.

All the design goals explained just before have a huge impact on the Nuxeo EP architecture. Before going into more details, here are the main concepts of Nuxeo EP architecture.

Building the Nuxeo Runtime was one of the first tasks we started. This is one of the main infrastructure components of the Nuxeo EP architecture.

This section will give you a quick overview of the Nuxeo Runtime. A more detailed technical presentation can be found in Section 28.1, “Overview” of this book.

Nuxeo Runtime provides the component model for the platform.

This component model is heavily based on OSGi and provides the following features:

Nuxeo Runtime also provides deployment services to manage how components are deployed and contribute to each other

Here is a simple example of a deployment-fragment.

<fragment>
  <extension target="application#MODULE">
    <module> <ejb>${bundle.fileName}</ejb> </module>
  </extension>
  <extension target="faces-config#VALIDATOR">
    <validator>
      <validator-id>dueDateValidator</validator-id>
      <validator-class>org.nuxeo.ecm.platform.workflow.web.ui.jsf.DueDateValidator</validator-class>
    </validator>
  </extension>
  <install>
    <!-- unzip the war template -->
    <unzip from="${bundle.fileName}" to="/">
      <include>nuxeo.war/**</include>
    </unzip>
    <!-- create a temp dir -->
    <!-- be sure no directory with that name exists -->
    <delete path="nxworkflow-client.tmp" />
    <mkdir path="nxworkflow-client.tmp" />
    <unzip from="${bundle.fileName}" to="nxworkflow-client.tmp">
      <include>OSGI-INF/l10n/**</include>
    </unzip>
    <append from="nxworkflow-client.tmp/OSGI-INF/l10n/messages.properties"
               to="nuxeo.war/WEB-INF/classes/messages.properties" addNewLine="true" />
    <append from="nxworkflow-client.tmp/OSGI-INF/l10n/messages_en.properties"
               to="nuxeo.war/WEB-INF/classes/messages_en.properties" addNewLine="true" />
    <append from="nxworkflow-client.tmp/OSGI-INF/l10n/messages_fr.properties"
               to="nuxeo.war/WEB-INF/classes/messages_fr.properties" addNewLine="true" />
    <append from="nxworkflow-client.tmp/OSGI-INF/l10n/messages_de.properties"
               to="nuxeo.war/WEB-INF/classes/messages_de.properties" addNewLine="true" />
    <append from="nxworkflow-client.tmp/OSGI-INF/l10n/messages_it.properties"
               to="nuxeo.war/WEB-INF/classes/messages_it.properties" addNewLine="true" />
    <delete path="nxworkflow-client.tmp" />
  </install>
</fragment> 

Nuxeo EP components are separated in 3 main layers: Core / Service / UI

From the logical point of view each layer is a group of components that provide the same nature of service:

The layer organization can also be seen as a deployment strategy

Thanks to the Nuxeo Runtime remoting features it is very easy to split the components on several JVMs. But splitting some services can have a very bad effect on the global system performance.

Because of this, all the storage oriented services are inside the core. All components that have extensive usage of the repository and need multiple synchronous interaction with it are located in the core. This is especially true for all synchronous event handlers.

The services layer can itself be split in multiple deployment units on multiple JVMs.

On the UI side all the services are logically deployed inside the same JVM. At least each JVM must have the minimum set of services to handle user interaction for the given application.

The components are also grouped by layers according to their dependencies.

Core Modules can depend on Core Internal API.

Generic ECM services can depend on Core external API and can depend on external optional library (like jBPM, Jena, OpenOffice.org ...).

UI services can rely on a client side API (like Servlet API) and share a common state associated to the user session.

Layers are also organized according to deployment target.

The Core layer is a POJO Layer with an optional EJB facade. The core can be embedded in a client application.

The services are mostly implemented as POJO services so that they can be used as an embedded library. But some of them can depend on typical Application Server infrastructure (like JMS or EJB).

Inside the UI Layer most services are dedicated to a target platform: web (JSF/Seam), Eclipse RCP or other.

Because the layer organization has several constraints, the implementation of a unique feature is spread across several layers.

Typically a lot of these "transverse services" are split into several sub-components in each layer in order to comply with deployment constraints and also to provide better reusability. For example, the Audit service is made of 3 main parts which are split across 3 layers:

The layer organization can also be seen in the API.

Nuxeo core provides all the storage services for managing documents.

The repository enforces data integrity and consistency based on Document types definition.

Each document type is defined by:

Here is a simple DocumentType declaration:

<extension target="org.nuxeo.ecm.core.schema.TypeService"
    point="doctype">
    <documentation>The core document types</documentation>
    <doctype name="Folder" extends="Document">
      <schema name="common" />
      <schema name="dublincore" />
      <facet name="Folderish" />
    </doctype>
    </extension>

For further explanation on Schemas and Document types, please see Chapter 5, Schemas and Documents.

Inside the Nuxeo repository each document may be associated with a life-cycle. The life-cycle defines the states a document may have and the possible transitions between these states. Here we are not talking about workflow or process, rather we are just defining the possible states of a document inside the system.

The Nuxeo Core contains a LifeCycleManager service that exposes several extension points:

Life-Cycle service is detailed later in this document (Section 29.4.5, “Life Cycle” and Section 29.5.2, “LifeCycle Managers”).

Note: You may also want to read the chapter on "Access Control and Security" in the Learning Nuxeo EP5 Guide.

Inside the Nuxeo Repository security is always checked when accessing a document.

The Nuxeo security model includes :

Inside the repository each single document can have an ACP. By default security descriptors are inherited from their parent, but inheritance can be blocked when needed.

The security engine also lets you contribute custom policy services so that security management can include business rules.

The security model and policy service are described in detail later in this document.

When an event occurs inside the repository (document creation, document modification, etc...), an event is sent to the event service that dispatches the notification to its listeners. Listeners can perform any number of actions when receiving an event, which may include modifying the document on the fly.

As an example, part of the dublincore management logic is implemented as a CoreEvent listener: whenever a document is created or modified, the "creation date", "modification date", "author" and "contributors" fields are automatically updated by a CoreEvent Listener.

The Core Events system is explained in more detail later in this document (see Chapter 31, Nuxeo Event Service and Chapter 9, Event Listeners and Scheduling) and in the Learning Nuxeo EP5 guide.

The Repository supports a Query API to extract Documents using SQL like queries.

NXQL (the associated Query Language) is presented later in this document (see Example 11.2, “Sample NXQL queries”).

The documents in the repository can be versioned.

Nuxeo Core provides:

The versioning system is explained in details later in this document (see Chapter 16, Document Versioning).

Nuxeo Core exposes a repository API on top of Jackrabbit JSR170 repository.

Nuxeo repository is implemented using an SPI and extension point model: this basically means that a non JCR based repository plugin can be contributed. In fact, we have already started a native SQL repository implementation (that is not yet finished because we have no direct requirement for such a repository).

Nuxeo core can server several repository: it provides a extension point to declare an additional repository: this means a single web application can use several document repositories.

Inside Nuxeo EP and especially inside the Core API the main data object is a Document.

Inside Nuxeo Core API, the object artifact used to represent a Document is called a DocumentModel.

The DocumentModel artifact encapsulates several useful features:

A DocumentModel can be located inside the repository using a DocumentRef. DocumentRef can be an IdRef (UUID in the case of the JCR Repository Implementation) or PathRef (absolute path).

DocumentModels also hold information about the Type of the Document and a set of flags to define some useful characteristics of the Document:

A Proxy is a DocumentModel that points to a another one: very much like a symbolic link between 2 files.

Proxies are used when the same document must be accessible from several locations (paths) in the repository. This is typically the case when doing publishing: the same document can be visible in several sections (note: 'section' here has a special meaning as defined in the Nuxeo User Guide). In order to avoid duplicating the data, we use proxies that point to same document.

A proxy can point to a checked out document (not yet associated to a version label) or to a versioned version (typical use-case of publishing).

The proxy does not store document data: all data access are forwarded to the source document. But the Proxy does holds:

TO DO

The service layer is an ECM services stack on top of the Nuxeo Repository. In a sense, the Repository itself is very much like any service of this layer, it just plays a central role.

This service layer is used for :

This service layer provides the API used by client applications (Webapp or RCP based applications) to do their work.

This means that in this layer, services don't care about UI, navigation or pageflows: they simply explore an API to achieve document oriented tasks.

Nuxeo platform provides a lot of different services, but they all fellow the same implementation pattern. This basically means that once you understand how works one service, you almost know how they all work.

As with everything in the Nuxeo Platform the services use the Nuxeo Runtime component model.

A generic service will be composed of the following packages :

Typically, the POJO module will be a Nuxeo Runtime Component that inherits from DefaultComponent, provides extension points and implements a Service Interface.

public class RelationService extends DefaultComponent 
      implements RelationManager { ...}

The deployment descriptor associated with the component will register the component, declare it as service provider and it may also declare extension points

<?xml version="1.0"?>
<component name="org.nuxeo.ecm.platform.relations.services.RelationService">
  <implementation class="org.nuxeo.ecm.platform.relations.services.RelationService" />
  <service>
    <provide interface="org.nuxeo.ecm.platform.relations.api.RelationManager" />
  </service>
  <!-- declare here extension points -->
</component>      

The facade will declare an EJB that implements the same service interface. In simple cases, the implementation simply delegates calls to the POJO component.

The facade package will also contain a contribution to the Runtime Service management to declare the service implementation.

<?xml version="1.0" encoding="UTF-8"?>
<component name="org.nuxeo.ecm.platform.relation.service.binding.contrib">
  <extension target="org.nuxeo.runtime.api.ServiceManagement" point="services">
      <documentation> Define the Relation bean as a platform service. </documentation>
      <service class="org.nuxeo.ecm.platform.relations.api.RelationManager" group="platform/relations">
        <locator>%RelationManagerBean</locator>
      </service>
    </extension>
</component>

Thanks to this declaration the POJO and the EJB Facade can now be used for providing the same interface based on a configuration of the framework and not on the client code.

This configuration is used when deploying Nuxeo components on several servers: platform configuration provides a way to define service groups and to bind them together on physical servers.

Each service provides its own API composed of a main interface and of the other interfaces and types that can be accessed.

The API package is unique for a given service, and access to a remote EJB3 based service is the same as accessing the POJO service.

From the client point of view, accessing a service is very simple and independent from service location and implementation: this means a manual JNDI call is not required. Everything that is needed is encapsulated in the Framework.getService runtime API.

RelationManager rm = Framework.getService(RelationManager.class);

The framework.getService will return the interface of the required service:

The choice of the implementation to return is left to the Nuxeo Runtime that will take the decision based on the platform configuration.

The client can explicitly ask for the POJO service via the Framework.getLocalService() API: this is typically used in the EJB Facade to delegate calls to the POJO implementation.

DocumentModel adapters are a way to adapt the DocumentModel interface (that is purely data oriented) to a more business logic oriented interface.

In the pure Service logic, adding a comment to a document would look like this:

CommentManager cm = Framework.getService(CommentManager.class);
cm.createComment(doc,"my comment");
List<DocumentModel> comments = cm.getComments(doc);

DocumentModel adapters give the possibility to have a more object oriented API:

CommentableDoc cDoc = doc.getAdapter(CommentableDoc);
cDoc.addComment("my comment");
List<DocumentModel> comments = cDoc.getComments();

The difference may seem small, but DocumentModel adapter can be very handy

DocumenModelAdapters are declared using an extension point that defines the interface provided by the adapter and the factory class. DocumentModelAdapters can be associated to a Facet of the DocumentModel.

TO DO