==============================================================================
 README FOR JAHIA SOURCE CODE
==============================================================================

 All source code, binaries and documentation is copyrighted (c) 2002-2011 by
 Jahia Solutions Group SA. All Rights Reserved.

 INTRODUCTION
------------------------------------------------------------------------------

 Welcome to Jahia's source code! This code is provided under the Jahia Source
 Code License Agreement. You must comply to the agreement before using this
 code in any way, including reading it. Sorry for the mumble jumbo but there
 are people trying to make a living while producing this code and would like
 to bring more so it helps if people play fair :)

 USING THIS SOURCE CODE (QUICKSTART)
------------------------------------------------------------------------------

 Requirements:
 - JDK 1.5 or later 
 - Maven 2.1 / 3.x
 - Subversion client (for Windows at http://www.collab.net/downloads/subversion/
   for Mac OS X from http://www.finkproject.org/ or Xcode tools, under
   Linux install a subversion client from your package repository). Basically,
   you need to have an "svn" command available in your PATH so that the build
   system can calculate the build number
 - (Optional) JetBrains IntelliJ IDEA 7.0.3 or later

 Here is quick start steps to use this source code:

    1. Make sure you have all the above requirements, especially the Subversion
       client!

    2. Code to checkout:
       http://subversion.jahia.org/svn/jahia/trunk/

       For more information, please check the template developer guide.

    3. Download and Install Maven 3.x or 2.x (http://maven.apache.org), and set an
       M2_HOME environment variable pointing at the installation
       directory. Put M2_HOME/bin folder in path. Also increase the
       memory for Maven by setting the following environment variable:

         MAVEN_OPTS=-Xmx1024m

    4. Download and Install a Java JDK (http://www.oracle.com/technetwork/java/javase/downloads/index.html).
       Configure the JDK by installing a JAVA_HOME environment variable pointing to it's
       installation directory.
       - Under Windows:
           right-click "My Computer", select "Properties", "Advanced",
           "Environment", add a variable to the user or system settings with
           the following value: name=JAVA_HOME, value=YOUR_PATH_TO_THE_JDK
           where YOUR_PATH_TO_THE_JDK could be something like
           C:\Java\jdk1.6.0_24 if you've installed JDK 1.6.0 update 24.
       - Under Linux:
           Add the following like to the /etc/profile configuration file
           (close for example to where the PATH is declared):
             JAVA_HOME=YOUR_PATH_TO_THE_JDK
           You could also add this environment variable to your
           ~/bash_profile.
       - Other unix systems:
           Basically the same as under Linux, set the environement variable
           JAVA_HOME to point to your JDK installation.

    5. Copy the settings.example.xml file into ${USER_HOME}/.m2 directory, renaming
       it to settings.xml, and modify it to your environment.
       As there are problems with JSP compilation on path with spaces on Windows environments, it is
       recommended you specify a default location for your local repository
       that DOESN'T CONTAIN ANY SPACES IN THE PATH, for example:
         C:/development/m2repository

    6. When you use a new Tomcat server make sure you give it enough memory and adjust its options.
       This can be increase by editing bin/catalina.sh and add the following lines:
         CATALINA_OPTS="$CATALINA_OPTS -Xms1024m -Xmx1024m -Djava.awt.headless=true -XX:MaxPermSize=256m -server -Dhibernate.jdbc.use_streams_for_binary=true -verbose:gc"
         export CATALINA_OPTS
         CATALINA_PID=/tmp/jahia-6.5.pid
         export CATALINA_PID
       before the line
         # OS specific support.
       On Windows systems, edit the bin\catalina.bat file and add:
         set CATALINA_OPTS=%CATALINA_OPTS% -Dsun.io.useCanonCaches=false -Xms1024m -Xmx1024m -XX:MaxPermSize=256m -server -Dhibernate.jdbc.use_streams_for_binary=true -verbose:gc
       before the line
         rem Guess CATALINA_HOME if not defined
       
       If using embedded Derby database, please specify the correct Derby home folder in the
       Tomcat startup options by adding into bin/catalina.sh:
       
         CATALINA_OPTS="$CATALINA_OPTS -Dderby.system.home=$CATALINA_HOME/webapps/ROOT/WEB-INF/var/dbdata"
         export CATALINA_OPTS
         
       on Windows by adding into bin\catalina.bat:
       
         set CATALINA_OPTS=%CATALINA_OPTS% -Dderby.system.home=%CATALINA_HOME%\webapps\ROOT\WEB-INF\var\dbdata
         
    7. In the main directory, type:
       mvn install jahia:deploy jahia:configure

       This should compile and deploy into your local repository all of Jahia, deploy and install everything in the
       application server configured in your settings.xml file.

       An purely indicative time of initial compilation time (including all
       dependency download) is 16 minutes. A "mvn clean install" on the same
       machine takes 2 minutes 40 seconds. These times do not include JSP or
       GWT compilation.

    8. Point your browser to http://localhost:8080/
    	 Default root password is root1234

    9. Create your first virtual site and enjoy.

 Using IDEs
------------------------------------------------------------------------------

  IDEA:

    1. IDEA has direct support for Maven 2, so you can simply open the project
       using the IDE.

       Here are the steps to create the new project:

       - Open File -> New Project ...
       - Select Import project from external model
       - Click Next
       - Select Maven
       - Click Next
       - Select directory where source was checked out and check the box
         named "Automatically synchronize maven structure on startup"
       - It should find just one project org.jahia.server:jahia-root
       - Click next
       - For the project name you can leave the default
       - Click finish

       If you have trouble with the above procedure, you can also generate
       the IDEA project structure using the Maven 2 IDEA plugin this way:

         mvn idea

       You can find the plugin documentation here:

       http://maven.apache.org/plugins/maven-idea-plugin/

  Eclipse:

    1. Add a new 'M2_REPO' classpath variable in Eclipse, pointing to your
       Maven 2 repository folder (either using Maven or manually):

        a) Using Maven: execute:
              mvn -Declipse.workspace=<path-to-eclipse-workspace> eclipse:add-maven-repo
           where <path-to-eclipse-workspace> is the path to your Eclipse workspace

        b) Manually: in Eclipse open
             Window / Preferences -> Java -> Build Path -> Classpath Variables.
           Click on 'New...'
           and enter M2_REPO as a name of the variable and full path to your
           Maven 2 repository as path value

    2. In the Jahia root folder execute the following command:
          mvn eclipse:eclipse
       This will generate '.project' and '.classpath' files for the seven
       projects in Jahia (jackrabbit-core-ext, jackrabbit-server-ext,
       jahia-api, jahia-ear, jahia-impl, jahia-war, etc.)

    3. Open Eclipse and use import 'Existing Projects into Workspace'.
       Using 'Browse...' select the Jahia root folder. A list of  available
       projects will be shown. Import projects into the workspace.

 Setup Maven deployment configuration
