Welcome to your first GeoTools project!

But first a word of apology and explanation ... GeoTools is large. Well actually quite HUGE. And it depends on a lot of other open source libraries, toolkits, hacks and so on. Keeping track of all of this is a bit of a chore - so I would like to introduce a tool to you.

• Maven - http://maven.apache.org/

Maven is a build tool that is going to help sort all of this stuff out. You may be used to using ant, or sticking to the safe confines your your IDE. Bare with me for a moment as we set up a simple maven project, I think you will find this tool quite useful.

Getting Started

Setting up your Project Folder

First of all let's use maven to create our project:

C:java>mvn archetype:create -DgroupId=org.geotools.demo.example -DartifactId=geotools-example

It will wirr and click, downloading a bunch of stuff before creating a geotools-example directory for you.

If you have not installed maven before, please check out this page from our developers guide: 2 Maven Install You should also check out this page on configuring maven for your computer / LAN / firewall etc: 2.5.2 Maven Local Settings and Repository If this is your first experience with maven I apologize for being EVIL and inflicting it on you. Rest assured that it is so good that these are skills will find use for again and again.

IDE

Now let's set things up for your IDE (eclipse is used as an example):

C:java>cd geotools-example
C:java\geotools-example>mvn eclipse:eclipse

You can now give Eclipse the background information it needs to talk to your "maven repository" (maven downloaded something like 30 jars for you):

1. Start up Eclipse
2. Open up the Windows > Preferences menu
3. Navigate to the Java > Classpath Variables preferneces page
4. Add an M2_REPO classpath variable pointing to your "local repository" (in your home directory):
   C:\Documents and Settings\Jody\.m2\repository

For more information - well really any information since we did not explain: Eclipse FAQ

You can now import your project into eclipse:

1. Select the File > Import menu
2. Choose Existing Projects into Workspace from the list, and press Next
3. Select the project you created above
   • Select root directory: C:\java\geotools-example
4. Finish

Your New Project

POM.XML

You can now open up your pom.xml file and have a look.

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.geotools.demo.example</groupId>
  <artifactId>geotools-example</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>geotools-example</name>
  <url>http://maven.apache.org</url>
  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
  </dependencies>
</project>

This file describes your project for maven. Right now you have a single dependency on junit version 3.8.1.

You should be able to see this dependency in your IDE as well.

Making it a GeoTools Project

Depending on GeoTools

To make use of GeoTools we are going to add two things to your pom.xml file:

• A new dependency (ie GeoTools)
• A list of "repositories" where maven can find GeoTools and all the cool stuff it uses

Here is what that looks like:

<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
  xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
  <modelVersion>4.0.0</modelVersion>
  <groupId>org.geotools.demo.example</groupId>
  <artifactId>geotools-example</artifactId>
  <packaging>jar</packaging>
  <version>1.0-SNAPSHOT</version>
  <name>geotools-example</name>
  <url>http://maven.apache.org</url>

  <dependencies>
    <dependency>
      <groupId>junit</groupId>
      <artifactId>junit</artifactId>
      <version>3.8.1</version>
      <scope>test</scope>
    </dependency>
    <dependency>
      <groupId>org.geotools</groupId>
      <artifactId>gt2-main</artifactId>
      <version>2.4-RC0</version>
    </dependency>
  </dependencies>

  <!-- =========================================================== -->
  <!--     Repositories (ibiblio, refractions...).                 -->
  <!--     This is where Maven looks for dependencies.             -->
  <!-- =========================================================== -->
  <repositories>
    <repository>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <id>ibiblio</id>
      <name>Ibiblio - the public's library and digital archive</name>
      <url>http://www.ibiblio.org/maven2</url>
    </repository>
    
    <repository>
      <id>refractions</id>
      <name>Refractions Research Maven 2 Repository</name>
      <url>http://lists.refractions.net/m2</url>
    </repository>
    
    <repository>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <id>geotools</id>
      <name>Geotools repository</name>
      <url>http://maven.geotools.fr/repository</url>
    </repository>
    
    <repository>
      <snapshots>
        <enabled>false</enabled>
      </snapshots>
      <id>central</id>
      <name>Maven Repository Switchboard</name>
      <url>http://repo1.maven.org/maven2</url>
    </repository>
  </repositories>
</project>

In the future I will just show the dependency section (as we will be adding dependencies over time as we try out more of the library).

Updating the IDE

1. We can regenerate our .classpath and .project files so the IDE knows about this stuff.

   C:java\geotools-example>mvn eclipse:eclipse
   

2. Hit refresh in Eclipse

GeoTools (and a bunch of other stuff) will now show up in your project!)

Modifying Main

Let's open up your App.

package org.geotools.demo.example;

/**
 * Hello world!
 *
 */
public class App 
{
    public static void main( String[] args )
    {
        System.out.println( "Hello World!" );
    }
}

And add some GeoTools code to it.

package org.geotools.demo.example;

import org.geotools.factory.GeoTools;
/**
 * Hello world!
 *
 */
public class App 
{
    public static void main( String[] args )
    {
        System.out.println( "Hello GeoTools:" + GeoTools.getVersion() );
    }
}

Running The Application

You can run the application from your IDE.

Hello GeoTools:2.4.SNAPSHOT

Or from the command line:

C:\java\geotools-example>mvn exec:java -Dexec.mainClass="org.geotools.demo.example.App
[INFO] Scanning for projects...
[INFO] Searching repository for plugin with prefix: 'exec'.
[INFO] ----------------------------------------------------------------------------
[INFO] Building geotools-example
[INFO]    task-segment: [exec:java]
[INFO] ----------------------------------------------------------------------------
[INFO] Preparing exec:java
[INFO] No goals needed for project - skipping
[INFO] [exec:java]
Hello GeoTools:2.4.SNAPSHOT
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESSFUL
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1 second
[INFO] Finished at: Tue May 29 11:19:13 PDT 2007
[INFO] Final Memory: 3M/6M
[INFO] ------------------------------------------------------------------------

Fun Fun Fun.

Congratulations

You have completed your first GeoTools application, you are now ready to proceed to 04 How to Read a Shapefile.

Questions

Q: I am unplugged from the Internet- can I still use Maven?

Maven really likes the internet, but you can ask it to work offline:

mvn -o install

Q: My maven build could not download a required jar

The world wide web is an interesting place; the maven servers are under attack from so many projects that they occasionally skip people. And "people" does on occasion include you.

Please try again!

If that still does not work can you confirm that the "required jar" is actually available in the external repository.

Q: I want to use some random library

You can look up that library here:

• http://mvnrepository.com/

The website is really nice and will include the dependency xml fragment for you to cut and paste.

For many of the geospatial specific libraries they are only to be found on the refractions maven repository:

• http://lists.refractions.net/m2/

Q: I added some random library and mvn eclipse:eclipse did not find it

The "mvn eclipse:eclipse" command just sets up your .project and .classpath files - you will need to use one of the normal maven targets to actually get it to download stuff.

To download:

mvn compile

To force a download of everything:

mvn -U compile

And then hit refresh and your eclipse project should be happy.