To start the nuxeo server from the command line (assuming it is installed in ~/nuxeo):

$ cd ~/nuxeo

$ bin/run.sh

Note: you can shutdown the server from the command line by entering ^C (control-C) or by running the script "~/nuxeo/bin/shutdown.sh -S" from another shell session.

You can also set up an instance of the nuxeo server to run within Eclipse. You do this by pointing your eclipse server to the installation of the nuxeo server on your filesystem. Defining a server configuration for the Nuxeo runtime within eclipse enables you to start and stop Nuxeo directly from within eclipse.

This can be achieved by launching the new server wizard from the servers tab (make sure you are in the J2EE view in Eclipse): Right click inside the server pane, and select New>Server. You should select a Jboss v4.0 server type, click 'Next' and provide the Nuxeo EP home directory as server home (eg. ~/nuxeo) on the next screen. Select the defaults for the remainder and then click 'Finish'.

Now double click your server so you can see the server configuration we just created. We need to change the default timeout value on the server startup, because it is likely that starting the nuxeo server will exceed the default value. You should configure a starting timeout value suitable for your computer.

Expand the 'Timeouts' section and change the default to 300 seconds for example. Don't forget to save your changes.

You may also want to click the 'open launch configuration' link in the server settings view. On the arguments tab you can change the amount of memory available to the VM to avoid PermGen out of memory errors:

	  -XX:MaxPermSize=512M
	  

Now right click on the server and select 'Start' to start the server from within eclipse.

You can look at your server logs to look for any errors which may occur on server startup in the following directory:

~/nuxeo/server/default/log/server.log

For example: One common error is when an instance of the server has failed to stop correctly and you try to start the server again, you will get an error like:

Port 8083 already in use

In this case you will have to kill the java process from the command line before re-starting the server:

[nuxeo ~/nuxeo] ps aux | grep java
nuxeo     9919  2.4 10.5 777428 297292 ?       Sl   15:44   3:37 /usr/lib/jvm/java-6-sun-1.6.0.16/bin/java -Dprogram.name=run.bat -Djava.endorsed.dirs=/home/nuxeo/nuxeo/bin/../lib/endorsed -Xms128m -Xmx512m -Dfile.encoding=UTF-8 -classpath /home/nuxeo/nuxeo/bin/run.jar org.jboss.Main -c default
[nuxeo ~/nuxeo]	kill -9 9919
	  

Now that your server is running, open up your web browser and go to the url:

http://localhost:8080/nuxeo/

Log in nuxeo with Administrator/Administrator.

In order to see what results our new jar plugin for the 'Book' document type has produced, we first need to create a Workspace (Note: A Nuxeo workspace is different from an Eclipse workspace. To understand more about the basic Nuxeo EP user concepts, see the Nuxeo User Guide). Once you have logged in, click on 'Workspaces' and select 'Create New Workspace'. Give it a title and click 'Create'.

Now click on the workspace you have created, and select 'New Document'. The list of available document types should now contain 'Book' as one of its types. Select 'Book', and Enter a title, description and ISBN, and upload a file if you want. Click 'create'.

Congratulations, you have successfully created a new Book type ! You should now see this in your Nuxeo workspace.

So away we go. To start with, we would like to declare a new Document type which represents a book (a book you can buy in a bookshop, a library book etc), that you can select and manage via our 'New Document' button on our UI:

When you click the 'New Document' button you should see our new 'Book' document type:

This new document type wasn't there before (ie. it doesn't appear in the default out-of-the-box Nuxeo installation). Our sample project created it. We can split the task of creating our new 'Book' type into 2 parts:

In this section we will describe how to declare it and define the schema for it. In the next, we will show how to display it on the UI. A good reference document for this section, is chapter 5 of the Nuxeo Book: Schemas and Documents.

Declaring the book type and creating its schema, requires only configuration changes (ie. no Java code). The changes we will need to make are:

We want our 'Book' to be composed of four fields isbn, rating, publicationDate and literals. This is the schema which defines our 'Book' type. We will declare this schema in a file called src/main/resources/books.xsd. Here is a snippet from it:

...
	  <xs:element name="isbn" type="xs:string"/>
	  <xs:element name="rating" type="xs:int"/>
	  <xs:element name="publicationDate" type="xs:date"/>
	  <xs:element name="keywords" type="bk:stringArray"/>
	  ...

We should note however, that a Document in Nuxeo is generally a composite of many schemas. If you look at the full source of the 'doctype' extension point contribution in the core-types-contrib.xml file of the next section, you'll see that the book.xsd schema we defined above, is simply one of many schemas that contribute to making up our new 'Book' document type. But we don't need to define fields like 'Title' or 'Author' in our schema, because these fields are considered standard fields that have been already well defined in already existing schemas that are available to us like the dublincore schema.

