Using Nuxeo as a service platform

Nuxeo EP exposes services in several ways:

• Java services (both local and remote)

• Web services (SOAP and JAX-RS)

• Content Automation

This chapter will give you a brief overview of how and when to use these services.

Java Services

Nuxeo EP contains a built-in notion of service.

Services are Java interfaces exposed and implemented by a Component.

From within a Nuxeo Runtime aware context, you can access a service locally (in the same JVM) by simply looking up its interface:

Most Nuxeo Services are also exposed for remote RMI access via EJB3 remoting.

This means that, depending on the Nuxeo Runtime configuration, the service lookup can return a local object or a proxy to a remote interface.

A small number of services are not remotely exposed because they are designed for local or internal usage (high-level services using sub-services).

Using the Java remote Service API

From the code point of view, using the java remote API is the same as using the local one.

In fact, that the reason why you can split a Nuxeo application in several parts on several JVM without changing the code.

Since modules only depends on each others via Services interfaces, it's only a service binding configuration issue for doing the split.

Theoretically, Java Services could also be invoked directly via a JNDI lookup, but actually this is not a good idea:

• you will have to do JNDI lookups "by hand"

• objects returned by service may want to do a service lookup (that will fail if Runtim is not initialized)

For that purpose, we provide a small nuxeo-client that takes care of Nuxeo Runtime initialization and also allows to initialize the JAAS context that will be used for login and security propagation.

Using java remote API has some advantages:

• you can access directly to almost all services of the platform

• your code can run embeded inside Nuxeo or remotly

• remoting is completly transparent

Nevertheless, this last advantage may also become your worst enemy because it may lead you to a bad separation between the client and the server : remoting is transparent for the code, not for the performances.

An other point to take into consideration is transaction management. Because remote API is very fine grained you main want/need to do several calls within the same transaction and in this case you will need to correctly start a remote transaction.

For more informations about declaring and using java services see the associated section.

Web Services (JAX-WS and JAX-RS)

Nuxeo EP includes 2 Web Service stacks:

• one for SOAP Web service (JAX-WS) based on SUN-JAX-WS or JBossWS depending on the application server

• one for REST Web service (JAX-WS) based on Jersey

Unlike the Remote Java service binding, Nuxeo EP does not provide a one to one mapping via Web Services.

There are at least 2 reasons for that:

• serialization cost

• granularity of the API

About the first point, Nuxeo Java service API exposes some complexe objects, the first one of them being the DocumentModel:

• that can contain a lot of data

• that supports lazy loaading and streaming

This DocumentModel object is used as input or output of most services (and that makes sense for an ECM platform).
Completely serializing the DocumentModel object in XML is possible (we provide helper for that), but it's clearly not very efficient since it generate big XML objects.

For the second point, the java API is finely grained and a direct WebService mapping would imply 2 problems :

• too many network calls

• difficult transaction management

Given these limitations, we choose :

• to expose the main features via specific Web Service

• to provide a framework to easily expose dedicated WebService API

Our approach is to provide the needed tools so that you can easily expose the exacte API needed by your remote client.  

So depending of the needs of your application, the idea is to select the needed java services and create a java wrapper that provides a high level API and use Nuxeo framework to expose the wrapper via Web Service.

For more informations about declaring custom webservices on top of Nuxep EP, please see the JAX-WS and JAX-RS binding sections.

Content Automation

Writing a custom wrapper allows to expose a very optimized and very precise Web Service.

But on the other hand, it implies to write and deploy custom code.

In a lot of the cases, Content Automation provides an alternative to this approach with a very minimal performance overhead.

The idea is to define a simple and high level API on top of the java services : we call this Operations.

In order to avoid back and forth exchanges and costly serialization we want to chain the operations on the server side.

Using Content Automation, you can define you own Web Service API without writing code, you simply have to assemble the needed operations (via XML or via Nuxeo Studio).

Of course, if needed, you can also contribute your own custom java operations.

Operations and Operation chains are automatically exposed via a REST API using JSON marshaling.

For more information about Content Automation, please see the Content Automation chapter.

OpenSocial

Since 5.4.2, Nuxeo EP is an OAuth service provider.

This means you can consume Nuxeo Automation REST Services from any OpenSocial compliant application.

Please see the OpenSocial Page for more informations.