Home › Groups › GeoNetwork configuration and development

Windows 7 64-bit guide for GeoNetwork development within Eclipse

Submitted by wgrunberg on Wed, 07/28/2010 - 11:38am

This setup guide for downloading GeoNetwork using Subversion, building using Maven 2, developing, deploying and debugging on Tomcat and Eclipse on Windows 7 64-bit still uses the MckoiDB and should be updated to use MySQL.

Introduction

This document was developed for GeoNetwork’s new Maven 2 based setup. See http://trac.osgeo.org/geonetwork/wiki/Maven for more information.

Note that several installation and configuration options may not be necessary for GeoNetwork development but can be necessary for other software development projects.

This document was compiled from experiments, notes, and web sites by the following contributors and sources (in alphabetical order):

  • Ryan Clark
  • Mathieu Coudert
  • Wolfgang Grunberg
  • Dominic Owen
  • Timo Pröscholdt
  • Francois Prunayre
  • Lund Wolfe

Install and Configure Java JDK and JRE

  • Install the latest 64 bit version of Java JDK 1.6 (includes 64 bit JRE) from Sun/Oracle ( http://www.java.com/en/download/manual.jsp ) to e.g. D:\jdk1.6.0_21. A 64 bit SDK is required for a 64 bit installation of Tomcat. GeoNetwork requires a 1.6 JRE.
  • Or Install the latest 32-bit version of the Java JRE 1.6 from Sun/Oracle (http://www.java.com).
  • Set the JAVA_HOME and JRE_HOME environmental variables (see http://www.itechtalk.com/thread3595.html ) to the JDK root (e.g. D:\jdk1.6.0_21)

Install and Configure Tomcat

  • Install the latest 64 bit version of the Tomcat 6 or 7 servlet/http engine from Apache Foundation from http://tomcat.apache.org/ to a path without spaces (e.g. D:\Tomcat6028).
    • Use the installer to select the optional services component to run Tomcat 6 as a Windows service or the zip to just unzip and run a bat file to start Tomcat.
    • Add a CATALINA_HOME environmental variable and point it to the Tomcat root (e.g. D:\Tomcat6028)

Install Ant and Maven

  • Apache Ant "is a software tool for automating software build processes" ( http://en.wikipedia.org/wiki/Apache_Ant ) .
    • Download Ant from http://ant.apache.org/bindownload.cgi and install it to a path without spaces (e.g. D:\apache-ant-1.8.1)
    • Set the "ANT_HOME" environmental variable to your Ant root path (e.g. D:\apache-ant-1.8.1)
    • Add Ant’s bin folder (e.g. "D:\apache-ant-1.8.1\bin") to the "path" environmental variable (semicolon delimited)
    • (OPTIONAL) Some software projects such as degree require you to add a ant-contrib-1.0b3-bin (or newer) Ant-Contrib Tasks libraries from http://ant-contrib.sourceforge.net/ . Download  the library and copy it to your "<ANT_HOME>/lib" folder
  • Apache Maven 2 "is a software tool for project management and build automation" ( http://en.wikipedia.org/wiki/Apache_Maven ).
    • Download Maven from http://maven.apache.org/download.html and install it to a path without spaces (e.g. D:\apache-maven-2.2.1)
    • set the M2_HOME environment variable to the install directory and set the M2 environment variable to the bin directory.
    • Add Maven’s bin folder (e.g. D:\apache-maven-2.2.1\bin) to the "path" environmental variable

Install and Configure Eclipse IDE for Java EE

  • Download the latest 64-bit version of "Eclipse IDE for Java EE Developers" (not SE!) at http://www.eclipse.org/downloads/
    • Extract it to a path without spaces - e.g.  D:\eclipse
    • Add the following line AFTER  "-vmargs" to your eclipse.ini in order to avoid hang ups during SVN checkouts:
      -XX:MaxPermSize=256m
      (see https://bugs.eclipse.org/bugs/show_bug.cgi?id=319514 ).
    • Some Eclipse plugins - such as the M2Eclipse Maven integration plugin - require Eclipse to run from a JDK instead of its default JRE. Modify your eclipse.ini file by adding the path to your JDK.Insert the following lines BEFORE "-vmargs" (the carriage return is mandatory):
  • Eclipse Configuration
    • Install Subversion (SVN) Client(s)
      • Like most software projects hosted by SourceForge, GeoNetwork uses SVN as its source control, and code repository.
      • Install the latest 64 bit version of the Slik Subversion command-line client - http://www.sliksvn.com/en/download
        Subclipse (an Eclipse SVN plugin) requires a 64 bit compatible Java HL library that it is provided by Slik Subversion above.  Otherwise you can download it separately: (http://subclipse.tigris.org/wiki/JavaHL#head-0ae839721445e3f59d10a128ec9439d4f4988d5f).
        • Make sure SlikSvn\bin\ is in your path environment variable or use an absolute path to svn on the command line.
      • You may run into an Eclipse SVN incompatibility with the otherwise nice 64-bit Tortoise SVN client which integrates with Windows Explorer (graphical user interface).
      • Stay away from the Tortoise CVS client! It breaks on Windows 7 64 bit.
    • Add SVN support through the Subclipse add on.
      • You will have to add http://subclipse.tigris.org/update_1.6.x to Available Software sites under Help | Install New Software
    • Add maven support through M2Eclipse (see http://m2eclipse.sonatype.org/index.html )
      • Uninstall IAM Eclipse plugin if it is already installed
      • Install the M2Eclipse module by using the http://m2eclipse.sonatype.org/sites/m2e path in Eclipse's Help | Install New Software | Add… | Location
      • To integrate M2Eclipse with Subclipse SVN download capability, install the "Maven SCM Integration" and "Maven SCM handler for Subclipse" (optional?) plugin from http://m2eclipse.sonatype.org/sites/m2e- extras (use in Help | Install New Software | Add… | Location)
      • NOTE! M2Eclipse requires Eclipse to run on a JDK and that the installed JREs are also using a JDK instead of a JRE.
      • IAM is an alternative Maven plug-in for Eclipse (see http://code.google.com/p/q4e/wiki/Installation ) that might work too.

Disable Windows Indexing on SVN and CVS folders

Create GeoNetwork Maven project

  • In contrast to Ant, Maven is capable of downloading dependent libraries and entire repositories.
  • Here are two ways to create a Maven project of GeoNetwork

Get source with SVN, then build with Maven

  • In Eclipse, go to File | New | Other and select SVN | Checkout Projects from SVN
    • Use https://geonetwork.svn.sourceforge.net/svnroot/geonetwork/trunk as the SVN location URL
    • Under Check Out As selecte the "Check out as a project in the workspace" option and rename the Project Name from "trunk" to, for example,  "geonetwork".
      Once the trunk is checked out, right click on the pom.xml file in the root folder and select Run As | Maven package to download dependencies and compile the code. Make sure to look at the Eclipse Console to determine if the build was successful: 
          [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO]
    [INFO] GeoNetwork opensource............................. SUCCESS [0.780s] [INFO] Caching xslt
    module............................... SUCCESS [1.708s] [INFO] Jeeves modules
    ....................................SUCCESS [3.081s] [INFO] Oaipmh modules....................................
    SUCCESS [0.955s] [INFO] ArcSDE module (dummy-api)......................... SUCCESS [0.741s] [INFO] GeoNetwork Web
    module............................. SUCCESS [1:09.761s [INFO] GeoServer module..................................
    SUCCESS [20.073s] [INFO] Gast module....................................... SUCCESS [11.054s] [INFO]
    ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO]
    ------------------------------------------------------------------------
  • To create an installer, right click on the root pom.xml file and select Run As | Maven install. 
      [INFO] ------------------------------------------------------------------------ [INFO] Reactor Summary: [INFO] [INFO]
  GeoNetwork opensource ............................. SUCCESS[1.147s] [INFO] Caching xslt module
  ............................... SUCCESS[1.061s] [INFO] Jeeves modules ....................................
  SUCCESS[0.570s] [INFO] Oaipmh modules .................................... SUCCESS[0.303s] [INFO] ArcSDE module
  (dummy-api) ......................... SUCCESS[0.296s] [INFO] GeoNetwork Web module .............................
  SUCCESS[19.848s] [INFO] GeoServer module .................................. SUCCESS[10.797s] [INFO] Gast module
  ....................................... SUCCESS[0.480s] [INFO]
  ------------------------------------------------------------------------ [INFO] BUILD SUCCESS [INFO]
  ------------------------------------------------------------------------
  • If Subclipse doesn't work you can create a new project within Eclipse and go out to the command line and create a directory within the project (I could not get Eclipse to use the classes or bin folder located outside the Eclipse project) and pull the maven project source with the Subversion command line client and build using the command line Maven with:
    • svn co https://geonetwork.svn.sourceforge.net/svnroot/geonetwork/trunk geonetwork
    • cd geonetwork
    • mvn clean install
    • mvn assembly:assembly

Maven all the way (not working yet)

  • This method has the advantage that Maven is controlling the download from the code repository as well as the compiling from the get-go. However, I can't get GAST to compile correctly. I also encountered compilation errors once I ran SVN updates.
  • In Eclipse, go to File | New | Other and select Maven | Checkout Maven Project from SCM.

Create the GeoNetwork application and run it

  • Use the zip name actually built by Maven 2: move target\release\geonetwork-2.6.0-RC2-bin.zip   \tmp\.
  • cd /tmp
  • Use a command line zip or just right click the zip file in Windows 7 to unzip: unzip geonetwork-2.6.0-RC2-bin.zip
  • cd geonetwork
  • cd bin
  • Edit start-geonetwork.bat and use the full path to java and javaw on your machine or make sure the java and javaw bin directory is in your path environment variable.
  • Run geonetwork as an application in the embedded jetty webserver with: start-geonetwork.bat

Deploying to Tomcat 6 or 7 and Debugging from within Eclipse

  • To use the internal builder in Eclipse for the GeoNetwork web app
    • Copy the unzipped \tmp\geonetwork\web\geonetwork\ contents to a new directory (web\geonetwork) under your Eclipse project directory
    • In the Eclipse properties for the project in the Builders uncheck all but Java Builder
    • Now go to the Java Build Path
      • In the Libraries tab add the jars in the WEB-INF\lib directory using the add jars or add external jars button
      • In the source tab
        • Make sure the source directory is set only to the maven project's original web\src\main\java directory
        • Make sure the default output directory is set to the new web app's web/geonetwork/WEB-INF/classes or bin directory (where you compile to and debug from)
    • Do an Eclipse build using the menu: Project -> Build Project
      • Check the problems tab in the bottom frame of your Java view for errors.  If Eclipse couldn't delete a directory in your classes or bin directory, delete it manually and retry.  You may have to do a Clean in the Build menu to delete any bad class files first.
    • Configure debugging
      • Go to the Debug Configurations... through the Debug button bar button menu item or right clicking the project and selecting Debug As
      • Select the Remote Java Application and click the top left button to create new launch configuration
      • In the Connect tab set the name of the debug configuration and set the Connection Type to Standard (Socket Attach) and the Host to localhost, or whatever server name is running Tomcat, and the Port to 8000, or whatever port you are setting in Tomcat and click the apply button to save
  • Deploy and setup Tomcat for debugging
    • Create a new startup file in the tomcat\bin directory to start Tomcat called startup-debug.bat with the following content:
      • catalina jpda start
    • Edit the catalina.bat file in the tomcat\bin directory
      • Make sure the port is set to the port you set for debug in Eclipse on this line in the catalina.bat file:
      • Set JPDA_ADDRESS=8000
    • Add your webapp to Tomcat to deploy it when Tomcat starts up
      • Create a geonetwork.xml file in the \conf\Catalina\localhost\ directory of your Tomcat install directory.  Use the server name instead of localhost if the webapp is on a different server.  You may have to startup Tomcat once so Tomcat can create the Catalina\localhost directory.
        • Put these contents in the file:
        • <Context docBase="D:/eclipse-projects/azgs/geonetwork" />
        • Use your actual absolute path to the Eclipse workspace and project (web app) and save the file.  This is a context.xml type tomcat file for adding web apps outside tomcat.
  • Test debugging
    • Start Tomcat using the bin\startup-debug.bat file
    • Go into Eclipse and open the \WEB-INF\src\org\fao\geonet\services\login\Login.java file in the editor and set a breakpoint on an executable line
    • Start the debugger by clicking the Debug Configuration you created previously by going through the Debug button bar button menu item
    • Open your web browser and go to the url of the geonetwork web app: http://localhost:8080/geonetwork/srv/en/main.home
      • Enter the name and password and click the login button.  This should start running and stop at the breakpoint in Eclipse
      • If the web app has errors in Tomcat and the files and directories (META-INF and crosswalks) have been deleted from the bin or classes directory, go back to the original directory where they were unzipped from the maven build and copy them back to your bin or classes directory.

Debugging from within Jetbrains IDEA 9.x

  • Create a new Java project by importing (using in place external) from an external Eclipse project (or a Maven project ?)
    • Copy the same web app structure over to IDEA as was done in Eclipse or use the external structure and create project from external sources
  • Make sure Tomcat is already setup for debugging as done previously for Eclipse
  • Make sure IDEA is compiling for debug in the menu for File  -> Settings -> Compiler -> Java Compiler
  • Create a new Debug Configuration in the menu Run -> Debug... -> Edit Configurations
    • Add a new remote configuration with a Name (like GeoNetworkDebug), Transport, Debugger mode, host, and port just as was done for Eclipse, and then click the Apply button
  • Set the same breakpoints as was done in Eclipse.
  • Start Tomcat as before
  • Start the debugger in IDEA from the menu Run -> Debug -> GeoNetworkDebug
  • Open your web browser and go to the url the same as described for Eclipse
  • IDEA will not stop the webserver and shutdown.bat in the tomcat 7.x  install\bin folder didn't shut it down either when stopping in debug mode, so you may have to use ctrl + c to kill tomcat in its command prompt window

Moving from MckoiDB to MySQL

  • To do …
Groups: