Skill Level: Any Skill Level

GeoTools is an open source toolkit that provides a Java API to work with spatial data. This recipe takes you through the steps to visualize and access spatial data in a DB2 for z/OS, DB2 LUW or DashDB database.


With this recipe you will populate DB2 tables with spatial data, display a simple map and use the GeoTools API to access spatial data  from DB2.

This recipe uses Eclipse on Ubuntu Linux but any Java development environment can be used on Windows, OS-X or Linux platforms.


  1. Setup DB2 and sample data

    1. Note: this recipe uses GeoTools on Ubuntu Linux connecting to a local DB2 database. Change the database connection values in the examples to your database name and userid.

    2. Download and unzip the sample data to a convenient directory.

    3. Open a DB2 command window where you can execute SQL statements. If you are using a remote database, make sure it is cataloged locally. You can use the scripts catalog-luw.sql or catalog-zos.sql as appropriate and make changes for the remote server location. (Use catalog-luw.sql for DashDB)

      You can execute the script with a command like:
      db2 -tvf catalog-luw.sql

    4. Import sample spatial for banks, customers and San Jose streets.
      – Modify the scripts import-luw.sql or import-zos.sql as appropriate to change the userid in the stored procedure. (The scripts contain descriptions of each of the steps and any modifications needed.
      – Execute the script with a command like:
      db2 -tvf import-luw.sql
      – Check that there were no processing errors

    5. Verify the imported data with the SQL statement (change “osuser” to your connection userid):
      db2 select name, street, varchar(db2gse.st_astext(geom),32) from osuser.banks
      which should return the name, street address and location of the Meridian and San Carlos branches
  2. Setup development environment

    1. If you don't already have a Java 8 JDK (or later) and/or Eclipse environment installed, use the following steps.
    2. Ensure that Java 8 JDK is installed. In a command window, run 'javac -version'. If this doesn't return 1.8 or higher, install the Java 8 JDK with the command:
      sudo apt install openjdk-8-jdk
    3. From eclipse.org, download the Eclipse Java IDE, eclipse-java-neon-1a-linux-gtk.tar.gz, and open with the Archive manager.
  3. Display a shapefile using GeoTools

    Before attempting to access spatial data in it is a good idea to first go through the excellent GeoTools tutorial.

    Instead of downloading and opening the shapefile listed in the tutorial, select the file sjstreets.shp in the db2-recipe-data that was downloaded earlier in setting up the database.


    This should result in a display similar to the following:


  4. Display a map accessing DB2

    1. In Eclipse, use the context menu on the tutorial project to select Build Path > Add External Archives and navigate to the DB2 installation directory and select the db2jcc.jar and db2jcc_license_cu.jar files which in a typical DB2 Linux installation will be in /opt/ibm/db2/V10.5/java.
    2. Edit the pom.xml, add the following dependencies before </dependencies> and save the pom.xml.
    3. Create a new class DB2TestMap, replace the generated code with the source code DB2TestMap.java in db2-recipe-data and save the source file. Comments in the source code describe the various steps to display the connection dialog, connect to DB2, access a particular table (FeatureSource) and display the contents.

    4. Run the application which will display a connection dialog and enter the connection values for your database. Note that the schema must be specified in uppercase.
    5. This should display a similar map as above:
  5. Use the GeoTools API

    Many applications don't need to visualize a map but simply access the spatial data directly in order to perform some analysis.

    Create a new class DB2TestAPI, replace the generated code with the source code DB2TestAPI.java in db2-recipe-data and save the source file.

    Comments in the source code describe the various steps to:

    1. Specify the DB2 connection parameters (hard-coded)

    2. Connect to the DB2 DataStore

    3. Access the BANKS table (FeatureSource) and display the bank name and its location using well-known text

    4. Access the CUSTOMERS table (FeatureSource) to get the bounds of all the customers, a count of all the customers within the bounds and a count of a subset of the customers in a smaller rectangular window.

    Run the application. The output should look like the following:


  6. Conclusion

    GeoTools is a widely-used Java-based GIS toolkit that can be used in most Java environments to build geospatial applications that don't necessarily require visualization of the data.

Join The Discussion