Spatial starter by markxnelson · Pull Request #255 · oracle/spring-cloud-oracle

markxnelson · 2026-04-01T13:24:59Z

📌 Description

Adds a new Oracle Spatial starter for the database starters project, including:

oracle-spring-boot-spatial-data-tools with Spring Boot auto-configuration and GeoJSON-first Oracle Spatial helpers
oracle-spring-boot-starter-spatial as the thin dependency starter
oracle-spring-boot-sample-spatial as a REST sample backed by Oracle Spatial and Testcontainers

The new starter provides:

OracleSpatialGeoJsonConverter for SDO_UTIL.FROM_GEOJSON and SDO_UTIL.TO_GEOJSON
OracleSpatialSqlBuilder for SDO_FILTER, SDO_RELATE, SDO_WITHIN_DISTANCE, and SDO_NN
OracleSpatialProperties with oracle.database.spatial.* configuration

This PR also includes:

Oracle Free Testcontainers integration tests for the spatial data-tools module
end-to-end sample test coverage for the spatial sample
review-driven follow-up fixes for query correctness, auto-configuration coverage, configuration metadata/Javadoc, seed SQL consistency, and README/docs improvements

✅ Checklist

Code builds and runs locally
Tests have been added/updated (if applicable)
Documentation has been updated (if applicable)
Follows project coding style and conventions
Signed the Oracle Contributor Agreement (OCA) to contribute to this project

🔗 Related Issue

n/a

📸 Screenshots / Logs (if applicable)

Test commands run successfully:

mvn -pl oracle-spring-boot-spatial-data-tools clean test
mvn -pl oracle-spring-boot-starter-samples/oracle-spring-boot-sample-spatial -am clean test

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

andytael

LGTM

anders-swanson · 2026-04-01T14:36:48Z

...l-data-tools/src/test/java/com/oracle/spring/spatial/OracleSpatialAutoConfigurationTest.java

+        assertThat(properties.getDefaultDistanceUnit()).isEqualTo("M");
+        assertThat(converter.fromGeoJsonSql(":geometry")).isEqualTo("SDO_UTIL.FROM_GEOJSON(:geometry, null, 4326)");
+        assertThat(converter.distanceClause(500)).isEqualTo("distance=500 unit=M");
+        assertThat(sqlBuilder.withinDistancePredicate("geometry", "shape", 500))


we probably should not use string sql builders. can something similar be done with jdbcclient?

these are just helpers to create geospatial sql fragments, that are then actually used in a JdbcClient when we want to run a query (see LandmarkService for example)

.ai/oracle-spatial-starter-plan.md

...e-spatial/src/test/java/com/oracle/database/spring/spatial/SpatialSampleApplicationTest.java

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

anders-swanson · 2026-04-01T15:01:58Z

general q's:

are there any spring APIs we can wire into for this starter? If we can do something with RowMapper, JdbcClient, Converter, for SDO_GEOMETRY?
for raw strings helper utility, I think it should probably be avoided. String SQL fragments disconnected from Spring or JDBC seem problematic.
can we do anything for spatial repositories?

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

anders-swanson · 2026-04-01T18:35:17Z

...patial-data-tools/src/main/java/com/oracle/spring/spatial/OracleSpatialGeoJsonRowMapper.java