Next we will create a file called src/main/resources/OSGI-INF/core-types-contrib.xml which will declare our new 'Book' type and then link it to the schema which we have just created for it. But more importantly, this core-types-contrib.xml file provides an 'extension point contribution' to the Nuxeo org.nuxeo.ecm.core.schema.TypeService. This core Nuxeo class (TypeService) exposes a number of extension points which is like the Nuxeo class saying "You can add new customized functionality at this point, by providing this Nuxeo class with the information it needs to add this functionality in for you". For example the TypeService class exposes the following extension points, for which we can provide contributions:

	 org.nuxeo.ecm.core.schema.TypeService
	  |-- doctype (declare a new Document Type)	
	  |-- schema  (declare your new Document Type's schema)
	  |-- type    (show your new Document Type on the UI)
	  |-- ...
	  |-- etc
	  |-- ...	
	

Contributions to the doctype and schema extension points, only require the addition of the configuration files we are defining here (core-types-contrib.xml and book.xsd). Once defined, the TypeService class knows how to use them to create our new 'Book' type in Nuxeo. All we have to worry about is giving the TypeService the information it needs.

Here is the corresponding XML snipset extracted from the core-types-contrib.xml file

      
	  ...
	  <!-- Declare our schema and give it a name -->
	  <extension target="org.nuxeo.ecm.core.schema.TypeService"
          point="schema">
	  <schema name="book" src="schemas/book.xsd" prefix="bk">
	  </extension>
	  ...
	  <!-- Declare our new Book type and tell it to use
	          our new book schema -->
	  <extension target="org.nuxeo.ecm.core.schema.TypeService"
	  point="doctype">
	  <doctype name="Book" extends="Document">
	  ...
	  <schema name="book" >
	  ...
	  </doctype>
	  </extension>
	  ...

How do we know what information the TypeService needs ? Fortunately all this is documented here: Extension Points Documentation (5.1) and here: Extension Points Documentation (5.2) . For example if you click on the org.nuxeo.ecm.core.schema.TypeService link, you will see all the extension points that it exposes, and how to configure these in your xml.

Adding a reference to our core-types-contrib.xml to our manifest tells the container and nuxeo where to find our changes to add a new 'Book' document type. Here is the relevant snippet:

	  ....
      Nuxeo-Component: OSGI-INF/core-types-contrib.xml,	  
	  ....
	  

So far we have declared the 'Book' type and schema, but all that means is that Nuxeo knows about it. As it stands, the user wont be able to see our new 'Book' type unless we explicitly add it to the UI (That's where the next section comes in). However we can still test what we have done, and in fact it is important to do so. We do this by writing some junit tests.

There are differences in the way Nuxeo version 5.1 and 5.2 handles new Document types, based on the fact that changes were made in the repository between the 2 versions.

The TestBookType.java test inherits from RepositoryOSGITestCase in 5.1 and SQLRepositoryTestCase in 5.2, which both inherit from NXRuntimeTestCase which in turn eventually inherits from JUnitTestCase.

junit.framework.TestCase
|-- ....
     |--NXRuntimeTestCase
           |--RepositoryOSGITestCase (5.1)
           |--SQLRepositoryTestCase (5.2)
	  
	  

The NXRuntimeTestCase is the "raw" testcase which does a lot of OSGI related test setup, and is primarily concerned with the startup and shutdown of the nuxeo runtime in our tests. The RepositoryOSGITestCase is used for 5.1, as it handles the JCR implementation of the repository, whereas the SQLRepositoryTestCase is used for 5.2 as it handles the VCS implementation of the repository (See Nuxeo Book chapter xxxx)

The test for our declaration of the new 'Book' type and its associated schema, is inside the testBookCreation() method within TestBookType.java, which has inline documentation to explain what each step does.

A useful thing to know is that the RepositoryOSGITestCase methods:

The session can be thought of as a series of changes that are written to it. Each change written to a session (like the coreSession.saveDocument() one) is very cheap because it is done in memory. At the end, calling the coreSession.save() writes all these changes to disk in one hit, which again helps with performance.

In this section we want to get our new Book document type to appear on the UI. Again, this involves only configuration changes (ie. no java coding is necessary). We will end up adding or changing the following files:

Books are displayed on the screen using a specific icon and label. You can see in second figure in the Section 3.6.4.1, “Objective” above, the little 16x16 image of a book, followed by the label "Book". This is achieved by providing an extension point contribution to the TypeService's exposed extension point called "type" which is responsible for displaying both of these on the UI (see section Section 3.6.4.4, “core-types-contrib.xml” above for the listing of exposed extension points of TypeService). Note however, that instead of adding our contribution to the core-types-contrib.xml file as we did when we were declaring our Book document type, we will instead add this contribution to the ui-types-contrib.xml file. This is so that all the contributions to do with UI changes can be grouped together separately. Here is the corresponding XML snipset extracted from the ui-types-contrib.xml file

...
	  <extension target="org.nuxeo.ecm.core.schema.TypeService"
	  point="type">
	  ...
	  <type id="Book" coretype="Book">
	  ...
	  <label>Book</label>
	  <icon>/icons/book.png</icon>
	  ...
	  </type>
	  ...
	  </extension>
	  ...

The attribute id="Book" must match the "doctype name" declared in the core-types-contrib.xml declared above. The coretype="Book" attribute is now optional in 5.2, but if it is present, its value must match the id attribute's value.

Also, we need to put our little 16x16 icon "book.png" in the src/main/resources/nuxeo/icons directory for it to be deployed correctly to the server (where it will ultimately end up in the ~/nuxeo/server/default/deploy/nuxeo.ear/nuxeo.war/icons directory).

In order to ensure that it does indeed end up there, we need to make sure we have the following line in the OSGI_INF/deployment_fragment.xml file:

	  <!-- Unzip the war template -->
        <unzip from="${bundle.fileName}" to="/">
          <include>nuxeo.war/**</include>
        </unzip>
	  

Adding a reference to our ui-contrib.xml to our manifest tells the container and nuxeo where to find our new additions. Here is the relevant snippet:

	  ....
      Nuxeo-Component: OSGI-INF/core-types-contrib.xml,
	  ....
	  OSGI-INF/ui-contrib.xml,	  
	  ....
	  

Note that the order of these components matters, because our ui-contrib.xml depends on the core-types-contrib.xml.

Remember above ( Section 3.5.10.2, “Viewing your changes”) we had to create a new Nuxeo Workspace in which to create our new Book document. The rules that determine where we can display our new Book document on the UI are actually defined in our ui-types-contrib.xml file as well.

We will make a rule that Book documents can be displayed under Nuxeo folders or workspaces. These containment rules are declared to the exposed extension point called "types" in the org.nuxeo.ecm.platform.types.TypeService class. Note that this is a different "TypeService" class than the one above (check the fully qualified path name !). Documentation for the extension points exposed by this class can be found here: org.nuxeo.ecm.platform.types.TypeService

We will define this extension point contribution in the ui-types-contrib.xml file as well because our contribution relates to UI changes. Here is the XML snipset extracted from the ui-types-contrib.xml that defines them.

  ...
	  <extension target="org.nuxeo.ecm.platform.types.TypeService"
	  point="types">
	  ...
	  <type id="Folder" coretype="Folder">
	  <subtypes>
          <type>Book</type>
	  </subtypes>
	  </type>

	  <type id="Workspace" coretype="Workspace">
	  <subtypes>
          <type>Book</type>
	  </subtypes>
	  </type>
	  ...
	  </extension>
	  ...

Again, the "coretype" attribute must contain a value that relates to one of the Nuxeo Core Types or a Type that we have created ourselves like 'Book'.

Don't forget to add entries into your MANIFEST.MF file to reference the new files you have created:

	  ....
      Nuxeo-Component: OSGI-INF/core-types-contrib.xml,
	  OSGI-INF/ui-contrib.xml,	  
      OSGI-INF/layouts-contrib.xml,
	  ....
	  

It is possible to install Selenium to test our new UI changes as it is difficult to write JUnit tests to do so. For now, we suggest just starting up the Nuxeo server and going in and verifying that your changes work by creating a new Book document and seeing if you can view it.

In this section we described how to get the our Book document's fields to be displayed on the screen, and how to display them.

We can add tabs to the different views a user has in the Nuxeo UI and associate different behaviors with each tab.

In this section we will describe how to add 2 tabs:

It is the first time also that we will be using some Java code in addition to configuration changes/additions. The java code will help us implement some of the custom behavior we want. However we will not focus on this, as it is important to understand that you can do a lot with just the configuration changes that we will explain.

A good reference for this section is Section 7.1, “Introduction”

Our configuration happens in a file called actions-contrib.xml. In this file we provide a contribution to the extension points called "actions" and "filters" on the ActionService class. Here is the actions-contrib.xml file:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.actions">

  <extension target="org.nuxeo.ecm.platform.actions.ActionService" point="actions">
    <action id="tab_book_view"
      link="/incl/tabs/book_view.xhtml" enabled="true"
      label="Book" icon="/icons/file.gif" order="9">
      <category>VIEW_ACTION_LIST</category>
      <filter id="book_filter">
      </filter>
    </action>

    <action id="tab_folder_books_list"
      link="/incl/tabs/folder_books_view.xhtml" enabled="true"
      label="Books" icon="/icons/file.gif" order="15">
      <category>VIEW_ACTION_LIST</category>
      <filter id="workspace_books_filter">
        <rule grant="true">
          <type>Folder</type>
          <type>Workspace</type>
        </rule>
      </filter>
    </action>
  </extension>

  <extension target="org.nuxeo.ecm.platform.actions.ActionService" point="filters">
    <filter id="book_filter" append="true">
      <rule grant="true">
        <type>Book</type>
      </rule>
    </filter>
  </extension>

</component>	  
	  

The first thing to note are the 2 extension point contributions "actions" and "filters".

The "filters" extension point: is where you can add a "filter". Filters are generally are used to change the access rights to a tab. We name and create filters in this section when our filter is particularly complex (and we then want to separate it, define it, and call it by name from the "actions" extension point), or when we just want to re-use a particular filter, and therefore we can again reference it by its name.

Our example filter in actions-contrib.xml called "book_filter", is saying that if a Document is a child of the "Book" type, then grant access (visibility) to this tab. This example shows how filters can be used to manage access rights to tabs. It is convenient, as the user does not have to write Java code to deal with permissions.

The "actions" extension point: is used to configure what action to take when it is selected. The action id names the action. If you hover your mouse over the "Book" tab in the Book view (select a book that you have already created and then hover your mouse over the "Book" tab on the next screen), you'll see that the url contains the action id.

The "link" attribute identifies which action to call when your tab is selected. The link here specifies a JSF page called book_view.xhtml. We will describe this JSF page in brief in a following section. For now, all we need to know is that clicking the "Book" tab will request this action. The "enabled" attribute is also important, because it defines whether or not a tab will be visible to the user or not. So we can turn the visibility of tabs on and off with this attribute which is quite useful. The "label" is the text that will appear on the tab, and the "icon" is the icon associated with the tab.

The "category" node defines a pre-defined place on the page on which to display your tab. Common values are:

See Section 7.2.2.2, “Manage category to display an action at the right place” for more information.

The "filter" node is also important. You can define either an inline filter (as has been done with the "tab_folder_books_list" action), or you can just call a named filter (which is what the "tab_book_view" action does). The "filter" nodes define what filters to associated with this action. For the "tab_book_view" action, our filter allows the user access to the tab only if the document is a child of the Book type.

The actions-contrib.xml file above, calls the book_view.xhtml and folder_books_view.xhtml jsf pages as its actions. (Note that tab's templates are defined into the folder nuxeo.war/inc/tabs.) Without going into detail, you can see from the snippet below that the jsf looks a lot like html, but with the use of jsf tags like <h:outputLabel value="keywords"> instead of html.

Note also that these templates get their model using the BookManagerBean which implements book behaviours. You'll see that anything with the "#{}" around it is a call to the BookManager.java class.

In this section we saw how to add tabs with access permissions and behaviors using contributions to the "actions" and "filters" extension points on the ActionService class. Don't forget to add a line to your MANIFEST.MF to include the actions-contrib.xml file. The next section includes details of how the "Books" tab page is used.

We want to allow our book to be searchable via the Nuxeo UI. There is a little 'search box' in the top left corner of our Nuxeo UI. You don't need to do anything specific to have this search, search any of your book documents.

However, in the section below, we will show how to do a customized search that you can set up 'programatically'. To do this we need to do 4 things:

A good reference for this section is Section 11.1, “Introduction”.

Our first step is to tell Nuxeo which fields in our Book schema we want indexed. These indexed fields will be the ones that can be searched. This step is only necessary in Nuxeo 5.1. In 5.2, all fields from our Book schema will be searchable by default.

To tell Nuxeo which fields to index, we register an extension point contribution to the extension point called "indexableDocType" on the SearchServiceImpl class. We do this in a file called the search-contrib.xml file. Don't forget that we need a reference to this in our MANIFEST.MF as it is a new file. Here is the contents of the search-contrib.xml:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.search">

  <extension
    target="org.nuxeo.ecm.core.search.service.SearchServiceImpl"
    point="indexableDocType">
    <indexableDocType indexAllSchemas="true" name="Book" />
  </extension>

</component>	  
	  

As you can see we are telling the SearchServiceImpl class to index all fields on all schemas that make up our Book document. So all fields of our book will be searchable.

Next we need to tell Nuxeo how we want to search. This is called our 'Query Model'. The query model lets us define our search in an 'SQL-like' way so that we can specify our search parameters. An example in pseudo-code might be:

"select all Book documents where the user's input string matches one of the book's keywords.".

To do this, we register a 'Query Model' with the "model" extension point of the QueryModelService. We can do this by creating a new file called querymodel-contrib.xml and specifying the search "pattern":

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.querymodels">

  <extension
    target="org.nuxeo.ecm.core.search.api.client.querymodel.QueryModelService"
    point="model">

    <queryModel name="BOOK">
      <pattern>
        SELECT * FROM Document WHERE ecm:primaryType = 'Book' AND ecm:path STARTSWITH ? AND
        bk:keywords = ?
      </pattern>
         <sortable value="true" defaultSortColumn="dc:title"
        defaultSortAscending="true" />
    </queryModel>

  </extension>


</component>	  
	  

The query language that we use in the "pattern" attribute is called NXQL and more documentation about it can be found here: Section 11.3.1, “Fields and literals” .

After we have setup our query model, we need to register the Java Class that will be invoking this query model (and dealing with the results of the query), with the "model" extension point of the ResultsProviderService. Again we do this in a new file called: resultsprovider-contrib.xml. Here are the contents of that file:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.resultsproviders">

  <extension
    target="org.nuxeo.ecm.webapp.pagination.ResultsProviderService"
    point="model">

    <resultsProvider name="BOOK" farm="bookResultsProviderFarm" />

  </extension>
</component>
      

Notice that the "farm" attribute points to the src/main/java/BookResultsProvider.java class that we have written. This class will be the class that retrieves the query model we setup above and uses it to perform our customized search.

Finally having set up our search, we need a page to display the search options and show the results of our search on the UI. We do both these things on the same page: Books are both searched for, and listed, in the book's tab using the resultsProviderCache which we can access in the folder_books_view.xhtml JSF page we setup above: Section 3.6.6.2, “Configuration”

...
	  <nxu:methodResult name="provider"
          value="#{resultsProvidersCache.get('BOOK')}">

	  <h:form>
          <ui:decorate template="/pagination/pageNavigationControls.xhtml">
          <ui:param name="provider" value="#{provider}" />
          </ui:decorate>
	  </h:form>

	  <h:dataTable var="bookinfo" value="#{provider.currentPage}"
	  ...
	  </h:dataTable>
	  ...
	  

The following screen shot shows the results of our handiwork:

Note: you can setup your books to appear in this screen like this by selecting a book that you have already created, going to the "Book" tab and entering in Keyword and Note for your book. Then clicking on a Keyword searches for all the books that contain that keyword if it was entered against them on the "Book" tab.

Nuxeo makes it easy to enable drag and drop so that dragging a file onto a workspace will automatically create a Book document. In this section we will show you how to enable drag and drop in Nuxeo.

As by-product of explaining how to enable drag and drop in Nuxeo in this section, we will see how to create our own Service and create an extension point on that service. So far we have been only providing contributions to existing extension points in services within Nuxeo. But this section gives us the opportunity to

But first, before we create our own service with its own extension point, let us again begin by providing an extension point contribution to an existing Nuxeo service. By providing an extension point contribution to the "plugins" extension point on the FileManagerService class, we can have this class notify us when a drag and drop event occurs. We will put this contribution in the filemanager-contrib.xml file:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.filemanager">

  <extension
    target="org.nuxeo.ecm.platform.filemanager.service.FileManagerService"
    point="plugins">
    <plugin name="book_plugin"
      class="org.nuxeo.project.sample.BookFileManagerPlugin">
      <filter>image/gif</filter>
      <filter>image/jpeg</filter>
    </plugin>
  </extension>

</component>	  
	  

The BookFileManagerPlugin has requested that the FileManagerService call the BookFileManagerPlugin class whenever a gif or jpeg upload (drag and drop) occurs. The notification takes the form of calling the BookFileManagerPlugin's create() method.

Now we get to register our own service with its very own extension point exposed. This service is called by our BookFileManagerPlugin when it has been notified by the Nuxeo FileManagerService that a ".gif" or ".jpeg" has been dragged and dropped onto the UI. The BookFileManagerPlugin will use this Service to help it create a new Book document from the uploaded file.

We will register the service in the booktitle-service-contrib.xml file as follows:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.BookTitleService">

  <implementation class="org.nuxeo.project.sample.BookTitleServiceImpl" />

  <service>
    <provide interface="org.nuxeo.project.sample.BookTitleService" />
  </service>

  <extension-point name="title">
    <object class="org.nuxeo.project.sample.BookTitleDescriptor" />
  </extension-point>

</component>
	  

In creating this xml configuration, we are defining a new nuxeo <component> called org.nuxeo.project.sample.BookTitleService which defines a new service called BookTitleService whose <implementation> class is the org.nuxeo.project.sample.BookTitleServiceImpl class. Furthermore, we define an <extension> point on our component called "title", which we will map to a java class called BookTitleDescriptor.

Ok. Now when we define our extension point contribution, which we will do in the booktitle-contrib.xml file, the fields in this xml file should map to the annotations in our BookTitleDescriptor. This is essentially how you find out what information your extension point requires:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.booktitle">
  <extension 
         target="org.nuxeo.project.sample.BookTitleService" 
         point="title">
    <configuration>
      <addInitialCapital>true</addInitialCapital>
      <removeExtension>true</removeExtension>
      <addComment>(automatic)</addComment>
    </configuration>
  </extension>
</component>

package org.nuxeo.project.sample;

import org.nuxeo.common.xmap.annotation.XNode;
import org.nuxeo.common.xmap.annotation.XObject;

@XObject("configuration")
public class BookTitleDescriptor {

  @XNode("addInitialCapital")
  protected boolean addInitialCap;

  @XNode("addComment")
  private String addComment;

  public String getAddComment() {
	return addComment;
  }

  private boolean remove;

  @XNode("removeExtension")
  protected void setRemoveExtension(boolean remove) {
	this.remove = remove;
  }

  public boolean getRemoveExtension() {
	return remove;
  }
}

So the flow of events when a ".gif" or ".jpeg" document is dragged onto the Nuxeo UI is as follows:

The FileManagerService notifies the BookFileManagerPlugin by calling its create() method. To do its work of creating a new Book document, the BookFileManagerPlugin class calls the BookTitleService's correctTitle(title) method, passing it the name of the file that was uploaded. The BookTitleService then retrieves the values provided by the "title" extension point which are set in the booktitle-contrib.xml file, and uses these to correct the title (ie. Change the first letter to a capital, removes the file extension - eg. ".gif"), and adds a comment, before creating a new Book document with this title and saving it to the repository.

FileManagerService
  |-- BookFileManagerPlugin.create()
        |--BookTitleServiceImpl.correctTitle(title)
		      |-- BookTitleDescriptor (get values from booktitle-contrib.xml config)
			  |-- create the title base on the values
        |-- create the new Book with this title in the repository
			     
	  

The Sample Project contains a class called TestBookTitleService which tests whether our new configuration and java changes for creating our new BookTitleService service works.

If you look at the source code of the BookFileManagerPlugin in the 5.1 vs 5.2 branch, you will notice that in 5.1 it extends AbstractPlugin whereas in 5.2 it extends AbstractFileImporter. The AbstractPlugin is deprecated in 5.2.

The BookManager and BookMangerBean classes have import(s) changed from 5.1 to 5.2:

	  import org.jboss.seam.annotations.WebRemote; (5.1)
	  import org.jboss.seam.annotations.remoting.WebRemote; (5.2)
	  

and

	  import org.jboss.seam.core.FacesMessages; (5.1)
	  import org.jboss.seam.faces.FacesMessages; (5.2)
	  

As these have changed packages between the jboss versions used between 5.1 (4.0.5) and 5.2 (4.2.3).

The BookManager interface has been changed to return a DocumentModelList instead of a ResultSet

	  public ResultSet getSearchResults() throws Exception; // (5.1)
	  public DocumentModelList getSearchResults() throws Exception; //(5.2)
	  

and the BookManagerBean which implements the BookManager interface, has had its code updated accordingly, and also been made Serializable. The reason is that SearchService is not used anymore. Now queries are executed with the method query() from the CoreSession, and this new method returns a DocumentModelList instead of a ResultSet.

The BookResultsProviderFarm has also been made Serializable in 5.2, and had its call to getResultsProvider() updated.

We want to make Books be regulated by the standard life cycle ( project, approved, obsolete, deleted states). As defined in the Chapter 4 of the Nuxeo User's Guide "The evolution of a document, each time contributors edit it, constitutes its life cycle ... To change the life cycle state of a document, you need to submit it to a workflow.". You can find out more about life cycles and workflows from the user's perspective by reading Chapter 4 of the Nuxeo User's Guide .

In this section we will show you just how to register a document to the default life cycle states. To get it to actually transition between these states will be discussed in a separate section on Section 3.6.10, “Workflow” .

We can get a Book to follow the Nuxeo standard lifecycle by declaring to the "types" extension point of the LifeCycle Service that Books follow the "default" life cycle. Here is the lifecycle-contrib.xml file

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.lifecycles">

  <extension target="org.nuxeo.ecm.core.lifecycle.LifeCycleService"
    point="types">
    <types>
      <type name="Book">default</type>
    </types>
  </extension>

</component>
	  

Getting your new Book document type to follow the standard Nuxeo lifecycle is as simple as that. Don't forget that a reference to the lifecycle-contrib.xml file also needs to go in the MANIFEST.MF file.

We can also write a JUnit Test to test our life cycle contribution. If you look in the sample project's src/test/java directory you'll see a test class called TestBookLifeCycle.java. It is self documented for you to follow the steps.

TO DO (code not yet implemented in 5.1 branch either)

TO DO (code exists in 5.2 branch)

Event Listeners are java classes that get notified by nuxeo when a particular type of event (that they are "listening" for) occurs. In this section we will show you how to create your own Event Listener java classes to listen for particular events and then to do something useful when the event occurs.

Event Listeners are registered as contributions to the extension point "listener" on the EventServiceComponent class (in 5.2) or on the CoreEventListenerService class (in 5.1). In the sample project we have registered these event listeners in the event-listener-contrib.xml file. These contributions are basically registering a java class that you will write (our "EventListener" classes), that will get notified when a particular event occurs. The event or events that your customized class listens for can be specified by the <event> tag in the xml. Here is the listing of event-listener-contrib.xml:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.event-listeners">
	<extension target="org.nuxeo.ecm.core.event.EventServiceComponent"
		point="listener">
		<listener name="book_create" async="false" postCommit="false"
			class="org.nuxeo.project.sample.BookEventListener">
			<event>emptyDocumentModelCreated</event>
		</listener>
		<listener name="book_update_isbn" async="false" postCommit="false"
			class="org.nuxeo.project.sample.BookISBNEventListener" order="157">
			<event>documentCreated</event>
			<event>documentModified</event>
		</listener>
	</extension>
</component>	   
	   

As we can see above are 2 event listeners in the sample project:

Our BookEventListener class will get notified whenever a emptyDocumentModelCreated event occurs. In other words, when the user clicks the 'New Document' button, it will get notified. The class itself is very simple. It implements the EventListener interface, which means that we must implement a handleEvent(Event event) method in our event listener, which is passed the event that has occurred:

	  public void handleEvent(Event event) throws ClientException {
        EventContext ctx = event.getContext();
        if (ctx instanceof DocumentEventContext) {
            DocumentEventContext docCtx = (DocumentEventContext) ctx;
            DocumentModel doc = docCtx.getSourceDocument();
            if (doc != null) {
                String type = doc.getType();
                if ("Book".equals(type)) {
                    process(doc);
                }
            }
        }
	  

This method checks to see if our Document type is a 'Book' and if it is, it calls the process(doc) method (not shown), passing it the Book document, which does all the work of creating some default values for the Book's 'Title' and 'Description' fields. The user sees these as 'Sample Book' and the '(Created on 2009-01-01)' in the editable Title and Description fields respectively on the screen where a new Book is being created. The user can overwrite these values if they wish.

The BookISBNEventListener class listens for documentCreated and documentModified events. When it is notified that one of these events has occurred, once again its handleEvent() method is called. After checking that the event applies only to Book document types, it calls its process() method do deal with these events.

It is at this point that we can see that it that we need to digress a little, to explain what is happening next. That is because it starts doing things with a DirectoryService and a Vocabulary.

The sample project defines an extension contribution to the SQLDirectoryFactory class called "directories" in the file directories-contrib.xml whose contents are listed below:

<?xml version="1.0"?>
<component name="org.nuxeo.project.sample.directories">
  <extension target="org.nuxeo.ecm.directory.sql.SQLDirectoryFactory"
    point="directories">
    <directory name="book_keywords">
      <schema>vocabulary</schema>
      <idField>id</idField>
      <dataSource>java:/nxsqldirectory</dataSource>
      <table>book_keywords</table>
      <!-- one of "never", "on_missing_columns" or "always" -->
      <createTablePolicy>on_missing_columns</createTablePolicy>
      <dataFile>directories/book_keywords.csv</dataFile>
    </directory>
  </extension>
</component>
	  

In Nuxeo, a Directory is a programmatic abstraction that let's us deal with any relational database, regardless of the actual underlying implementation (some examples might be certain implementations of ldap, databases, csv files etc). The chapter on Directories and Vocabularies in the nuxeo book, contains a convenient diagram in the Introduction section which diagrams this abstraction. A The "directories" extension contribution contained in the directories-contrib.xml file shown above, defines a new directory called "book_keywords". This directory is based on the <vocabulary> schema, which is a core nuxeo schema and can be found in the vocabulary.xsd file in the ~/nuxeo/server/default/data/NXRuntime/schemas/ directory under your server installation. If you look at this schema you'll see it contains 4 fields: id, label, obsolete and ordering. The <id> xml node in the directories-contrib.xml defines which of these 4 fields is the key field.

The other xml nodes define the other aspects of the book_keywords directory that we are defining. The <dataFile> node defines that we will keep the initial data that will populate this directory in the book_keywords.csv file. If you browse to that file in the sample project you'll see its contents:

id, label, obsolete
"1","Novel",0
"2","Bestseller",0
"3","Academic",0	  
	  

The <dataSource> node points to the actual implementation of our directory and where our data will be really stored. In our case we are using the default nuxeo sql data source and naming the table that holds our data in this dataSource <table>book_keywords</table>. Finally the <createTablePolicy> node, takes a value of on_missing_columns, which means that nuxeo will load the contents of your book_keywords if your book_keywords schema is updated. Thus when the server is first started, and no data exists in the table, the book keywords will be loaded in. Then if the server is restarted, no changes will be made to the database unless the schema has been changed.

So we have defined a Directory that will hold our book keywords that we get from our book_keywords.csv file. What do we then do with this Directory ? We can see what happens when we look at the process() method of BookISBNEventListener. Whenever a document is created or modified, our process() method gets a DirectoryService to our "book_keywords" directory. It then matches the value of the ISBN field of our book against the value of the id column of our book_keywords data (the call to dir.getEntry() will use the value of the key field 'id' defined in our book_keywords directory to match against).

	  dir = dirService.open("book_keywords");
      DocumentModel entry = dir.getEntry(isbn);
	  

If there is no match (the entry returned is null), it will create a new entry in our directory with the isbn as the "id" and the title as the "label". The mapping between our Book and our book_keywords fields is shown in the table below:

If you look at the rest of the code in the process() method of BookISBNEventListener, you'll see that if there is a match between the isbn of the book and the id of the book_keywords, it will update the label of the matching book_keyword entry with the title of the matching book.

So that explains what BookISBNEventListener does, and what all the Directory/Vocabulary code in the sample project is about. The page that actually uses this code is the search facility of the 'Books' tab described in the Section 3.6.6, “Actions, tabs and behavior ” section above.

TO DO

An ECM platform like Nuxeo EP can be used in a lot of different cases.

The deployment of Nuxeo EP must be adapted to all these different cases:

There are certainly a lot of other use cases, but mainly the constraints are:

Before building Nuxeo EP we worked during several years on the Zope platform with the CPS solution. CPS was deployed for a lot different use cases and we learned a lot of good practices and design patterns. Although Nuxeo EP is a full rewrite of our ECM platform, we wanted to keep as many of the good CPS concepts as possible.

CPS was constructed as a set of pluggable components relying on a common platform. This modularity has been maintained in the new platform. Deploying a new feature or component on the new platform is as simple as it was on the old one.

This requirement has a huge impact on the platform because the Java packaging model and the Java EE constraints are not directly compatible with it.

Adding a new component should be as simple as dropping a file or an archive in some directory without having to rebuild nor repackage the application.

This is important from the administrator point of view: be able to easily deploy new features.

This is also very important from the support point of view: to be able to deploy customized components without taking the risk of forking the platform, and maintaining the possibility to upgrade the standard components.

The CPS framework was powerful but we know it was very complex to use. Not only because of the unusual CMF/Zope/Python programming model, but also because there was a lot of different concepts and you had to understand them all to be able to leverage the platform when building a new application on top of it.

Nuxeo EP aims at simplifying the task of the developer

We know what it's like to have to build and maintain an entire framework starting from the application server. With the switch to the Java technology, we will use as many existing open source components as possible and focus on integrating them seamlessly into the ECM platform. Nuxeo EP is a complete integrated solution for building an ECM application, but Nuxeo won't write all infrastructure components. This approach will also make the platform more standards compliant.

Thus developers can optimize their Java/JEE and open source experience to use Nuxeo EP.

Because ECM applications often need to be deeply integrated into the existing SI, Nuxeo EP will be easily integrable

The Nuxeo EP platform was rewritten from the ground up with the switch to Java. But we don't plan to do this kind of work every couple of years, it won't be efficient neither for us, nor for the users of the platform. For that reason, we choose innovative Java technologies like OSGi, EJB3, JSF, Seam ....

Nuxeo EP is built of several layers, following at least the 3 tiers standard architecture

Depending on the components, their complexity and the needed pluggability, there can be more than 3 layers.

This layering of all the components brings Nuxeo EP the following advantages

Thanks to this separation in component families you can easily extract from Nuxeo EP the components you need for your application.

If you need to include Document storage facilities into your application you can just use Nuxeo EP Core: It will offer you all the needed features to store, version and retrieve documents (or any structured but flexible dataset). If you also need process management and workflow you can also use Nuxeo EP Workflow service. And finally, if you want to have a Web application to browse and manage your data, you can reuse the Nuxeo EP Web layer.

The targeted platform does not provide the same mechanism to handle all the deployment tasks:

Because of these differences, Nuxeo EP provides a unified deployment service that hides the specificity of the target platform. This is also a way to add a pluggable component deployment system to some platforms that don't handle this (like Java EE).

This is one of the motivating factors for the Nuxeo Runtime that will be briefly introduced later in this document.

In Nuxeo EP, an ECM application is seen as an assembly of components.

This assembly will include:

Inside Nuxeo EP each feature is implemented by one or several reusable components and services. A feature may be implemented completely at storage level, or may require a dedicated service and a dedicated GUI.

Nuxeo EP Web application is a default distribution of a set of ECM components. This can be used "as is" or can be the base for making a business ECM application.

Here is a quick list of the Java technology we use inside Nuxeo EP platform:

Because most Nuxeo EP components are shared by Nuxeo RCP (OSGI/RCP) and Nuxeo EP (Java EE), an abstraction layer is required so the components can transparently use the components services independently from the underlying infrastructure.

Nuxeo Runtime provides an abstraction layer on top of the target host platform. Depending on the target host platform, this Runtime layer may be very thin.

Nuxeo Runtime already supports Equinox (Eclipse RCP OSGi layer) and JBoss 4.x (JMX). The port of Nuxeo Runtime to other Java EE application servers is in progress, we already have a part of Nuxeo EP components that can be deployed on top of SUN Glassfish application server. Technically speaking, the port of Nuxeo Runtime could be done on any JEE5 compliant platform and will be almost straightforward for any platform that supports natively the OSGi component model.

Java EE is a great standard, but it was not designed for a component based framework: it is not modular at all.

Nuxeo Runtime provides an extensible component model that supports all these features. It also handles the deployment of these components on the target host platform.

OSGi (Open Services Gateway initiative) is a great standard for components based Java architecture.

OSGi provides out of the box the following features:

For Nuxeo EP, the OSGi standard provides a lot of the needed features. This is the reason why Nuxeo Runtime is based on OSGi. In fact Nuxeo Runtime component model is a subset of the OSGi specification.

To ensure platform transparency, Nuxeo Runtime provides adapters for each target platform to help it support OSGi components.

OSGi does not define a plugin model, but the Eclipse implementation (Equinox) does provide an extension point system.

Because we found many benefits in the Eclipse Extension Point system, Nuxeo Runtime also includes an Extension Point system. In other words, the underlying mechanism which allows extension points to be implemented in Nuxeo EP, has been built into the Nuxeo EP runtime and core.

An extension point is a way to declare that your component can be customized from the outside:

Basically every Nuxeo Component can:

Extension points and contributions to extension points are defined using a XML descriptor that has to be referenced in the MANIFEST.MF. For a more detailed understanding of extension points in Nuxeo EP, we recommend reading the Learning Nuxeo EP5 guide.

Most of the components forming the core are exposed via the DocumentManager / CoreSession interface. The interfaces and dependencies needed to access the Core services are packaged in an API package: even if there are several Core components, you have only one dependency and API package.

The idea is that for accessing the core, you will only need to use the DocumentManager to manipulate DocumentModels (the document object artifact). Some core services can be directly accessed via the DocumentModel (like the life cycle or security data).

Each service exposes its own API and then has its own API package. Service related data (like process data, relation data) are not directly hosted by the DocumentModel object but can be associated to it via adapters and facets.

The web layer can be very specific to the target application. Nuxeo EP provides a default web application and a set of base classes, utility classes and pluggable services to handle web navigation inside the content repository.

Most features are made of several Java projects and generate several Maven 2 artifacts.

Nuxeo packaging and deployment system (Nuxeo Runtime, Platform API, Maven ...) leverage this separation to help you distributing the needed deployment unit according to your target physical platform.

The repository service lets you define new document repositories. Defining separate repositories for your documents is pretty much like defining separate Databases for your records.

Because Nuxeo Core defines an SPI on repository, you can configure how you want the repository to be implemented. For now, the default implementation uses JSR-170 (Java Content Repository) reference implementation: Apache Jack Rabbit. In the future, we may provide other implementations of the Repository SPI (like native SQL DB or Object Oriented DB).

Even if for now there is only one Repository implementation available, using JCR implementation, you can configure how your data will be persisted: filesystem, xml or SQL Database. Please see "How to"s about repository configuration (Chapter 44, RDBMS Storage and Database Configuration).

When defining a new repository, you can configure:

The requirements for the Nuxeo Web Framework are :

Nuxeo Web Layer uses JSF (SUN RI 1.2) and Facelets as presentation layer: JSF is standard and very pluggable, Facelets is much more flexible and adapted to JSF than JSP.

NXThemes provides a flexible Theme and composition engine based on JSF and Facelets.

In the 5.1 version of the platform, Nuxeo Web Layer uses Apache Tomahawk and trinidad as a components library and AJAX4JSF for Ajax integration. In the 5.2 version we will move to Rich Faces.

Nuxeo Web Layer also uses Seam Web Framework to handle all the ActionListeners.

Using Seam provides :

Nuxeo Web Layer comes on top of a set of pluggable services.

Because this stack of services is very modular, the web layer must also be modular.

This basically means that depending on the set of deployed services and on the configuration, the web framework must provide a way

In order to fullfill these requirements, the key points of Nuxeo Web Frame fulfill:

Inside the web framework, each component will need to know at least

In some cases, this context information may be huge, and it's time consuming to recompute all this information for each request.

Inside Nuxeo Web Framework, Seam context management is used to store this data. Depending on the lifecycle of the data, Session, Conversation or Event context are used.

At some point the components of the web framework need to interact with each other. But because components can be present or not depending on the deployment scenario, they can't call each other directly.

For that matter, the Nuxeo Web Framework uses a lot of Seam features:

In order to facilitate Nuxeo Services integration into the web framework, we use the Seam Unwrap pattern to wrap a Nuxeo Service into Seam Components that can be injected and manipulated as a standard Seam component.

The Web Layer is composed of several components.

The main components are webapp-core (default webapp base) and ui-web (web framework). On top of these base components, dedicated web components are deployed for each specific service.

For example, the workflow-service has its own web components package, so do relation-service, audit-service, comment-service and so on.

Each package contains a set of views, actions, and ActionsListeners that are dedicated to one service and integrate this service into the base webapp.

Because JEE standards require the webapp to be monolithic (ie. it cannot be split up), we use the Nuxeo Runtime deployment service to assemble the target webapp at deployment time.

This deployment framework let you: override resources, contribute XML descriptors like web.xml from several components and manage deployment order.

TO DO

Here is the new layout configuration:

<layouts mode="any">
  <layout>heading</layout>
  <layout>note</layout>
</layouts>

Layouts are defined in a given mode (default modes are "create", "edit" and "view") ; layouts in the "any" mode will be merged with layouts defined for specific modes.

The layout names refer to layouts defined on another extension point. Please see the layouts section for more information.

Here is the old layout configuration that has been replaced by the above. If present, it is used instead of the new configuration for compatibility purposes.

<layout>
  <widget jsfcomponent="h:inputText"
    schemaname="dublincore" fieldname="title"
    required="true" />
  <widget jsfcomponent="h:inputTextarea"
    schemaname="dublincore" fieldname="description" />
  <widget jsfcomponent="h:inputText"
    schemaname="sample" fieldname="sample1" />
  <widget jsfcomponent="h:inputText"
    schemaname="sample" fieldname="sample2" />
</layout>

This section defines a series of widgets, that describe what the standard layout of this document type will be. A layout is a series of widgets, which make the association between the field of a schema with a JSF component.

The layout is used by the standard Nuxeo modification and summary views, to automatically display the document according to the layout rules. Note that the layout system is still young and is subject to minor changes in the future. Here we define four widgets, displayed as simple input fields or as a text area.

An action can be registered using the following example extension:

<extension target="org.nuxeo.ecm.platform.actions.ActionService"
    point="actions">

  <action id="logout" link="#{loginLogoutAction.logout}"
    label="command.logout">
    <category>USER_SERVICES</category>
  </action>

</extension>

The above action will be used to display a "logout" link on the site. Here are its properties:

Other properties can be used to define an action. They are listed here but you can have a look at the main actions contributions file for more examples: nuxeo-platform-webapp-core/srs/main/resources/OSGI-INF/actions-contrib.xml.

Actions extension point provides merging features: you can change an existing action definition in your custom extension point provided you use the same identifier. Properties holding single values (label, link for instance) will be replaced using the new value. Properties holding multiple values (categories, filters) will be merged with existing values.

Actions in the same category are supposed to be displayed in the same area of a page. Here are listed the main default categories if you want to add an action there:

An action visibility can be controlled using filters. An action filter is a set of rules that will apply - or not - given an action and a context.

Filters can be registered using their own extension point, or registered implicitly when defining them inside of an action definition:

<filter id="view_content">
  <rule grant="true">
    <permission>ReadChildren</permission>
    <facet>Folderish</facet>
  </rule>
  <rule grant="false">
    <type>Root</type>
  </rule>
</filter>

<action id="newSection" link="#{documentActions.createDocument('Section')}"
    enabled="true" label="command.create.section"
    icon="/icons/action_add.gif">
  <category>SUBVIEW_UPPER_LIST</category>
  <filter id="newSection">
    <rule grant="true">
      <permission>AddChildren</permission>
      <type>SectionRoot</type>
    </rule>
  </filter>
</action>

A filter can accept any number of rules. It will grant access to an action if, among its rules, no denying rule (grant=false) is found and at least one granting rule (grant=true) is found. A general rule to remember is that if you would like to add a filter to an action that already has one or more filters, it has to hold constraining rules: a granting filter will be ignored if another filter is already too constraining.

If no rule is set, the filter will grant access by default.

The default filter implementation uses filter rules with the following properties:

Filters do not support merging, so if you define a filter with an id that is already used in another contribution, only the first contribution will be taken into account.

It is important to understand that an action does *not* define the way it will be rendered: This is left to pages, templates and other components displaying it. Most of the time, actions will be rendered as command links or command buttons.

For instance, actions using the USER_SERVICES category will be rendered as action links:

<nxu:methodResult name="actions"
    value="#{webActions.getActionsList('USER_SERVICES')}">
  <nxu:dataList layout="simple" var="action" value="#{actions}"
    rowIndexVar="row" rowCountVar="rowCount">
    <h:outputText value=" | " rendered="#{row!=(rowCount-1)}" />
    <nxh:commandLink action="#{action.getLink()}">
      <t:htmlTag value="br" rendered="#{row==(rowCount-1)}" />
      <h:outputText value="#{messages[action.label]}" />
    </nxh:commandLink>
  </nxu:dataList>
</nxu:methodResult>

The nxu:methodResult tag is only used to retrieve the list of actions declared for the USER_SERVICES category. The nxh:commandLink is used instead of a simple h:commandLink so that it executes commands that where described as action expression methods.

Another use case is the document tabs: actions using the VIEW_ACTION_LIST category will be rendered as action links too, but actions are managed by a specific seam component that will hold the information about the selected tab. When clicking on an action, this selected tab will be changed and the link it points to will be displayed.

A standard JSF navigation rule can be defined in the OSGI-INF/deployment-fragment.xml files, inside the faces-config#NAVIGATION directive.

<extension target="faces-config#NAVIGATION">

    <navigation-case>
      <from-outcome>create_document</from-outcome>
      <to-view-id>/create_document.xhtml</to-view-id>
      <redirect />
    </navigation-case>

    <navigation-case>
      <from-outcome>view_documents</from-outcome>
      <to-view-id>/view_documents.xhtml</to-view-id>
      <redirect />
    </navigation-case>

</extension>

A certain Nuxeo document type, can have defined a default view (used to view/edit the document) and a create view (used to create the document). These views are specified in the OSGI-INF/ecm-types-contrib.xml file, as in the following example.

<extension target="org.nuxeo.ecm.platform.types.TypeService" point="types">    
    <type id="Workspace" coretype="Workspace">
      <label>Workspace</label>
      <icon>/icons/workspace.gif</icon>
      <icon-expanded>/icons/workspace_open.gif</icon-expanded>
      <default-view>view_documents</default-view>
      <create-view>create_workspace</create-view>
    </type>
</extension>

The default view of a document is rendered as a list of tabs. As mentioned before, the document tabs are defined as actions in the OSGI-INF/actions-contrib file, having as category VIEW_ACTION_LIST. A tab can be added to a document default view as shown in the following example.

<extension target="org.nuxeo.ecm.platform.actions.ActionService" point="actions">   
    <action id="TAB_EDIT" link="/incl/tabs/document_edit.xhtml" enabled="true"
      order="20" label="action.view.edit" icon="/icons/file.gif">
      <category>VIEW_ACTION_LIST</category>
      <filter-id>edit</filter-id>
      <filter-id>mutable_document</filter-id>
    </action>
</extension>

The standard widget type "list" is actually a widget of type "template" using a static template path: /widgets/list_widget_template.xhtml. If this default behavior does not suit your needs, you can simply copy this template, make your changes, and use a widget of type "template" with the new template path.

This template assumes that each element of the list will be displayed using subwidgets definitions.

For instance, to handle a list of String elements, you can use the definition:

<widget name="contributors" type="list">
  <fields>
    <field>dc:contributors</field>
  </fields>
  <subWidgets>
    <widget name="contributor" type="text">
      <fields>
        <field></field>
      </fields>
    </widget>
  </subWidgets>
</widget>

The empty field definition in the subwidget is used to specify that each element of the list is itself the element to display.

With nuxeo version <= 5.3.0, to handle a list of complex properties (each entry of the list is a map with keys 'name' and 'email' for instance), you can use the definition:

<widget name="employees" type="list">
  <fields>
    <field>company:employees</field>
  </fields>
  <subWidgets>
    <widget name="employee" type="template">
      <labels>
        <label mode="any"></label>
      </labels>
      <fields>
        <field></field>
      </fields>
      <properties mode="any">
        <property name="template">
          /widgets/complex_widget_template.xhtml
        </property>
      </properties>
      <!-- subwidgets for complex -->
      <subWidgets>
        <widget name="name" type="text">
          <fields>
            <field>name</field>
          </fields>
        </widget>
        <widget name="email" type="text">
          <fields>
            <field>email</field>
          </fields>
        </widget>
      </subWidgets>
    </widget>
  </subWidgets>
</widget>

With nuxeo version > 5.3.0, to handle a list of complex properties (each entry of the list is a map with keys 'name' and 'email' for instance), you can use the definition:

<widget name="employees" type="list">
  <fields>
    <field>company:employees</field>
  </fields>
  <subWidgets>
    <widget name="employee" type="template">
      <labels>
        <label mode="any"></label>
      </labels>
      <properties mode="any">
        <property name="template">
          /widgets/complex_list_item_widget_template.xhtml
        </property>
      </properties>
      <!-- subwidgets for complex -->
      <subWidgets>
        <widget name="name" type="text">
          <fields>
            <field>name</field>
          </fields>
        </widget>
        <widget name="email" type="text">
          <fields>
            <field>email</field>
          </fields>
        </widget>
      </subWidgets>
    </widget>
  </subWidgets>
</widget>

A builtin template has been added to handle complex properties. It is available at /widgets/complex_widget_template.xhtml. It assumes that each element of the complex property will be displayed using subwidgets definitions.

To handle a complex property (the value is a map with keys 'name' and 'email' for instance, you can use the definition:

<widget name="manager" type="template">
  <fields>
    <field>company:manager</field>
  </fields>
  <properties mode="any">
    <property name="template">
      /widgets/complex_widget_template.xhtml
    </property>
  </properties>
  <subWidgets>
    <widget name="name" type="text">
      <fields>
        <field>name</field>
      </fields>
    </widget>
    <widget name="email" type="text">
      <fields>
        <field>email</field>
      </fields>
    </widget>
  </subWidgets>
</widget>

A builtin template has been added to handle sublists: the original "list" widget is equivalent to a widget of type "template" using the file "/widgets/list_widget_template.xhtml". To handle the sublist, this template needs to be changed. The file "list_subwidget_template.xhtml" is available for it since nuxeo version 5.2 GA.

To handle a sublist property, you can use take example on this definition:

<widget name="employees" type="list">
  <fields>
    <field>company:employees</field>
  </fields>
  <subWidgets>
    <widget name="employee" type="template">
      <labels>
        <label mode="any"></label>
      </labels>
      <properties mode="any">
        <property name="template">
          /widgets/complex_list_item_widget_template.xhtml
        </property>
      </properties>
      <!-- subwidgets for complex -->
      <subWidgets>
        <widget name="phoneNumbers" type="template">
          <fields>
            <field>phoneNumbers</field>
          </fields>
          <properties mode="any">
            <property name="template">
              /widgets/list_subwidget_template.xhtml
            </property>
          </properties>
          <subWidgets>
            <widget name="phoneNumber" type="text">
              <label mode="any"></label>
              <fields>
                <field></field>
              </fields>
            </widget>
          </subWidgets>
        </widget>
      </subWidgets>
    </widget>
  </subWidgets>
</widget>

The field type tells the search engine how to process the field. This is a mandatory, case-insensitive, attribute.

The following table summarizes the available types. The listed Java classes are guaranteed to work. The backend might implement more converting facilities.

Although the Search Service is meant to provide an unified abstraction on the tasks of indexing and querying, text fields have to be somewhat an exception. Indeed, search engines have very different capabilities, depending on provided analyzers. They are nonetheless all expected to provide a direct syntax for full text searches, that an end user can use from, e.g., an input box on a web page. Given the very special kind of constraint that indexing a text field represents, it's not guaranteed that exact matches are supported.

See Section 11.4.4, “Text fields behavior” from the documentation of the Compass backend to get a more concrete view on this (with examples).

On a multi-valued field, the = operator is true if the right operand belongs to the set of field values. The IN operator is true if the intersection between the set of field values and the right operand is non empty.

SELECT * FROM Document WHERE dc:contributors = 'sally'

SELECT * FROM Document WHERE dc:contributors IN ('sally', 'harry')

This behavior is in conformance with the JCR specification, which states it the following more general terms:

The following fields are available on all document resources. They don't correspond to document fields and aren't configurable, that's why they're called pseudo-fields.

The names of these fields are synchronized with constants from the class BuiltinDocumentFields. Any use from java code should rely on these.

All Compass specific configuration files are relative to the classpath of the compass plugin. A default configuration is provided for Nuxeo EP 5 WebApp. To customize it, one sadly has to put the configuration at the right place within the backend's JAR.

Here is an ant fragment to perform this in a JBoss context, assuming that the Search Service has already been installed in the application server and that the server's deployment directory is stored in the deploy.dir property.

<copy todir="${deploy.dir}/nuxeo.ear/system/nuxeo-platform-search-compass-plugin-1.0.0-SNAPSHOT.jar"
      overwrite="true" failonerror="false">
  <fileset dir="src/main/resources">
    <include name="myfile.xml" />
  </fileset>
</copy>

The backend's JAR is included as a directory in nuxeo.ear during the Maven build of nuxeo-platform-ear for this single purpose. This is prone to change in the future.

The Compass backend itself is registered against the Search Service through the searchEngineBackend extension point of org.nuxeo.ecm.core.search.service.SearchServiceImpl. Your component can use the configurationFileName element to specify a path to the master configuration file, like this:

<searchEngineBackend name="compass" default="true"
    class="org.nuxeo.ecm.core.search.backend.compass.CompassBackend">
  <configurationFileName>/mycompass.cfg.xml</configurationFileName>
</searchEngineBackend>

The default path is /compass.cfg.xml.

Compass supports several storage possibilities, called connections in Compass configuration objects. The configuration is done trough a Nuxeo Runtime extension point and possibly within the Compass master configuration file. The extension point always takes precedence over the Compass file, but can be used to fall back to Compass file, that offers currently more possibilities.

The target is org.nuxeo.ecm.core.search.backend.compass.CompassBackend, and the point is connection. Contributions are made of a single XML element; the latest one wins.

To set the connection to a file system Lucene store, put a file element in the contribution, and set the path attribute to the target location. If the path doesn't start with /, it will be interpreted as being relative to Nuxeo Runtime's home directory, e.g, /opt/jboss/server/default/data/NXRuntime in the default Nuxeo EP installation on JBoss.