Get the Chandler Server Source
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.
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):
- Download a J2SE SDK release from http://java.sun.com/j2se/
- Install the J2SE SDK according to the instructions included with the release.
- Set an environment variable
JAVA_HOME to the pathname of the directory into which you installed the J2SE SDK release.
- 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.
If your operating system does not already provide it (try running
mvn -v), download and install the Maven build tool:
- Download Maven 2.0.4 from http://maven.apache.org/download.html
- Install Maven according to the instructions displayed at the bottom of the download page.
The source code is stored in a Subversion repository. See SubversionGuidelines for more information about OSAF's Subversion repositories.
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
To do this, you'll first need to build a packaged version of the Chandler Server webapp:
Next, head into the bundled Tomcat directory and use Maven to build your working server:
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:
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:
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.
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.
To build the
inplace debugging target, do the following:
This will cause the various webapp pieces to be inserted into the
mvn clean compile war:inplace
src/main/webapp/ part of the Cosmo source tree.
To generate the Cosmo war file, do the following:
You will now find a Cosmo-*.war file located in the
You can remove all of the compiled source code and generated helper files with
To ask Maven to run the unit tests (and compile if necessary), do the following:
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
-Pjs-dev to their
Using the release-mode packed dojo.js
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
mvn -Prelease install
~/.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
- 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
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
Some common development customizations:
See maven docs for info on how to configure the above compile time 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.
Previous Chandler Server Releases