Nuxeo Core
Documentation

Last Modi cation Project Code Document ID Copyright

0 9 /2 2 / 2 0 0 6 NXECM NXCORE- GUIDE Copyright Š 2006 Nuxeo. All Rights Reserved.

Versioning
Version 0.1 0.2 0.3 0.4 0.5 0.6 Date 2006- 10-10 2006- 10-13 2006- 10-15 2006- 10-19 2006- 10-20 2006- 10-20 Participant(s) ˇ Bogdan Stefanescu ˇ Florent Guillaume ˇ Julien Anguenot ˇ Bogdan Stefanescu ˇ Julien Anguenot ˇ Julien Anguenot Comments Created Updates Life cycle chapter JCA chapter Repository listeners, events Nuxeo core components chapter and misc updates Remove directory and relations references as this is not part of Nuxeo Core Fix some typos

0.7

2006- 10-20

ˇ Julien Anguenot

0.7.1

2006- 10-24

ˇ Stefane Fermigier

Table of Contents
1 Overview...........................................................................................................................................4 1.1 Main goals...................................................................................................................................4 1.2 Nuxeo core components...............................................................................................................4 2 Nuxeo Core Architecture ....................................................................................................................5 2.1 2.2 2.3 2.4 Model Layer (or Internal API).......................................................................................................5 Implementation Layer..................................................................................................................5 Facade Layer (or Public API)........................................................................................................6 Deployment.................................................................................................................................6 2.4.1 Local Access............................................................................................................................................................................................6 2.4.2 Remote Access.....................................................................................................................................................................................7 2.5 Client Session..............................................................................................................................7 3 The Repository Model.........................................................................................................................8 3.1 3.2 3.3 3.4 and Schemas...............................................................................................................8 Facets.........................................................................................................................9 Annotations.................................................................................................................9 Access Control...........................................................................................................10 3.4.1 Access Control Entry (ACE)........................................................................................................................................................10 3.4.2 Access Control List (ACL)............................................................................................................................................................11 3.4.3 Access Control Policy (ACP)......................................................................................................................................................11 3.4.4 Evaluating Privileges......................................................................................................................................................................12 Life Cycle..................................................................................................................................13 3.5.1 Example of document life cycle.............................................................................................................................................13 3.5.2 Life cycle de nition.........................................................................................................................................................................14 3.5.3 Life Cycle Manager..........................................................................................................................................................................14 3.5.4 Document types to life cycles mapping de nition...................................................................................................16 3.5.5 Core life cycle service.....................................................................................................................................................................16 3.5.6 The life cycle document API and the exposure at the facade layer................................................................16 3.5.7 Repository events and listeners..............................................................................................................................................19 Query Engine.............................................................................................................................19 The Public API...........................................................................................................................20 3.7.1 DocumentModel ............................................................................................................................................................................20 3.7.2 DataModel ...........................................................................................................................................................................................21 3.7.3 CoreSession..........................................................................................................................................................................................21 3.7.4 CoreInstance.......................................................................................................................................................................................22 Integration with Applications Servers..........................................................................................22 Session Factories.......................................................................................................................24 Repositories...............................................................................................................................24 Repository Listeners...................................................................................................................25 Schemas...................................................................................................................................26 Document Types........................................................................................................................26 Life Cycle Managers...................................................................................................................27 Life Cycle Types ........................................................................................................................27 Life Cycles.................................................................................................................................27 Document Document Document Document

3.5

3.6 3.7

3.8 4.1 4.2 4.3 4.4 4.5 4.6 4.7 4.8

4 Extension Points...............................................................................................................................24

NXECM I Nuxeo Core Documentation

1 Overview
Nuxeo Core is the foundation of the Nuxeo ECM project. It defines and provides all the basic services and functionalities needed to build a complete ECM product:
ˇ ˇ ˇ ˇ ˇ ˇ

a repository model, schema and document type management, a query service, a security model, a document life cycle service a flexible core event service

Like every Nuxeo ECM component, Nuxeo Core is running on top of Nuxeo Runtime which is defining an OSGi-compatible component model.

1.1 Main goals
The main goals of Nuxeo Core are:
ˇ ˇ

to provide the common services needed to build a state-of-the-art ECM product, to be accessible both remotely or locally (i.e: to provide a common API accessible both from a remote JVM or directly on the local one), to be deployable anywhere without any modification (through Nuxeo Runtime): in a Java EE application server like JBoss, or embedded in a desktop application like an RCP Eclipse application, to be extensible and flexible; this is inherited from Nuxeo Runtime which provides an extensible component model.

