Package org.opentcs.components.kernel

# Interface Router

All Superinterfaces:
  `Lifecycle`

    public interface Router
    extends Lifecycle

This interface declares the methods a router module for the openTCS kernel must implement.

A router finds routes from a start point to an end point, rating them according to implementation specific criteria/costs parameters.

- ## Field Summary

  Fields
  Modifier and Type | Field | Description
  --- | --- | ---
  `static java.lang.String` | `PROPKEY_ROUTING_COST_FORWARD` | The key (prefix) of a path property defining the routing cost when its travelled in forward direction.
  `static java.lang.String` | `PROPKEY_ROUTING_COST_REVERSE` | The key (prefix) of a path property defining the routing cost when its travelled in reverse direction.
  `static java.lang.String` | `PROPKEY_ROUTING_GROUP` | The key of a vehicle property defining the group of vehicles that may share the same routing.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `java.util.Set<Vehicle>` | `checkRoutability​(TransportOrder order)` | Checks the general routability of a given transport order.
  `long` | `getCosts​(Vehicle vehicle, Point sourcePoint, Point destinationPoint)` | Returns the costs for travelling a route from one point to another with a given vehicle.
  `long` | `getCostsByPointRef​(Vehicle vehicle, TCSObjectReference<Point> srcPointRef, TCSObjectReference<Point> dstPointRef)` | Returns the costs for travelling a route from one point to another with a given vehicle.
  `java.util.Optional<Route>` | `getRoute​(Vehicle vehicle, Point sourcePoint, Point destinationPoint)` | Returns a route from one point to another, passable for a given vehicle.
  `java.util.Optional<java.util.List<DriveOrder>>` | `getRoute​(Vehicle vehicle, Point sourcePoint, TransportOrder transportOrder)` | Returns a complete route for a given vehicle that starts on a specified point and allows the vehicle to process a given transport order.
  `java.util.Map<Vehicle,​java.util.List<DriveOrder>>` | `getSelectedRoutes()` | Returns an unmodifiable view on the selected routes the router knows about.
  `java.util.Set<Point>` | `getTargetedPoints()` | Returns all points which are currently targeted by any vehicle.
  `void` | `selectRoute​(Vehicle vehicle, java.util.List<DriveOrder> driveOrders)` | Notifies the router of a route being selected for a vehicle.
  `void` | `topologyChanged()` | Notifies the router of changes in the topology.

  ### Methods inherited from interface org.opentcs.components.Lifecycle

  `initialize, isInitialized, terminate`

- ## Field Details

  - ### PROPKEY_ROUTING_GROUP

    static final java.lang.String PROPKEY_ROUTING_GROUP
    The key of a vehicle property defining the group of vehicles that may share the same routing.

    The value is expected to be an integer.

    See Also:
      Constant Field Values

  - ### PROPKEY_ROUTING_COST_FORWARD

    static final java.lang.String PROPKEY_ROUTING_COST_FORWARD
    The key (prefix) of a path property defining the routing cost when its travelled in forward direction.

    The value is expected to be a (long) integer.

    See Also:
      Constant Field Values

  - ### PROPKEY_ROUTING_COST_REVERSE

    static final java.lang.String PROPKEY_ROUTING_COST_REVERSE
    The key (prefix) of a path property defining the routing cost when its travelled in reverse direction.

    The value is expected to be a (long) integer.

    See Also:
      Constant Field Values

- ## Method Details

  - ### topologyChanged

    void topologyChanged()
    Notifies the router of changes in the topology.

  - ### checkRoutability

    @Nonnull java.util.Set<Vehicle> checkRoutability​(@Nonnull TransportOrder order)
    Checks the general routability of a given transport order.
    Parameters:
      `order` - The transport order to check for routability.
    Returns:
      A set of vehicles for which a route for the given transport order would be computable.

  - ### getRoute

    @Nonnull java.util.Optional<java.util.List<DriveOrder>> getRoute​(@Nonnull Vehicle vehicle, @Nonnull Point sourcePoint, @Nonnull TransportOrder transportOrder)
    Returns a complete route for a given vehicle that starts on a specified point and allows the vehicle to process a given transport order. The route is encapsulated into drive orders which correspond to those drive orders that the transport order is composed of. The transport order itself is not modified.
    Parameters:
      `vehicle` - The vehicle for which the calculated route must be passable.
      `sourcePoint` - The position at which the vehicle would start processing the transport order (i.e. the vehicle's current position).
      `transportOrder` - The transport order to be processed by the vehicle.
    Returns:
      A list of drive orders containing the complete calculated route for the given transport order, passable the given vehicle and starting on the given point, or the empty optional, if no such route exists.

  - ### getRoute

    @Nonnull java.util.Optional<Route> getRoute​(@Nonnull Vehicle vehicle, @Nonnull Point sourcePoint, @Nonnull Point destinationPoint)
    Returns a route from one point to another, passable for a given vehicle.
    Parameters:
      `vehicle` - The vehicle for which the route must be passable.
      `sourcePoint` - The starting point of the route to calculate.
      `destinationPoint` - The end point of the route to calculate.
    Returns:
      The calculated route, or the empty optional, if a route between the given points does not exist.

  - ### getCosts

    long getCosts​(@Nonnull Vehicle vehicle, @Nonnull Point sourcePoint, @Nonnull Point destinationPoint)
    Returns the costs for travelling a route from one point to another with a given vehicle.
    Parameters:
      `vehicle` - The vehicle for which the route must be passable.
      `sourcePoint` - The starting point of the route.
      `destinationPoint` - The end point of the route.
    Returns:
      The costs of the route, or `Long.MAX_VALUE`, if no such route exists.

  - ### getCostsByPointRef

    long getCostsByPointRef​(@Nonnull Vehicle vehicle, @Nonnull TCSObjectReference<Point> srcPointRef, @Nonnull TCSObjectReference<Point> dstPointRef)
    Returns the costs for travelling a route from one point to another with a given vehicle.
    Parameters:
      `vehicle` - The vehicle for which the route must be passable.
      `srcPointRef` - The starting point reference of the route.
      `dstPointRef` - The end point reference of the route.
    Returns:
      The costs of the route, or `Long.MAX_VALUE`, if no such route exists.

  - ### selectRoute

    void selectRoute​(@Nonnull Vehicle vehicle, @Nullable java.util.List<DriveOrder> driveOrders)
    Notifies the router of a route being selected for a vehicle.
    Parameters:
      `vehicle` - The vehicle for which a route is being selected.
      `driveOrders` - The drive orders encapsulating the route being selected, or `null`, if no route is being selected for the vehicle (i.e. an existing entry for the given vehicle would be removed).

  - ### getSelectedRoutes

    @Nonnull java.util.Map<Vehicle,​java.util.List<DriveOrder>> getSelectedRoutes()
    Returns an unmodifiable view on the selected routes the router knows about. The returned map contains an entry for each vehicle for which a selected route is known.
    Returns:
      An unmodifiable view on the selected routes the router knows about.

  - ### getTargetedPoints

    @Nonnull java.util.Set<Point> getTargetedPoints()
    Returns all points which are currently targeted by any vehicle.
    Returns:
      A set of all points currently targeted by any vehicle.