GeoTools

OSGeo

Table Of Contents

Previous topic

Netbeans Quickstart

Next topic

Maven Quickstart

This Page

IntelliJ Quickstart

This guide will help you setup the IntelliJ IDE in order to work with GeoTools and follow along with the rest of the GeoTools tutorial.

Pre-Requisites

This guide assumes the following:

  • You have the latest JDK installed (8 at the time this article was written) installed. If not the TODO Eclipse Quickstart provides instructions on how to do this.
  • You have IntelliJ installed. This article targets IntelliJ CE 2016; however, previous versions at least as far back as 13 should work fine. Ultimate versions should also work fine. IntelliJ can be downloaded from JetBrains and generally works out of the box on common operating systems.

Create a New Project

To start with we’ll create a new project using the Maven quickstart archetype.

  1. Choose File -> New Project from the menu. In the New Project dialog choose Maven project, ensure Create from archetype is selected, and choose the org.apache.maven.archetypes:maven-archetype-quickstart archetype. Press Next

    ../../_images/new_project_screen.png
  2. The next screen asks us for basic identifying information for our project:

    • GroupId: org.geotools
    • ArtifactId: tutorial
    • Version: 1.0-SNAPSHOT
    ../../_images/new_project2.png
  3. Hit next. The following screen we should be able to leave with the defaults. For our purposes IntelliJ’s bundled Maven should be fine, unless the version is lower than 3, in which case you should consider using a new external verision.

    ../../_images/new_project3.png
  4. Hit next. Give the project a name (this name is only used internally by IntelliJ), tutorial should work for our purposes. You can change the project location to suit your needs and hopefully leave More Settings as their defaults (recommended)

    ../../_images/new_project4.png
  5. Hit finish and our new project will be created. IntelliJ will show us our newly created Maven file and do an initial Maven build (let this finish before attempting the next steps, it shouldn’t take long). IntelliJ should also ask if you want to enable Auto Import for Maven dependencies. Let’s turn that on for the purposes of this tutorial, it will automatically detect changes we make to our POM file and automatically import them.

    ../../_images/auto_import.png

IntelliJ has created an empty App.java with a simple Hello World! along with a JUnit test case. You can run App or AppTest by right clicking on them in the Project Explorer and choosing Run from the context menu.

../../_images/run_menu.png

Adding Jars to Your Project

The pom.xml file describes the structure, configuration, dependencies and many other facets of your 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 copies if the dependencies it downloads.

PLATFORM LOCAL REPOSITORY
Windows XP: C:\Documents and Settings\You\.m2\repository
Windows: C:\Users\You\.m2repository
Linux and Mac: ~/.m2/repository

Maven downloads jars from public repositories on the internet where projects such as GeoTools publish their work.

  1. Open up the pom.xml file at the root of the project. You can see some of the information we entered through the wizard earlier.

  2. We’re going to add three things to this file. First, at the top of the file after moduleVersion we want to add a properties element defining the version of GeoTools we wish to use. This workbook was written for 19-SNAPSHOT although you may wish to try a different version.

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

        <properties>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <geotools.version>19-SNAPSHOT</geotools.version>
        </properties>
    

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

        <properties>
            <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
            <geotools.version>19-SNAPSHOT</geotools.version>
        </properties>
    
  3. We are going to add a dependence to GeoTools gt-main and gt-swing jars. Note we are making use of the geotools.version defined above.

        <dependencies>
            <dependency>
                <groupId>junit</groupId>
                <artifactId>junit</artifactId>
                <version>4.11</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>
    
  4. Finally we need to list the external repositories where maven can download GeoTools and and other required jars from.

        <repositories>
            <repository>
                <id>maven2-repository.dev.java.net</id>
                <name>Java.net repository</name>
                <url>http://download.java.net/maven/2</url>
            </repository>
            <repository>
                <id>osgeo</id>
                <name>Open Source Geospatial Foundation Repository</name>
                <url>http://download.osgeo.org/webdav/geotools/</url>
            </repository>
            <repository>
              <snapshots>
                <enabled>true</enabled>
              </snapshots>
              <id>boundless</id>
              <name>Boundless Maven Repository</name>
              <url>http://repo.boundlessgeo.com/main</url>
            </repository>
        </repositories>
    

    Note

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

  5. If you’d like to use Java 8 language level features (eg. lambdas), you need to tell Maven to use the 1.8 source level

        <build>
            <plugins>
                <plugin>
                    <inherited>true</inherited>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-compiler-plugin</artifactId>
                    <configuration>
                        <source>1.8</source>
                        <target>1.8</target>
                    </configuration>
                </plugin>
            </plugins>
        </build>
    
  1. For comparison here is the completed pom.xml file for download.

    You may find cutting and pasting to be easier than typing, you can choose Code -> Reformat Code to fix indentation

