Eclipse Quickstart

Welcome Eclipse Developers

Welcome to Geospatial for Java. This workbook is aimed at Java developers who are new to geospatial and would like to get started.

We are going to start out carefully with the steps needed to set up your Eclipse IDE. This workbook is also available for NetBeans or Maven command line use. If you are comfortable with the build tool Maven, it is our preferred option for downloading and managing jars but we will also document how to set up things by hand.

These are visual tutorials that allows you to see what you are working with while you learn. These examples make use of Swing; be assured that this is only to make the examples easy and fun to use. These sessions are applicable to both server side and client side development.

Java Install

We are going to be making use of Java, so if you don’t have a Java Development Kit installed now is the time to do so. Even if you have Java installed already check out the optional Java Advanced Imaging and Java Image IO section.

  1. Download the latest Java Development Kit (JDK) from the Oracle website:

    http://www.oracle.com/technetwork/java/javase/downloads/

  2. At the time of writing the latest was JDK 8. Choose a download for your platform, for example:

    jdk-8u66-windows-i586.exe

    For Windows 32bit platforms.

  3. Click through the installer. You will need to accept a license agreement, choose a directory and so forth.

    By default this will install to:

    C:\\Program Files\\Java\\jdk1.8.0\\

  4. Optional: Java Advanced Imaging is used by GeoTools for raster support. If you install JAI 1.1.3 performance will be improved:

    http://www.oracle.com/technetwork/java/javase/tech/jai-142803.html

    Both a JDK and JRE installer are available:

    • jai-1_1_3-lib-windows-i586-jdk.exe

    • jai-1_1_3-lib-windows-i586-jre.exe

  5. Optional: ImageIO Is used to read and write raster files. GeoTools uses version 1_1 of the ImageIO library:

https://docs.oracle.com/javase/6/docs/technotes/guides/imageio/index.html

Both a JDK and JRE installer are available:

  • jai_imageio-1_1-lib-windows-i586-jdk.exe

  • jai_imageio-1_1-lib-windows-i586-jre.exe

For more details of how to install these packages see this page

Eclipse