------------------------------------------------------------------------------
In order to be able to deploy to the Jahia Maven repository, you must have setup a public/private
key pair in your settings.xml file. In order to do this you must first generate a public/private
key pair if you don't have one.

In order to do deployments to the maven repository, you need to have a public/private key pair setup on
your machine and setup the correct authorization on the remote machine.

   1. ssh-keygen -b 2048 -t rsa
          * If you want the key to be used in an automated setting, use an empty passphrase when the program asks for it (i.e., hit enter at the prompt without typing anything else first).
   2. Append the public key (id_rsa.pub) to your <path to user home>/.ssh/authorized_keys file on the remote machine. If you don't already have the directory or the file, first create the <path to user home>/.ssh/ directory, then copy the id_rsa.pub file to the remote machine, and finally rename it to <path to user home>/.ssh/authorized_keys.

   3. Add the following information in your ${USER_HOME}/.m2/settings.xml file :

  <servers>
    <server>
      <id>jahiaRepository</id>
      <username>YOUR_USERNAME</username>
      <privateKey>${user.home}/.ssh/id_rsa</privateKey> <!-- not needed if using pageant -->
    </server>
  </servers>

 Deploying new JARs to maven.jahia.org
------------------------------------------------------------------------------

 Requirements:
 - on Windows: putty SSH applications (puttygen.exe)
 - on Linux/Mac OS X/UNIX: OpenSSH for JAR deployment to maven.jahia.org

 First check if the JAR is not available by googling for it (ex using the
 command:
   maven2 YOURJAR
 as a search criteria). It is better to use a public resource, which will
 probably include transitive dependencies.

 You should always remember to send your new JARs to the maven.jahia.org
 repository. Here is the procedure on how to do it.

    1. Generate an OpenSSH public/private DSA key pair (on Windows this can be
       done with puttygen and export to OpenSSH format)

    2. Send the public key to the Jahia IT admin and ask for it to be
       installed on the maven.jahia.org server

    3. Use the mvndeploy.bat file on Windows to deploy your JAR, or use the
       equivalent command line. Also, if you have a POM for your JAR that
       includes dependencies this is a better than letter Maven generate one
       for you.

 Compiling a single GWT module
