Skip to content

Latest commit

 

History

History
258 lines (188 loc) · 11.1 KB

development-guide.adoc

File metadata and controls

258 lines (188 loc) · 11.1 KB

Development guide

Project structure

The project is a multi-module Maven project.

modules.dot
Figure 1. Module dependency tree diagram

At the bottom of the module tree there are the back end and front end modules, which contain the application source code.

The standalone module is an assembly module that combines the back end and front end into a single executable JAR file.

The distribution module represents the final assembly step. It takes the standalone application and the documentation and wraps them in an archive that is easy to distribute.

Developing OptaWeb Vehicle Routing

The back end and front end are separate projects that can be built and deployed separately. In fact, they are written in completely different languages and built with different tools. Both projects have tools that provide a modern developer experience with fast turn-around between code changes and the running application.

In the next sections you will learn how to run both back end and front end projects in development mode.

Back end

The back end module contains a server-side application that uses OptaPlanner to optimize vehicle routes. Optimization is a CPU-intensive computation that must avoid any I/O operations in order to perform to its full potential. Because one of the chief objectives is to minimize the travel cost, either time or distance, we need to keep the travel cost information in RAM memory. While solving, OptaPlanner needs to know the travel cost between every pair of locations entered by the user. This information is stored in a structure called the distance matrix.

When a new location is entered, we calculate the travel cost between the new location and every other location that has been entered so far, and store the travel cost in the distance matrix. The travel cost calculation is performed by a routing engine called GraphHopper.

Finally, the back end module implements additional supporting functionality, such as:

  • persistence,

  • WebSocket connection for the front end,

  • data set loading, export, and import.

In the next sections you will learn how to configure and run the back end in development mode. To learn more about the back end code architecture, see appendix-backend-architecture.adoc.

Running the back end using Spring Boot Maven plugin

Prerequisites

  • Java 11 or higher is installed.

  • The data directory is set up.

  • An OSM file is downloaded.

You can manually set up the data directory and download the OSM file or you can use the run script to complete these tasks.

Procedure

To run the back end in development mode, enter the following command:

mvn spring-boot:run

Automatic restart

Automatic restart is provided by Spring Boot DevTools and only works when the back end is running using Spring Boot Maven Plugin. It scans files on the classpath, so you only need to recompile your changes to trigger application restart. No IDE configuration is needed.

If your IDE has a compile-on-save feature (for example Eclipse or NetBeans), you just need to save the files that have changed since the last compilation.

IntelliJ IDEA saves changes automatically and you need to select either menu:Build[Recompile], which recompiles the file in the active tab, or menu:Build[Build Project] which recompiles all changes. See Compile and build applications with IntelliJ IDEA.

Running the back end from IntelliJ IDEA

  1. Run org.optaweb.vehiclerouting.OptaWebVehicleRoutingApplication. This will create a run configuration that you will edit in the next step.

    1. Open the OptaWebVehicleRoutingApplication class in the editor.

    2. Click the green symbol in the editor window gutter and select Run 'OptaWebVehicleRoutingApplication'.

      Note
      		 The run fails because the working directory is set to the root of the project, whereas the back end module directory is expected. You are going to change the working directory in the next step.
      Note
      		 See Run applications to learn more about running applications in IntelliJ IDEA.

  2. Select menu:Run[Edit Configurations…​] and then select menu:Spring Boot[OptaWebVehicleRoutingApplication].

  3. Set Program arguments to --spring.profiles.active=local to activate the Spring profile called local. This will make the application use configuration from application-local.properties.

  4. Change Working directory to the back end module (optaweb-vehicle-routing-backend).

  5. Optionally, set On Update action to Hot swap classes and update trigger file if failed. This will allow you to use the Update action to quickly restart the application.

Configuration

There are many ways that you can set configuration properties. If you are running locally, you will probably want to use one of these:

  • Set configuration properties in the application.properties file, under /src/main/resources/.

  • Use a command line argument when running the packaged application (for example java -jar optaweb-vehicle-routing-backend.jar --app.my-property=value1).

  • Use an environment variable when running the application with spring-boot:run.

    For example: app_my_property=value1 ./mvnw spring-boot:run if the property name is app.my-property (this requires relaxed binding which only works if the property is defined using @ConfigurationProperties).

Note
 It is not possible to set properties by specifying -D when running the application using the Spring Boot Maven plugin (./mvnw spring-boot:run -Dmy-property). Any system properties that should be set by the plugin to the forked Java process in which the application runs need to be specified using systemPropertiesVariables plugin configuration.

You can learn more about configuring a Spring Boot application on the Spring Boot Externalized Configuration page.

Tip
 Use src/main/resources/application-local.properties to store your personal configuration without affecting the Git working tree.

See the complete list of appendix-backend-config.adoc.

See also the complete list of common application properties available in Spring Boot.

Logging

OptaWeb uses the SLF4J API and Logback as the logging framework. The Spring environment enables you to configure most logging aspects including levels, patterns, and log files in the same way as any other Configuration (most often using application.properties or arguments --property=value). See the Spring Boot Logging documentation for more information.

Following are examples of properties you can use to control logging level of some parts of the application:

  • Use logging.level.org.optaweb.vehiclerouting=debug to enable debug level for the back end code.

  • Use logging.level.org.optaplanner.core=warn to reduce OptaPlanner logging.

  • Use logging.level.org.springframework.web.socket=trace to access more details when investigating problems with WebSocket connection.

Front end

The front end project was bootstrapped with Create React App. Create React App provides a number of scripts and dependencies that help with development and with building the application for production.

Setting up the development environment

Procedure

  1. On Fedora, run the following command to install npm:

    sudo dnf install npm

See Downloading and installing Node.js and npm for more information about installing npm.

Install npm dependencies

Unlike Maven, the npm package manager installs dependencies in node_modules under the project directory and does that only when requested by running npm install. Whenever the dependencies listed in package.json change (for example when you pull changes to the master branch) you must run npm install before you run the development server.

Procedure

  1. Change directory to the front end module:

    cd optaweb-vehicle-routing-frontend

  2. Install dependencies:

    npm install

Running the development server

Prerequisites

  • npm is installed.

  • npm dependencies are installed.

Procedure

  1. Run the development server:

    npm start

  2. Open http://localhost:3000/ in a web browser. By default, the npm start command attempts to open this URL in your default browser.

Tip
Prevent npm start from launching your default browser

If you don’t want npm start to open a new browser tab each time you run it, export an environment variable BROWSER=none.

You can use .env.local file to make this preference permanent. To do that, enter the following command:

echo BROWSER=none >> .env.local

The browser refreshes the page whenever you make changes in the front end source code. The development server process running in the terminal picks up the changes as well and prints compilation and lint errors to the console.

Running tests

Procedure

  1. Run npm test.

Changing the back end location

Use an environment variable called REACT_APP_BACKEND_URL to change the backend URL when running npm start or npm run build. For example:

REACT_APP_BACKEND_URL=http://10.0.0.123:8081

Note that environment variables will be "baked" inside the JavaScript bundle during the npm build, so you need to know the back end location before you build and deploy the front end.

Learn more about the React environment variables in Adding Custom Environment Variables.

Building the project

Run ./mvnw install or mvn install.