MultipleGraphs

[PageOutline]

Introduction

Rather than running several OTP webapps, with a bit of configuration a single OTP instance can now use multiple graphs for routing in several distinct geographic areas. The multi-graph machinery could also support dynamically reloading graph data files when they change, but this is not yet fully implemented.

The routerID

Multi-graph mode uses the routerId query parameter. A router ID can be any string you want (provided that substituting it into a file path will not violate any path naming rules on your OS). The config.js configuration file in the opentripplanner-webapp module contains a default empty value you can modify.

Spring XML Configuration

The key to multi-graph operation is to include the routerId placeholder "{}" somewhere in the GraphService's path property. Every API request to the OTP server can contain a routerId parameter, and the "{}" in the path will be replaced with that routerId to form a directory name, where OTP will look for the corresponding Graph.obj. Modify the GraphService bean in data-sources.xml as shown below:

<!-- specify a GraphService, configuring the path to the serialized Graphs -->
<bean id="graphService" class="org.opentripplanner.routing.impl.GraphServiceImpl">
  <property name="path" value="/var/otp/graphs/{}/" />
  <property name="defaultRouterId" value="arbor" />
</bean>

In the event that no routerId is specified in a request, the defaultRouterId will be used. If no defaultRouterId is specified, the empty string will be substituted. This means that if the above configuration did not specify a defaultRouterId, the default graph would be found at /var/otp/graphs/Graph.obj and the graph for routerId "alpha" would be found in /var/otp/graphs/alpha/Graph.obj.

Dynamically reloading graph data

(Legacy documentation, not yet fully re-implemented)

The multi-graph feature support the dynamic reload of graph data (the Graph.obj serialized file) upon change. At each request the application checks if the file has been modified, and reload it if necessary (blocking or not all requests depending on the asyncReload option, see below).

To update a graph, please make sure you use an atomic copy/move. There is an internal protection against non-atomic copy which may handle some situation (it retries a number of times in case of truncated file), but to be on the safe side, in production and/or automated scripting mode please use an atomic copy:

• On UNIX, use "mv -f";

• Within JAVA, use the Files.move(...) function with the "ATOMIC_MOVE" option set (see http://download.oracle.com/javase/tutorial/essential/io/move.html) - it throws an exception if atomic move is not supported by the underlying file system;

• On Windows NTFS, use a transactional move (TODO: is there a scriptable command existing here?) (see http://msdn.microsoft.com/en-us/magazine/cc163388.aspx)

Note: You may want to use the multi-graph feature even if you have a single router context to use the dynamic reload feature. This is straightforward: either provide an empty/null routerID (the default value) with a pathPattern without any {}, or a fixed routerId.

Asynchronous Graph Reloading

OTP can be configured to reload a graph file when it is modified, without restarting the entire servlet. However, for large graphs the loading process may take a long time and force the user to wait. The asyncReload option will keep the old graph in memory until the new one is ready, in order to serve other requests made while the new one is being loaded. Please note that in the worst case, this may require double the amount of RAM, as two graphs will be present in memory at the same time. This can have a huge impact if you update all graphs for all routerIds at once. In production scripts you can follow the following sequence if you use the asyncReload feature:

• (If needed) Copy the new data to the same filesystem as the old data
• Atomically move the new data over the old
• Immediately poll the planner (wget http://host.tld/webapp/ws/metadata?routerId=new-york) to force a reload and wait until it's done
• Process the next graph/routerId

This will ensure that 1) the blocking request which will reload the data will not be a user request, and 2) you minimize the number of graph objects present at the same time in RAM.

Graph eviction

For now there is no option to evict from memory a previously loaded graph. The only solution is to force a webapp reload. It has been planned to add an admin webservice to do that.