| |
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):
- Download a J2SE SDK release from http://java.sun.com/j2se/
- Windows or Linux: the 1.5 SDK is available at http://java.sun.com/j2se/1.5.0/download.jsp -- don't get the NetBeans? edition, get "JDK 5.0 Update n"
- OS X: find Apple's version of the SDK at http://www.apple.com/support/downloads/java2se50release3.html
- 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.
Maven
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.
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:
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:
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