GeoServer Development Setup

Contents

Overview

  • These notes describe setting up an Eclipse development environment for GeoServer and GeoTools trunk, with the principal aim of providing application schema ("app-schema") support.
  • I use Windows XP desktop, but other environments should be similar.
  • I run Eclipse Helios 3.6 under Java 6. I use the "Java EE Developers" bundle, including a Java IDE, tools for Java EE, JPA, JSF, Mylyn and others.
  • Maven and Eclipse are configured to use Java 6 for building and testing.
  • *The old version of this guide:
GeoServer is build on GeoTools. Both are Open Source projects. All source code is available from their Subversion repositories. See also the top level page:

Resources

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

Java 6

Both GeoTools and GeoServer trunk use Sun Java 6 as their reference implementation. Be sure to build and test with this implementation.

I installed a Java 6 JDK: jdk1.6.0_23

I did not install the Java 6 public JRE. I did install source, which is very handy for debugging.

JAI extensions are now optional for building GeoTools. I did not install them.

Maven

I installed Maven 2.2.1. Maven 3.x.x is also supported as of 25 July 2011.

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.6.0_23
set M2_HOME=C:\Program Files\maven
set MAVEN_OPTS=-Xmx512m -ea
set PATH=%JAVA_HOME%\bin;%M2_HOME%\bin;%PATH%
mvn %*

This approach allows me to ensure that I use Sun Java 6 for all building and testing.

Install command line Git client

Checkout source code from GitHub repository

Used the command line (open up the "Git Shell") to check out the source code from the GitHub repository:

Useful reference links for Git :
  • http://git-scm.com/book
  • http://docs.geotools.org/latest/userguide/build/git.html
  • http://docs.geotools.org/latest/developer/procedures/git.html
  • http://git.or.cz/course/svn.html

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 this is a subdirectory).

Change into each of the directories and use the command for a full rebuild:
  • In geotools
    • mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -Dall -Pwebservice clean install eclipse:clean eclipse:eclipse
  • In geoserver/src
    • mvn -Dtest.maxHeapSize=768m -DdownloadSources=true -PallExtensions -Poracle -Papp-schema -Pwebservice clean install eclipse:clean eclipse:eclipse
Notes:
  • Maven goals are executed for each module in the order given. Eclipse goals are last to leave workspace alone if tests fail.
  • -Dtest.maxHeapSize=256m restricts unit test JVM heap size to 256m, for consistency with OpenGeo and Computational Geoscience continuous integration. Use this if you want your builds to behave the same way, so you are not surprised by an unexpected build failure when the build succeeds on your desktop. This option will also make unit tests fail on 64-bit JVMs. frown
  • -Dtest.maxHeapSize=1024m may be required to get some tests to pass under a 64-bit JVM. This might no longer be the case since Gabriel and Rini put app-schema on a diet. :-P
  • -Dall for GeoTools ensures all optional modules are built. This allows you to detect when any changes you make break an optional supported module. It also gives you access to the new generation of JDBC DataStores. You will need this later when you include Oracle support for GeoServer.
  • -Pwebservice in GeoTools enables the unsupported webservice module. This option can be left out by those who just want to use app-schema, but core app-schema developers should use this module to ensure they do not break the webservice module. (Our buildbot uses this option). The same option in GeoServer is used to build the community/app-schema/webservice-test module, which is the corresponding unit tests for the GeoTools webservice module.
  • -PallExtensions for GeoServer ensures all optional extensions are built. This allows you to detect when any changes you make break an optional supported extension.
  • -Poracle for GeoServer includes Oracle support in the web application.
  • -Papp-schema ensures app-schema support is included in Eclipse dependencies for the GeoServer web-app module for debugging, and in the GeoServer deployment bundle.
  • -Psqlserver is required in GeoServer if you need Microsoft SQL Server support. See details at GeoserverMsSqlServerConnectivity.
  • -DdownloadSources=true is always optional. This downloads sources for dependencies, where available. Maven attaches source in Eclipse projects, allowing source browsing into dependencies. This is very useful for debugging in Eclipse. One downside is it will make Maven slower because it will check for updated source for every dependency, for every module. You may wish to use it only now and then.
  • If no pom files or dependencies have changed, you can omit the eclipse goals.
  • -Dorg.geotools.image.test.enabled=true may be specified if you want to perform optional perceptual diff tests for app-schema WMS support. These will only actually be performed if perceptual diff is in fact installed on your computer. This option is particularly recommended if you are (possibly) modifying the app-schema wms functionality.
  • -o can be added to run offline. This will make the build faster by not checking for updated remote artifacts. You can use this flag if you are rerunning a build shortly after running an online build.
  • -DskipTests=true can be added to skip tests, making the build process much, much faster. Tests are there to help you detect problems, so avoid skipping them. Never commit anything to the subversion repository without running all tests, or you risk breaking the build. Skipping tests will also cause test artifacts to not be built, and break dependencies on test artifacts.
  • -Papp-schema-online-test enable online testing profile. Please read AppSchemaTestDatabase to prepare your databases for the app-schema online tests suite. More information can be found http://docs.geoserver.org/latest/en/developer/programming-guide/app-schema/index.html