ˇ

ˇ

1.2 Nuxeo core components
Nuxeo core is composed by the following components:
ˇ ˇ ˇ ˇ

NXCore: core ECM model, services and default implementation NXCoreAPI: defines a client API for NXCore NXCoreFacade: Java EE facade NXJCRConnector: JCR storage backend that leverages jackrabbit this is the default NXCore storage backend

All these components are running on top of Nuxeo runtime (NXRuntime).

Draft I All Rights Reserved. I Page 4/27

NXECM I Nuxeo Core Documentation

2 Nuxeo Core Architecture
The Nuxeo Core top level components are all roughly following the same style of development, which is structured in three layers:
ˇ ˇ ˇ

model layer, implementation layer, facade layer.

There are also a number of services used by top level components to provide them with common functionalities like the schema service, query service, life cycle or security. These services are simple and cannot operate on their own they need a context to operate on. These services are exposed through top level components and may not follow the layering presented below.

2.1 Model Layer (or Internal API)
Top level components provide a model (an API) that is internal to the Core this means that they are not directly accessible from remote JVMs and should not be directly used by clients. The model provides a generic API that defines the concepts used by the service and that may have several implementations (using different storage backends for example). Usually this API cannot be accessed remotely since implementations may use local resources that cannot be sent over the network. For example, the Repository model defines objects like Document, Property, Session, etc. The JCR-based implementation for the Repository model is directly wrapping JCR (Jackrabbit) nodes that cannot be detached from the local JVM and sent over the network.

2.2 Implementation Layer
Each service may have one or more implementations for their model. For example, the Repository service may have several implementation for the model it defines this could be a JCR-based implementation, an SQL-based one, or something else. The same goes for the Directory service, it defines a model that could have an SQL-based implementation or an LDAP-based one. Implementations may use very specific resources and configuration, and are hidden by the common model defined by the service. This means that implementation-specific objects or APIs are never used directly by other Core components, they are only accessed by the implementation of the internal API.

Draft I All Rights Reserved. I Page 5/27

NXECM I Nuxeo Core Documentation

2.3 Facade Layer (or Public API)
On top of their model, components usually define a facade layer that enables external clients to remotely access service implementations. This layer is also named the Public API because it defines the API exposed to clients. Any client, local or remote, must use the public API of the component, and must not make calls to the internal API. The main requirement of the public API is to use only serializable objects that can be sent over the network and reconstructed on the client machine.

2.4 Deployment
The architecture presented above makes it possible to access the Core services when the Core is running inside the same JVM as the client application (e.g., when embedded in a desktop application) but also when it is on a remote JVM (e.g., deployed as a module inside an application server). In both cases the Core services are accessed in the same way through the public API.

2.4.1 Local Access

Draft I All Rights Reserved. I Page 6/27

NXECM I Nuxeo Core Documentation

2.4.2 Remote Access

2.5 Client Session
Usually a client opens a session on a Core service through the facade and can then send requests to the Core service until it closes the session. While a client is connected to a Core service, the latter should track the client session and restore its state (if any) at each client request. When the session is closed by the client, the Core service releases any resource held by that session. Any data passed between the client and the Core service is serializable and so it can safely be sent over the network. In this way a client can operate identically when running on the same JVM or when running on a remote one.

Draft I All Rights Reserved. I Page 7/27

NXECM I Nuxeo Core Documentation

3 The Repository Model
The repository model is the main functionality provided by the Core; it represents the very raison d'ętre of the Core. Most of the other Core services were written as auxiliary components to perform specific needs of the repository model or to enrich it. The repository model, as its name suggest, is describing a software component for managing repositories of documents. Repositories store documents in a tree-like structure that enables grouping documents inside folders in an hierarchic manner. Besides the storage, the repository provides functionalities like:
ˇ ˇ ˇ ˇ ˇ

document versioning, security management, document life cycle, annotations, SQL-like query.

3.1 Document and Schemas
Documents are structured objects described by a set of properties. These properties may be used to store document meta-data (e.g., creation date, author, state, etc.) or the document data itself (e.g., binary or text files, attachments, etc.). The properties that a document may have and their types and constraints are defined through several schemas. The repository model natively supports XML Schemas to define document schemas. A Schema is therefore the way the structure and contents of a document is defined. Through schemas you can usually specify things like:
ˇ ˇ ˇ ˇ ˇ

what properties are allowed, the type of each property, the default value of the property, if any, the restrictions on the property values, if any, whether a property is mandatory or not.

In order to create and use documents you first need to define their structure. For this you have to define a document type. Then you can create instances of documents of that type.

Draft I All Rights Reserved. I Page 8/27

NXECM I Nuxeo Core Documentation

In some ways document types and schemas are similar to Java classes and interfaces. A document type may implement some schemas in the same way that Java classes implement interfaces, and a document type can extend another document type in the same way that a Java class can extend another class. Document Types defines one or more schemas that the document structure must satisfy and some other extra properties like facets which will be discussed later. In conclusion, the unit of work in a repository is the document. To create a new document you must specify the document type and a path. You can either use existing document types or register new types as we will see in the Extension Points section. For more information on document types and schemas see the section.

3.2 Document Facets
A Facet is a behavioral property of a document. As schemas define the document structure and content, facets are used to describe behaviors or capabilities of a document. For now facets are simple strings attached to a document type to specify a capability for documents of that type. In the future facets may evolve to more complex structures, for example to dynamically provide interfaces to manipulate documents according to a capability they offer. Currently the Core defines two facets:
ˇ

Folderish : adds folder capability to a document, so that it can have zero or more children documents, Versionable : adds versioning capabilities to a document.

ˇ

3.3 Document Annotations
As we've seen, a document structure and content is strictly defined by the schemas its type implements. But there are many situations where some application-specific data need to be dynamically attached to the document and retrieved later without having to modify the document schemas. This is very useful for repository extensions that needs to store placeful (i.e., location sensitive) information on a document information that cannot be specified by any document schema since its type is not necessarily known in advance.

Draft I All Rights Reserved. I Page 9/27

NXECM I Nuxeo Core Documentation

Annotations are not required to be stored through the same data storage as the document itself. For example one may choose to store document in a Jackrabbit-based repository and to store annotations in a dedicated SQL database. These annotations usually keep some internal state or data about the document. For example, a tool that may use annotations is the workflow service.

3.4 Document Access Control
Usually, manipulating documents requires a set of privileges to be granted to the current user. Privileges given to a user over a document are very dependent on the current context and on the document itself. Usually privileges depend on:
ˇ ˇ ˇ ˇ

the document location (i.e., privileges are placeful), the access rules defined on document parents in the hierarchy, the document state, and generally on any rule that was defined over a particular location on the document parents.

Privileges are a standard example of extra information that needs to be stored on the document in a placeful manner, so it may be a perfect candidate for the annotation service. But since privileges are very dynamic and may require expensive computations on every document that is accessed, a separate Security Service exists to manage the storage as it sees fit - and not necessarily through annotations on the document. This is more efficient from a performance point of view. In the following subsections we will see what type of information is stored on the document to enforce security and how security checks are done. To ease comprehension of security concepts and evaluation we will begin the presentation from the smallest unit of security information to the largest one that is stored at the document level.

3.4.1 Access Control Entry (ACE)
This is the smallest unit specifying a security rule. It is a very simple object containing three fields:
ˇ

principal: an authenticated entity. For example the user that opened the session on the repository is a principal but a principal may also be a group of users. permission : the kind of action that may be granted or denied for a principal. This may also be a group of permissions. This corresponds to the Java concept of privilege. granting : specifies whether the given permission is granted or denied to the given principal.

ˇ

ˇ

Draft I All Rights Reserved. I Page 10/27

NXECM I Nuxeo Core Documentation

Examples:
ˇ

DENY, John, Read: an access entry that specifies that the reading is denied for the principal John. GRANT, Developers, Drink: an access entry that specifies that drinking is granted for any principal from the developer group.

ˇ

3.4.2 Access Control List (ACL)
An ACL is an ordered list of ACEs. This means it represents a set of access rules. Why ordered? Because usually when evaluating access rules the order is important. This is because evaluation stops on the first DENY or GRANT rule that match the criteria check. Here is a simple example showing how ordering may influence the security checks. Suppose that we have a principal John that belongs to the Readers group, and an ACL that contains the following two ACEs:
1. 2.

DENY, John, Read GRANY, Readers, Read

Suppose we want to check whether principal John is granted reading. Every entry in the ACL is checked (in the order they were defined) and if an entry matches the security check the evaluation stops. Using the example above, John will be denied reading even if it is a member of the Readers group. But if you swap the order of ACEs in the ACL, John will be granted reading.