Tips:

  • If Maven isn’t downloading dependencies automatically for some reason (maybe Auto-Import is turned off) you can manually download dependencies by right-clicking on your project and choosing Maven -> Reimport.
  • If you’d like to download the Javadoc for your dependencies you can again go to the Maven context menu and choose Download Documentation

Quickstart Application

Now that our environment is set up we can put together a simple Quickstart. This example will display a shapefile on the screen.

  1. Let’s create a class called Quickstart in the package org.geotools.tutorial.quickstart. IntelliJ can create both the package and the class for us in one shot; right click on the org.geootools package in the Project panel and in the context menu choose New -> Java Class.

    ../../_images/new_class_menu.png ../../_images/new_class_dialog.png
  2. Fill in the following code:

package org.geotools.tutorial.quickstart;

import java.io.File;

import org.geotools.data.FileDataStore;
import org.geotools.data.FileDataStoreFinder;
import org.geotools.data.simple.SimpleFeatureSource;
import org.geotools.map.FeatureLayer;
import org.geotools.map.Layer;
import org.geotools.map.MapContent;
import org.geotools.styling.SLD;
import org.geotools.styling.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 {

    /**
     * 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
        File file = JFileDataStoreChooser.showOpenFile("shp", null);
        if (file == null) {
            return;
        }

        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);
    }

}
  1. 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.

  2. Run the application to open a file chooser. Choose a shapefile from the example dataset.

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

    ../../_images/QuickstartMap.png
  4. 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
  • You can zoom in, zoom out and show the full extents and Use the select 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 performance should be very good when zoomed in.
  • Performance: 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).
     * 
     * 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();
        
        // CachingFeatureSource is deprecated as experimental (not yet production ready)
        CachingFeatureSource cache = new CachingFeatureSource(featureSource);

        // 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(cache, style);
        map.addLayer(layer);

        // Now display the map
        JMapFrame.showMap(map);
    }

This code won’t compile initially because we’re missing an import. IntelliJ should prompt to import the missing class immediately. Press Alt-Enter (^-Enter on OS X) to bring up a dialog to import the missing class. It will pull in the following import:

import org.geotools.data.CachingFeatureSource;

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 19-SNAPSHOT is under active development.

    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <geotools.version>19-SNAPSHOT</geotools.version>
    </properties>

You will also need to change your pom.xml file to include the following snapshot repository:

    <repositories>
        <repository>
            <id>maven2-repository.dev.java.net</id>
            <name>Java.net repository</name>
            <url>http://download.java.net/maven/2</url>
        </repository>
        <repository>
            <id>osgeo</id>
            <name>Open Source Geospatial Foundation Repository</name>
            <url>http://download.osgeo.org/webdav/geotools/</url>
        </repository>
        <repository>
            <snapshots>
              <enabled>true</enabled>
            </snapshots>
            <id>boundless</id>
            <name>Boundless Maven Repository</name>
            <url>http://repo.boundlessgeo.com/main</url>
        </repository>
    </repositories>

    <build>
        <plugins>
            <plugin>
                <inherited>true</inherited>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-compiler-plugin</artifactId>
                <configuration>
                    <source>1.8</source>
                    <target>1.8</target>
                </configuration>
            </plugin>
        </plugins>
    </build>