GeoServer WAR built with application schema support

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

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).

Eclipse workspaces

I created separate Eclipse workspaces for GeoServer and GeoTools called geoserver and geotools respectively.

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.

Working Set

A working set is a group of elements shown in the different Eclipse views. Working sets are used to clearly separating projects. This can become a very useful feature when you are working simultaneously in many non-directly related projects. Organising your different project groups in working sets will speed up the process of finding the desired elements and will decrease the view visual clutter.

To define a working set, click the Package Explorer menu icon (the inverted triangle) and select Configure Working Set. Here you will be able to create a new working set and to select its related resources, as well as to edit or remove existing working sets. Every available working set will be shown the next time you click on the view triangular icon.

To configure GeoServer and GeoTools to use a single workspace (Optional), select a workspace (or create a new one) and create working sets for both GeoServer and GeoTools respectively. Under Workspace content, select and add the desired packages. Click Finish to confirm the changes.

Notes: All packages from every project added will be listed and a good way to determine which packages are required would be to load the project in an new instance of Eclipse. Under Navigator view, take note of all the packages included and add them accordingly.

To "load" the working sets, navigate to Configure Working Set once again, and select checkbox(es) to load the desired working set(s).

Set Java 6 as default JRE for Eclipse workspace

Under Window > Preferences > Java > Installed JREs I added Java\jdk1.6.0_whatever (browsing under Program Files) and made it the default for the workspace.

I set the default VM arguments to: -Xmx512m -ea . I found this to be sufficient heap for my purposes. The -ea enables any assertions that might be present.

It should be fine to use the JRE instead of the JDK. 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.
If you use the JDK, Eclipse will find the source automagically, so you will not need the above workaround.

Set Java compiler compliance for Eclipse workspaces

  • Maven should set compliance for each Eclipse project it creates, so this step should not be necessary. I use it to be robust against misconfigured modules and to make any extra projects I add consistent.
  • Compiler compliance level is set under Preferences > Java > Compiler.
  • Set compliance level to 1.6.

Set code formatter to use GeoTools conventions

Use the GeoTools code conventions for both GeoTools and GeoServer. The GeoTools formatter profile for Eclipse is stored in your geotools-trunk checkout:
  • build/eclipse/formatter.xml
Import this profile into each workspace using Preferences > Java > Code Style > Formatter.

For GeoTools, you can also set the Code Templates, which include automatic generation of the copyright header in new files.
  • build/eclipse/codetemplates.xml
See also the GeoTools style guide (Oracle Java, spaces not tabs, width 100):

Configure Eclipse XML formatting

Make your Eclipse XML formatting style consistent with the GeoTools / GeoServer Java coding style: 100 character line width with four-space indenting. This is not an official GeoTools / GeoServer rule, but app-schema developers use a lot of XML and we care. smile

In your Eclipse XML Editor settings (XML > XML Files > Editor) set:
  • Line Width: 100
  • Indent using spaces
  • Indentation size: 4

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 geoserver-trunk into the geoserver-trunk workspace.
  • Import all projects from geotools-trunk into the geotools-trunk 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 to delete all class files.
  • I have Eclipse configured Preferences > General > Workspace with Build Automatically selected (this is the default), so it then recompiles everything.

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.

Debugging GeoServer using embedded Jetty

  • The embedded Jetty application main class is org.geoserver.web.Start in the GeoServer web-app module (in src/test/java).
  • Use the Debug dialog to make Java Application launch configurations for this class.
  • In each Java Application launch configuration, 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:
    • 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.
  • If you want to access a Microsoft SQL Server database, you need add a SQLJDBC driver (e.g. sqljdbc.jar) to your classpath.
  • Debug with this launch configuration.
  • You can make WFS requests in a web browser with URLs like this:
Configurations can be set in eclipse using its vm arguments:
  • -DGEOSERVER_DATA_DIR=C:\VWork\test\data
  • -Dapp-schema.properties=C:\VWork\test\app-schema.properties
  • -Djetty.config.file=C:\VWork\test\earthresource.jetty.xml

Frequently Asked Questions

Java 6 for Eclipse?

Q: In the Overview section, you wrote "I run Eclipse 3.3 Europa under Java 6". Do you mean Java 5, since the rest of the document refers to Java 5?

A: Java 6 is correct. I use Java 6 to run Eclipse (faster, less bugs), and Java 5 to run Maven, and to compile against and run in Eclipse, for compatibility. Eclipse allows you to set a JRE to use to compile and run that is different to the one you use to run Eclipse.

GeoServer modules?

Q: Also, do you need to do this: cd geoserver-trunk/geoserver/community; mvn -Pcommunity-schemas eclipse:clean clean install eclipse:eclipse. I was able to, but I'm guessing this is not needed in trunk?

A: You can do it, but it has no effect, because there is no community-schemas profile on trunk. The command just builds some optional modules unrelated to app-schema. The community-schemas modules (web-c and wfs-c) used on 1.6.x do not exist on trunk. The intent of the port is to use the core web and wfs modules. There are no extra modules to build. The only reason we have -Papp-schema is to ensure the GeoTools app-schema module is added as a dependency so the app-schema DataAccessFactory can be detected. This also includes the app-schema GeoTools modules in the GeoServer WAR file for deployment.

Separate workspaces?

Q: Since both GeoServer and GeoTools from trunk would (always?) use the same Java version, I don't see the need to create separate workspaces. Wouldn't it be easier to have one workspace for both projects? Or is there a reason behind this?

A: There are several issues:
  1. Separate workspaces are not strictly necessary. It was more important for GeoTools 2.4.x, which is a Java 1.4 project, to make it easier to set 1.4 as the default for misconfigured modules. GeoServer 1.6 and trunk are both Java 5. It may become important again when GeoServer switches to Java 6.
  2. Separate workspaces aid management of the large number of modules.
  3. There are problems with the way Maven handles transitive dependencies (A uses B uses C), meaning GeoTools and GeoServer must be built separately. I tried to build them together earlier this year using an aggregating pom that enclosed both GeoServer 1.6.x and GeoTools 2.4.x, but got many dependency problems (accidental capture of transitive dependencies, e.g. multiple incompatible versions of Xerces). Another problem is that Maven has a more sophisticated dependency model than Eclipse, so Eclipse project dependencies are a superset of the Maven compile/test dependencies, leading to more accidental capture. These problems together mean separate Maven runs for GeoServer and GeoTools, so the GeoServer Eclipse projects depend on the jars in the Maven repository, not the GeoTools projects in your Eclipse workspace, even if they are in the same workspace. This is because Maven creates Eclipse workspace project dependencies only for projects processed in the same Maven run. All other artifacts are resolved in the Maven repository. This limits the benefit of having a combined workspace.
A combined workspace may behave better on trunk. Feel free to try.

A2: See Working Sets on how to configure GeoServer and GeoTools in a single workspace.

Comments

Rini Angreani commented:

I don't know if this is worth mentioning, but I'll mention it anyway. On the page, you said to get svn client 1.4.5. This is only compatible with subclipse 1.2.x, which is no longer supported. I installed subclipse 1.4.6, and the command line client became unusable after this. It complained that the client is too old. I read that subclipse 1.4.x is only compatible with svn 1.5.x. After upgrading my svn client to 1.5.1, it's working again. But it's all common sense, and I'm sure people would figure it out easily.

Ben replied: Yes, that is right. At some point we all have to upgrade to svn 1.5 compatible clients. When you have a stable, supported set of subclipse/svn/... please upgrade, as you have.


I have now updated to svn 1.5 / subclipse 1.4.7, as suggested by Rini, and updated to documentation to match.

-- BenCaradocDavies - 10 Dec 2008
 
Topic revision: r46 - 19 Aug 2013, RiniAngreani
 

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