Eclipse is a popular integrated development environment most often used for all kinds of Java development. For this tutorial we are doing straight up Java programming using the smallest download available - if you already have an Eclipse download please go ahead and use it and switch to the “Java Perspective”.

  1. Visit the Eclipse download page (http://www.eclipse.org/downloads/eclipse-packages/) and download “Eclipse IDE for Java developers”.

  2. Eclipse now provides an installer; however this tutorial targets the binary packages that you simply extract and run.

  3. To start out with create the folder C:\java to keep all our java development in one spot.

  4. Unzip the downloaded eclipse-java-mars-R-win32.zip file to your C:\\java directory - the folder C:\\java\\eclipse will be created.

  5. Navigate to C:\\java\\eclipse and right-click on the eclipse.exe file and select Send To -> Desktop (create shortcut).

  6. Open up the eclipse.ini file.

    • Use our JDK directly by providing a -vm argument

  7. Double click on your desktop shortcut to start up eclipse.

  8. When you start up eclipse for the first time it will prompt you for a workspace. To keep our java work in one spot you can type in:

    C:\\java\\workspace

  9. On the Welcome view press Workbench along the right hand side and we can get started

M2E

Maven is a build system for Java which is very good at managing dependencies. The GeoTools library is plugin based and you get to pick and choose what features you need for your application. While this is useful when determining just what is needed for delivery - it can be a pain to manage by hand so we encourage the use of a tool such as maven.

In previous years we used the command line (gasp!) when working with maven. This year we are going to be using the M2E plugin from Sonyatype.

The M2E plugin is included by default since Eclipse 3.7.

Quickstart

For this Quickstart we are going to produce a simple maven project, hook it up to GeoTools, and then display a shapefile.

This tutorial is really focused on your development environment and making sure you have GeoTools ready to go. We will cover what a shapefile is and how the map is displayed shortly.

Creating a Simple Maven project

Maven works by asking you to describe your project, the name, the version number, where the source code is, how you want it packaged, and what libraries it makes use of. Based on the description it can figure out most things: how to compile your code, creating javadocs, or even downloading the library jars for you.

To use M2E plugin to create a create a new maven project:

  1. File > New > Other from the menu bar

  2. Select the wizard Maven > Maven Project and press Next to open the New Maven Project wizard

  3. The New Maven project page defaults are fine, press Next

    ../../_images/newmaven.png
  4. The default of maven-archtype-quickstart is fine, press Next

    ../../_images/archetype.png
  5. The archetype acts a template using the parameters we supply to create the project.

    • Group Id: org.geotools

    • Artifact Id: tutorial

    • Version: 0.0.1-SNAPSHOT (default)

    • Package: org.geotools.tutorial

    ../../_images/artifact.png
  6. Press Finish to create the new project.

  7. You can see that an application has been created; complete with App.java and a JUnit test case

  8. Open up src/main/java and select org.geotools.tutorial.App and press the Run button in the toolbar:

    Hello World!
    
  9. You may also open up src/main/test and run org.geotools.tutorial.AppTest as a JUnit Test.

Adding Jars to your Project

The pom.xml file is used to describe the care and feeding of your maven project; we are going to focus on the dependencies needed for your project

When downloading jars maven makes use of a “local repository” to store jars.

PLATFORM

LOCAL REPOSITORY

Windows XP:

C:\Documents and Settings\You\.m2\repository

Windows:

C:\Users\You\.m2repository

Linux and Mac:

~/.m2/repository

To download jars maven makes use of public maven repositories on the internet where projects such as GeoTools publish their work.

  1. Open up pom.xml in your new project. You can see some of the information we entered earlier.

    ../../_images/pomOverview.jpg
  2. This editor allows you to describe all kinds of things; in the interest of time we are going to skip the long drawn out explanation and ask you to click on the pom.xml tab.

  3. To make use of GeoTools we are going to add three things to this pom.xml file.

  4. At the top after moduleVersion add a properties element defining the version of GeoTools we want to use. This workbook was written for 30-SNAPSHOT although you may wish to try a different version.

    For production a stable release of 30 should be used for geotools.version:

      <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <geotools.version>30-SNAPSHOT</geotools.version>
        <maven.deploy.skip>true</maven.deploy.skip>
      </properties>
    

    To make use of a nightly build set the geotools.version property to 30-SNAPSHOT .

  5. We are going to add a dependence to GeoTools gt-main and gt-swing jars. Note use of geotools.version defined above.

      <dependencies>
        <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.13.2</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-shapefile</artifactId>
          <version>${geotools.version}</version>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-swing</artifactId>
          <version>${geotools.version}</version>
        </dependency>
      </dependencies>
    
  6. Finally we need to list the external repositories where maven can download GeoTools and other required jars from.

      <repositories>
        <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
        <releases><enabled>true</enabled></releases>
        </repository>
        <repository>
        <id>osgeo-snapshot</id>
        <name>OSGeo Snapshot Repository</name>
        <url>https://repo.osgeo.org/repository/snapshot/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
        </repository>
      </repositories>
    

    Note

    Note the snapshot repository above is only required if you are using a nightly build (such as 30-SNAPSHOT)

  7. GeoTools now requires Java 11 - you need to tell Maven to use the 11 source level.

      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
    
  8. Here is what the completed pom.xml 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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
      <groupId>org.geotools.tutorial</groupId>
      <artifactId>quickstart</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      <packaging>jar</packaging>
      <name>GeoTools Quickstart</name>
      <url>http://maven.apache.org</url>
      <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <geotools.version>30-SNAPSHOT</geotools.version>
        <maven.deploy.skip>true</maven.deploy.skip>
      </properties>
      <dependencies>
        <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.13.2</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-shapefile</artifactId>
          <version>${geotools.version}</version>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-swing</artifactId>
          <version>${geotools.version}</version>
        </dependency>
      </dependencies>
      <repositories>
        <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
        <releases><enabled>true</enabled></releases>
        </repository>
        <repository>
        <id>osgeo-snapshot</id>
        <name>OSGeo Snapshot Repository</name>
        <url>https://repo.osgeo.org/repository/snapshot/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
        </repository>
      </repositories>
      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
    </project>
    
    • Recommend cutting and pasting the above to avoid mistakes when typing

    • You may also download pom.xml, if this opens in your browser use Save As to save to disk.

      The download has an optional quality assurance profile you can safely ignore.

Tips:

  • If maven has trouble downloading any jar; you can try again by selecting Project ‣ Update All Maven Dependencies.

  • If the dependencies do not update automatically use Project ‣ Clean

Quickstart Application

Now that your environment is setup we can put together a simple Quickstart. This example will display a shapefile on screen.

  1. Create the package org.geotools.tutorial.quickstart using your IDE.

  2. Create the org.geotools.tutorial.quickstart.Quickstart class using your IDE.

    ../../_images/class.png
  3. Fill in the following code Quickstart.java:

    /*
     *    GeoTools Sample code and Tutorials by Open Source Geospatial Foundation, and others
     *    https://docs.geotools.org
     *
     *    To the extent possible under law, the author(s) have dedicated all copyright
     *    and related and neighboring rights to this software to the public domain worldwide.
     *    This software is distributed without any warranty.
     * 
     *    You should have received a copy of the CC0 Public Domain Dedication along with this
     *    software. If not, see <http://creativecommons.org/publicdomain/zero/1.0/>.
     */
     package org.geotools.tutorial.quickstart;
    
    import java.io.File;
    import java.util.logging.Logger;
    
    import org.geotools.api.data.FileDataStore;
    import org.geotools.api.data.FileDataStoreFinder;
    import org.geotools.api.data.SimpleFeatureSource;
    import org.geotools.map.FeatureLayer;
    import org.geotools.map.Layer;
    import org.geotools.map.MapContent;
    import org.geotools.styling.SLD;
    import org.geotools.api.style.Style;
    import org.geotools.swing.JMapFrame;
    import org.geotools.swing.data.JFileDataStoreChooser;
    
    /**
     * Prompts the user for a shapefile and displays the contents on the screen in a map frame.
     *
     * <p>This is the GeoTools Quickstart application used in documentationa and tutorials. *
     */
    public class Quickstart {
    
        private static final Logger LOGGER = org.geotools.util.logging.Logging.getLogger(Quickstart.class);
        /**
         * GeoTools Quickstart demo application. Prompts the user for a shapefile and displays its
         * contents on the screen in a map frame
         */
        public static void main(String[] args) throws Exception {
            // display a data store file chooser dialog for shapefiles
            LOGGER.info( "Quickstart");
            LOGGER.config( "Welcome Developers");
            LOGGER.info("java.util.logging.config.file="+System.getProperty("java.util.logging.config.file"));
            File file = JFileDataStoreChooser.showOpenFile("shp", null);
            if (file == null) {
                return;
            }
            LOGGER.config("File selected "+file);
    
            FileDataStore store = FileDataStoreFinder.getDataStore(file);
            SimpleFeatureSource featureSource = store.getFeatureSource();
    
            // Create a map content and add our shapefile to it
            MapContent map = new MapContent();
            map.setTitle("Quickstart");
    
            Style style = SLD.createSimpleStyle(featureSource.getSchema());
            Layer layer = new FeatureLayer(featureSource, style);
            map.addLayer(layer);
    
            // Now display the map
            JMapFrame.showMap(map);
        }
    }
    
    • You may find cutting and pasting from the documentation to be easier then typing.

    • You may also download Quickstart.java

  4. We need to download some sample data to work with. The http://www.naturalearthdata.com/ project is a great project supported by the North American Cartographic Information Society. Head to the link below and download some cultural vectors. You can use the ‘Download all 50m cultural themes’ at top.

    Please unzip the above data into a location you can find easily such as the desktop.

  5. Run the application to open a file chooser. Choose a shapefile from the example data set.

    ../../_images/QuickstartOpen.png
  6. The application will connect to your shapefile, produce a map content, and display the shapefile.

    ../../_images/QuickstartMap.png
  7. A couple of things to note about the code example:

  • The shapefile is not loaded into memory - instead it is read from disk each and every time it is needed This approach allows you to work with data sets larger than available memory.

  • We are using a very basic display style here that just shows feature outlines. In the examples that follow we will see how to specify more sophisticated styles.

Things to Try

Each tutorial consists of very detailed steps followed by a series of extra questions. If you get stuck at any point please ask your instructor; or sign up to the geotools-users email list.

Here are some additional challenges for you to try:

  • Try out the different sample data sets.

  • Zoom in, zoom out and show the full extent and use the info tool to examine individual countries in the sample countries.shp file.

  • Download the largest shapefile you can find and see how quickly it can be rendered. You should find that the very first time it will take a while as a spatial index is generated. After that rendering will become much faster.

  • Fast: We know that one of the ways people select a spatial library is based on speed. By design GeoTools does not load the above shapefile into memory (instead it streams it off of disk each time it is drawn using a spatial index to only bring the content required for display).

    If you would like to ask GeoTools to cache the shapefile in memory try the following code:

        /**
         * This method demonstrates using a memory-based cache to speed up the display (e.g. when
         * zooming in and out).
         *
         * <p>There is just one line extra compared to the main method, where we create an instance of
         * CachingFeatureStore.
         */
        public static void main(String[] args) throws Exception {
            // display a data store file chooser dialog for shapefiles
            File file = JFileDataStoreChooser.showOpenFile("shp", null);
            if (file == null) {
                return;
            }
    
            FileDataStore store = FileDataStoreFinder.getDataStore(file);
            SimpleFeatureSource featureSource = store.getFeatureSource();
            SimpleFeatureSource cachedSource =
                    DataUtilities.source(
                            new SpatialIndexFeatureCollection(featureSource.getFeatures()));
    
            // Create a map content and add our shapefile to it
            MapContent map = new MapContent();
            map.setTitle("Using cached features");
            Style style = SLD.createSimpleStyle(featureSource.getSchema());
            Layer layer = new FeatureLayer(cachedSource, style);
            map.addLayer(layer);
    
            // Now display the map
            JMapFrame.showMap(map);
        }
    

    For the above example to compile you will need to add the necessary imports.

    Note

    When building you may see a message that CachingFeatureSource is deprecated. It’s OK to ignore it, it’s just a warning. The class is still under test but usable.

  • Try and sort out what all the different “side car” files are – and what they are for. The sample data set includes shp, dbf and shx. How many other side car files are there?

  • Advanced: The use of FileDataStoreFinder allows us to work easily with files. The other way to do things is with a map of connection parameters. This techniques gives us a little more control over how we work with a shapefile and also allows us to connect to databases and web feature servers.

            File file = JFileDataStoreChooser.showOpenFile("shp", null);
    
            Map<String, Object> params = new HashMap<>();
            params.put("url", file.toURI().toURL());
            params.put("create spatial index", false);
            params.put("memory mapped buffer", false);
            params.put("charset", "ISO-8859-1");
    
            DataStore store = DataStoreFinder.getDataStore(params);
            SimpleFeatureSource featureSource = store.getFeatureSource(store.getTypeNames()[0]);
    
  • Important: GeoTools is an active open source project – you can quickly use maven to try out the latest nightly build by changing your pom.xml file to use a SNAPSHOT release.

    At the time of writing 30-SNAPSHOT is under active development.

    <properties>
    &nbsp;&nbsp;<project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
    &nbsp;&nbsp;<geotools.version>|branch|-SNAPSHOT</geotools.version>
    </properties>

    Double check your pom.xml file to include the OSGeo snapshot repository:

      <repositories>
        <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
        <releases><enabled>true</enabled></releases>
        </repository>
        <repository>
        <id>osgeo-snapshot</id>
        <name>OSGeo Snapshot Repository</name>
        <url>https://repo.osgeo.org/repository/snapshot/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
        </repository>
      </repositories>
      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
      <profiles>
        <profile>
          <id>qa</id>
          <activation>
            <property>
              <name>qa</name>
            </property>
          </activation>
          <properties>
            <maven.pmd.plugin.version>3.20.0</maven.pmd.plugin.version>
            <pmd.version>6.55.0</pmd.version>
            <pom.fmt.action>sort</pom.fmt.action>
          </properties>
          <build>
            <plugins>
              <plugin>
                <artifactId>maven-pmd-plugin</artifactId>
                <version>3.14.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-core</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-java</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <linkXRef>false</linkXRef>
                  <rulesets>
                    <ruleset>${project.basedir}/../../build/qa/pmd-ruleset.xml</ruleset>
                    <ruleset>${project.basedir}/../../build/qa/pmd-junit-ruleset.xml</ruleset>
                  </rulesets>
                  <failurePriority>3</failurePriority>
                  <minimumPriority>3</minimumPriority>
                  <verbose>true</verbose>
                  <printFailingErrors>true</printFailingErrors>
                  <includeTests>true</includeTests>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.spotbugs</groupId>
                <artifactId>spotbugs-maven-plugin</artifactId>
                <version>4.0.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <effort>More</effort>
                  <!-- threshold>High</threshold -->
                  <xmlOutput>true</xmlOutput>
                  <maxRank>15</maxRank>
                  <excludeFilterFile>${project.basedir}/../../build/qa/spotbugs-exclude.xml</excludeFilterFile>
                  <jvmArgs>-XX:+TieredCompilation -XX:TieredStopAtLevel=1</jvmArgs>
                  <compilerArgs combine.children="append">
                    <arg>-Xlint:${lint}</arg>
                  </compilerArgs>
                </configuration>
              </plugin>
              <plugin>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <version>3.1.2</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>com.puppycrawl.tools</groupId>
                    <artifactId>checkstyle</artifactId>
                    <version>9.3</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <logViolationsToConsole>true</logViolationsToConsole>
                  <configLocation>${project.basedir}/../..//build/qa/checkstyle-cc0.xml</configLocation>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.ekryd.sortpom</groupId>
                <artifactId>sortpom-maven-plugin</artifactId>
                <version>2.15.0</version>
                <executions>
                  <execution>
                    <phase>verify</phase>
                    <goals>
                      <goal>${pom.fmt.action}</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <skip>true</skip>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
    

    You can check the status of the build server producing current 30-SNAPSHOT here:

  • When cutting and pasting GeoTools code examples use Control-Shift-O to organise imports (resolving any missing imports).

  • So what jars did maven actually use for the Quickstart application? Open up your pom.xml and switch to the dependency hierarchy or dependency graph tabs to see what is going on.

    ../../_images/quickstart-dependency.png

    We will be making use of some of the project in greater depth in the remaining tutorials.

Alternatives to M2Eclipse

There are two alternatives to the use of the M2Eclipse plugin; you may find these better suit the needs of your organization.

Maven Plugin

The first alternative to using eclipse to setup a maven project … is using a maven to setup an eclipse project.

The maven build tool also works directly on the command line; and includes a plugin for generating eclipse .project and .classpath files used by Eclipse.

  1. Download Maven from http://maven.apache.org/download.html

    The last version we tested with was: Maven 3.3.3

  2. Unzip the file apache-maven-3.3.3-bin.zip to C:\java\apache-maven-3.3.3

  3. You need to have a couple of environmental variables set for maven to work. Use Control Panel ‣ System ‣ Advanced ‣ Environmental Variables to set the following System Variables:

    Add the following system variables:

    • JAVA_HOME = :file:`C:\\Program Files (x86)\\Java\\jdk1.8.0_66`

    • MAVEN_HOME = :file:`C:\\java\\apache-maven-3.8.6`

    And add the following to your PATH:

    • PATH = :file:`%JAVA_HOME%\\bin;%MAVEN_HOME%\\bin`

    ../../_images/env-variables.png
  4. Open up a commands prompt Accessories ‣ Command Prompt

  5. Type the following command to confirm you are set up correctly:

    C:\\java> mvn -version
    

    If the mvn command is not found check your path using:

    C:\\java> echo %PATH%
    
  6. This should produce the following output

    ../../_images/maven-version.png
  7. We can now generate our project from maven-archetype-quickstart with:

    C:>cd C:\java
    C:java>  mvn archetype:generate -DgroupId=org.geotools -DartifactId=tutorial -Dversion=1.0-SNAPSHOT -DarchetypeGroupId=org.apache.maven.archetypes -DarchetypeArtifactId=maven-archetype-quickstart
    
  8. And ask for our project to be set up for eclipse:

    C:java> cd tutorial
    C:java\tutorial> mvn eclipse:eclipse
    
  9. You can now give Eclipse the background information it needs to talk to your “maven repository” (maven downloaded something like 30 jars for you)

  10. Return to Eclipse

  11. Use Windows ‣ Preferences to open the Preference Dialog. Using the tree on the left navigate to the Java > Build path > Classpath Variables preference Page.

../../_images/classpath-variables.png
  1. Add an M2_REPO classpath variable pointing to your “local repository”

    PLATFORM

    LOCAL REPOSITORY

    Windows XP:

    C:\Documents and Settings\Jody\.m2\repository

    Windows:

    C:\Users\Jody.m2\repository

    Linux and Mac:

    ~/.m2/repository

  2. We can now import your new project into eclipse using File ‣ Import

  3. Choose Existing Projects into Workspace from the list, and press Next

    ../../_images/import-existing.png
  4. Select the project you created: C:javatutorial

  5. Press Finish to import your project

  6. Navigate to the pom.xml file and double click to open it up.

  7. We are going to start by defining the version number of GeoTools we wish to use. This workbook was written for 30-SNAPSHOT although you may wish to try a newer version, or make use of a nightly build by using something like 15-SNAPSHOT.

      <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <geotools.version>30-SNAPSHOT</geotools.version>
        <maven.deploy.skip>true</maven.deploy.skip>
      </properties>
    
  8. The following dependencies:

      <dependencies>
        <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.13.2</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-shapefile</artifactId>
          <version>${geotools.version}</version>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-swing</artifactId>
          <version>${geotools.version}</version>
        </dependency>
      </dependencies>
    
  9. Setup repositories to download GeoTools from:

      <repositories>
        <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
        <releases><enabled>true</enabled></releases>
        </repository>
        <repository>
        <id>osgeo-snapshot</id>
        <name>OSGeo Snapshot Repository</name>
        <url>https://repo.osgeo.org/repository/snapshot/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
        </repository>
      </repositories>
      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
      <profiles>
        <profile>
          <id>qa</id>
          <activation>
            <property>
              <name>qa</name>
            </property>
          </activation>
          <properties>
            <maven.pmd.plugin.version>3.20.0</maven.pmd.plugin.version>
            <pmd.version>6.55.0</pmd.version>
            <pom.fmt.action>sort</pom.fmt.action>
          </properties>
          <build>
            <plugins>
              <plugin>
                <artifactId>maven-pmd-plugin</artifactId>
                <version>3.14.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-core</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-java</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <linkXRef>false</linkXRef>
                  <rulesets>
                    <ruleset>${project.basedir}/../../build/qa/pmd-ruleset.xml</ruleset>
                    <ruleset>${project.basedir}/../../build/qa/pmd-junit-ruleset.xml</ruleset>
                  </rulesets>
                  <failurePriority>3</failurePriority>
                  <minimumPriority>3</minimumPriority>
                  <verbose>true</verbose>
                  <printFailingErrors>true</printFailingErrors>
                  <includeTests>true</includeTests>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.spotbugs</groupId>
                <artifactId>spotbugs-maven-plugin</artifactId>
                <version>4.0.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <effort>More</effort>
                  <!-- threshold>High</threshold -->
                  <xmlOutput>true</xmlOutput>
                  <maxRank>15</maxRank>
                  <excludeFilterFile>${project.basedir}/../../build/qa/spotbugs-exclude.xml</excludeFilterFile>
                  <jvmArgs>-XX:+TieredCompilation -XX:TieredStopAtLevel=1</jvmArgs>
                  <compilerArgs combine.children="append">
                    <arg>-Xlint:${lint}</arg>
                  </compilerArgs>
                </configuration>
              </plugin>
              <plugin>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <version>3.1.2</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>com.puppycrawl.tools</groupId>
                    <artifactId>checkstyle</artifactId>
                    <version>9.3</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <logViolationsToConsole>true</logViolationsToConsole>
                  <configLocation>${project.basedir}/../..//build/qa/checkstyle-cc0.xml</configLocation>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.ekryd.sortpom</groupId>
                <artifactId>sortpom-maven-plugin</artifactId>
                <version>2.15.0</version>
                <executions>
                  <execution>
                    <phase>verify</phase>
                    <goals>
                      <goal>${pom.fmt.action}</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <skip>true</skip>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
    

Note

Note the snapshot repository above is only required if you are using a nightly build (such as 30-SNAPSHOT)

  1. GeoTools now requires Java 11 - you need to tell Maven to use the 11 source level.

      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
      <profiles>
        <profile>
          <id>qa</id>
          <activation>
            <property>
              <name>qa</name>
            </property>
          </activation>
          <properties>
            <maven.pmd.plugin.version>3.20.0</maven.pmd.plugin.version>
            <pmd.version>6.55.0</pmd.version>
            <pom.fmt.action>sort</pom.fmt.action>
          </properties>
          <build>
            <plugins>
              <plugin>
                <artifactId>maven-pmd-plugin</artifactId>
                <version>3.14.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-core</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-java</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <linkXRef>false</linkXRef>
                  <rulesets>
                    <ruleset>${project.basedir}/../../build/qa/pmd-ruleset.xml</ruleset>
                    <ruleset>${project.basedir}/../../build/qa/pmd-junit-ruleset.xml</ruleset>
                  </rulesets>
                  <failurePriority>3</failurePriority>
                  <minimumPriority>3</minimumPriority>
                  <verbose>true</verbose>
                  <printFailingErrors>true</printFailingErrors>
                  <includeTests>true</includeTests>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.spotbugs</groupId>
                <artifactId>spotbugs-maven-plugin</artifactId>
                <version>4.0.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <effort>More</effort>
                  <!-- threshold>High</threshold -->
                  <xmlOutput>true</xmlOutput>
                  <maxRank>15</maxRank>
                  <excludeFilterFile>${project.basedir}/../../build/qa/spotbugs-exclude.xml</excludeFilterFile>
                  <jvmArgs>-XX:+TieredCompilation -XX:TieredStopAtLevel=1</jvmArgs>
                  <compilerArgs combine.children="append">
                    <arg>-Xlint:${lint}</arg>
                  </compilerArgs>
                </configuration>
              </plugin>
              <plugin>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <version>3.1.2</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>com.puppycrawl.tools</groupId>
                    <artifactId>checkstyle</artifactId>
                    <version>9.3</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <logViolationsToConsole>true</logViolationsToConsole>
                  <configLocation>${project.basedir}/../..//build/qa/checkstyle-cc0.xml</configLocation>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.ekryd.sortpom</groupId>
                <artifactId>sortpom-maven-plugin</artifactId>
                <version>2.15.0</version>
                <executions>
                  <execution>
                    <phase>verify</phase>
                    <goals>
                      <goal>${pom.fmt.action}</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <skip>true</skip>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
    
  2. Here is what the completed pom.xml 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 https://maven.apache.org/xsd/maven-4.0.0.xsd">
      <modelVersion>4.0.0</modelVersion>
      <groupId>org.geotools.tutorial</groupId>
      <artifactId>quickstart</artifactId>
      <version>0.0.1-SNAPSHOT</version>
      <packaging>jar</packaging>
      <name>GeoTools Quickstart</name>
      <url>http://maven.apache.org</url>
      <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <geotools.version>30-SNAPSHOT</geotools.version>
        <maven.deploy.skip>true</maven.deploy.skip>
      </properties>
      <dependencies>
        <dependency>
          <groupId>junit</groupId>
          <artifactId>junit</artifactId>
          <version>4.13.2</version>
          <scope>test</scope>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-shapefile</artifactId>
          <version>${geotools.version}</version>
        </dependency>
        <dependency>
          <groupId>org.geotools</groupId>
          <artifactId>gt-swing</artifactId>
          <version>${geotools.version}</version>
        </dependency>
      </dependencies>
      <repositories>
        <repository>
        <id>osgeo</id>
        <name>OSGeo Release Repository</name>
        <url>https://repo.osgeo.org/repository/release/</url>
        <snapshots><enabled>false</enabled></snapshots>
        <releases><enabled>true</enabled></releases>
        </repository>
        <repository>
        <id>osgeo-snapshot</id>
        <name>OSGeo Snapshot Repository</name>
        <url>https://repo.osgeo.org/repository/snapshot/</url>
        <snapshots><enabled>true</enabled></snapshots>
        <releases><enabled>false</enabled></releases>
        </repository>
      </repositories>
      <build>
        <plugins>
          <plugin>
            <inherited>true</inherited>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-compiler-plugin</artifactId>
            <version>3.10.1</version>
            <configuration>
              <source>1.8</source>
              <target>1.8</target>
            </configuration>
          </plugin>
        </plugins>
      </build>
      <profiles>
        <profile>
          <id>qa</id>
          <activation>
            <property>
              <name>qa</name>
            </property>
          </activation>
          <properties>
            <maven.pmd.plugin.version>3.20.0</maven.pmd.plugin.version>
            <pmd.version>6.55.0</pmd.version>
            <pom.fmt.action>sort</pom.fmt.action>
          </properties>
          <build>
            <plugins>
              <plugin>
                <artifactId>maven-pmd-plugin</artifactId>
                <version>3.14.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-core</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                  <dependency>
                    <groupId>net.sourceforge.pmd</groupId>
                    <artifactId>pmd-java</artifactId>
                    <version>${pmd.version}</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <linkXRef>false</linkXRef>
                  <rulesets>
                    <ruleset>${project.basedir}/../../build/qa/pmd-ruleset.xml</ruleset>
                    <ruleset>${project.basedir}/../../build/qa/pmd-junit-ruleset.xml</ruleset>
                  </rulesets>
                  <failurePriority>3</failurePriority>
                  <minimumPriority>3</minimumPriority>
                  <verbose>true</verbose>
                  <printFailingErrors>true</printFailingErrors>
                  <includeTests>true</includeTests>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.spotbugs</groupId>
                <artifactId>spotbugs-maven-plugin</artifactId>
                <version>4.0.0</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <effort>More</effort>
                  <!-- threshold>High</threshold -->
                  <xmlOutput>true</xmlOutput>
                  <maxRank>15</maxRank>
                  <excludeFilterFile>${project.basedir}/../../build/qa/spotbugs-exclude.xml</excludeFilterFile>
                  <jvmArgs>-XX:+TieredCompilation -XX:TieredStopAtLevel=1</jvmArgs>
                  <compilerArgs combine.children="append">
                    <arg>-Xlint:${lint}</arg>
                  </compilerArgs>
                </configuration>
              </plugin>
              <plugin>
                <artifactId>maven-checkstyle-plugin</artifactId>
                <version>3.1.2</version>
                <executions>
                  <execution>
                    <goals>
                      <goal>check</goal>
                    </goals>
                  </execution>
                </executions>
                <dependencies>
                  <dependency>
                    <groupId>com.puppycrawl.tools</groupId>
                    <artifactId>checkstyle</artifactId>
                    <version>9.3</version>
                  </dependency>
                </dependencies>
                <configuration>
                  <logViolationsToConsole>true</logViolationsToConsole>
                  <configLocation>${project.basedir}/../..//build/qa/checkstyle-cc0.xml</configLocation>
                </configuration>
              </plugin>
              <plugin>
                <groupId>com.github.ekryd.sortpom</groupId>
                <artifactId>sortpom-maven-plugin</artifactId>
                <version>2.15.0</version>
                <executions>
                  <execution>
                    <phase>verify</phase>
                    <goals>
                      <goal>${pom.fmt.action}</goal>
                    </goals>
                  </execution>
                </executions>
                <configuration>
                  <skip>true</skip>
                </configuration>
              </plugin>
            </plugins>
          </build>
        </profile>
      </profiles>
    </project>
    
    • Recommend cutting and pasting the above to avoid mistakes when typing

    • You may also download pom.xml, if this opens in your browser use Save As to save to disk.

  1. Return to the command line and maven to download the required jars and tell eclipse about it:

    C:\java\example> mvn eclipse:eclipse
    
  2. Return to eclipse and select the project folder. Refresh your project using the context menu or by pressing F5. If you open up referenced libraries you will see the required jars listed.

    ../../_images/maven-refresh.png
  3. Using this technique of running mvn eclipse:eclipse and refreshing in eclipse you can proceed through all the tutorial examples.

Download GeoTools

We can also download the GeoTools project bundle from source forge and set up our project to use them. Please follow these steps carefully as not all the GeoTools jars can be used at the same time.

  1. Download the GeoTools binary release from http://sourceforge.net/projects/geotools/files

  2. We are now going to make a project for the required jars. By placing the jars into their own project is is easier to upgrade GeoTools.

    Select File > New > Java Project to open the New Java Project wizard

  3. Type in “GeoTools Download” as the name of the project and press Finish.

  4. Choose File > Import to open the Import Wizard.

  5. Select General > Archive File and press Next

  6. Navigate to the geotools-bin.zip download and import the contents into your project.

  1. Next we update our Java build path to include the remaining jars. Choose Project > Properties from the menu bar

  2. Select Java Build Path property page; and switch to the library tab.

  3. Press Add JARs button and add all the jars in the lib folder.

  4. Switch to the Order and Export tab and press Select All

  5. We can now create a new Example project to get going on our Example.

  6. Use Project > Properties on your new Example project to open up the Java Build Path page.

  7. Switch to the Projects tab and use the Add.. button to add GeoTools Downloads to the build path.

  8. Our example project can now use all the GeoTools jars.

  9. Please proceed to the Quickstart, the bin download already includes Quickstart.java for your use.