3.4.3 Access Control Policy (ACP)
An ACP is an ordered list of ACLs. Each ACL stored in the ACP is uniquely identified by a name. The ordering is important when security is checked ACLs at the beginning of the list will be checked first. The ACP is the object containing the security information that is attached to a document. Note that ACLs are inherited so that a document will inherit any defined ACLs from its parents in the hierarchy. Inherited ACLs are evaluated after evaluating the local ACLs and from the nearest parent to the remotely related parent. You may wonder why an ACP is containing several ACLs? And what about ACL names? In a typical situation where security information may only be changed by an administrator through a user interface, a single ACL is enough. But a complex application may have complex rules to set privileges according to the current document state or context. This is the case for a workflow engine which may decide to revoke or grant privileges depending on the document state or the context.

Draft I All Rights Reserved. I Page 11/27

NXECM I Nuxeo Core Documentation

This means that access rules are changed not only by administrators but also by services like the workflow. To avoid collisions, every tool that needs to change access rules may use its own (named) ACL for setting these rules. If the workflow service considers that its rules are more important than the ones explicitly set by the administrator, it simply places its ACL before the one reserved for the administrator so that it will be evaluated first. Currently there are two predefined ACLs:
ˇ

local : the local ACL The local ACL is the only ACL an administrator may explicitly change through the User Interface.

ˇ inherited: the inherited ACL

This ACL is computed each time a security check is performed (unless caching is used). The inherited ACL is the ACL obtained by merging all existing ACLs on the document's hierarchy. This ACL is appended to the ACL list, so it will be evaluated last. So from a simple security unit like the ACE we end up with a sophisticated structure like inheritable ACPs. These use cases are not artificial, they are real use cases that a mature ECM product should satisfy.

3.4.4 Evaluating Privileges
The evaluation mechanism has been described above. Here is an example of how an evaluation is done. Let's say the the principal John is trying to edit the document D. Editing a document requires the Write permission. Suppose the document D has the path /A/B/C/D it is a child of the document C which is a child of the document B which is the child of the document A. To decide if the principal John can edit this document the following steps are taken:
1.

The merged ACP for the document D is computed. This ACP is the local ACP set on the document D merged with all parent ACPs. ACLs imported from the parents are appended to the local ACLs so that they will be evaluated at last. Each ACL is evaluated in respect to the order defined by the ACP. Each ACE is evaluated in respect to the order defined by the ACL. If an ACE match a security rule regarding the principal John (or a group which it belongs) and the permission Write (or a permission group from which Write belongs) then the evaluation ends and the access right of the matching ACE is returned If no matching ACE is found then the privilege is denied.

2. 3. 4.

5.

Draft I All Rights Reserved. I Page 12/27

NXECM I Nuxeo Core Documentation

3.5 Life Cycle
Within organizations, documents are often regulated. At a given time, a document has a state or is within a phase. The way the document transitions in compliance with regulations from one state to another (or from one phase to another) is in most of the cases defined and managed by business processes or workflows. Nuxeo Core itself doesn't embed a workflow engine, or still a BPM engine, as such. It only provides a generic way to define document life cycles, the way the document properties related the life cycle are stored and a way to specify which document types follow which life cycles at deployment time. Thus, the workflow engine that will be deployed along with Nuxeo Core will leverage the API exposed by Nuxeo Core to set the life cycle properties. The APIs defined in Nuxeo Core regarding life cycle are highly inspired from the JCR283 specifications that are still in a draft state at the time of writing this document. Another advantage of such a design is the fact that the life cycle state of a document will be independent of the application (i.e.: workflow variables) and will be embedded within the document itself at storage time, and thus will be exported along with the document properties. Nuxeo 5 provides a BPM engine that knows how to leverages the Nuxeo Core life cycle API. See http://www.nuxeo.org

3.5.1 Example of document life cycle
Here is a typical life cycle example.

Author review reject Publish Archive Obsolete
Draft I All Rights Reserved. I Page 13/27

NXECM I Nuxeo Core Documentation

3.5.2 Life cycle de nition
Nuxeo Core allows one to define life cycle using extension points. (See the Nuxeo Runtime documentation for more information about extension points.). You will find at the end of this document the complete list of extension points defined by the core, you will find an example of life cycle definition there using the life cycle definition extension point. The life cycle model defined by Nuxeo core is simple stateful, or state-transition engine. Including the following elements :
ˇ ˇ ˇ

Life cycle definition Life cycle state definition Life cycle state transition definition

Again, here, no policy regarding transitions are specified. The workflow or BPM engine will deal with this. Here are the reasons :
ˇ

