"Seegrid will be due for a migration to confluence on the 1st of August. Any update on or after the 1st of August will NOT be migrated"

Setup of GeoServer 1.6 Development Environment

Contents

Overview

These notes describe setting up an Eclipse development environment for GeoServer 1.6.x and GeoTools 2.4.x, with the principal aim of providing complex feature / community schema support. I use Windows XP desktop, but other environments should be similar. I use Eclipse 3.3 Europa under Java 6.

  • This page is deprecated. It is retained for those wishing to examine the behaviour of this old software.
  • No further development will take place on these branches.
  • See GeoserverDevelopmentSetup for information on developing on trunk.

GeoServer is build on GeoTools. Both are Open Source projects. All source code is available from their Subversion repositories. This guide describes the GeoServer 1.6.x branch, which uses the GeoTools 2.4.x branch. Community schema support is enabled by building optional modules.

See also the top level page:

Resources

Setup follows the developers guides, with clarifications and deviations documented below: Developers are strongly encouraged to subscribe to the mailing lists:

Java 1.5

I installed:
  • Java 5 JDK (and included JRE), that is
    • jdk1.5.0_14
    • jre1.5.0_14

JAI 1.1.3 and JAI imageio 1.0

These can be downloaded from:

I installed
  • JAI extensions for JDK and JRE
    • jai-1_1_3-lib-windows-i586-jdk.exe installed into jdk1.5.0_14
    • jai-1_1_3-lib-windows-i586-jre.exe installed into jre1.5.0_14
  • JAI imageio for JDK and JRE
    • jai_imageio-1_1-lib-windows-i586-jdk.exe installed into jdk1.5.0_14
    • jai_imageio-1_1-lib-windows-i586-jre.exe installed into jre1.5.0_14

Maven

I installed Maven 2.0.9 from maven-2.0.9-bin.zip.

To avoid system environment variables that would interfere with other applications, I start Maven with a batch file. I created a bin directory in my home, added it to my (user) PATH, and placed in it the following mvn.bat:
@echo off
set JAVA_HOME=C:\Program Files\Java\jdk1.5.0_14
set M2_HOME=C:\Program Files\maven
set MAVEN_OPTS=-Xmx512m -ea
set PATH=%JAVA_HOME%\bin;%M2_HOME%\bin;%PATH%
mvn %*

Command-line Subversion client

  • I installed the Win32 command-line Subversion client from the installer svn-1.4.5-setup.exe from the Subversion download site.
  • Do not use the Cygwin svn client because Cygwin has a minimal iconv and cannot translate UTF-8 filenames to local encoding. Yes, there are UTF-8 filenames in the code base.
  • Ran svn once to create my user configuration (including "Application Data"\Subversion\config in my home directory).
  • Downloaded the Subversion config attached to the GeoTools developers guide and replaced the above mentioned config with this version. I use the GeoTools version because it appears to be a superset of the GeoServer version. Setting this file is necessary to set auto-properties and fix line endings.
  • Because community schema support requires the manipulation of *.xsd files, it is strongly recommended that you add an entry for *.xsd in your subversion config. Copy the line for *.xml if you do not have one for *.xsd. Hint: Wordpad handles Unix line endings better than Notepad.
  • Note that the configuration file installed for your command-line Subversion client is also honoured by TortoiseSVN http://tortoisesvn.tigris.org/

Checkout source code from subversion repository

Do not keep your source code in a path with spaces. For example, do not put your working directory under "Documents and Settings". The core code will run in such a directory, but many unit tests are broken because they do not handle spaces correctly. This affects both GeoServer and GeoTools. For example, using File.toUrl() [wrong] not File.toUri().toUrl() [right], or not using URLDecoder when going the other way. The work around is to ensure that the working directory path has no spaces.

Used the command line to check out the source code from the subversion repository:

While it may seem attractive to use Subclipse for all Subversion tasks, it will not be possible to synchronise all files with it, because Maven uses nested projects, and these horribly confuse Subclipse. Eclipse will pretend any file not in a project does not exist, so there is no way to access the top-level pom.xml without including the top level as a project, and this will break Subclipse. Horribly, horribly.

