Table of Contents
Objective: Create a new document type with its own unique meta-data. Understand the basics of Nuxeo projects' structure, build process, and deployment.
Minor things can become moments of great revelation when encountered for the first time. Margot Fonteyn, English ballerina ( 1919 - 1991 )
If you have any comments, questions, or general-purpose harassment you would like give us about this book, then please use the comment form at the bottom of each page! We promise that we will try to incorporate any feedback you give (minus the profanity, of course), will respond to your questions, and credit you appropriately.
Back in the first lesson, we explained that we would expect you to use Eclipse to compile Nuxeo programs and Maven to deploy them. While that was true, it was true in the sense that "Darth Vader betrayed and murdered Luke's father," that is, from a certain point of view. A more complete answer is that Eclipse and Maven have to be convinced to peacefully co-exist so that you can use them each for the purpose they are best suited-and that their duties substantially overlap. At various times, each will be used to accomplish the task of building a Nuxeo bundle, for example. Maven is quite particular about the layout of project files and Eclipse can handle almost any layout, so we will now discuss how to layout your files in the arrangement preferred by Maven.
You may be tempted to use one of the Eclipse plugins that allows Maven to be run from within Eclipse, such as m2eclipse. The authors have extensive experience with Maven, eclipse, and these plugins and have found them to consistently cause much more trouble than they are worth for a beginning developer on Nuxeo: trust us, you don't want to go there! An example difficulty with using Maven-in-Eclipse plugins is that the build and test classpaths for Nuxeo bundles are quite large and complex and, at best, the use of Maven for building will make your builds so slow that they cannot be done interactively; without the plugins, Eclipse caches enough information to do builds as you type without trouble, even on a computationally weak machine. At worst, Maven plugins can become confused about how to run your test harness and actively change (destroy) your Eclipse setup! Trust us, if you have a Maven plugin for eclipse in your eclipse this is a good time to remove it.
The set of directories that you should use when building a Nuxeo bundle, also referred to as a Nuxeo plugin, is shown in this listing of what happens when you check out the skeleton of lesson4 (explained below):
$ svn co http://svn.nuxeo.org/nuxeo/sandbox/iansmith/book/lesson-bundle
A lesson-bundle/src
A lesson-bundle/src/test
A lesson-bundle/src/test/java
A lesson-bundle/src/test/resources
A lesson-bundle/src/main
A lesson-bundle/src/main/java
A lesson-bundle/src/main/resources
A lesson-bundle/src/main/resources/META-INF
A lesson-bundle/src/main/resources/OSGI-INF
Briefly, we will discuss the purpose of the directories in
lesson-bundle above. The src
directory and its children are the primary focus of interest for
developers. The top level division into main and
test subdirectories is to differentiate between the
bundle's implementation, in main, and the code used
to test the bundle in test. Each of these directories
has two children, java and
resources, to distinguish between Java code and all
the other support files needed. Within the Java directories, the usual
Java convention applies, a production Java class with the fully qualified
name org.nuxeo.foo.MyClass found in the file
src/main/java/org/nuxeo/foo/MyClass.java . Within the
main directory, you can see the
META-INF and OSGI-INF
directories that were discussed in the previous lesson. This layout is
quite standardized for Maven projects and although there are many more
options possible for Maven projects, this arrangement is instantly
recognizable to anyone with experience using Maven.
To make this project a bit easier to get started, we have prepared
a skeleton for you to start from, with all the directories and files in
the correct structure as explained above. We will make a new
subdirectory of /nuxeo called
/nuxeo/workspace to be used as the Eclipse
workspace for all the remaining projects. Retrieve the project skeleton
from Nuxeo's subversion repository and unpack the skeleton to create the
directory lesson-bundle that you will use in
Eclipse as your project.
iansmith@Photo /nuxeo $ mkdir workspace iansmith@Photo /nuxeo $ cd workspace iansmith@Photo /nuxeo/workspace $ mvn -Declipse.workspace=. eclipse:add-maven-repo iansmith@Photo /nuxeo/workspace $ svn export http://svn.nuxeo.org/nuxeo/sandbox/iansmith/book/lesson-bundle/ iansmith@Photo /nuxeo/workspace $ cd lesson-bundle iansmith@Photo /nuxeo/workspace/lesson-bundle $ ls -F pom.xml* src/
There is mvn command in the listing above
that initializes the Eclipse workspace. The syntax provided is for the
most common version of the Eclipse support in Maven (version 2.4).
This command simply creates a single Eclipse variable
M2_REPO. If you find that your version of Maven
does not support this command (it is currently deprecated, but still
available, in version 2.5 of the Eclipse support for Maven) you may
want to try using configure-workspace instead of
add-maven-repo.
This lesson and several upcoming lessons will be about building a new type of document, Upcoming which repesents an upcoming event as we explained in the first chapter to this book. For this lesson, our goal, roughly, is to be able to create this new type of document through the Nuxeo web user interface. An example of an Upcoming document would be a document that describes a concert that will occur at some point in the future. Obviously, there are a number of special types of meta-data associated with upcoming events, such as when they will occur and how much they cost to attend. We will be filling out the definition of this new document type as we proceed through the lessons.
Go ahead and use Maven to create our Eclipse project files (!) with a command like this:
iansmith@Photo /nuxeo/workspace/lesson-bundle
$ mvn eclipse:eclipse
Since you have never used Maven with Nuxeo before, or perhaps have never used it all before, do not be alarmed if Maven begins wildly downloading a great many things from the internet; instead, go get a cup of coffee-this will take a few minutes. It only happens the first time you use Maven with Nuxeo. When this completes, you should see a "build successful" message like this:
[INFO] Wrote settings to C:\nuxeo\workspace.lessons\lesson-bundle\.settings\org.eclipse.jdt.core.prefs [INFO] Wrote Eclipse project for "lesson-bundle" to c:\nuxeo\workspace.lessons\lesson-bundle. [INFO] [INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 36 seconds [INFO] Finished at: Wed Jan 21 16:47:44 EST 2009 [INFO] Final Memory: 25M/45M [INFO] ------------------------------------------------------------------------
Note that the build above only took 36 seconds! If you don't see a message like that at the end of your mvn output, you probably have something wrong with either your internet connectivity or your Maven configuration.
To import the project into eclipse, start up eclipse and use
/nuxeo/workspace as the workspace. Then you can use
the File Menu's Import option, hereafter written as File >
Import, and choose the General option from the dialog box that
appears. Choosing General will open up a few more choices and you should
select Existing Projects into Workspace. From here on, will write a
selection like this with square brackets around it to indicate a dialog
box and we use the plus sign to indicate a sub-choice and so importing
this existing project would be written as [ General + Existing
Projects into Workspace ] and is shown graphically in this
screen shot:
After you click , you can use
the button next to the choice to choose the
lesson-bundle directory created above. Don't choose
any of it's subdirectories. After you click ,
you should see a project layout like this in your Eclipse Package
Explorer:
Some things may vary in your particular Eclipse. First,
you may have a slightly different JRE version than shown above. More
important, you must insure that the only two directories that Eclipse
should look in for source code are src/main/java and
src/test/java. You can correct any errors, such as
those shown above, by using Project > Properties
with lesson-bundle selected as above, and then choosing Java Build Path
and the tab for Source. We write the last command of these as
Java Build Path ->> Source. To remove a source
directory, you should click on it's name in the dialog and then click the
button as is shown below:
We'll start by writing a manifest file for our bundle. Create this
file by selecting the directory
src/main/resources/META-INF in the Package Explorer
and then use File > New > File to create the
new file. It must be named MANIFEST.MF so it can be
found by the container. The contents of this file should be:
Manifest-Version: 1.0 Bundle-ManifestVersion: 1 Bundle-Name: lesson on first bundle, project Bundle-SymbolicName: org.nuxeo.book.upcoming;singleton:=true Bundle-Version: 0.0.1 Bundle-Vendor: your name Nuxeo-Require: org.nuxeo.ecm.core, org.nuxeo.ecm.core.schema Nuxeo-Component: OSGI-INF/schema-contrib.xml, OSGI-INF/doctype-contrib.xml, OSGI-INF/ui-contrib.xml
If you do not remember what some of
these lines mean you can check back with the previous lesson. The
required bundles for this project are the core ECM capabilities of Nuxeo
and the schema support from the core. [Definition: In Nuxeo, a document
schema is a set of properties that are associated
with a document.] A document can be, and usually is, a
composite of many schemas. We often say "associated" or "attached" when
referring to schemas and their relationship to documents. Most documents
have the dublincore schema attached to them.
dublincore provides a number of basic properties that most
documents need, such as title,
creator, and dateCopyrighted.
(If you would like to read more about the dublin core meta-data
initiative, you can find that information at
http://dublincore.org/.) Since Nuxeo's repository and web
user interface already understand the dublincore schema,
there is no reason for us to duplicate any of these properties. Nuxeo
developers usually write a property and the schema that defined it using
this notation, dublincore:title or using the
schema's abbreviation like this dc:title, and we will do so
in this book.
In a previous lesson on running the Nuxeo 5 server, we suggested some exercises for you to try with the Nuxeo EP Server's web user interface. When you were manipulating the properties of a document, you were actually changing properties of schemas that are shipped with Nuxeo, for example title property of the dublincore schema. Although as a user you think of the web interface as "being" the Nuxeo server, in reality the interface is just a view into in the underlying repository. Writing a program to change a property has exactly the same effect as changing it through the web interface.
Be careful about ordering with your contributions listed on
the Nuxeo-Component line above. They need to
remain in the order shown! There are dependencies between the
contributions: The schema contribution must come before
contributions that reference it, in this case the doctype
contribution, and similarly these a dependency on this ordering
between the doctype and the ui contribution. This is always true
with the Nuxeo-Component line: ordering in this line implies a
dependency and the order the contributions are made.
Another problem that can happen with manifest files is bad formatting. As shown above, you want to have "continued" lines indented by one space from their predecessors. More subtle is to leave a trailing comma at the end of the list of required bundles or the list contributions. If you do so, your bundle will not be loaded properly and you are likely to get an error saying in the log of JBoss/Nuxeo that the bundle cannot be resolved.
The manifest file above says that our bundle will be making three
contributions to extension points. The contributions will all be found
in the OSGI-INF directory of the final
bundle.
In the final bundle schema-contrib.xml will
be located at OSGI-INF/schema-contrib.xml but in
the Eclipse project it is located at
src/main/resources/OSGI-INF/schema-contrib.xml.
As before, create this file using File > New >
File with the OSGI-INF directory
selected and name the file as shown in the manifest file. The ability
to add your own meta-data to documents is a key ingredient of the
power of the Nuxeo platform. The contribution is as follows:
<?xml version="1.0"?>
<component name="org.nuxeo.book.upcoming.schema">
<extension target="org.nuxeo.ecm.core.schema.TypeService" point="schema">
<schema name="upcoming" src="schemas/upcoming.xsd" prefix="up" />
</extension>
</component>What is this, no meta-data definition? Not
yet. This is a contribution to the TypeService bundle at
the extension point schema. We have told the
TypeService about our new schema,
upcoming (with a lower case 'u' indicating it is a
schema) and we have told the extension point where to read the
definition, the file schemas/upcoming.xsd. This
file name is relative to the root directory of the bundle, so the path
in the final bundle would be schemas/upcoming.xsd
and in the Eclipse project
src/main/resources/schemas/upcoming.xsd. The
final part of the schema tag creates
namespace for our schema so we can refer to a
property foo of our schema as
up:foo (more on namespaces in just a
moment).
To actually define the fields of meta-data for upcoming, create
the file src/main/resources/schemas/upcoming.xsd
in Eclipse and use this content:
<?xml version="1.0"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" targetNamespace="http://nuxeo.org/schemas/upcoming/" xmlns:up="http://nuxeo.org/schemas/upcoming/"> <xs:element name="occursOn" type="xs:dateTime" /> <xs:element name="presenter" type="xs:string" /> </xs:schema>
If you have experience working with XML, you'll recognize this
as an XSD or XML Schema Descriptor. Whether or
not you have experience with XML, be sure to note that this file is
not a contribution to an extension point! If it
were a contribution, it would have been referenced in the
MANIFEST.MF file in the
Nuxeo-Component line! The first tag,
xs:schema is to define the XML namespace used by our
schema. We defined this in the schema contribution file as "up" and it
is good practice that they match (both use "up" in our example files)
and that targetNamespace attribute point to a URL that uniquely
identifies the schema. The critical nodes in this file are the two
xs:element nodes that define our meta-data's field names,
occursOn and presenter, and the
data type of each of our new fields.
So, we now are beginning to see how an Upcoming
document type might be used! We can set the date and time that the
event occurs, upcoming:occursOn, and we can set who
(or what organization) is going to be presenting the event,
upcoming:presenter. These values might be something
like 'Feb-2-2015-19:00:00' and 'the Rolling Stones',
respectively.
Create the doctype-contrib.xml file the
same way as our previous contribution to the schema
extension point. Here is the content of
doctype-contrib.xml:
<?xml version="1.0"?>
<component name="org.nuxeo.book.upcoming.doctype">
<extension target="org.nuxeo.ecm.core.schema.TypeService" point="doctype">
<doctype name="Upcoming" extends="Document">
<schema name="common" />
<schema name="dublincore" />
<schema name="upcoming" />
<schema name="file" />
<schema name="uid" />
<facet name="Commentable" />
<facet name="Versionable" />
<facet name="Indexable" />
</doctype>
</extension>
</component>At this point, all the details of this file
are not critical, but there are a couple of things to notice. First,
the extension point doctype in the Nuxeo-supplied
bundle TypeService is the same bundle as in the previous
section, but a different extension point. This extension point is
being advertised for creating new document types and we are
contributing the new type Upcoming to this extension
point (we use an uppercase 'U' for the document type). This document
type is a composite of a number of different schemas, including the
dublincore schema we discussed before. Another part of
the Upcoming document type is the schema upcoming that we
defined just a moment ago (with the lower case 'u'); this new schema
is where we can add our own meta-data to the document. The facets
shown in this example indicate to the extension point that we would
like some of the standard functionality for manipulating documents in
the UI, such as the ability to add comments and have many versions of
the document.
In some configurations of Eclipse, creating a new XML or XSD file causes Eclipse to try to use a "pretty" editor rather than just allowing you to edit the file's text. You can tell if you are in this state if, when you create a new XML file, you see something like this in your Eclipse editor.
The document is empty. Right mouse click here to insert content.
Although this type of "structural" editor is nice in some circumstances, it is important for these lessons that you edit the "raw" XML source code. You can always access this in eclipse by using the tabs at the bottom of the editor. Try clicking on the one labelled to edit text normally.
This contribution is one that is not strictly required to create
a new type of document with its own meta-data fields. This
contribution, though, is necessary if you want to have the
satisfaction of seeing your new datatype through
the web UI of Nuxeo. It should not come as a surprise, after some
thought, that a system as large and configurable as Nuxeo's ECM
solution will place some small burdens on new document types to "play
nicely" within the Nuxeo system. We will contribute the minimal amount
to the user interface that is possible and still be able to see our
Upcoming events. You should create this file in the same
way as the other contributions, in the OSGI-INF
directory:
<?xml version="1.0"?>
<component name="org.nuxeo.book.upcoming.ui">
<extension target="org.nuxeo.ecm.platform.types.TypeService" point="types">
<type id="Upcoming">
<label>Upcoming Event</label>
<default-view>view_documents</default-view>
<layouts mode="any">
<layout>heading</layout>
<layout>file</layout>
</layouts>
</type>
<type id="Workspace">
<subtypes>
<type>Upcoming</type>
</subtypes>
</type>
</extension>
</component>There are two "contributions" to the
type extension point of the
TypeService in this file. If you have been paying close
attention, you will have noticed that we have now used three different
extension points (types, schema,
and doctype) of the TypeService; no
surpise, since our objective in this lesson was to create a new
document type! The two contributions in the
ui-contrib.xml declare two different things.
First, that the type (more directly, the document
type) Upcoming has some display properties such as a
textual label, "Upcoming Event." We will discuss views and layouts in
an upcoming lesson, but for now you can assume that we are selecting
some default output choices so that an Upcoming document
will look like other file types you have seen in the web UI of
Nuxeo.
The latter declaration concerns the Workspace document type that you first encountered when you were exploring the Nuxeo UI in a previous lesson. In effect, this declaration says that an Upcoming document is a "subtype" of Workspace. The effect of this declaration is that workspaces can contain upcoming events as you view them on the web. This is an important property: based on this declaration about the type relationship between Upcoming and Workspace, an upcoming event cannot be seen, for example, within a Folder in the Nuxeo UI.
There is another file that must be placed in
the OSGI-INF directory, although it is not a contribution to any
extension point. This file must be named
deployment-fragment.xml and it describes activities
that the container needs to perform when the bundle is loaded. A
deployment fragment might, for example, install various files in
directories so that they can be used by other contributions or java code
in the the bundle. For this simple bundle, one need only declare that we
are a module and part of the larger (Nuxeo EP Server)
application:
<?xml version="1.0"?>
<fragment>
<extension target="application#MODULE">
<module>
<java>${bundle.fileName}</java>
</module>
</extension>
</fragment>
This nomenclature is really confusing: We have bundles, components, plugins, extensions, and now modules. Why so many?
With all that we have covered in this section you should now have
eight six files in your Eclipse project. The
MANIFEST.MF file is in the
META-INF directory and points at three other files,
these three contributions to extension points are in
OSGI-INF and all end in
-contrib.xml, the deployment fragment is also in
OSGI-INF, and the crucial file for all this work,
upcoming.xsd, is alone in the
schemas directory and referred to by the
schema-contrib.xml contribution. It is worth noting
that only the deployment-fragment.xml and
MANIFEST.MF have strictly specified filenames in
the bundle by the Nuxeo infrastructure. These are specified because
these files these must be found without any help by Nuxeo as the bundle
is loaded. All the other files are found by reading the filenames from
other files.
Since this lesson requires no java code, you do not need to use Eclipse to compile your code code-or test it. We will return to the command line to build and install the bundle with Maven. To compile the files into a bundle:
iansmith@Photo /nuxeo/workspace/lesson-bundle
$ mvn clean install
This mvn command cleans up from any previous build and builds the resulting jar file into the target directory. As Maven runs, you should see Maven inform you that there are no java files to compile and no tests to run. (These come in a future lesson!) After doing its job you should see the usual Maven success message, something like this:
[INFO] ------------------------------------------------------------------------ [INFO] BUILD SUCCESSFUL [INFO] ------------------------------------------------------------------------ [INFO] Total time: 23 seconds [INFO] Finished at: Wed Jan 21 21:25:29 EST 2009 [INFO] Final Memory: 28M/50M [INFO] ------------------------------------------------------------------------
You can now copy the bundle into your installation of Nuxeo 5 EP
server and restart the server, as shown below. (If your server is
currently running, you should shut it down first using one of the scripts
in the bin directory of
NuxeoServer.)
[/nuxeo/workspace/lesson-bundle] $ cp target/lesson-bundle-0.0.1.jar /nuxeo/tools/NuxeoEP5/NuxeoServer/server/default/deploy/nuxeo.ear/plugins/ [/nuxeo/workspace/lesson-bundle] $ cd /nuxeo/tools/NuxeoEP5/NuxeoServer/ [/nuxeo/tools/NuxeoEP5/NuxeoServer] $ bin/run.sh
The first command above copies the output of the maven build
process, called lesson-bundle-0.0.1.jar, into the
designated area for "plugins" (a.k.a. user-written bundles) to the Nuxeo
system.
Once the server starts up (the 2nd and 3rd commands above), log in is Administrator and go to the section of the interface for Workspaces. If you do not have any workspaces, you should create one-the name doesn't matter-using the button. Click on any workspace and then click the button (its under the tab) and you should see some choices for document types like this:
Success! If you go ahead and try to create one of these documents you will not notice anything different from creating any other type of file. You will have to trust the authors that, in fact, there are some extra meta-data fields associated an Upcoming Event and that these can be changed and searched for. You will see these for yourself soon enough. We have yet to tell Nuxeo much about how we want the UI to look, we did not even specify an icon for the Upcoming Event type shown above, so it appears out of "alignment" with the other document types. Improving the UI to this new document type might make for an interesting lesson...
If you return to the listing of the workspace you created the upcoming event in, you will see the upcoming event listed in the contents of the workspace with the title you have supplied. You should see a display in the workspace content something like this:
At this point, you have created a new document type with new fields that are specific to your application! Don't worry, we'll fix the problem with the crowded display shortly. The strange display is caused because we made the programming error (!) of not teaching you yet how to include an icon for the type Upcoming.
Allow Upcoming documents to be created inside Folders as well as Workspaces. Verify that this works properly through the UI by creating a Folder inside a Workspace and then an Upcoming document in the Folder.
Add another meta-data field to the Upcoming document, the admissionPrice field. This field should be a floating point value.