mn create-app example.micronaut.micronautguide \
--features=data-jdbc,liquibase,oracle,serialization-jackson,validation \
--build=gradle \
--lang=groovy \
--test=spock
Find Nearby Delivery Drivers with Micronaut Data JDBC and Oracle Geospatial
Learn how to use Micronaut Data JDBC and Oracle spatial queries to find the closest available delivery driver within 5 km of a food delivery order.
Authors: Milenko Supic
Micronaut Version: 5.0.0
1. Getting Started
In this guide, we will create a Micronaut application written in Groovy.
In this guide, you will build the dispatch part of a food delivery application. When a customer places an order, the application stores driver positions in Oracle SDO_GEOMETRY columns and asks Micronaut Data JDBC for available drivers near the order location. The dispatch service then chooses the closest candidate within 5 km.
The sample uses WGS 84 coordinates (SRID 4326), the coordinate system commonly used by GPS. With Oracle geodetic data, SDO_WITHIN_DISTANCE interprets the distance value in meters when no explicit unit parameter is supplied.
2. What you will need
To complete this guide, you will need the following:
-
Some time on your hands
-
A decent text editor or IDE (e.g. IntelliJ IDEA)
-
JDK 21 or greater installed with
JAVA_HOMEconfigured appropriately -
Docker installed to run Oracle Database with Micronaut Test Resources.
3. Solution
We recommend that you follow the instructions in the next sections and create the application step by step. However, you can go right to the completed example.
-
Download and unzip the source
4. Writing the Application
Create an application using the Micronaut Command Line Interface or with Micronaut Launch.
If you don’t specify the --build argument, Gradle with the Kotlin DSL is used as the build tool. If you don’t specify the --lang argument, Java is used as the language.If you don’t specify the --test argument, JUnit is used for Java and Kotlin, and Spock is used for Groovy.
|
The previous command creates a Micronaut application with the default package example.micronaut in a directory named micronautguide.
If you use Micronaut Launch, select Micronaut Application as application type and add data-jdbc, liquibase, oracle, serialization-jackson, and validation features.
| If you have an existing Micronaut application and want to add the functionality described here, you can view the dependency and configuration changes from the specified features, and apply those changes to your application. |
4.1. Oracle Driver
Add also the Oracle Driver
runtimeOnly("com.oracle.database.jdbc:ojdbc11")
Micronaut Data builds repository queries at compilation time. Add the Jakarta Persistence API as a compile-only dependency so the compile-time query model has the Criteria API types available:
compileOnly("jakarta.persistence:jakarta.persistence-api")
4.2. Database Configuration
And the database configuration:
datasources.default.schema-generate=NONE
(1)
datasources.default.driver-class-name=oracle.jdbc.OracleDriver
(2)
datasources.default.db-type=oracle
(3)
datasources.default.dialect=ORACLE
| 1 | Use Oracle driver. |
| 2 | In order for the database to be properly detected by Micronaut Test Resources. |
| 3 | Configure the Oracle dialect. |
test-resources.containers.oracle.image-name=gvenzl/oracle-free
test-resources.containers.oracle.image-tag=latest
4.3. Database Migration with Liquibase
We need a way to create the database schema. For that, we use Micronaut integration with Liquibase.
Add the following snippet to include the necessary dependencies:
implementation("io.micronaut.liquibase:micronaut-liquibase")
Configure the database migrations directory for Liquibase in application.properties.
liquibase.datasources.default.change-log=classpath\:db/liquibase-changelog.xml
Create the following files with the database schema creation:
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.1.xsd">
<include file="changelog/01-schema.xml" relativeToChangelogFile="true"/>
</databaseChangeLog>
<?xml version="1.0" encoding="UTF-8"?>
<databaseChangeLog
xmlns="http://www.liquibase.org/xml/ns/dbchangelog"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://www.liquibase.org/xml/ns/dbchangelog
http://www.liquibase.org/xml/ns/dbchangelog/dbchangelog-3.1.xsd">
<changeSet id="01" author="micronaut-guides">
<createSequence sequenceName="delivery_driver_seq" startValue="1" incrementBy="1"/>
<createTable tableName="delivery_driver">
<column name="id" type="BIGINT" autoIncrement="true">
<constraints primaryKey="true" primaryKeyName="pk_delivery_driver" nullable="false"/>
</column>
<column name="name" type="VARCHAR(255)">
<constraints nullable="false"/>
</column>
<column name="status" type="VARCHAR(32)">
<constraints nullable="false"/>
</column>
<column name="location" type="MDSYS.SDO_GEOMETRY">
<constraints nullable="false"/>
</column>
</createTable>
<sql>
DELETE FROM USER_SDO_GEOM_METADATA
WHERE TABLE_NAME = 'DELIVERY_DRIVER'
AND COLUMN_NAME = 'LOCATION'
</sql>
<sql>
INSERT INTO USER_SDO_GEOM_METADATA (TABLE_NAME, COLUMN_NAME, DIMINFO, SRID)
VALUES (
'DELIVERY_DRIVER',
'LOCATION',
MDSYS.SDO_DIM_ARRAY(
MDSYS.SDO_DIM_ELEMENT('X', -180, 180, 0.005),
MDSYS.SDO_DIM_ELEMENT('Y', -90, 90, 0.005)
),
4326
)
</sql>
<sql>
CREATE INDEX idx_delivery_driver_location
ON delivery_driver(location)
INDEXTYPE IS MDSYS.SPATIAL_INDEX
</sql>
</changeSet>
</databaseChangeLog>
The migration creates the delivery_driver table with an Oracle SDO_GEOMETRY column, registers the column in USER_SDO_GEOM_METADATA, and creates a spatial index. In production, keep those metadata and index statements in your migration tool instead of relying on test-only schema generation.
5. Domain Model
Create a DeliveryDriver entity:
package example.micronaut
import groovy.transform.CompileStatic
import io.micronaut.data.annotation.GeneratedValue
import io.micronaut.data.annotation.Id
import io.micronaut.data.annotation.Index
import io.micronaut.data.annotation.MappedEntity
import io.micronaut.data.annotation.Srid
import io.micronaut.data.model.geo.Point
import jakarta.validation.constraints.NotBlank
import jakarta.validation.constraints.NotNull
@CompileStatic
@MappedEntity('delivery_driver') (1)
class DeliveryDriver {
enum Status {
AVAILABLE,
BUSY
}
@Id
@GeneratedValue
Long id
@NotBlank
String name
@NotNull
Status status (2)
@NotNull
@Srid(4326) (3)
@Index(columns = 'location') (4)
Point location
DeliveryDriver() {
}
DeliveryDriver(String name, Status status, Point location) {
this.name = name
this.status = status
this.location = location
}
}
Micronaut Data geospatial model types use GeoJSON conversion by default. Oracle stores the value in the SDO_GEOMETRY column declared in the Liquibase migration.
| 1 | Map the entity to the delivery_driver table created by Liquibase. |
| 2 | Represent whether a driver is available or busy so dispatch queries can filter drivers before applying the spatial predicate. |
| 3 | Use SRID 4326 for GPS-style longitude and latitude coordinates. |
| 4 | Mark the location column as spatially indexed in the Micronaut Data model. |
6. Repository
Create a repository that declares the Oracle dialect:
package example.micronaut
import io.micronaut.data.jdbc.annotation.JdbcRepository
import io.micronaut.data.model.geo.Point
import io.micronaut.data.model.query.builder.sql.Dialect
import io.micronaut.data.repository.CrudRepository
@JdbcRepository(dialect = Dialect.ORACLE) (1)
interface DeliveryDriverRepository extends CrudRepository<DeliveryDriver, Long> {
List<DeliveryDriver> findByStatusAndLocationNear(DeliveryDriver.Status status, Point orderLocation, double maxDistanceMeters) (2)
}
| 1 | @JdbcRepository tells Micronaut Data to generate an Oracle JDBC repository. |
| 2 | The Near predicate is translated to Oracle SDO_WITHIN_DISTANCE. |
7. Dispatch Service
The repository returns available drivers within 5 km of the order location. The service then selects the nearest driver from those candidates:
package example.micronaut
import groovy.transform.CompileStatic
import io.micronaut.data.model.geo.Point
import jakarta.inject.Singleton
@CompileStatic
@Singleton
class DispatchService {
private static final double MAX_DISTANCE_METERS = 5_000d (1)
private static final double EARTH_RADIUS_METERS = 6_371_008.8d
private final DeliveryDriverRepository deliveryDriverRepository
DispatchService(DeliveryDriverRepository deliveryDriverRepository) {
this.deliveryDriverRepository = deliveryDriverRepository
}
Optional<DriverMatch> findClosestAvailableDriver(Point orderLocation) {
List<DeliveryDriver> candidates = deliveryDriverRepository.findByStatusAndLocationNear(
DeliveryDriver.Status.AVAILABLE,
orderLocation,
MAX_DISTANCE_METERS
) (2)
DriverMatch closest = null
for (DeliveryDriver driver : candidates) {
DriverMatch match = new DriverMatch(
driver.id,
driver.name,
distanceMeters(orderLocation, driver.location)
)
if (closest == null || match.distanceMeters < closest.distanceMeters) {
closest = match
}
}
return Optional.ofNullable(closest) (3)
}
private double distanceMeters(Point left, Point right) { (4)
double leftLatitude = Math.toRadians(left.y())
double rightLatitude = Math.toRadians(right.y())
double deltaLatitude = Math.toRadians(right.y() - left.y())
double deltaLongitude = Math.toRadians(right.x() - left.x())
double sinHalfDeltaLatitude = Math.sin(deltaLatitude * 0.5d)
double sinHalfDeltaLongitude = Math.sin(deltaLongitude * 0.5d)
double a = sinHalfDeltaLatitude * sinHalfDeltaLatitude +
Math.cos(leftLatitude) * Math.cos(rightLatitude) *
sinHalfDeltaLongitude * sinHalfDeltaLongitude
double c = 2d * Math.atan2(Math.sqrt(a), Math.sqrt(1d - a))
EARTH_RADIUS_METERS * c
}
}
| 1 | Query radius is 5,000 meters. Oracle uses meters as the default distance unit for geodetic data. |
| 2 | Ask Micronaut Data for available drivers near the order location. |
| 3 | Select the closest candidate in application code using a geodetic distance calculation. |
| 4 | Calculate the approximate great-circle distance between the order and driver locations with the Haversine formula. Point.x() is longitude and Point.y() is latitude, so the method converts latitude and coordinate deltas from degrees to radians before applying trigonometric functions. The a value is the haversine of the central angle between the points, c is that angle in radians, and multiplying by the average Earth radius converts the angular distance to meters. |
Create a small response object for the match:
package example.micronaut
import groovy.transform.CompileStatic
import io.micronaut.serde.annotation.Serdeable
@CompileStatic
@Serdeable
class DriverMatch {
final Long driverId
final String name
final double distanceMeters
DriverMatch(Long driverId, String name, double distanceMeters) {
this.driverId = driverId
this.name = name
this.distanceMeters = distanceMeters
}
}
8. Controller
Expose the dispatch operation through an HTTP endpoint:
package example.micronaut
import groovy.transform.CompileStatic
import io.micronaut.data.model.geo.Point
import io.micronaut.http.annotation.Controller
import io.micronaut.http.annotation.Get
import io.micronaut.http.annotation.QueryValue
@CompileStatic
@Controller('/orders') (1)
class DeliveryDispatchController {
private final DispatchService dispatchService
DeliveryDispatchController(DispatchService dispatchService) {
this.dispatchService = dispatchService
}
@Get('/nearest-driver') (2)
Optional<DriverMatch> nearestDriver(@QueryValue double longitude, @QueryValue double latitude) { (3)
dispatchService.findClosestAvailableDriver(new Point(longitude, latitude))
}
}
| 1 | Expose order dispatch operations under /orders. |
| 2 | Accept the order location as longitude and latitude query parameters. |
| 3 | Returning an empty Optional makes the framework respond with 404 Not Found when no driver is available within 5 km. |
9. Test
Add a test that verifies the dispatch endpoint:
package example.micronaut
import io.micronaut.data.model.geo.Point
import io.micronaut.http.HttpRequest
import io.micronaut.http.HttpResponse
import io.micronaut.http.HttpStatus
import io.micronaut.http.client.BlockingHttpClient
import io.micronaut.http.client.HttpClient
import io.micronaut.http.client.annotation.Client
import io.micronaut.http.client.exceptions.HttpClientResponseException
import io.micronaut.test.extensions.spock.annotation.MicronautTest
import jakarta.inject.Inject
import spock.lang.Specification
@MicronautTest(transactional = false) (1)
class DeliveryDispatchControllerSpec extends Specification {
@Inject
DeliveryDriverRepository deliveryDriverRepository
@Inject
@Client('/') (2)
HttpClient httpClient
void setup() {
deliveryDriverRepository.deleteAll()
}
void "finds closest available driver within five kilometers"() {
given:
deliveryDriverRepository.save(new DeliveryDriver(
'Nearby Driver',
DeliveryDriver.Status.AVAILABLE,
new Point(-73.9757d, 40.7554d)
))
DeliveryDriver closest = deliveryDriverRepository.save(new DeliveryDriver(
'Closest Driver',
DeliveryDriver.Status.AVAILABLE,
new Point(-73.9827d, 40.7504d)
))
deliveryDriverRepository.save(new DeliveryDriver(
'Busy Driver',
DeliveryDriver.Status.BUSY,
new Point(-73.9850d, 40.7488d)
)) (3)
deliveryDriverRepository.save(new DeliveryDriver(
'Far Driver',
DeliveryDriver.Status.AVAILABLE,
new Point(-73.9000d, 40.8000d)
)) (4)
when:
BlockingHttpClient client = httpClient.toBlocking()
HttpResponse<DriverMatch> response = client.exchange(
HttpRequest.GET('/orders/nearest-driver?longitude=-73.9857&latitude=40.7484'),
DriverMatch
) (5)
then:
response.status() == HttpStatus.OK
response.body().driverId == closest.id (6)
}
void "returns not found when no available driver is close enough"() {
given:
deliveryDriverRepository.save(new DeliveryDriver(
'Busy Driver',
DeliveryDriver.Status.BUSY,
new Point(-73.9850d, 40.7488d)
))
deliveryDriverRepository.save(new DeliveryDriver(
'Far Driver',
DeliveryDriver.Status.AVAILABLE,
new Point(-73.9000d, 40.8000d)
))
when:
BlockingHttpClient client = httpClient.toBlocking()
client.exchange(
HttpRequest.GET('/orders/nearest-driver?longitude=-73.9857&latitude=40.7484'),
DriverMatch
) (7)
then:
HttpClientResponseException thrown = thrown()
thrown.status == HttpStatus.NOT_FOUND
}
}
| 1 | Start the Micronaut application with an embedded server and disable the test transaction. The test inserts data directly with the repository, and the HTTP request reads it through a separate connection. |
| 2 | Inject an HTTP client bound to the embedded server. |
| 3 | A busy driver can be nearby, but should not be returned. |
| 4 | An available driver outside the 5 km radius should not be returned. |
| 5 | Call the dispatch endpoint with the order longitude and latitude. |
| 6 | The response body contains the closest available driver within 5 km. |
| 7 | When no available driver is close enough, the endpoint responds with 404 Not Found. |
10. Testing the Application
To run the tests:
./gradlew test
Then open build/reports/tests/test/index.html in a browser to see the results.
When you run the test, Micronaut Test Resources starts an Oracle Database container and configures the JDBC datasource automatically.
11. Next Steps
Read more about Micronaut Data geospatial support.
12. Help with the Micronaut Framework
The Micronaut Foundation sponsored the creation of this Guide. A variety of consulting and support services are available.
13. License
| All guides are released with an Apache License 2.0 for the code and a Creative Commons Attribution 4.0 license for the writing and media (images). |