Plan-X: Project Development

The core Plan-X components (including XMLStore) are written in Java. So far, components building on top of these have been written in Java and ML. This guide is intended for people doing projects related to Plan-X with access to the Plan-X CVS repository. However, people without CVS access should be able to use most of the information. The guide is written with examples for Windows users. This is because anyone bright enough to choose Linux will have no difficulty in adapting the information to Linux.

CVS

A good CVS client for Windows is TortoiseCVS. It integrates nicely into Explorer and gives easy access to all CVS commands without knowing much about CVS. However, if you have never used CVS before, you should familiarize yourself with the concepts of checkout, update, and commit (and what to do about conflicts). A good place to start is www.cvshome.org/docs/. When you have not done any development in a long time, it is a good idea to start by running CVS update to avoid being surprised that other people have been working while you have been lying on the beach.

CVS Access

To gain access to the Plan-X CVS Repository send an email to Fritz Henglein requesting a username and password. To do a command line checkout (common on Linux):

$ cd mydir
$ cvs -d :pserver:myusername@plan-x.org:2402/var/cvs/plan-x login
$ cvs -d :pserver:myusername@plan-x.org:2402/var/cvs/plan-x checkout plan-x

Where myusername is your username. You will be prompted for the password. To checkout using TortoiseCVS, open the directory where you want the checkout to take place in Explorer, right-click and choose "CVS Checkout...". In the field "CVSROOT" type:

:pserver:myusername@plan-x.org:2402/var/cvs/plan-x

In the field "Module" type:

plan-x

Checkout takes a long time since there is (probably) more than 100 MB of data. However, you will only need to do this once. Updates will be light-weight because chances are that not much data has changed.

CVS Access from Behind a Firewall

Some of DIKU's nets and servers do not allow outgoing access on port 2402. The only work-around is to log on to a machine that does allow access (such as ask.diku.dk) and make the checkout from there. However, you may not have enough quota/storage capacity on the server to do this, so an alternative is to make an SSH tunnel. What this essentially means is that you assign a local TCP port on your own machine (say, port 2402) to pretend that it is plan-x.org:2402. All communication on localhost:2402 will then actually be forwarded to plan-x.org:2402 through the remote server. Yes, this is cumbersome, but may be your only choice.

First download an SSH client which is capable of tunnelling (such as SSH Secure Shell Client). Connect to ask.diku.dk (or whatever remote server you wish), choose "Add Profile" (so the connection will be easily available next time), and choose "Profiles->Edit Profiles". Under your new profile choose "Tunnelling->Add..." and enter the following:

Display Name: cvs
Type: TCP
Listen Port: 2402
Allow Local Connections Only: true
Destination Host: plan-x.org
Destination Port: 2402

You will probably need to reconnect to the remote server using the profile for the changes to take place. With the tunnel in place (the SSH client must be open with the connection to the remote server while you use CVS), you should be able to checkout the Plan-X CVS repository with the only change of replacing "plan-x.org" with "localhost" in the connection strings of the previous section.

CVS Repository Layout

The two main directories that you should know about are "plan-x/projects/" and "plan-x/web/projects/". Everything under "plan-x/web/" is reflected to the www.plan-x.org webserver as soon as it is committed. Therefore, everything stored under "plan-x/web/" is visible on the web. Your project should have a short name used to identify directories, jars, etc. From here on that name will be referred to as myproject. You should create the following directories:

plan-x/projects/myproject/
plan-x/web/projects/myproject/

The first directory is used to store source code during development, and you are encouraged to also use it for drafts of the paper itself, literature, etc. This is your "playground" directory, and you can use it for what you want. The second directory contains the project website (and consequently should have an index.html file). Please look at the existing projects and imitate their design (for instance using copy-paste-replace of an existing index.html file).

Remember to use CVS add to add any new files you create, and CVS commit to actually store them in the repository.

Java Projects

There are essentially two ways to develop a Java project building on the Plan-X components: the ad hoc way, and using development tools. Either way, you will need at least J2SE 5.0 since the core components are written using this.

It is a good idea to create and set an environment variable, JAVA_HOME, to point to the install directory of your J2SE 5.0 development kit. This is not needed for basic use, but many additional development tools you may install use this environment variable to select the desired JDK to use. On Windows 2000 environment variables are set by right clicking "My Computer" on the desktop, and selecting "Advanced->Environment Variables". For ease of use also add %JAVA_HOME%\bin (Windows syntax) to the PATH variable (if it does not exist, simply create it). This will allow you to call java and javac directly from the command line. (Note, that these executables may also exist in, say C:\winnt\system32\, and thus already be on the system path. The version invoked by these executables is controlled by the Java control panel.)

Simple Development

The ad hoc way consists of simply downloading the required jar-files from the Plan-X website and using javac to compile the code "by hand". The core jars can be downloaded from www.plan-x.org/xmlstore/. Additional Plan-X components can be downloaded from www.plan-x.org/maven/plan-x/. Remember to set the -source 1.5 and -target 1.5 options to enable the use of J2SE 5.0 features.

Maven

Maven is a Java project management and project comprehension tool. However, it can easily be used simply as a build tool. Maven sits on top of Ant and provides additional mechanisms to keep track of inter project dependencies. Maven can automatically download dependencies (in the required versions) from repositories on the web (do not confuse CVS and Maven repositories).

Like Ant uses a build.xml file to describe the build process, Maven uses a project.xml file to describe the project (including the build process). Maven is more high-level than Ant and thus the project.xml file tends to be simpler than Ant build.xml files while actually expressing more information. Roughly speaking, all that needs to be in the project.xml file is information about where your source files are stored, where your JUnit test cases are stored, and which components compilation of your project depends upon. Maven will automatically download and include the jar files of these dependencies on the compilation class path.

