Calculates distances in a specified graph, using Dijkstra's single-source-shortest-path algorithm. All edge weights in the graph must be nonnegative; if any edge with negative weight is found in the course of calculating distances, an IllegalArgumentException will be thrown. (Note: this exception will only be thrown when such an edge would be used to update a given tentative distance; the algorithm does not check for negative-weight edges "up front".)
Distances and partial results are optionally cached (by this instance) for later reference. Thus, if the 10 closest vertices to a specified source vertex are known, calculating the 20 closest vertices does not require starting Dijkstra's algorithm over from scratch.
Distances are stored as double-precision values. If a vertex is not reachable from the specified source vertex, no distance is stored. This is new behavior with version 1.4; the previous behavior was to store a value of Double.POSITIVE_INFINITY. This change gives the algorithm an approximate complexity of O(kD log k), where k is either the number of requested targets or the number of reachable vertices (whichever is smaller), and D is the average degree of a vertex.
The elements in the maps returned by getDistanceMap are ordered (that is, returned by the iterator) by nondecreasing distance from source.
Users are cautioned that distances calculated should be assumed to be invalidated by changes to the graph, and should invoke reset() when appropriate so that the distances can be recalculated.
@author Joshua O'Madadhain
@author Tom Nelson converted to jung2