Java Client Library v2.24.0

The official GeoServer Java SDK provides a type-safe, async-ready interface for interacting with GeoServer instances. It supports WMS, WFS, WCS, and REST API operations out of the box, with built-in connection pooling, retry logic, and OAuth2/OpenID Connect support.

Installation

Add the dependency to your project using Maven or Gradle:

<dependency>
    <groupId>org.geoserver</groupId>
    <artifactId>geoserver-client-java</artifactId>
    <version>2.24.0</version>
</dependency>

For Gradle users:

implementation "org.geoserver:geoserver-client-java:2.24.0"

Quick Start

Initialize the client, connect to your instance, and retrieve a feature collection:

import org.geoserver.client.GeoServerClient;
import org.geoserver.client.GeoServerConfig;
import org.geoserver.wfs.FeatureCollection;
import org.geoserver.wfs.FeatureType;

// 1. Configure the connection
GeoServerConfig config = GeoServerConfig.builder()
    .url("https://geoserver.example.com/geoserver")
    .username("admin")
    .password("geoserver")
    .connectTimeout(5000)
    .readTimeout(30000)
    .build();

// 2. Initialize client (thread-safe singleton recommended)
GeoServerClient client = new GeoServerClient(config);

// 3. Query features from a workspace
FeatureType type = client.wfs().featureType("topp:states");
FeatureCollection<Feature> collection = type.query()
    .bbox("-130,20,-60,50")
    .limit(100)
    .execute();

System.out.println("Fetched " + collection.size() + " features.");

💡 Best Practice: The GeoServerClient instance is designed to be thread-safe and long-lived. Reuse it across your application instead of recreating it per request.

Common Operations

WMS Map Generation

Render map images programmatically with custom styling and format support:

MapImage map = client.wms().getMap("topp:states")
    .styles("pophatch")
    .format("image/png")
    .width(800).height(600)
    .crs("EPSG:4326")
    .execute();

map.writeTo(new File("map_output.png"));

WFS Feature Manipulation

Insert, update, or delete features using transactions:

TransactionResult result = client.wfs().transaction()
    .insert("workspace:layer", featureBuilder.fromJson(jsonString))
    .update("workspace:layer", "ID > 100", Map.of("status", "archived"))
    .execute();

if (result.success()) {
    System.out.println("Inserted: " + result.inserted() + ", Updated: " + result.updated());
}

Authentication & Security

The SDK supports multiple authentication strategies out of the box:

Method	Configuration	Use Case
Basic Auth	`.username().password()`	Internal services, legacy systems
OAuth2 Client Credentials	`.oauth2ClientId().oauth2ClientSecret()`	Server-to-server automation
JWT Bearer	`.jwtTokenFactory()`	Microservices, short-lived tokens
Proxy Headers	`.proxyConfig()`	Behind load balancers or VPNs

Example: OAuth2 Integration

GeoServerConfig config = GeoServerConfig.builder()
    .url("https://geoserver.example.com")
    .oauth2TokenUrl("https://auth.example.com/oauth2/token")
    .oauth2ClientId("my-java-client")
    .oauth2ClientSecret("secret_key_here")
    .tokenRefreshInterval(Duration.ofMinutes(45))
    .build();

Next Steps

Explore the following guides to integrate GeoServer deeply into your Java applications:

📚 WFS Advanced Filtering & CQL
📚 Async API & CompletableFuture Usage
📚 Performance Tuning & Connection Pooling
📚 Migrating from JSTS / GeoTools

← Previous: Quick Start Next: WMS Integration →