Skip to end of metadata
Go to start of metadata

Schema extension is one of the core features of CollectionSpace. It is anticipated that CollectionSpace application could be customized by extending base schema for a museum domain. The multi-tenant architecture explains why Nuxeo is selected to realize this requirement. The following sections describe the anatomy of a (Nuxeo 5.2 GA) document type representing a CollectionSpace entity called CollectionObject.

There are three aspects concerning a Nuxeo document type.

  1. Definition
  2. Packaging
  3. Deployment

Following sections describe each of these aspects with the help of an example document type for CollectionObject.

Definition

Core Type Definition

The core type definition describes constituent XML schemas of a document type. In the example of CollectionObject (in [Release 0.3]), the CollectionObject document type consists of the following 4 schemas. In Nuxeo's terms, these are called fragments of a document type. We will be using terms components, parts and fragments interchangeably in this document.

core-types-contrib.xml

As shown in the type definition above, the four parts are:

  1. collectionobjects_common (common entity schema for CollectionObject entity)
  2. collectionobjects_anthropology (test schema for anthropology museum)
  3. dublincore (not used by collectionspace, might be removed in future)
  4. common (just for manipulating documents using Nuxeo's web application during debug and testing, not used by the CollectionObjects service)

Location: OSGI-INF/core-types-contrib.xml

XML Schema(s)
collectionobjects_common.xsd
collectionobjects_common.xsd

Location: schemas/collectionobjects_common.xsd

collectionobjects_anthropology.xsd
collectionobjects_anthropology.xsd

Note The schemas do not use complex types. This is due to limitations of the Nuxeo Query Language (NXQL). Also, note that the example for anthropology domain schema is just an example used here to explain the concept, it does not reflect the real anthropology domain schema for the collection object.

Type definition for Nuxeo ECM

Corresponding to the core type definition, Nuxeo requires an ECM type definition to relate the new core type to one or more existing core types. The following ECM type definition for CollectionObject core type indicates that it has two parent core types: Folder and Workspace. That means a document for CollectionObject could be created under Folder or Workspace document types.

Location: OSGI-INF/ecm-types-contrib.xml

Layout (only for Nuxeo webapp)

Layout definition is only required to indicate to the Nuxeo web application, how to lay out the new core type definition. CollectionSpace service team uses the Nuxeo webapp for verification, debug and testing purposes only.

Note The example file shown above has been truncated for succinct description.

Location: OSGI-INF/layouts-contrib.xml

Packaging

A Nuxeo document type is packaged as an OSGI bundle. The following sections describe the directory structure, manifest and Maven build task.

Directory structure

The constituent parts of a document type as described above should be laid out in directories as shown below (under nuxeo-platform-cs-collectionobject).

OSGI manifest - MANIFEST.MF

As mentioned earlier, a Nuxeo document type is packaged and deployed as an OSGI bundle. The manifest for the document type describes the version, namespace, required bundles and components of the document type as shown below.

Maven build

Following maven build task describes how to package a document type.

Deployment

For CollectionSpace, the document type is deployed into Nuxeo repository backed by MySQL datastore. The following sections describe how a document type and its components (or fragments) are mapped into various MySQL tables.

RDBMS Mapping

Nuxeo creates a table for each sub-component (or fragment) of a document type. The following tables represent each fragment of the CollectionObject document type.

  1. collectionobjects_common
  2. collectionobjects_anthropology
  3. dublincore
  4. common

If there are schemas (such as common and dublincore in the example above) that are shared between various document types, all those document types share the same table schemas for these base types. The columns of a table representing each fragment are all the single-valued properties of the corresponding schema. Multi-valued properties are stored in a separate table.

Document type fragments

Following shows the table for the collectionobjects_common fragment.

All the fragments of a document type are related by using the same identifier (id). For example, select a fragment reflecting the common entity of the CollectionObject document type from the collectionobjects_common table as follows.

You could find the corresponding dublincore fragment using the same id, i.e. 000c022a-fffb-4aa8-95a9-e7bbae6b28a1 as that of the collectionobject fragment as follows from the dublincore table.

Question is: how Nuxeo traverses these various tables at runtime?

Searching for fragments - The hierarchy table

The hierarchy table represents the containment hierarchy between various nodes for a document in the Nuxeo repository. A document root could be considered one such node.

Now select a root document node for a CollectionObject document type as follows.

Note to explain the example better, we have deliberately shown the result above that relates to the collectionobject instance (id=000c022a-fffb-4aa8-95a9-e7bbae6b28a1) being discussed here.

When retrieving a document by its id, the primary type is consulted first in the hierarchy table. If a value is found, all applicable fragments are deduced (from perhaps the cached document type information in Nuxeo repository runtime?), to give full information about all the fragment tables (e.g. common and dublincore) that apply to the document.

A parent could be deduced by using the parent id and executing a similar query. The following shows that the parent of CollectionObject is a Workspace.

JBoss domain

Document type packages
Schema files

When a document type package is deployed in the Nuxeo domain, it creates necessary tables in the SQL storage of the repository as shown above and it also copies the constituent XML schema files on the root directory of the domain as shown below. The following information is provided here only for debugging purposes. It is not advisable to modify these files by hand.

Document access

There are two ways to manage and access documents in Nuxeo.

  1. Using DocumentModel APIs
  2. Search and query using NXQL

Using DocumentModel APIs

The Nuxeo document model is a serializable representation of a core document. It is made from several data models, each data model is bound to a schema.

Create
document model:create
Get
document model:get
Delete
document model:delete

Search and query using NXQL

References

  1. Nuxeo schemas and documents
  2. Nuxeo SQL Storage Specification

Recently Updated