Table of Contents
This chapter describes how to setup a development environment for working on Nuxeo EP. It currently deals with an Eclipse environment and will be completed soon with Netbeans and IDEA.
You will see how to easily start a new project. If you encounter a problem don't forget you can share your experience on the ecm mailing list.
We assume from now on that on your computer, you have the following ready-to-use environment:
Java Development Kit (JDK) 1.5.x (Nuxeo EP is known to work now with Java 6 or OpenJDK, but this is currently not supported)
Apache Ant 1.7.0 (or later), from http://ant.apache.org/.
Maven 2.0.8 (or later, not Maven 2.0.7), from http://maven.apache.org/.
Eclipse 3.3
A Nuxeo EP installation from the last release (download the installation
wizard). You can also download a nightly build installer from http://www.nuxeo.org/static/snapshots/ but keep in mind that
this one may be broken, so don't erase your working setup with a nightly build: the
result is not guaranteed.
Note : The Nuxeo EP installer also installs and sets up the right version of JBoss on your computer, so you don't need to install it by your own.
If some of these software are not already set up on your computer, please refer to Appendix B, Detailed Development Software Installation Instructions, where you will find useful help.
Before starting, if for you mvn sounds like an other more boring acronym to learn, you should read these few lines, otherwise, you can skip it and go to the next step.
Maven is an IT project helper, that structures the development process in many ways:
it helps you using always the same code organization, so that everybody in the company works the same way
it allows you to apply in an easy and standard way many tools to your application and your application source: tools for testing, quality, deployment, documentation site generation, etc.
it simplifies a lot the way you manage dependencies in your projects by using the pattern of public / local repository.
Depending on how deep you will go with Nuxeo, you may use part or all of the
aforementioned items. But for now, we will have special attention for
repositories, pom and
dependencies. When you start a project under eclipse, you usually begin
by downloading then adding all the libraries you will need, and put them all in a
subdirectory of the project. You may have some libraries copied many times, like
JUnit. And after some time you may end up with many versions of
the same libraries in different places of your projects.
Maven is really useful for that. When you
start a project, you create a pom.xml which will contains all the
information Maven needs to act. Especially, it will contain the dependencies of your
project. The dependencies are the libraries you usually add with the "add external jar"
command under Eclipse. In Maven terminology, it is called an artifact.
So you specify in pom.xml which artifacts you need and which version.
At compilation time (of course with Maven) it will automatically find the jar corresponding
to the artifacts specified, so that there are no "no class found" error.
How does Maven know where to find it?
Maven uses repositories of artifacts (libraries) One of the goals
of Maven is to gather all of the code production in the same place, in company or public
scoped repositories, so that everybody shares the same libraries and knows where to find
them. There are the official an public Maven repositories, automatically inspected when
using Maven, but you can also set up private repository like Nuxeo's. You declare the repositories
you want your Maven installation to look up into in
$HOME/.m2/settings.xml. Maven will download the needed dependencies
from those specified repositories into the $HOME/.m2/repository
directory, that acts as a "cache".
Then, suppose you want to compile your project with Maven. Maven will read the
POM, see that it needs, for instance the JUnit library. It will check
if this library is present in the local Maven repository $HOME/.m2 and
if not, it will check in a remote one. For sure, it will look into Maven repository, and
maybe some private remote repositories you might have set up in your
$HOME/.m2/settings.xml file. At compilation time, if your code uses a
JUnit TestCase class, it will know it has to go to the repository to download
the dependency.
If you manage all your projects with Maven, you will save a lot of time at the beginning of the project, and your deployment procedure will be more reliable. So Nuxeo is developed through a full Maven process. And we encourage people who wants to develop over Nuxeo to also use Maven.
To achieve this, when you start a new project with Nuxeo, you will have to create your
own pom.xml that will reference Nuxeo libraries, for document
manipulation, etc. A POM represents a project, a resource, and has three main
characteristics: its name, its domain and its version. Then it has a lot of XML to specify
everything you want. For a Nuxeo project, you have to reference Nuxeo artifacts. So starting
a new project with all this structure is tedious and always the same.
To avoid doing the Maven packaging by hand, we prepared for Nuxeo platform users a
Maven archetype, that acts as a template system: we defined the
typical structure and POM of a Nuxeo Customization project and then, typing a command as
short as mvn archetype and a few parameters, Maven will auto-generate the
structure of your project, and you are sure it will be Nuxeo compliant.
You can also read the Wikipedia entry for Maven and the Maven archetype introduction for more information about archetypes.
The goal of the nuxeo-archetype-start template is to setup a development environment to work on a Nuxeo EP plugin.
The default code provides: a maven layout for sources, tests and dependencies, a Ant target for deployment. It also customizes the web application a litte bit.
To create a project named my-project in the
com.company.sandbox.myproject package:
mvn org.apache.maven.plugins:maven-archetype-plugin:1.0-alpha-7:create \
-DartifactId=my-project \
-DgroupId=com.company.sandbox.myproject \
-DarchetypeArtifactId=nuxeo-archetype-start \
-DarchetypeGroupId=org.nuxeo.archetypes \
-DarchetypeVersion=5.1.4 \
-DremoteRepositories=http://archiva.nuxeo.org/archiva/repository/nuxeo_release
You can see that you need to supply six arguments:
artifactId: the name of your project, usually with '-' to separate the words if there are many.
groupId: the domain name of your project. Usually it is the package parent name of your classes, you should use '.' to separate the words ('-' is not supported here).
archetypeArtifactId: the maven archetype artifact id. To generate a new project, Nuxeo provides you with nuxeo-archetype-start
archetypeGroupId: unique for all nuxeo maven archetypes : org.nuxeo.archetypes
archetypeVersion: the version of the archetype which is equivalent to the version of Nuxeo EP without the GA or RC part. (5.1.4, ...).
remoteRepositories: the repository location to download the archetype.
The warnings you see when creating your project are expected. If you see BUILD SUCCESSFUL at the end, your project was created successfully.
You should have the following source layout:
my-project
|-- README.txt
|-- build.properties.sample
|-- build.xml
|-- pom.xml
`-- src
|-- main
| |-- java
| | `-- com
| | `-- company
| | `-- sandbox
| | `-- myproject
| | `-- DocEventListener.java
| `-- resources
| |-- META-INF
| | |-- MANIFEST.MF
| | `-- ejb-jar.xml
| |-- OSGI-INF
| | |-- deployment-fragment.xml
| | |-- event-listener-contrib.xml
| | |-- l10n
| | | |-- messages.properties
| | | |-- messages_en.properties
| | | `-- messages_fr.properties
| | `-- theme-contrib.xml
| |-- nuxeo.war
| | `-- img
| | |-- default_logo.gif
| | `-- login
| | `-- login_01.jpg
| |-- seam.properties
| `-- themes
| |-- nxfonts.properties
| `-- theme-sample.xml
`-- test
|-- java
| `-- com
| `-- company
| `-- sandbox
| `-- myproject
| `-- TestDocEventListener.java
`-- resources
|-- META-INF
| `-- MANIFEST.MF
`-- log4j.properties
You should create a build.properties file on
the base of the build.properties.sample so that
jboss.dir points to your jboss path. This
build.properties file will be used by
Ant to send the packaged file in the good
directory at deployment time. Note that when using the Nuxeo EP
installer, the JBOSS home directory is the same as the Nuxeo EP home
directory.
If you try to import your project into Eclipse right now, you will see many errors in
the source. This is because Eclipse is unaware of the classpath. Indeed when you (used to
;-) ) do the "add library" operation from Eclipse, it creates into the project directory a
.classpath file. So Maven (thanks to a plugin it will auto install)
generates this file for you, providing that you execute the following commands, at the root
of your newly created project:
mvn install mvn -Declipse.workspace=/the/full/path/to/your/workspace eclipse:add-maven-repo mvn eclipse:eclipse
The mvn eclipse:eclipse can be quite long
as it download all available package sources, this can be configured with
the downloadSources property in the
pom.xml file.
Now you can run Eclipse, and import the project from the file system as you are used to:
Then go back to the Java perspective and import the projects you have previously checked out as eclipse projects:
File > Import > General > Existing Projects Into Workspace
You can see on the left the Nuxeo project structure (directly inspired from Maven project structure) and you can browse the classes without errors.
You can navigate in the whole Nuxeo EP sources if you have keep the
downloadSources option.
Note: if you still have errors, it might be that the M2_REPO variable
has not been set up correctly. This variable should point to your home Maven repository,
generally here : $HOME/.m2/repository. To check, create or update this
variable in Eclipse, right-click on your project, choose "properties". Then in the "Java
Build Path" entry, click on "Add variable" (see here for detailed instructions).
Now that you have created your new custom project, you would want to see what your (not so tough) work produced? As easy as one line of command!
On your project root folder (provided you created the right build.properties, as mentioned earlier):
ant deploy
This will run Maven, install the needed dependencies if needed, compile the code, do the packaging and copy it onto the server directory.
Run your server (.../NUXEO_HOME/bin/run.sh or .bat), go to
http://jboss_host:8080/nuxeo/
Try to log with Admin signature (Administrator/Administrator) and to create a new document: if your project was correctly deployed, you should now see a "Book" document type.
Do you still find mvn as a boring command? :-)
The xhtml pages refresh period is controled by facelets and set by default to -1 (no refresh) for performance reasons. When developing, you will find it useful not to have to restart jboss when performing changes in xhtml pages. Since releases 5.1.5 and 5.2-M2, you can add the line "facelets.REFRESH_PERIOD=2" to the nuxeo.properties file in the nuxeo.ear/config folder: pages will be refreshed within 2 seconds.
The nxthemes framework has its own caching, so do not forget to hit the "refresh" button in the themes management page for changes to be taken into account outside of the "main" themes fragment at the center of a nxtheme page.
Nuxeo provides a sample project that you can find at org.nuxeo.project.sample. This sample project implements more customizations: a new document type, a new action, a new event listener, etc. Play with this example to start learning Nuxeo.
This Nuxeo Book is getting to be the most complete source of information around Nuxeo EP, both for beginners and advanced developer. It is a good start.
The extension point documentation is also very useful: although you may find it rough, it is the best way to evaluate the Nuxeo extensibility potential, and one should always start with a quick look around all the extension points, to "think Nuxeo" before starting a new project, and not reinventing the wheel.
The wiki: we try to reference all the documentation from the wiki welcome page, and you will find tricks, howtos, etc. If you want to have a writer account to help update the content, ask on the Nuxeo's mailing list.
The JBoss IDE has been morphed into the JBoss Tools (aka Exadel Studio, aka Red Hat Developer Studio). We're going to evaluate this new offering to understand how it can fit into the Nuxeo development process.
The JBoss IDE offers many useful features when dealing with JEE 5 projects, for creating EJB, managing Hibernate, etc. Especially, the JBoss IDE packaging contains JBPM Designer. You would want to use JBPM designer for writing new workflow procedures to leverage the default embedded JBPM implementation of Nuxeo EP workflow abstraction layer.
Here are the references for the Eclipse Update Manager:
Name: EMF Update Manager Site URL: http://download.eclipse.org/modeling/emf/updates
Name: JBoss IDE URL: http://download.jboss.org/jbosside/updates/development
The second site has dependencies on the first one: use the "Select required" to check EMF automatically when selecting JBossIDE.
Use case: suppose you just deployed Nuxeo EP on your JBoss server and run into a new crash or any unexpected behavior. Instead of stopping the server and rerunning inside Eclipse to reproduce the bug in the debugger, you can setup a new remote debugging profile for Eclipse.
Linux: edit /opt/jboss/bin/run.conf, add the following line
at the end of the file and restart
JBoss.
JAVA_OPTS="$JAVA_OPTS -Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n"
Windows: edit JBOSS/bin/run.bat, modify the line:
rem set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=y %JAVA_OPTS%
by erasing the remark ('rem'), and disabling the suspend ('suspend=n'). You should have:
set JAVA_OPTS=-Xdebug -Xrunjdwp:transport=dt_socket,address=8787,server=y,suspend=n %JAVA_OPTS%
Restart JBoss.
Then from Eclipse create a new debugger profile in menu > create a new Remote Java Application profile and set the source to the filesystem directory that host your complete Eclipse workspace and set the port to 8787.
Then edit the offending source code file and set breakpoints and run your new remote debug profile. From your web browser, refresh the page that was crashing and look back into Eclipse: the debug perspective should open automatically at your fist breakpoint.
Many Eclipse plugins allow you to browse JCR compliant repositories (the very back-end of Nuxeo uses, as a default storage system, the JackRabbit JCR reference implementation repository.
JCR Browser is available here: http://sourceforge.net/projects/jcrbrowser/
IntelliJ IDEA from Jetbrains is a very lovable IDE for Java that has many fans in the Java developers community. It is unfortunately not open source.
To start using IDEA for coding on the Nuxeo project, you just need to type mvn
idea:idea from your top-level source directory: Maven will download all the
dependencies, then generate the configuration files needed by IDEA and you will be able open
nuxeo-ecm.ipr from IDEA.
At the time of this writing, IDEA will report some (spurious) compilation failures and you won't be able to compile the whole application from IDEA. You can still use IDEA with the current configuration to write Java code ("with pleasure"), and use Ant and/or Maven to build/deploy the application.