A fully functional Maven project demonstrating how to interact with the JOpt.TourOptimizer REST API from Java. Examples cover the full job lifecycle submitting optimizations, tracking progress via Server-Sent Events, retrieving results, and working with the synchronous run mode. The generated client is built on Spring WebFlux, giving you reactive Flux and Mono access to every endpoint.
- Documentation hub: dna-evolutions.com/docs/learn-and-explore/rest/rest_client_touroptimizer
- TourOptimizer server guide: dna-evolutions.com/docs/learn-and-explore/rest/rest-server-touroptimizer
- Sandbox quickstart: dna-evolutions.com/docs/getting-started/quickstart/jopt_sandboxes_quickstart
- Interactive API: dna-evolutions.com/api
- Java SDK examples: github.com/DNA-Evolutions/Java-TourOptimizer-Examples
- JavaDocs: public.javadoc.dna-evolutions.com
Requires JOpt.TourOptimizer 1.3.5 or higher.
- What is JOpt.TourOptimizer
- Example categories
- Getting started
- Browser sandbox (Docker)
- Clone and run locally
- How the REST client is generated
- Troubleshooting
- Further links
JOpt.TourOptimizer is DNA Evolutions' route optimization and scheduling engine, available as a containerised REST service built on Spring WebFlux. It exposes a reactive OpenAPI 3 contract and can be hosted locally via Docker or accessed via a cloud endpoint.
Click to watch the introduction:
The project is subdivided into the following example packages. Each has its own README.
| Package | Description |
|---|---|
touroptimizer |
Core optimization examples submit jobs, poll status, stream progress, retrieve results |
fullstack |
End-to-end examples combining multiple API features |
secretscreation |
Create the secrets.json file required by all examples |
Two ways to start:
- Browser sandbox zero installation, runs in your browser via Docker.
- Clone locally import as a Maven project in your IDE.
In either case you need a secrets.json file and a running TourOptimizer instance. Run SecretsCreatorExampleHelper from the secretscreation package once to generate it.
The sandbox is a browser-based IDE (code-server / Visual Studio Code) with Java, Maven, and the latest examples pre-installed. The generated client classes are built automatically on the first run.
Docker Hub: dnaevolutions/jopt_rest_example_server
docker run -it -d \
--name jopt-rest-examples \
-p 127.0.0.1:8043:8080 \
-v "$PWD/:/home/coder/project" \
dnaevolutions/jopt_rest_example_server:latestThe -v flag mounts your current directory so your changes and secrets.json survive restarts.
Navigate to http://localhost:8043 and log in with:
joptrest
On the first run Maven downloads dependencies and generates all client classes — this takes a few minutes. A tutorial video (~3 minutes) walks through the full sandbox workflow.
System requirements: at least 2 GB RAM and 2 CPU cores.
The examples need a running TourOptimizer instance. The simplest approach is to start TourOptimizer on your host and reach it from inside the sandbox container via host.docker.internal:
docker run -d --rm --name jopt-touroptimizer \
-p 8081:8081 \
-e SPRING_PROFILES_ACTIVE=cors \
dnaevolutions/jopt_touroptimizer:latest
docker run -it -d \
--name jopt-rest-examples \
-p 127.0.0.1:8043:8080 \
-v "$PWD/:/home/coder/project" \
dnaevolutions/jopt_rest_example_server:latestFrom inside the sandbox, point the client at http://host.docker.internal:8081 instead of localhost.
Alternatively, run both containers on a shared Docker network so the sandbox can reach TourOptimizer by container name:
docker network create jopt-network
docker run -d --rm --name jopt-touroptimizer \
--network jopt-network \
-p 8081:8081 \
-e SPRING_PROFILES_ACTIVE=cors \
dnaevolutions/jopt_touroptimizer:latest
docker run -it -d \
--name jopt-rest-examples \
--network jopt-network \
-p 127.0.0.1:8043:8080 \
-v "$PWD/:/home/coder/project" \
dnaevolutions/jopt_rest_example_server:latestWhen using a Docker network, point the client at http://jopt-touroptimizer:8081.
Job mode requires MongoDB. Examples that use the job endpoints (
POST /api/v1/jobs,GET /api/v1/jobs/{jobId}/result, etc.) require a connected MongoDB instance. Without it, job endpoints are inactive and only the synchronous run endpoints (POST /api/v1/runs) are available. See the TourOptimizer server guide for the full Docker Compose setup including MongoDB.
- Java 17 or later
- Maven 3.6 or later
- A running TourOptimizer instance (see Docker REST TourOptimizer)
git clone https://github.com/DNA-Evolutions/Java-REST-Client-Examples.gitImport the project as a Maven project in your IDE. On the first build the OpenAPI generator plugin creates all client classes automatically from the bundled spec files. Then run SecretsCreatorExampleHelper once, and run any example's main method.
The client classes are auto-generated at build time from the OpenAPI 3 spec files in src/main/resources/swagger/ using the openapi-generator-maven-plugin. You never need to edit these files manually.
The key configuration in pom.xml uses the webclient library to produce Spring WebFlux-compatible types:
<configuration>
<generatorName>java</generatorName>
<typeMappings>
<typeMapping>OffsetDateTime=Instant</typeMapping>
</typeMappings>
<importMappings>
<importMapping>java.time.OffsetDateTime=java.time.Instant</importMapping>
</importMappings>
<library>webclient</library>
</configuration>This gives you reactive Mono<T> and Flux<T> return types on every generated API method, compatible with the TourOptimizer's Spring WebFlux backend.
To regenerate from a newer spec, replace the JSON file in src/main/resources/swagger/ and run mvn generate-sources.
NoSecretFileFoundException
There is no secret file present in: .../secrets/secrets.json
You have not created the secrets file yet. Run SecretsCreatorExampleHelper from the secretscreation package once.
Connection refused: localhost/127.0.0.1:8081
finishConnect(..) failed: Connection refused: localhost/127.0.0.1:8081
If you are running the examples inside the sandbox container, localhost refers to the container itself, not your host machine. Use http://host.docker.internal:8081 instead — this is the simplest fix and requires no network configuration. Alternatively, run TourOptimizer on a shared Docker network and use its container name (e.g. http://jopt-touroptimizer:8081). The example TourOptimizerSimpleLocalDockerExample in the touroptimizer/dockerhosted package is pre-configured for the host.docker.internal endpoint.
- REST client and TourOptimizer guide
- TourOptimizer server guide
- Sandbox quickstart
- Getting started
- Special features overview
- Interactive API testing
- JavaDocs
Get an extended free license designed for small businesses and customers evaluating the product:
DNA Evolutions Portal (sign-in required)
For help or questions reach us at www.dna-evolutions.com/contact or info@dna-evolutions.com.
For license terms and plans please visit www.dna-evolutions.com.
A product by DNA Evolutions GmbH ©