------------------------------------------------------------------------------
GWT compilation of modules is quite a heavy operation, and it may require a
lot of time to build an entire build. For this, we have added the possibility
to only compile a single module by using command line parameters. The syntax
is the following:

  mvn MAVEN_GOAL -DsingleModule=true -DsingleModuleName=MODULE_NAME

and an example would be:

  mvn install -DsingleModule=true -DsingleModuleName=org.jahia.ajax.gwt.module.edit.Edit

In order to make things even easier, we have provided script and batch files
for UNIX and Windows, called single_module.sh and single_module.bat. With
these the above example becomes:

  ./single_module.sh install org.jahia.ajax.gwt.module.edit.Edit

This executes in 1 minute instead of 20!

Also, if you just don't care about GWT compilation, you can single call:

  mvn install -DsingleModule=true

This will compile only the org.jahia.ajax.gwt.module.edit.Edit
module. You can also achieve the same result with the simple call:

  ./single_module.sh

This will call the install goal and generate the Edit module. If you still
want to specify a Maven goal, you can simply do just that:

  ./single_module.sh compile

 Developing and running unit tests
------------------------------------------------------------------------------
Tests are all packaged in the test module. They are intended to be executed in a live jahia context, and are able to
test any stuff on the server side, from a simple DAO to a high end service.

Adding a new test simply consist in adding a TestCase class in the test module. All tests commited in the test module
will be executed automatically after each build on the Bamboo server.

To manually run the tests:

- Go to the test module, execute:

mvn install jahia:deploy
( note that class hotswap is also working for this module, test code change won't require a jahia restart )

- Startup your jahia

- Execute:

All tests: mvn jahia:test surefire-report:report-only
or one single test: mvn -Dtest=org.jahia.services.stuff.MyTest jahia:test surefire-report:report-only

The plugin will use the url set in the parameter " <jahia.test.url> " in your settings.xml file

- Open the file target/site/surefire-report.html and look at the result.

- To execute selenium tests, server selenium is require. You have to download selenium RC here: http://seleniumhq.org/download/
 This tests are configure to be run through http://localhost:8080/cms


 Code coverage generation
------------------------------------------------------------------------------
Jahia's maven project structure is now integrated with the Atlassian Clover
reporting tool. The new "code-coverage" profile must be activated in your
settings.xml. You must also add the following plugin group in the same file:

    <pluginGroup>com.atlassian.maven.plugins</pluginGroup>

In your Tomcat, add to the shared library directory the clover*.jar that you
should find in your Maven repository in the

.m2/repository/com/cenqua/clover/clover/2.4.2

directory. Deploy to tomcat/shared/lib under Tomcat 5.x and under tomcat/lib
under Tomcat 6.x.

Then do from root:

mvn clean install -P testJahia

This will deploy jahia,start your tomcat and stop it, and then undeploy jahia.

The resulting report will be generated in target/site/clover/ for clover and in
the file target/site/surefire-report.html and look at the test result.

WARNING: Clover will instrument your code in your local repository, meaning
that the JARs will contain code to analyse the code's behavior and also
hardcoded paths to store the analysis results. So you should NEVER upload
instrumented JARs to the remote repository, because they will simply not work.

It might be a good idea, when compiling for code coverage, to use an
alternate remote repository. You can do this by using the following command
line argument:

-Dmaven.repo.local=/home/myusername/.m2/repository-for-clover

 Troubleshooting
------------------------------------------------------------------------------

If you encounter javascript errors, java exceptions related to an AJAX class,
or any other engine GUI problem, it is likely that you have upgraded your
Jahia server without emptying the browsers'cache. Before requesting support,
try the following:

1. Empty the browser cache using the browsers options. The option to empty the cache
   is usually located in the "privacy options".
2. Close all browsers windows.
3. Restart your browser and try again. If the problem persists, please contact us.

 Version numbering
------------------------------------------------------------------------------

We following the following convention for version numbering :

MAJOR.MINOR.SERVICEPACK.PATCH

Please respect this when performing releases so that all the parsing code
works correctly.

 Performing a release with the Maven Release plugin
------------------------------------------------------------------------------
It is now possible to use the Maven Release plugin to automate the build of
a release. This will change all the pom.xml versions, commit the change,
compile the project, create a tag and then change all the pom.xml back to
a SNAPSHOT version and commit again.

But before we do this, there are a few changes we must do to the Jahia
project :

1. Create the adequate license.xml files

2. Commit the changes and then use the Maven Release Plugin (see below) to
perform the rest of the release

3. It is recommended also to do all the following steps on a clean checkout of
the codebase, as in your working directory you might have local changes or
IDE project files that will conflict with proper preparation. You can for example
checkout the project like this : 

svn checkout https://username@svnserver/svn/jahia/trunk

You will probably want to also test a commit to make sure you have setup everything
properly before running the Maven release plugin

4a. If you're not familiar with the release plugin or want to simply double-check things, you can perform first
a dry run with the command :

mvn -DdryRun release:prepare -P installer,windows-installer,qa-build,test

Once it is completed reset the project by using the command :

mvn release:clean -P installer,windows-installer,qa-build,test

4b. You can perform all this with the following command line :

mvn release:prepare -P installer,windows-installer,qa-build,test

When asked for versions, here is an example :

There are still some remaining snapshot dependencies.
: Do you want to resolve them now? (yes/no) no: : yes
Dependency type to resolve,: specify the selection number ( 0:All 1:Project Dependencies 2:Plugins 3:Reports 4:Extensions ): (0/1/2/3) 1: :
What is the release version for "Jahia Project Root"? (org.jahia.server:jahia-root) 6.5: : 6.5-BETA2
What is SCM release tag or label for "Jahia Project Root"? (org.jahia.server:jahia-root) jahia-root-6.5-BETA2: : JAHIA_6_5_BETA2
What is the new development version for "Jahia Project Root"? (org.jahia.server:jahia-root) 6.5-BETA3-SNAPSHOT: : 6.5-SNAPSHOT

5. Test a staging of the release by doing the following :

mvn -DstagingRepository=stagingDir::default::file:///Users/loom/java/temp release:stage

6. Once everything looks right, you can perform the release by doing :

mvn release:perform

   This step requires that you have correctly setup deployment to the Maven repository
as described in this README in the section called "Deploying new JARs to maven.jahia.org"

Tips :

- If for some reason you need to start again you can use the release:clean or
if something was already committed, prepare a rollback with release:rollback

- If you want to perform staging on a specific tag, here is an example :

mvn -DconnectionUrl=scm:svn:https://devtools.jahia.com/svn/jahia/tags/JAHIA_6_5_BETA2 -DstagingRepository=stagingDir::default::file:///Users/loom/java/temp release:stage

- If you're running of these an the Bamboo server, make sure you use the alternate local repository with the following
command line option : -Dmaven.repo.local=/home/bamboo/.m2/repository-for-package