+    }
+
+    @Override
+    public String mapRow(ResultSet rs, int rowNum) throws SQLException {


if we're doing rs.getString(), when would I use this over a plain row mapper?

gpt says:

The main value is not that it does something rs.getString() cannot do. The value is that it gives the starter a small, explicit Spring JDBC integration point for the common case of projecting SDO_UTIL.TO_GEOJSON(...) back to a GeoJSON String.

So the reasons to use it over an inline lambda are:

it makes the intent obvious: spatial.geoJsonRowMapper("geometry") reads as “map this projected spatial column as GeoJSON”

it avoids repeating the same one-line mapper everywhere

it gives the starter at least one concrete RowMapper integration hook, which was part of the review feedback

it gives us a stable place to evolve behavior later if Oracle/JDBC handling ever needs to be less trivial than getString()

That said, I think the reviewer’s instinct is fair: today it is a very thin wrapper. So I’d probably add that if the team feels this is too small to justify a public class, I’d be comfortable with either:

keeping geoJsonRowMapper(...) on OracleSpatialJdbcOperations but making the implementation class non-public, or

inlining it and dropping the named class entirely

My own preference would be:

keep the geoJsonRowMapper(...) factory method as the public API

make OracleSpatialGeoJsonRowMapper an internal implementation detail if we want to reduce surface area

So the short answer is: it is about starter-level Spring integration and readability, not extra mapping power today.

wdyt @anders-swanson

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

...spatial-data-tools/src/test/java/com/oracle/spring/spatial/OracleSpatialIntegrationTest.java

anders-swanson · 2026-04-01T18:42:04Z

...patial-data-tools/src/main/java/com/oracle/spring/spatial/OracleSpatialGeoJsonRowMapper.java

+    }
+
+    @Override
+    public String mapRow(ResultSet rs, int rowNum) throws SQLException {


also curious if geojson we can return as OSON? Java string doesn't seem too useful - thoughts? maybe we can offer rowmapper to cast geojson as a java object? would have to learn a bit more about how spatial best works with JDBC to offer a good suggestion here

anders-swanson · 2026-04-01T18:43:34Z

...spatial-data-tools/src/test/java/com/oracle/spring/spatial/OracleSpatialIntegrationTest.java

+    @Test
+    void geoJsonRoundTrip() {
+        SpatialExpression geometry = spatial.toGeoJson("geometry");
+        String geoJson = jdbcClient.sql("select " + geometry.selection("geometry") + " from landmarks where id = :id")


the plan said not to use string SQL fragments but this still looks like SQL concatenation

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

andytael · 2026-04-01T18:58:07Z

...le-spring-boot-starter-samples/oracle-spring-boot-sample-spatial/src/test/resources/init.sql

@@ -0,0 +1,48 @@
+create table if not exists landmarks (
+    id number primary key,


Maybe use generated ID? (id NUMBER GENERATED ALWAYS AS IDENTITY PRIMARY KEY)

markxnelson · 2026-04-01T18:59:50Z

...ng-boot-sample-spatial/src/main/java/com/oracle/database/spring/spatial/LandmarkService.java

+
+    public Landmark getById(Long id) {
+        SpatialExpression geometry = spatial.toGeoJson("geometry");
+        return jdbcClient.sql("select id, name, category, "


@anders-swanson

markxnelson added 5 commits March 31, 2026 15:18

initial spatial starter impl

710739a

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

tests clean

87e5ee2

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

code review, updates, doc updates

087ce41

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

second review

14fed50

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

doc udpate

cb7286b

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

oracle-contributor-agreement bot added the OCA Verified All contributors have signed the Oracle Contributor Agreement. label Apr 1, 2026

markxnelson self-assigned this Apr 1, 2026

markxnelson added 3 commits April 1, 2026 09:31

organize ai files

5b171e1

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

Merge branch 'main' into spatial-starter

adbbcb1

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

copyright header check

108ef3a

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

markxnelson requested review from anders-swanson and andytael April 1, 2026 13:39

andytael previously approved these changes Apr 1, 2026

View reviewed changes

anders-swanson reviewed Apr 1, 2026

View reviewed changes

.ai/oracle-spatial-starter-plan.md Show resolved Hide resolved

anders-swanson reviewed Apr 1, 2026

View reviewed changes

...e-spatial/src/test/java/com/oracle/database/spring/spatial/SpatialSampleApplicationTest.java Outdated Show resolved Hide resolved

anders-swanson reviewed Apr 1, 2026

View reviewed changes

...e-spatial/src/test/java/com/oracle/database/spring/spatial/SpatialSampleApplicationTest.java Outdated Show resolved Hide resolved

review feedback

beb5983

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

markxnelson dismissed andytael’s stale review via beb5983 April 1, 2026 14:51

idiomatic redesign plan

4c36262

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

anders-swanson previously approved these changes Apr 1, 2026

View reviewed changes

redesign impl

192239f

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

markxnelson dismissed anders-swanson’s stale review via 192239f April 1, 2026 18:05

markxnelson added 2 commits April 1, 2026 14:14

doc udpates

284bdc8

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

extra data and cors stuff

17f841a

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

anders-swanson reviewed Apr 1, 2026

View reviewed changes

review cleanup

a5612fa

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

anders-swanson reviewed Apr 1, 2026

View reviewed changes

...spatial-data-tools/src/test/java/com/oracle/spring/spatial/OracleSpatialIntegrationTest.java Outdated Show resolved Hide resolved

anders-swanson reviewed Apr 1, 2026

View reviewed changes

...spatial-data-tools/src/test/java/com/oracle/spring/spatial/OracleSpatialIntegrationTest.java Outdated Show resolved Hide resolved

anders-swanson reviewed Apr 1, 2026

View reviewed changes

markxnelson added 3 commits April 1, 2026 14:44

review feedback

5325556

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

cors woopsie

bea45cf

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

improve sql idempotency for ci

78800a9

Signed-off-by: Mark Nelson <mark.x.nelson@oracle.com>

andytael reviewed Apr 1, 2026

View reviewed changes

markxnelson commented Apr 1, 2026

View reviewed changes

anders-swanson approved these changes Apr 1, 2026

View reviewed changes

markxnelson merged commit ac7f348 into main Apr 1, 2026
4 checks passed

markxnelson deleted the spatial-starter branch April 1, 2026 19:16

		@@ -0,0 +1,48 @@
		create table if not exists landmarks (
		id number primary key,

Conversation

markxnelson commented Apr 1, 2026

📌 Description

✅ Checklist

🔗 Related Issue

📸 Screenshots / Logs (if applicable)

Uh oh!

andytael left a comment

Choose a reason for hiding this comment

Uh oh!

anders-swanson Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

markxnelson Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

anders-swanson commented Apr 1, 2026

Uh oh!

anders-swanson Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

markxnelson Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

anders-swanson Apr 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

anders-swanson Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

andytael Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

markxnelson Apr 1, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

anders-swanson Apr 1, 2026 •

edited

Loading

anders-swanson Apr 1, 2026 •

edited

Loading