Getting Started

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