Get the Chandler Server Source


Prerequisites

These instructions help you set up your platform for hacking on OSAF's Java server projects. These projects utilize specific versions of particular Java tools. Only use the versions that are explicitly listed here. Using other versions will likely cause problems that we might not know how to help you solve.

Java SDK

If your operating system does not already provide it (try running java -version and/or echoing $JAVA_HOME), download and install a Java SDK (only use version 1.5 which is labeled as "5.0" on Sun's site):

  1. Download a J2SE SDK release from http://java.sun.com/j2se/
  2. Install the J2SE SDK according to the instructions included with the release.
  3. Set an environment variable JAVA_HOME to the pathname of the directory into which you installed the J2SE SDK release.
  4. On OS X, you may have to change the symlink for /System/Library/Frameworks/JavaVM.framework/Versions/Current (and CurrentJDK) to the 1.5.x version of the JDK.

Maven

If your operating system does not already provide it (try running mvn -v), download and install the Maven build tool:

  1. Download Maven 2.0.4 from http://maven.apache.org/download.html
  2. Install Maven according to the instructions displayed at the bottom of the download page.

Subversion

The source code is stored in a Subversion repository. See SubversionGuidelines for more information about OSAF's Subversion repositories.

Source code

If you have commit privileges to the Cosmo repository you will need to check out the source as read/write svn co svn+ssh://svn.osafoundation.org/svn/server/cosmo/trunk cosmo otherwise you can check it out as read-only svn co http://svn.osafoundation.org/server/cosmo/trunk cosmo

Setting up a development server

Cosmo is a Tomcat web application, so the first thing you'll need is a working container (a server that runs Tomcat web applications). If you already have this, skip to the next section. Otherwise, we recommend you use the server bundled with your source checkout, which can be found in $COSMO_ROOT/snarf.

To do this, you'll first need to build a packaged version of the Chandler Server webapp:

  • cd $COSMO_ROOT/cosmo/
  • mvn package

Next, head into the bundled Tomcat directory and use Maven to build your working server:

  • cd $COSMO_ROOT/snarf/
  • mvn assembly:directory

Once this is done you'll be able to find your working Tomcat server in a subdirectory of $COSMO_ROOT/snarf/dist, which will look like:

$COSMO_ROOT/snarf/dist/osaf-server-bundle-0.15-SNAPSHOT/osaf-server-bundle-0.15-SNAPSHOT/

and will hereafter be referred to as $SNARF_HOME.

For development purposes it is generally most convenient to run the webapp from an "inplace" debugging target. To do this, edit $SNARF_HOME/tomcat/conf/Catalina/localhost/chandler.xml and set the docBase attribute of the <Context> element to the full filesystem path of the Chandler Server development webapp.

For example, if you checked out the source code in /home/travis/dev/cosmo you'll need to set docBase as in the following example:

<Context docBase="/home/travis/dev/cosmo/cosmo/src/main/webapp">
...
</Context>

Building Chandler Server

Generally Chandler Server is built in one of two ways: either as an inplace debugging target or a war file used to install into a Tomcat container. For most development you will most likely want to use an inplace debugging target, but it is also feasible to package and deploy the Chandler Server war between every code change.

Dependencies

Cosmo is built on top of many external frameworks, libraries, and tools. Most are pulled straight from Ibiblio's Maven repository (or a mirror), but some are found in OSAF's Maven repository which contains dependencies that we build ourselves or which are not found on Ibiblio. At anytime if you want to force Maven to update the SNAPSHOT jar files, use the -U option. This is needed because, by default, Maven 2 will only check for updates once a day.

Maven targets

war:inplace

To build the inplace debugging target, do the following:

  • cd cosmo/
  • mvn clean compile war:inplace

This will cause the various webapp pieces to be inserted into the src/main/webapp/ part of the Cosmo source tree.

package

To generate the Cosmo war file, do the following:

  • cd cosmo/
  • mvn package

You will now find a Cosmo-*.war file located in the target/ sub-directory.

clean

You can remove all of the compiled source code and generated helper files with mvn clean.

test

To ask Maven to run the unit tests (and compile if necessary), do the following:

  • cd cosmo/
  • mvn test

Detailed test output is generated in text and XML format to target/surefire-reports. This, and the brief console output it generates, should be more than enough to debug test failures.

You can run a single test by specifying the name of the test class as a command line option: mvn -Dtest=DavMkTicketTest test

Maven options

js-dev

Developers interested in Javascript development should add -Pjs-dev to their mvn build commands. This adds a symbolic link in place of the cosmo Javascript directory to enable developers to test against the version controlled Javascript and avoid extra build steps. Developers will also need to make sure their container server is configured to allow symbolic links. For more information on Javascript development, please see ChandlerServerJavascriptDev.

Using the release-mode packed dojo.js

Normally during the edit/compile/test dev cycle the uncompressed dojo.js file is used so any javascript references for cosmo are pulled from the source tree, but if you are not working on the javascript side you may want to use the compressed dojo.js

  • cd cosmo-js
  • mvn -Prelease install

This will generate the dojo jar file using the compressed bits. The next time you compile/test cosmo use the -U command line option with Maven to force it to update the jar dependency. Or to really force it, delete the ~/.m2/repository/org/osaf/cosmo/dojo directory tree before you build the release-mode dojo jar.

To verify you are using the proper jar, when you next do a mvn war:inplace grep for "cosmo" in the dojo.js file - if it worked you will see results.

Setup Eclipse Dev Environment

Eclipse is a great IDE and is easy to setup to hack code in cosmo. To setup eclipse for a cosmo project:
  • goto Window-->Preferences, under Java-->Build Path-->Classpath Variables add a new variable M2_REPO with the path being the location of your maven 2 repository directory (for Unix its ~/.m2/repository and for windows its C:/Documents and Settings/[user]/.m2/repository)
  • create cosmo project by executing mvn eclipse:eclipse under cosmo dir
  • in Eclipse, import the project using File--> Import... (select Existing Projects into Workspace and navigate to cosmo dir)

Hack some code

You are now set up to write code. You will probably want to observe code changes in the browser or at the command line very frequently. How you do this depends on what code you're modifying:

  • If you make a change to a JSP, you should be able to reload the corresponding web page and observe the change in your browser without any further steps.

  • If you make a change to a Java class or to a configuration file, you'll need to run maven war:inplace again (probably with -Dmaven.test.skip=true so that you skip the unit tests). Because you made the webapp reloadable, Tomcat will automatically sense the recompiled class or modified config file and will redeploy the webapp after a few seconds. You can see it doing this by watching $OSAFSRV_HOME/logs/osafsrv.log and looking for the startup message (the timestamp should be more recent than when you ran maven war:inplace).

Javascript Development

If you plan on doing Javascript development, you should make sure to check out ChandlerServerJavascriptDev for more information.

Generate a release

There's a lot more to making a Cosmo release than just building a binary package. See CosmoReleaseProcess for more information.

Customize your build

Maven downloads Tomcat 5.5.17 to build the Snarf package. If you want to use a different version then you need to edit the apache-tomcat dependency in snarf/pom.xml

        <dependency>
          <groupId>org.osaf</groupId>
          <artifactId>apache-tomcat</artifactId>
          <version>5.5.17</version>
          <type>zip</type>
        </dependency>

Some common development customizations:

  • debug - Include debugging information in the compiled class files. Default value is true.
  • deprecation - Whether to show source locations where deprecated APIs are used. Default value is false
  • optimize - Optimize the compiled code using the compiler's optimization methods. Default value is false.

See maven docs for info on how to configure the above compile time customizations.

Archive

Previous Chandler Server Releases

This topic: Developers > WebHome > ChandlerServerSource
History: r9 - 30 Jun 2008 - 18:11:46 - TravisVachon
 
Except where otherwise noted, this site and its content are licensed by OSAF under an Creative Commons License, Attribution Only 3.0.
See list of page contributors for attributions.