Use Maven to build and configure Eclipse projects

Maven is used to retrieve the >140 jar dependencies and store them in a local repository. This will take some time. Maven must be run in a directory with a pom.xml file (for GeoServer-1.6 this is a subdirectory).

Change into each of the directories and use the command for a full rebuild:
  • GeoTools-2.4
    • mvn eclipse:clean clean install eclipse:eclipse
  • GeoTools-2.4\modules\unsupported\community-schemas
    • mvn eclipse:clean clean install eclipse:eclipse
  • GeoTools-2.4\modules\unsupported\geometryless
    • mvn eclipse:clean clean install eclipse:eclipse
  • GeoServer-1.6\geoserver
    • mvn eclipse:clean clean install eclipse:eclipse
  • GeoServer-1.6\geoserver\community
    • mvn -Pcommunity-schemas eclipse:clean clean install eclipse:eclipse

Notes:
  • Maven goals are executed for each module in the order given.
  • -Pcommunity-schemas now required when building in GeoServer-1.6\geoserver\community
  • Do not use -Pcommunity to turn on inclusion of the optional modules in GeoServer-1.6\geoserver\community because maven-eclipse-plugin will include unwanted transitive dependencies and cause conflicts at runtime: both wfs and wfs-c will be included when web-c Start is run from Eclipse. Dependencies must be resolved through the repository or transitive dependency exclusions will not be honoured, as there is no way to express them in Eclipse. This is done by the separate Maven invocation shown above.
  • Do not use -Dmaven.test.skip when building GeoServer-1.6\geoserver because if you do, test classes will not be built, and test artifacts will contain only non-class resources. This will cause some classes in GeoServer-1.6\geoserver\community that depend on test classes in the core code to fail to build in Eclipse.
  • The optional -Dmaven.test.skip is no longer required to process GeoServer-1.6\geoserver\community\community-schemas\wfs-c as its broken unit tests have been disabled. The Maven install goal should succeed.
  • If you need to rebuild Eclipse project metadata, first remove the old metadata with mvn eclipse:clean . This is done in the commands above.

Commentary:
  • I tried using Maven to get source packages, but most are missing for these branches. See the developers manual for details.
  • I tried to use an aggregate POM to build a single Eclipse workspace with all GeoTools/!GeoServer dependencies intra-workspace, but their POM files are at this time not robust against this, and the resulting transitive dependency conflicts caused much pain and woe. Even using -Pcommunity in GeoServer causes problems, and noted above.

GeoServer WAR built with community schema support

The Maven build process described above creates a GeoServer WAR file:
  • geoserver/community/community-schemas/web-c/target/geoserver.war
This WAR file is ready for deployment in a servlet context. It has a minimal (i.e. empty) configuration.

Eclipse workspaces

I created separate Eclipse workspaces for GeoServer and GeoTools called geoserver and geotools respectively. This requires some duplication of settings, but allows each to have separate workspace default setting of, for example, compiler compliance level and JRE. (Safe GeoTools-2.4 development requires building against Java 1.4 SDK).

When working with external tools it can be easier to have Eclipse automatically refresh its state to reflect filesystem changes.
  • You can go to Preferences > General > Workspace and select Refresh automatically.
  • To prevent Eclipse from fighting with Maven, shut down Eclipse during a Maven compile or Maven install, otherwise Maven pre-build clean will trigger a concurrent Eclipse build.
  • During unit tests Subclipse will go insane trying to get revision history as the test modifies the filesystem. This annoyed me enough to turn off auto-refresh.
If you leave auto-refresh turned off, you need to select all projects and press F5 to get Eclipse to recognise changes.

Subclipse configuration

In addition to using an external command line Subversion client, Subclipse can be used, but also requires configuration for auto-properties.
  • In Eclipse I selected Preferences > Team > SVN and set Configuration Location to be the directory containing the Subversion config file set for the command line Subversion client.
  • Subclipse should now honour this configuration, but this has not yet been tested.

Set Java 5 as default JRE for Eclipse workspace

Under Preferences > Java > Installed JREs I added jre1.5.0_14 and made it the default for the workspace.