Download Maven from maven.apache.org and follow the guide under Getting Started to install. Briefly, this includes making sure the environment variables JAVA_HOME and MAVEN_HOME are set, and running the configuration script that creates a local repository for downloaded components. On Windows the Maven program group will include an "Install Maven Repository" that does this. (Maven does not need Ant to be installed? Please provide feedback on whether this is true or not.)

Maven Proxy Server Setup

If you are behind a firewall and can only connect to the internet through a proxy server (as may be the case on some of DIKU's nets), you need to setup special Maven configuration values. This is because Maven will attempt to download any project dependencies (jar files) from the net on port 80. The first time you run Maven it will download dependencies needed for Maven itself. Since the proxy configuration values are common to all projects, but only on the same local machine, they should be placed in the ${user.home}/build.properties file. On Windows this is typically located in:

C:\Documents and Settings\${username}\build.properties

To setup Maven to use a proxy server include the following lines in this file:

maven.proxy.host = proxy.diku.dk
maven.proxy.port = 8080
maven.javadoc.additionalparam = -J-DproxyHost=${maven.proxy.host} -J-DproxyPort=${maven.proxy.port}

Maven Repository

Maven is automatically configured to attempt to download dependencies from www.ibiblio.org/maven/. However, the Plan-X components are not available there so a special Maven repository is located at www.plan-x.org/maven/ containing these components. (If you use the project template described below, Maven will automatically attempt download from both these repositories.) Note, that these repositories are no more Maven specific than you can browse them normally and download jars and source code distributions by hand.

Project Template

The special project "plan-x/projects/project-template/" is a template project which you can use as a skeleton for your own Java project (note, that if you copy the contents, remember not to copy the CVS directories as these contain meta data used by the CVS client). Most importantly there are sample project.xml, project.properties and maven.xml files that you can use. Values that need to be changed are clearly marked with !!!. However, you may also want to update dependency versions and add other dependencies.

The project template has the following directory layout:

src/ Source files.

src/java/ Java source files for your project.

src/resources/ Resources used by the classes (not including test classes).

src/test/ Java source files for your JUnit tests.

src/test-resources/ Resources only used by the test classes.

target/ Everything generated by Maven, including jars and documentation.

.cvsignore A text file specifying files and directories not under CVS control.

build.properties (Optional) User specific properties. Should not be under CVS control.

project.xml The general Maven configuration file.

project.properties (Optional) Project specific properties. Should be under CVS control.

maven.xml (Optional) Customized Maven goals.

Project specific properties common to all users go in the project.properties file. Project specific properties that only apply to a single user go in the build.properties file. Finally, properties common to all projects, but specific to the local machine, go in the ${user.home}/build.properties file.

You can also try to look at some of the existing projects. "plan-x/projects/msd/" has a very simple project setup (which is actually slightly simpler than the project template), while "plan-x/projects/xpath/" is an example of a complex project setup where customized goals need to be executed for the project to build (in this case, Java source code must be generated from parser definition files prior to compilation).

Maven Usage

When Maven is run it is given a goal. (If you know Ant, goals corresponds to Ant tasks.) Maven will use the project.xml file in the current directory, but you can give it a -f option to make it search upwards in the directory hierarchy for the project.xml file. (However, it seems that some goals will still use the current directory as base and not the directory of the project.xml file. JUnit tests may fail because of this if they use relative paths for test resources - which they should.) Typical Maven goals you will need are:

maven clean Delete all generated files (i.e. the target directory).

maven jar Compile, test, and generate jar.

maven jar:deploy Generate jar and deploy it to the Plan-X Maven repository. In the current setup this simply copies the jar on your local file system to "plan-x/web/maven/myproject/" where you will need to add and commit it to CVS yourself (not pretty) in order to publish it on the webserver (since all content under "plan-x/web/" are automatically deployed to the webserver upon commit).

maven dist:deploy Generate and deploy source and binary distributions. As with jar:deploy you will need to add and commit them by hand (the files are also located in "plan-x/web/maven/myproject/").

Maven can do much more, but these are the most essential goals.

ML Projects

In order for ML programs to interface with the Java XMLStore a special binding component is needed (not detailed here yet).

Resources

Last updated: October 21th, 2004 (Thomas Ambus)

`src/`	Source files.
`src/java/`	Java source files for your project.
`src/resources/`	Resources used by the classes (not including test classes).
`src/test/`	Java source files for your JUnit tests.
`src/test-resources/`	Resources only used by the test classes.
`target/`	Everything generated by Maven, including jars and documentation.
`.cvsignore`	A text file specifying files and directories not under CVS control.
`build.properties`	(Optional) User specific properties. Should not be under CVS control.
`project.xml`	The general Maven configuration file.
`project.properties`	(Optional) Project specific properties. Should be under CVS control.
`maven.xml`	(Optional) Customized Maven goals.

`maven clean`	Delete all generated files (i.e. the `target` directory).
`maven jar`	Compile, test, and generate jar.
`maven jar:deploy`	Generate jar and deploy it to the Plan-X Maven repository. In the current setup this simply copies the jar on your local file system to "plan-x/web/maven/myproject/" where you will need to add and commit it to CVS yourself (not pretty) in order to publish it on the webserver (since all content under "plan-x/web/" are automatically deployed to the webserver upon commit).
`maven dist:deploy`	Generate and deploy source and binary distributions. As with `jar:deploy` you will need to add and commit them by hand (the files are also located in "plan-x/web/maven/myproject/").