Containerizing an application helps to use it more conveniently across different platforms and, most importantly, as a microservice. Further, scaling an application becomes more straightforward as various standardized orchestration tools can be utilized. A Microservice can be launched either (locally) or, for example, as a highly-scalable web-micro-service in a Kubernetes cluster.
This repository is part of our JOpt-REST-Suite. It provides examples of how to set up a REST client in Java to access the following DNA Evolution's web services:
- JOpt-TourOptimizer based on JOpt-Core (available as local Container and via Azure)
- JOpt-GeoCoder based on JOpt-Core and Pelias (available via Azure)
- JOpt-RoutePlanner based on JOpt-Core and Valhalla (available via Azure)
You can find an extensive collection of examples for the core library in our Java-TourOptimizer-Examples repository. Please let us know if you need help to port an example and run it by a REST-Service.
The service can be called via an API-Key using our Microsoft Azure-Kubernetes Infrastructure. If you are interested in hosting our JOpt-REST-GeoCoder and JOpt-REST-GeoRouter products in your environment, please get in touch with us.
All our RESTful Services utilise Spring WebFlux and Swagger. Internally the Java version of TourOptimizer is used. Indeed all specifications for the different services are derived from the core library, leading to guaranteed compatibility between all three services.
Forward-/Reverse geocode Addresses or Positions.
Find distances and driving times between points. Either as turn-by-turn result optionally providing driving instructions and route shapes or as matrix request for multiple routings.
Optimize a problem consisting of Nodes, Resources, and optionally externally provided connections. In contrast to our other services, we allow you to host your JOpt-TourOptimizer locally.
The project is subdivided into five major types of examples:
Each of the example-sections has its own README.
The REST-Client class files used by the examples of this repository will be automatically generated from the provided API-docs (OpenAPI 3 Specification) in the resources swagger folder once the project gets built utilizing the openapi-generator-maven-plugin by OpenAPI Tools.
OpenApi Generator allows setting some generation configuration. Indeed, it is vital to adjust the generator to slightly create the correct client files.
As we use the maven-plugin, we define the configuration directly inside the pom.xml. For example, for our TourOptimizer endpoint, we use:
<configuration>
...
<generatorName>java</generatorName>
<typeMappings>
<typeMapping>OffsetDateTime=Instant</typeMapping>
</typeMappings>
<importMappings>
<importMapping>java.time.OffsetDateTime=java.time.Instant</importMapping>
</importMappings>
<library>webclient</library>
...
</configuration>Please see the pom.xml for the entire configuration description. Besides some mappings, we use the WebClient library to enable Flux and Mono compatible access to our swagger endpoints.
You can also generate a client in the programming language of your choice utilizing our API-docs. REST facilitates software integration in your desired language (including famous ones like C#, Java, JS, Scala, Python, and many more ). Don't hesitate to contact us if you need help setting up your client.
You can start using our examples in different ways.
In any case, you need to provide a secrets.json file. Please follow the README.md file inside the Secrets creation package.
- In your IDE as native Java dependency: Install at least Java 8, Maven
- In our sandbox: Working Docker environment
Clone this repository, import it as Maven project in your IDE, create a secrets.json and start any example.
If you want to get started without the hassle of installing Java, Maven and an IDE, we provide a sandbox. The sandbox is based on code-server and can be used inside your browser, and the interface itself is based on Visual Code. The sandbox is available via DockerHub (here). You have to host the sandbox in your Docker environment (Please provide at least 2-4Gb of Ram and 2 Cores). You can pull the sandbox from our DockerHub account (The Dockerfile for creating the sandbox is included in this repository). The latest version of our examples is cloned by default on launching the Docker container, and you can start testing JOpt-REST right away.
You must mount a volume to which the examples of this project are downloaded on the container's startup. After re-launching the container, the latest version of our examples is only cloned if the folder is not already existing, keeping your files safe from being overridden.
Launching a sandbox and mount your current directory ('$PWD') or any other directory you want:
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:latest
After starting the container, you can open http://localhost:8043/ with your browser and login with the password:
joptrest
During the run of your first example file, some dependencies are downloaded, and it will take some time (below 1 minute depending on your internet connection). Further, all client classes are generated on the fly. Be patient, the whole process can take a few minutes. In case you need help, contact us.
Please visit our tutorial video (approx. 3 minutes duration) hosted on YouTube on how to use our sandbox.
- If you see the following error:
Exception in thread "main" com.dna.jopt.rest.client.util.secretsmanager.caughtexception.NoSecretFileFoundException: There is no secret file present in: /home/coder/project/jopt.rest.examples/secrets/secrets.json
at com.dna.jopt.rest.client.util.secretsmanager.SecretsManager.<init>(SecretsManager.java:73)
at com.dna.jopt.rest.client.util.secretsmanager.SecretsManager.<init>(SecretsManager.java:52)
at com.dna.jopt.rest.client.example.touroptimizer.optimize.TourOptimizerExample.main(TourOptimizerExample.java:71)
you did not provide a secrets.json. Run SecretsCreatorExampleHelper in the package com.dna.jopt.rest.client.example.secretscreation once.
- If you see the error:
Error while processing. finishConnect(..) failed: Connection refused: localhost/127.0.0.1:8081
Exception in thread "main" java.lang.NullPointerException: Cannot invoke "com.dna.jopt.rest.client.model.RestOptimization.getExtension()" because "result" is null
at com.dna.jopt.rest.client.example.touroptimizer.optimize.TourOptimizerExample.main(TourOptimizerExample.java:96)
You are trying to connect to a local JOpt server but have not adjusted the endpoint. Remember, the sandbox is a docker container and you need to connect to it via the endpoint http://host.docker.internal:8081 instead of http://localhost:8081TourOptimizerSimpleLocalDockerExample from the package com.dna.jopt.rest.client.example.touroptimizer.dockerhosted
- Further documentation - docs.dna-evolutions.com
- Special features - Overview of special features
- Our official repository - public.repo.dna-evolutions.com
- Our official JavaDocs - public.javadoc.dna-evolutions.com
- Our YouTube channel - DNA Tutorials
- Documentation - DNA's RESTful Spring-TourOptimizer in Docker
- Our DockerHub channel - DNA DockerHub
- Our LinkedIn channel - DNA LinkedIn
If you need any help, please contact us via our company website www.dna-evolutions.com or write an email to [email protected].
Originally, JOpt is a flexible routing optimization-engine written in Java, allowing to solve tour-optimization problems that are highly restricted, for example, regarding time windows, skills, and even mandatory constraints can be applied.
Click, to open our video:
For reading our license agreement and for further information about license plans, please visit www.dna-evolutions.com.
A product by dna-evolutions ©