Set default VM arguments to: -Xmx512m -ea

It should be fine to use the JDK instead of the JRE. One disadvantage of the JRE is that it does not come with source for the runtime, but it is easy to attach source from the JDK. In Eclipse:
  • Press Ctrl-Shift-T and open type Math from java.lang
  • If you do not see the source, press button to attach source, and select the the src.zip in the JDK root directory (for the JDK corresponding to the JRE).
  • You might need to close Math and restart Eclipse before it recognises the source attachment.

Set Java compiler compliance for Eclipse workspaces

Compiler compliance level is set under Preferences > Java > Compiler.
  • For the geoserver workspace, set compliance level to 5.0.
  • For the geotools workspace, set compliance level to 1.4.

GeoTools-2.4 is a Java 1.4 project

GeoTools-2.4 is a Java 1.4 project, so if you make any changes to GeoTools modules, you need to be sure that they are Java 1.4 compatible. You can set compiler compliance to 1.4 for those Eclipse projects, but it might be best to have a special Maven to build them against a Java 1.4 SDK to be sure. You will not make any friends committing Java 5 code to GeoTools-2.4.

Addendum: I have noticed that maven-surefire-plugin (thing that runs unit tests from Maven) seems to know more about the Java 1.4 API than I expected. When I did inadvertently attempt to add a Java 5 API (String.format) call in GeoServer-1.6 test, it would not compile the tests. So there is some element of safety, but I do not know where it is getting its API information.

Add Maven repository to Eclipse build path

Eclipse needs to find the Maven-downloaded jars for compilation. Under Preferences > Java > Build Path > Classpath Variables I added an entry called M2_REPO set to .m2\repository directory in my home directory (this is my local Maven repository).

Import projects into Eclipse

This step makes Eclipse recognise the project metadata generated by Maven. Use File > Import > General > Existing Projects into Workspace:
  • Import all projects from GeoTools-2.4 into the geotools workspace.
  • Import all projects from GeoServer-1.6 into the geoserver workspace.
  • After importing, you might need to restart Eclipse to ensure directories are fully refreshed (e.g. by Subclipse). Your mileage may vary.
All projects should now compile in Eclipse. To test this:
  • Use Project > Clean > Clean All Projects delete all class files. I have Eclipse configured Preferences > General > Workspace with Build Automatically selected (this is the default), so it then recompiles everything.

Subversion update

To update to the latest revision of the Subversion repository (on the selected branches), for each of GeoTools-2.4 and GeoServer-1.6 change into the directory and
  • svn update

GeoServer configurations

GeoServer configurations can be exported or checked out from Subversion to external directories and referenced with the -DGEOSERVER_DATA_DIR=/whatever Java VM argument.

Here are some GeoServer configurations that use complex features. Use svn checkout instead of svn export if you are maintaining them.

Just click on the links if you want to browse them.

Debugging GeoServer using embedded Jetty

  • The community-schema versions of web and wfs are web-c and wfs-c respectively.
  • The embedded Jetty application main class is Start.java in the web-c module (in src/test/java).
  • Use the Debug dialog to make Java Application launch configurations for this class.
  • Add a VM argument -DGEOSERVER_DATA_DIR=/wherever pointing to the location of a GeoServer configuration.
  • If you want to access an Oracle Spatial database, you need add an Oracle JDBC driver (e.g. ojdbc5.jar) to your classpath.
    • The driver can be obtained from either of:
    • Either ojdbc14.jar (Java 1.4) or ojdbc5.jar (Java 5) should work.
    • Copy the Oracle JDBC driver to a local directory or Eclipse project in your workspace.
    • Add ojdbc5.jar on the Classpath tab of your Eclipse launch configuration.
  • Debug with this launch configuration.
  • When you see the Started SocketConnector line in your Console, GeoServer should be ready on http://localhost:8080/geoserver
  • You can make WFS requests in a web browser with URLs like this:
Topic revision: r41 - 15 Oct 2010, UnknownUser
 

Current license: All material on this collaboration platform is licensed under a Creative Commons Attribution 3.0 Australia Licence (CC BY 3.0).