Setting Up GW

%TOC%

GW is a Java web application. Java web applications are hosted in a servlet container, such as Tomcat. In this project we use the [[http://jetty.mortbay.org][Jetty]] servlet container, since Jetty is smaller and more configurable.

GW is deployed using the [[Trace.Nix][Nix]] deployment system. The Nix deployment system takes care of installing and configuring all required software. GW is build using [[http://ant.apache.org][Ant]], which is the most common build system for Java software.

If this is your first time on a Linux machine at the UU, then you might find the tips in [[user friendly linux]] useful to read first.

---++ Enable Nix

Before you can use Nix you should execute the following command:
<verbatim>
$ source /nix/etc/profile.d/nix.sh
</verbatim>
Note: you shouldn't type the =$= sign, it's there to indicate shell commands. 

This command sets up some environment variables that make it possible to use Nix.  It's best to put this command in your =~/.profile= file so you don't have to run it every time you open a new terminal.

---++ Checkout the GW Sources

*Note*: before you start working with Subversion, you should go to [[https://svn.cs.uu.nl:12443/][our Subversion server]] and fill in your full name and e-mail address (by clicking on _Edit your user information_).

If all GW project members are going to work on the same source tree,
then this will result in a complete mess. Therefore, each team will
start with a branch of the GW sources. The main 'branch' is the =trunk= directory
in the Subversion repository. The branches are in the branches directory. You can lookup 
the name of your branch at:

   * https://svn.cs.uu.nl:12443/repos/gw/branches/

So, your code is located at [[https://svn.cs.uu.nl:12443/repos/gw/branches/yourteam]].  As you can see, you can browse through the source with your web browser. You can now checkout your GW sources:

<verbatim>
$ svn checkout https://svn.cs.uu.nl:12443/repos/gw/branches/yourteam gw
</verbatim>

This will result in a directory =gw=. From now on we will be working
in this directory, so you need to change to this directory (=cd gw=).

---++ Building and Running GW

---+++ Installing Nix Packages

You should first get your very own copy of the Nix Package Collection, which contains packages such as Subversion (built with Java bindings), a Java compiler and runtime, Ant, etc. The procedure for installing these packages is automated in a small shell script:

<verbatim>
$ ./update-nixpkgs.sh
</verbatim>

Note that Nix installations are per-machine.  What you install on one machine won't follow you to another. If you are going to work on a different machine, then you have to run this command again.
If you have problems with this step, make sure you are in the newly created gw folder.

---+++ Compiling and Running GW

Now you've done all the hard work. Building and running GW is trivial:

<verbatim>
$ ./startup.sh
</verbatim>

If you are sharing a machine with someone else, you will probably need to change the port on which the server runs. You can do this by changing the =nix/server.nix= file and adding

<verbatim>
port = <some-port>;
</verbatim>

before the closing brace corresponding to the =body= declaration.

If you have not used any Nix package before, then this might download some software first. Next, it will compile the GW sources and deploy the resulting web archive in Jetty. Finally, Jetty will be started. You can visit GW at

   * http://localhost:8080/gw/view/trunk/WebHome

You might want to fool around a bit with the current implementation to
know for sure that it really works. Try clicking some links and edit
some topics.

---++ Using Eclipse

We strongly advice you to use Eclipse for Java development of GW. Eclipse will immediately give you compiler warnings and provides good refactoring support. In this section, we explain how to install and configure Eclipse.

---+++ Installing Eclipse

Unfortunately, the default installation of Eclipse is 3.0.1, which does not support Java 5.0 (1.5) projects. Therefore, you have to update Eclipse. Fortunately, this is easy to do:

   * Go to http://nix.cs.uu.nl/dist/courses/nixpkgs-swe-unstable-latest/
   * Click on "eclipse-sdk-3.1"
   * Open this file with the tool =/nix/bin/nix-install-package=
   * Enter =Y= in the new terminal

You have now installed Eclipse. Note that this is machine specific, so you might have to redo this if you are going to work on different machines. Eclipse is installed at:

<verbatim>
$ ~/.nix-profile/eclipse/eclipse
</verbatim>

Make sure that the Eclipse version that you start is 3.1 and not 3.0.1 (see the splash screen). If you get startup errors, removing the =.eclipse= directory in your home dir might help.

---+++ Import the GW project

   * File -> New -> Project
   * Select the "Java Project" wizard and click Next
   * Enter a Project name (for example GW)
   * In "Contents" select "Create project from existing source"
   * Click "Browse" and select the directory where your checkout of =gw= is.
   * In the next window you don't have to change anything. Just click "Finish"

---+++ Hide Generics Warnings

GW was developed on 1.4, so it does not use generics everywhere, which results in a lot of warnings. You can disable these:

   * Window -> Preferences
   * Java -> Compiler -> Errors/Warnings -> J2SE 5.0 options
   * Set "Unchecked generic type operation" to "Ignore".

If generics have been introduced more widely, then we could enable this warning again.

While you're at the JSE 5.0 stuff you might also want to make sure eclipse is using java 5.0.

   * In the same window (Window->Preferences)
   * Java -> Compiler
   * set the 'Compiler compliance level' to 5.0

---+++ Use spaces

   * Window -> Preferences -> Java -> Code Style -> Formatter -> Edit -> Indentation 
   * Set Tab policy to "Spaces only" and size 4.

---+++ Filters

First, the "Problems" view lists some warnings related to duplicate resources. I don't know how to disable them, so I've used a quick hack:

   * Click on the "Filters" icon in this Problems view. (small icon with arrows)
   * Go to "Where description", set to "does not contain" and enter "The resource is a duplicate" in the textfield.
   * It's also useful to set the filters to "On any resource in the same project".
  
---++ Developing GW

In this section the structure of the GW package will be explained.

---+++ Source Organisation

The main sources are in the =src= directory. This directory contains
the file =build.xml= for building the GW sources with Ant. The file
=gw.xml= is describes the gw web application. This description is used
by the servlet container (Jetty).

   * The directory =src/java= contains the Java sources of GW. All
     Java sources are in the =gw= package. You should start a
     subpackage of =gw= for your team.

   * The directory =src/web= contains the static content of GW (HTML,
     CSS, JSP, images).

---+++ Building GW

The =startup.sh= script rebuilds GW if anything has changed, so you
can just invoke =startup.sh= if you want to compile and test your
code. If you only want to compile, then you can use the =build.sh=
script at the top level. This script uses Nix to build GW. It does not
start the servlet container.

You should not invoke ant directly. Of course it is possible to build
GW by hand, but the Ant script requires some additional properties to
be set. These properties have no default values.

---+++ Configuring GW and Jetty

During the project you might need to change some of the configuration
of GW and Jetty. If you add a new servlet, then you must add it to the
web application descriptor (=gw.xml=). See the [[TechnicalDocumentation]] for links to tutorials for this. If you want to
generate javadoc documentation (useful for other teams), then you can
change the Ant =build.xml= file.

The configuration of the deployed software is controlled by the Nix
expressions in the directory =nix=. The =gw/default.nix= expression is
used to configure the =gw.war= web archive. The configuration of Jetty
is controlled by the =server.nix= expression. This expression
mainly applies the function in the file =jetty/default.nix=. This
function takes a number of argument (for example a list of web
applications) and creates a Jetty configuration from this.

---+++ Developing at Home

It is possible to work on GW at home. You will need a Linux
distribution for this.

The only thing you need to do is install Nix. Nix is available as an
easy to install tarball or RPM.

   * http://www.cs.uu.nl/wiki/Trace/Nix

The Nix manual explains how to get started with Nix (it's really easy)
and we will gladly help you with any problems. If you've installed
Nix, then you can just follow the installation instructions of GW.

Some people had some troubles, but found solutions. Please have a look at [[NixTroubleshooting][Nix Troubleshooting]].

It is not advisable to ignore the Nix-based deployment system of GW
and install all software by hand: this is not trivial. Of course you
can try, and we might even answer your questions if we're in the mood.