PostGIS Java bindings (Next Generation)

This project contains Java bindings for using PostGIS geometries coming from a PostgreSQL database.
It is originally based on postgis-java and I want to thank its authors for their work.

Project goals and improvements:

• Support for geometries containing arcs like CIRCULARSTRING or CURVEPOLYGON
• Support for PostGIS geography datatype
• Extended support for bounding boxes, i.e. box2d/box3d PostGIS data types (as PGbox2d/PGbox3d)
• Support for wrapped connections (like used in WildFly and c3p0 connection pooling)
• Use generic Java types where possible and simplify/streamline API
• Clean up code to basically only work on WKB/EWKB implementations to reduce code duplication and focus on the actual database format
• Support for binary transfer of geometry data (if enabled in PostgreSQL JDBC driver)
  • use PostgreSQL JDBC driver 42.5.1 or later to enable it automatically
• Support for the latest PostgreSQL and PostGIS versions
  • Recommended are PostgreSQL 15.1 and PostGIS 3.2.2
  • Supported are versions starting from PostgreSQL 9.6 and PostGIS 2.3
• Support for current JDKs
  • JDK 21 (main branch)
  • deprecated branches
    • JDK 17
    • JDK 11
    • JDK 8
• The license is still LGPL
• The authors are listed here

Supported geometry types:

• Point
• LineString
• CircularString
• CompoundCurve
• Polygon
• CurvePolygon
• MultiPoint
• MultiLineString
• MultiCurve
• MultiPolygon
• MultiSurface
• GeometryCollection
• box2d
• box3d

How to use it

There is a Maven artifact in the official Maven repository, so just add this to your Maven POM:

<dependency>
	<groupId>io.github.sebasbaumh</groupId>
	<artifactId>postgis-java-ng</artifactId>
	<version>24.1.0</version>
</dependency>

The version reflects the year of the release, e.g. 24.1.0 is a version released in 2024.

The API differs a bit from postgis-java with the main point being a different namespace (io.github.sebasbaumh.postgis) as publishing a project to Maven Central requires to own that namespace. In addition the class structure is a bit different (see below) to support arc geometries and reduce boilerplate code, but you should be able to adapt to it easily. The implementations of the parser and writer for the geometries have been heavily reworked to speed up processing and reduce complexity.

Hierarchy of geometry classes:

How to run tests utilizing a PostgreSQL server

You will need a PostgreSQL server with installed PostGIS extension for some of the tests.

In this example the server is named MyServer and the database UnitTestDB. The database can be empty except installing the PostGIS extension.

You should set up a database user for the unit tests, which has access rights to this database and only to this one. In this example the user is called unittest and has the password CHANGEME.

To run the unit tests accessing the server, add the following to your VM arguments (eclipse Run Configuration->Arguments->VM arguments):

-DtestJdbcUrl="jdbc:postgresql://MyServer/UnitTestDB" -DtestJdbcUsername="unittest" -DtestJdbcPassword="CHANGEME"

Or add the following Maven build parameters to the launch configuration in eclipse:

Parameter Name	Value
testJdbcUrl	jdbc:postgresql://MyServer/UnitTestDB
testJdbcUsername	unittest
testJdbcPassword	CHANGEME

If it works, you will see this line in the build output:

Tests are running with a database

else

Tests are running without a database

There are also local tests contained in the project, so you are still able to test most parts without specifying a PostgreSQL server. And the test console output will show if tests were run with or without a database.