It gives more flexibility regarding the policy that needs to be applied on the documents by letting dedicated BPM engines deal with that. Thus this is possible to choose which workflow engine to use for your application. (see NXWorkflow) Current JCR specifications doesn't include a default policy model regarding life cycle so it appears logical to not include this ourself at this layer of the architecture It simplifies the model

ˇ

ˇ

This is important to note that the life cycle definition is fully independent from the document types themselves which allows the reuse if life cycle for different document types.

3.5.3 Life Cycle Manager
The life cycle manager is responsible of the storage of the life cycle related properties. One could think of storing the life cycle property within the JCR, which is the default implementation provided by NXJCRConnector, or still one could think about storing it in a separated RDBMS apart from the content storage. Because of this, Nuxeo 5 provides an abstraction for this storage allowing one to define a life cycle manager per life cycle definition. Let's take a look at the life cycle manager exposed by Nuxeo Core :
/** * Life cycle manager * * * Responsible of the lifecycle property storage abstraction. * *

Draft I All Rights Reserved. I Page 14/27

NXECM I Nuxeo Core Documentation

* @see org.nuxeo.ecm.jcr.JCRLifeCycleManager * * @author <a href="mailto:ja@nuxeo.com">Julien Anguenot</a> * */ public interface LifeCycleManager {

/** * Returns the name of the manager * * @return the name of the manager as a string. */ public String getName();

/** * Sets the name of the life cycle manager * * @param name of the life cycle manager */ public void setName(String name);

/** * * * @param doc : a document instance * @return string holding the life cycle state of the */ public String getState(Document doc) throws LifeCycleException; Returns the state of a given document.

/** * Set the state of the given document * * @param doc a document instance * @param stateName the name of state as a string * @throws LifeCycleException */ public void setState(Document doc, String stateName) throws LifeCycleException;

Draft I All Rights Reserved. I Page 15/27

NXECM I Nuxeo Core Documentation

You can see that the interface is fairly simple. It basically, only specifies how to store and retrieve the state of a given document. For an example of JCR storage see the JCRLifeCycleManager definition : http://fisheye.nuxeo.org/browse/~raw,r=4233/nuxeo/ECMPlatform/NXJCRConnecto r/trunk/src/org/nuxeo/ecm/core/jcr/JCRLifeCycleManager.java Note this is how the JCR-283 current specifications specifies the life cycle storage repository side. You can register your own life cycle managers using the lifecyclemanager extension point defined on the Nuxeo Core side. See the extension points chapter of this document for an example.

3.5.4 Document types to life cycles mapping de nition
When your life cycle definitions are defined and you did specify the life cycle managers which will take care of the storage you will then need to specify associations in between document types and life cycle. To achieve this, Nuxeo core defines an extension point allowing one to specify, independently from the document type definition, such an associations. Please, check the example at the end if this document.

3.5.5 Core life cycle service
Nuxeo core defines a dedicated life cycle service that is used by the Nuxeo core internals. This service is not exposed at the facade layer because we don't need it there. This service is manipulating directly the repository document themselves. (not references and thus is not suitable for remoting purpose) Actually, the document model itself has been extended so that you can directly invoke this service through the document session itself at facade layer. See next chapter for an overview of the API. This service is defined under this namespace org.nuxeo.ecm.core.lifecycle.LifeCycleS er v i c e.

3.5.6 The life cycle document API and the exposure at the facade layer
The document model exposes a life cycle related API. You can take advantage of this API from the document itself if you are working at core level. Here is the api :
/** * Return the life cycle of the document *

Draft I All Rights Reserved. I Page 16/27

NXECM I Nuxeo Core Documentation

* @see org.nuxeo.ecm.core.lifecycle * * @return the life cycle as a string * @throws LifeCycleException */ public String getLifeCycle() throws LifeCycleException;

/** * Follow a given life cycle transition * * This will update the current life cycle of the document * * @param transition the name of the transtion to follow * @return a boolean representing the status if the operation * @throws LifeCycleException */ public boolean followTransition(String transition) throws LifeCycleException;

/** * Return the allowed state transitions for this document * * @return a collection of state transitions as string */ public Collection<String> getAllowedStateTransitions() throws LifeCycleException;

Here is an example of use at core level :
Document doc = root.addChild("docD", "File"); assertEquals("work", doc.getLifeCycle()); doc.followTransition("review"); assertEquals("review", doc.getLifeCycle()); doc.followTransition("reject"); assertEquals("rejected", doc.getLifeCycle()); doc.followTransition("backToWork"); assertEquals("work", doc.getLifeCycle());

Draft I All Rights Reserved. I Page 17/27

NXECM I Nuxeo Core Documentation

This API is wrapped at the facade layer so that you can use remotely through the core session. Here is the API :
/** * Return the life cycle of the document * * @see org.nuxeo.ecm.core.lifecycle * * @param docRef the document reference * @return the life cycle as a string * @throws LifeCycleException */ public String getLifeCycle(DocumentRef docRef) throws ClientException;

/** * Follow a given life cycle transition * * This will update the current life cycle of the document * * @parem docRef the document reference * @param transition the name of the transtion to follow * @return a boolean representing the status if the operation * @throws LifeCycleException */ public boolean followTransition(DocumentRef docRef, String transition) throws ClientException;

/** * Return the allowed state transitions for this document * * @param docRef the document reference * @return a collection of state transitions as string */ public Collection<String> getAllowedStateTransitions(DocumentRef docRef) throws ClientException;

Here is an example using the API :

Draft I All Rights Reserved. I Page 18/27

NXECM I Nuxeo Core Documentation

DocumentModel root = _getRootDocument(); DocumentModel childFile = new DocumentModelImpl(root.getPathAsString(), "file#" + _generateUnique(), "File"); childFile = _createChildDocument(root.getRef(), childFile);

assertEquals("work", remote.getLifeCycle(childFile.getRef())); assertTrue(remote.followTransition(childFile.getRef(), "review")); assertEquals("review", remote.getLifeCycle(childFile.getRef())); Collection<String> allowedStateTransitions = remote.getAllowedStateTransitions(childFile.getRef()); assertEquals(2, allowedStateTransitions.size()); assertTrue(allowedStateTransitions.contains("reject")); assertTrue(allowedStateTransitions.contains("validate"));

3.5.7 Repository events and listeners
Nuxeo core defines a service dedicated to repository events. This service is only responsible of those specific events and allows third party code to register listeners that will get notified when events occur (and that can take specific actions themselves) .This service doesn't take advantage of event service such as JMS or still the NXRuntime event service at this level because it needs ti be really fast at event processing to not decrease the repository performances. By using event listener extensions, you can hook up and bridge on another synchronous or asynchronous messaging systems. Let's take some examples.
ˇ

Nuxeo core defines a bridge to Nuxeo runtime forwarding events on the NXRuntime event service in an asynchronous way. It defines like that a local event loop shared by all components running on top of NXRuntime. The NXEvents component, not part of the Nuxeo core, registers a JMS listener bridging Nuxeo core events to a dedicated JMS topic. It allows message driven beans at the Nuxeo Enterprise Platform to get the Nuxeo core events. (for instance NXAudit)

ˇ

You could define whatever listeners you need to forward the Nuxeo core events on an external messaging system. See the end of this document for an example of such a registration.

3.6 Query Engine
The query engine is designed to provide an SQL-like language, called NXQL, to perform document and directory queries. NXQL offers standard SQL functionality to search records, but can also take advantage of the hierarchical nature of the content repository to provide path-based searches. NXQL is used as the uniform query syntax to access several kinds of repositories.
Draft I All Rights Reserved. I Page 19/27

NXECM I Nuxeo Core Documentation

The query engine itself must process and optimize the query, and dispatch it to the different backends and tables that are referenced in the query. Updates or creation statements are not covered and must be performed through the repository API. For more information about the query engine, refer to the document about NXQL.

3.7 The Public API
As we've seen the internal repository model is not remotely accessible. Because the Nuxeo Core deployment model requires supporting both local and remote clients, the APIs are separated between an internal API and a Public API, designed to fulfill the deployment needs. Any client should use the Public API to connect to a Nuxeo Repository. This Public API has only one limitation: any object transferred between the client and the core must be serializable. This way it can be sent over the network and restored on the client side. So the Public API is in fact is a serializable view of the repository model. This has a performance drawback compared to the internal API since it should transform any model object like a Document into a serializable form, but has the benefit of being totally independent from the JVM where the Core runs. The main objects composing the Public API are the:
ˇ

DocumentModel : the serializable view of a Document.

ˇ DataModel : the serializable view of a document subpart described by a schema.
ˇ ˇ

CoreSession: a session to the Core repository. CoreInstance : the gateway to the Core. It uses session factories to create new sessions (connections) to the Core.

3.7.1 DocumentModel
The document model is a data object that completely describes a document. You can see it as a serializable view of document. Apart being a data object this object also provides some logic. For example a document model is able to lazy load data from the storage if not already loaded or it may check permissions for a given user on the document it represent. The data contained by document model is grouped in DataModel objects. For each document schema there is a DataModel that contains concrete data as specified by the corresponding schema. You can see a DataModel as a data object described by a schema (i.e. a schema instance). A document contains also data that is not defined by shcemas like its internal ID, its name its parent etc. Thus, apart these data models there is some information stored as members on the document model like the document ID, the document name, a ref-

Draft I All Rights Reserved. I Page 20/27

NXECM I Nuxeo Core Documentation

erence to the document parent, the ACP information (used for security checks), the session ID etc. Also the data model contains the list of facets that the document type defines. One of the most important ability of the document model is to lazy load data the first time the data is required from the client. This feature is important because the document may contain a lot of schemas and fields and it will be a performance problem to load all this data from the storage each time a document model is created. Usually the client application is using only few DataModel fields like the Tile, Description, CreationDate etc. These are the fields commonly displayed by a tree like explorer of the repository. When the client is displaying or editing the document properties then the document model will load missing data models. To achieve this there are schemas or fields that are declared to be lazy loaded. When creating a document model from a document only the non-lazy schemas and fields are fetched from the storage. For example a blob field will be always lazy.

3.7.2 DataModel
As detailed above the data model is an object containing the concrete data for a document schema. Each data model is described by the schema name and the map of fields. The data model contains no logic. It is a pure data object. Apart the fields map the data model contains information about dirty fields (field that was modified by the client) so that when saving changes to the repository only modified fields are saved.

3.7.3 CoreSession
The core session is a session on the Nuxeo Core. The session is opened and closed by a client and gives the client the possibility to interact with the Core. The Core a session connects can be located in a separate JVM or in the current one. To create remote or local sessions you need to use a specific CoreSessionFactory object. These objects are usually specified using extension points but you can also use them programatically. After creating a session, you can begin to retrieve and modify documents through the API exposed by the CoreSession object. Example of creating and using a session:
CoreInstance core = CoreInstance.getInstance(); CoreSession session = core.open("jcr://demo/default", null); DocumentModel root = client.getRootDocument();

Draft I All Rights Reserved. I Page 21/27

NXECM I Nuxeo Core Documentation

DocumentModel dm = new DocumentModelImpl(root.getPathAsString(), "folder", "Folder"); session.createDocument(root.getRef(), dm); dm = new DocumentModelImpl(root.getPathAsString(), "file", "File"); session.createDocument(root.getRef(), dm); List<DocumentModel> children = session.getChildren(root.getRef()); ... core.close(client);

3.7.4 CoreInstance
This is the gateway to a Core instance. As mentioned above the Core may be located in a remote JVM. The CoreInstance is using CoreSessionFactory objects (declared through extension points) to connect to a Core instance and to create a session.

3.8 Integration with Applications Servers
The repository is plugged into an application server using the a resource adapter as specified by the J2EE Connector Architecture (JCA). The resource adapter is write over the repository model so it is not dependent on the repository implementation (like for example JackRabbit). Currently the resource adapter was tested only on JBoss AS The resource adapter enables the repository to take part on transactions managed by the application server.

Draft I All Rights Reserved. I Page 22/27

NXECM I Nuxeo Core Documentation

4 Extension Points
This section aims to cover all existing extension points defined by core components and to give some examples of creating new extensions.

4.1 Session Factories
Declaring component: org.nuxeo.ecm.core.api.CoreService Extension point name: sessionFactory This extension points is for registering new session factories. Session factories are used to create new Core Sessions. Currently two session factories are provided:
1.

a local session factory that create sessions to a local Core (that is running in the same JVM as the client) a remote session factory that create sessions to a remote Core (running in a JBoss Application Server)

2.

Example:
<extension target="org.nuxeo.ecm.core.api.CoreService" point="sessionFactory"> <factory class="org.nuxeo.ecm.core.api.local.LocalSessionFactory"/>

</extension>

4.2 Repositories
Declaring component: org.nuxeo.ecm.core.repository.RepositoryService Extension point name: repository This extension point is to declare new repositories. Example:
<extension target="org.nuxeo.ecm.core.repository.RepositoryService" point="repository"> <repository name="demo" factory="org.nuxeo.ecm.core.jcr.JCRRepositoryFactory" securityManager="org.nuxeo.ecm.core.jcr.JCRSecurityManager">  <Repository> <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem"> <param name="path" value="${rep.home}/repository"/> </FileSystem> <Security appName="Jackrabbit"> <AccessManager class="org.apache.jackrabbit.core.security.SimpleAccessManager">

Draft I All Rights Reserved. I Page 23/27

NXECM I Nuxeo Core Documentation

</AccessManager> <LoginModule class="org.apache.jackrabbit.core.security.SimpleLoginModule"> <param name="anonymousId" value="anonymous"/> </LoginModule> </Security> <Workspaces rootPath="${rep.home}/workspaces" defaultWorkspace="default"/> <Workspace name="${wsp.name}"> <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem"> <param name="path" value="${wsp.home}"/> </FileSystem> <PersistenceManager class="org.apache.jackrabbit.core.state.obj.ObjectPersistenceManager"> </PersistenceManager> <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex"> <param name="path" value="${wsp.home}/index"/> </SearchIndex> </Workspace> <Versioning rootPath="${rep.home}/version"> <FileSystem class="org.apache.jackrabbit.core.fs.local.LocalFileSystem"> <param name="path" value="${rep.home}/version" /> </FileSystem> <PersistenceManager class="org.apache.jackrabbit.core.state.obj.ObjectPersistenceManager"> </PersistenceManager> </Versioning> <SearchIndex class="org.apache.jackrabbit.core.query.lucene.SearchIndex"> <param name="path" value="${rep.home}/repository/index"/> </SearchIndex> </Repository> </repository> </extension>

4.3 Repository Listeners
Declaring component: org.nuxeo.ecm.core.repository.RepositoryListenerService

Extension point name: listener This extension points is for registering new repository listeners.

Example :
Draft I All Rights Reserved. I Page 24/27

NXECM I Nuxeo Core Documentation

<extension target="org.nuxeo.ecm.core.repository.RepositoryListenerService" point="listener"> <listener name="jmslistener" class="org.nuxeo.ecm.platform.ec.events.listener.JMSEventListener"/> </extension>

4.4 Schemas
Declaring component: org.nuxeo.ecm.core.schema.TypeService Extension point name: schema This extension point is to declare XSD schemas and bind them to a unique name so that they can be used to create document types. Example:
<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"/> <schema name="dublincore" src="schema/dublincore.xsd"/> </extension>

4.5 Document Types
Declaring component: org.nuxeo.ecm.core.schema.TypeService Extension point name: doctype This extension point is used to define document types. Example:
<extension target="org.nuxeo.ecm.core.schema.TypeService" point="doctype"> <doctype name="File" extends="Document"> <schema name="common"/> <schema name="file"/> <schema name="dublincore"/> </doctype> <doctype name="Folder" extends="Document"> <schema name="common"/> <facet name="Folderish"/> </doctype>

Draft I All Rights Reserved. I Page 25/27

NXECM I Nuxeo Core Documentation

</extension>

4.6 Life Cycle Managers
Declaring component: org.nuxeo.ecm.core.lifecycle.LifeCycleService Extension point name: lifecyclemanager This extension points is for registering new life cycle managers. A life cycle manager is responsible for managing and storing document life cycle information. Example:
<extension target="org.nuxeo.ecm.core.lifecycle.LifeCycleService" point="lifecyclemanager"> <lifecyclemanager name="jcrlifecyclemanager" class="org.nuxeo.ecm.core.jcr.JCRLifeCycleManager"/> </extension>

4.7 Life Cycle Types
Declaring component: org.nuxeo.ecm.core.lifecycle.LifeCycleService Extension point name: types This extension points is used to bind life cycle definitions to document types. Example:
<extension target="org.nuxeo.ecm.core.lifecycle.LifeCycleService" point="types"> <types> <type name="File">default</type> <type name="Folder">default</type> <type name="Workspace">default</type> <type name="Domain">default</type> <type name="Section">default</type> </types> </extension>

4.8 Life Cycles
Declaring component: org.nuxeo.ecm.core.lifecycle.LifeCycleService Extension point name: lifecycle This extension point is used to define life cycles. Example:
<extension target="org.nuxeo.ecm.core.lifecycle.LifeCycleService"

Draft I All Rights Reserved. I Page 26/27

NXECM I Nuxeo Core Documentation

point="lifecycle"> <lifecycle name="default" lifecyclemanager="jcrlifecyclemanager" initial="work"> <transitions> <transition name="review" destinationState="review"> <description>To review</description> </transition> <transition name="reject" destinationState="rejected"> <description>Reject</description> </transition> ... </transitions> <states> <state name="work"> <transitions> <transition>review</transition> </transitions> </state> <state name="review"> <transitions> <transition>validate</transition> <transition>reject</transition> </transitions> </state> ... </states> </lifecycle>

</extension>

Draft I All Rights Reserved. I Page 27/27