Module Organization

Purpose and Scope

This document explains how modules are organized within the GeoTools library. It describes the different types of modules, their hierarchical relationships, dependencies, and the overall structure of the codebase. For information about specific module implementations, see the respective documentation in Spatial Data Model and Data Access Framework.

Module Types

GeoTools is organized into a hierarchical structure of modules, each with specific responsibilities. These modules are grouped into four main categories based on their role in the library.

100%

Core Modules

Core modules form the foundation of GeoTools, providing essential interfaces and base functionality required by all other modules. These modules define the fundamental data structures and APIs used throughout the library.

Module	Description	Key Responsibility
gt-opengis	OGC/ISO interfaces	Standard interfaces from the Open Geospatial Consortium
gt-api	GeoTools interfaces	Standard interfaces implemented throughout the library
gt-metadata	Metadata	Implementations of metadata and core utility classes
gt-referencing	Referencing	Coordinate Reference Systems (CRS), conversion and transformation services
gt-main	Main	Default implementations of interfaces and factory system

Library Modules

Library modules build upon the core modules to provide common implementations and utilities that are used by multiple plugins. These modules handle specific aspects of geospatial data processing.

Module	Description	Key Responsibility
gt-coverage	Grid Coverage	Support for rasters and image processing
gt-cql	CQL	Constraint Query Language parser
gt-render	Rendering	Visualization of spatial data
gt-jdbc	JDBC	Common database access functionality
gt-xml	XML	XML parsing and encoding

Plugin Modules

Plugin modules provide implementations for specific data formats or services. They typically depend on library modules and extend the functionality to support particular file formats, databases, or web services.

Module	Description	Key Responsibility
gt-shapefile	Shapefile	Access to ESRI Shapefiles
gt-geotiff	GeoTIFF	GeoTIFF raster format support
gt-imagemosaic	ImageMosaic	Mosaicing of georeferenced images
gt-geopkg	GeoPackage	OGC GeoPackage format support
gt-jdbc-postgis	PostGIS	PostgreSQL/PostGIS database access
gt-jdbc-oracle	Oracle	Oracle Spatial database access

Extension Modules

Extension modules provide additional functionality that builds on the core library but is more specialized or optional. These modules often offer higher-level features.

Module	Description	Key Responsibility
gt-brewer	Brewer	ColorBrewer and other styling utilities
gt-css	CSS	CSS-based styling for maps
app-schema	Application Schema	Support for complex feature types

Module Hierarchy and Dependencies

The following diagram illustrates the hierarchical relationships and dependencies between key GeoTools modules:

Maven Project Structure

GeoTools uses Maven for build management and dependency resolution. The module organization is reflected in the project's directory structure and POM files.

The top-level project structure consists of three primary modules:

100%

Module Dependency Management

GeoTools uses Maven's dependency management to control how modules depend on each other and external libraries. The root POM defines common versions for external dependencies, which are then referenced by individual modules.

Dependency Patterns

The module organization follows these dependency patterns:

1. Core Independence: Core modules have minimal dependencies on external libraries
2. Upward Dependencies: Modules can depend on modules at the same level or below in the hierarchy
3. No Circular Dependencies: The dependency graph is directed and acyclic
4. Factory System: Implementations are obtained through factory finder methods rather than direct instantiation

100%

Module Artifact IDs

Each module follows a consistent naming pattern for its Maven artifact ID:

Module Type	Naming Pattern	Example
Core	gt-[name]	gt-api, gt-main
Library	gt-[name]	gt-coverage, gt-cql
Plugin	gt-[name]	gt-shapefile, gt-geotiff
JDBC Plugin	gt-jdbc-[database]	gt-jdbc-postgis
Extension	gt-[name] or [name]	gt-css, app-schema

Including Modules in Your Projects

When using GeoTools in your own projects, you can include specific modules based on your requirements. Each module is individually versioned and published to Maven repositories.

Typical Dependency Patterns

1. Basic GIS Application: Include core modules plus specific plugins

   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-main</artifactId>
     <version>${geotools.version}</version>
   </dependency>
   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-shapefile</artifactId>
     <version>${geotools.version}</version>
   </dependency>

2. Database Application: Include JDBC support and database-specific plugin

   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-jdbc</artifactId>
     <version>${geotools.version}</version>
   </dependency>
   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-jdbc-postgis</artifactId>
     <version>${geotools.version}</version>
   </dependency>

3. Raster Processing: Include coverage support and raster plugins

   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-coverage</artifactId>
     <version>${geotools.version}</version>
   </dependency>
   <dependency>
     <groupId>org.geotools</groupId>
     <artifactId>gt-geotiff</artifactId>
     <version>${geotools.version}</version>
   </dependency>

Build Profiles and Optional Modules

GeoTools uses Maven profiles to control which modules are included in the build. This allows for optional modules to be included or excluded based on build requirements.

Profile	Purpose	Example Usage
all	Build all modules	mvn install -Dall
docs	Include documentation	mvn -P docs install
pending	Include experimental modules	mvn -P pending install
online	Enable online tests	mvn -P online install

Module Testing and Quality Assurance

Each module includes its own test suite to ensure functionality. The testing framework supports various profiles for different testing scenarios:

• Unit tests: Basic functionality testing
• Integration tests: Testing with other modules
• Online tests: Tests requiring network access
• Stress tests: Performance and load testing

Many modules also build test JARs that can be reused by other modules for testing:

<plugin>
  <artifactId>maven-jar-plugin</artifactId>
  <executions>
    <execution>
      <goals>
        <goal>test-jar</goal>
      </goals>
      <phase>package</phase>
    </execution>
  </executions>
</plugin>