ORS JAR instance

Creates a new ORS instance object that operates on a JAR instance of OpenRouteservice, i.e. an instance that is started using a .jar file. This R6 class is typically constructed by ors_instance. ORSJar requires JDK >= 17 to be installed on the system. If this requirement cannot be met, consider using ORSDocker or ORSWar.

For technical details on the setup of local ORS instances, refer to the Running JAR documentation. For details on how to use ORSJar objects, refer to the installation vignette:

vignette("ors-installation", package = "rors")

Super classes

rors::ORSInstance -> rors::ORSLocal -> ORSJar

Public fields

paths

List of relevant file paths for the ORS setup. Includes the top directory, config file, and extract file.

proc

processx process that is used to control the external process running the OpenRouteService instance. Refer to process for a reference of methods.

Methods

Public methods

• ORSJar$new()

• ORSJar$purge()

• ORSJar$set_port()

• ORSJar$show_logs()

• ORSJar$up()

• ORSJar$stop()

• ORSJar$is_init()

• ORSJar$is_running()

• ORSJar$clone()

Inherited methods

• rors::ORSInstance$get_status()
• rors::ORSInstance$get_url()
• rors::ORSInstance$is_mounted()
• rors::ORSInstance$is_ready()
• rors::ORSLocal$add_profiles()
• rors::ORSLocal$report()
• rors::ORSLocal$rm_extract()
• rors::ORSLocal$rm_profiles()
• rors::ORSLocal$set_endpoints()
• rors::ORSLocal$set_extract()
• rors::ORSLocal$update()

---

Method new()

Initialize the ORSJar object.

Usage

ORSJar$new(
  dir,
  version = NULL,
  overwrite = FALSE,
  dry = FALSE,
  verbose = TRUE,
  ...
)

Arguments

dir

[character]

Custom OpenRouteService directory. If not specified, the jar file will be downloaded to the current working directory. If a directory called "openrouteservice-{version}" is present, the download will be skipped. Ignored if server is not NULL.

version

[character]

The OpenRouteService version to use. Can either be a version number (e.g. 8.1.1) or "master". Defaults to the most recent supported version.

overwrite

[logical]

Whether to overwrite the current OpenRouteService directory if it exists.

dry

[logical]

Whether to start a instance, i.e. initialize a ORSJar instance without downloading the executable. This allows you to manipulate config and extract files but does not allow you to interact with java.

verbose

[logical]

Level of verbosity. If TRUE, shows informative warnings and messages, spinners, progress bars and system notifications.

...

Not used.

---

Method purge()

Purge ORS instance, i.e. take down container, (optionally) delete image, delete ORS directory, and clean up R6 class.

This method can be useful for testing and writing reproducible examples and can easily be used together with on.exit.

Usage

ORSJar$purge()

---

Method set_port()

Set a HTTP port for the spring server.

Usage

ORSJar$set_port(port = NULL)

Arguments

port

[numeric]/NULL

Port to use. If NULL, assigns a random port using randomPort().

---

Method show_logs()

Show logs of OpenRouteService. Useful for debugging docker setups.

Usage

ORSJar$show_logs(source = c("logfile", "process"))

Arguments

source

[logical]

Where to retrieve logs from. If "process", reads the standard output from the external process running OpenRouteService. If "logfile", reads the log file in the top directory. Generally, the log file provides less information, but stores the logs from previous runs. The process logs are reset with every run. Process logs are also much more error-prone.

---

Method up()

Run ors.jar to start a local OpenRouteService server. Creates an attribute of ORSJar called proc which stores the external process used to run the server. A running server can (and should) be stopped using the $stop() method.

Usage

ORSJar$up(wait = TRUE, init = NULL, max = NULL, ...)

Arguments

wait

[wait]

Whether to wait for the server to start and then give out a visual and audible notification. If FALSE, returns control of the console back to the user. The status of the OpenRouteService server can then be polled using the proc attribute.

init

[numeric/NULL]

Initial memory. This can change if more memory is needed. If not specified, uses max. If both are NULL, estimates memory.

max

[numeric/NULL]

Maximum memory. The container is not allowed to use more memory than this value. If not specified, uses init. If both are NULL, estimates memory.

...

Further options passed to the java command.

---

Method stop()

Stops a running OpenRouteService instance by killing the external process.

Usage

ORSJar$stop()

---

Method is_init()

Checks if ORS is initialized. ORS is initialized if it was built for the first time. An initialized ORS instance has a subdirectory called "graphs" that contains built graphs for at least one routing profile. $is_init() therefore checks for the existence of at least one sub-directory of "graphs".

Usage

ORSJar$is_init()

---

Method is_running()

Checks if the ORS process is running. You can control this state using $up() and $stop(). Check $is_ready() to see if the ORS setup succeeded.

Usage

ORSJar$is_running()

---

Method clone()

The objects of this class are cloneable with this method.

Usage

ORSJar$clone(deep = FALSE)

Arguments

deep

Whether to make a deep clone.

Examples

if (FALSE) { # \dontrun{
# create a new ORS instance of type JAR
# downloads ors.jar to a new directory
ors <- ors_instance(type = "jar")

# set a random port to ensure that the port is not used
ors$set_port()

# download and set an OSM file
ors$set_extract("Rutland")

# run an OpenRouteService server
ors$up()

# the external process that runs the server is stored in the object
ors$proc$is_alive() # should return true

# retrieve runtime logs
ors$show_logs()

# stop the server
ors$stop()
} # }