org.opentcs.components.kernel.services.DispatcherService Maven / Gradle / Ivy

Go to download
// SPDX-FileCopyrightText: The openTCS Authors
// SPDX-License-Identifier: MIT
package org.opentcs.components.kernel.services;

import jakarta.annotation.Nonnull;
import org.opentcs.access.KernelRuntimeException;
import org.opentcs.components.kernel.Dispatcher;
import org.opentcs.components.kernel.dipatching.TransportOrderAssignmentException;
import org.opentcs.data.ObjectUnknownException;
import org.opentcs.data.TCSObjectReference;
import org.opentcs.data.model.Vehicle;
import org.opentcs.data.order.ReroutingType;
import org.opentcs.data.order.TransportOrder;
import org.opentcs.data.order.TransportOrder.State;

/**
 * Provides methods concerning the {@link Dispatcher}.
 */
public interface DispatcherService {

  /**
   * Explicitly trigger the dispatching process.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @throws KernelRuntimeException In case there is an exception executing this method.
   */
  void dispatch()
      throws KernelRuntimeException;

  /**
   * Withdraw any order that a vehicle might be processing.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @param ref A reference to the vehicle to be modified.
   * @param immediateAbort If {@code false}, this method once will initiate the withdrawal, leaving
   * the transport order assigned to the vehicle until it has finished the movements that it has
   * already been ordered to execute. The transport order's state will change to
   * {@link State#WITHDRAWN}. If {@code true}, the dispatcher will withdraw the order from the
   * vehicle without further waiting.
   * @throws ObjectUnknownException If the referenced vehicle does not exist.
   * @throws KernelRuntimeException In case there is an exception executing this method.
   */
  void withdrawByVehicle(TCSObjectReference ref, boolean immediateAbort)
      throws ObjectUnknownException,
        KernelRuntimeException;

  /**
   * Withdraw the referenced order.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @param ref A reference to the transport order to be withdrawn.
   * @param immediateAbort If {@code false}, this method once will initiate the withdrawal, leaving
   * the transport order assigned to the vehicle until it has finished the movements that it has
   * already been ordered to execute. The transport order's state will change to
   * {@link State#WITHDRAWN}. If {@code true}, the dispatcher will withdraw the order from the
   * vehicle without further waiting.
   * @throws ObjectUnknownException If the referenced transport order does not exist.
   * @throws KernelRuntimeException In case there is an exception executing this method.
   */
  void withdrawByTransportOrder(TCSObjectReference ref, boolean immediateAbort)
      throws ObjectUnknownException,
        KernelRuntimeException;

  /**
   * Explicitly trigger a rerouting for the given vehicles.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @param ref The vehicle to be rerouted.
   * @param reroutingType The type of the requested rerouting.
   */
  void reroute(
      @Nonnull
      TCSObjectReference ref,
      @Nonnull
      ReroutingType reroutingType
  )
      throws ObjectUnknownException,
        KernelRuntimeException;

  /**
   * Explicitly trigger a rerouting for all vehicles.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @param reroutingType The type of rerouting.
   */
  void rerouteAll(
      @Nonnull
      ReroutingType reroutingType
  );

  /**
   * Assign the referenced transport order (to its intended vehicle) now.
   * 
   * If called within the kernel application, this method is supposed to be called only on the
   * kernel executor thread.
   * 
   *
   * @param ref The transport order to be assigned.
   * @throws ObjectUnknownException If the referenced transport order does not exist.
   * @throws TransportOrderAssignmentException If the given transport order could not be assigned
   * to its intended vehicle.
   * @throws KernelRuntimeException In case there is an exception executing this method.
   */
  void assignNow(TCSObjectReference ref)
      throws ObjectUnknownException,
        TransportOrderAssignmentException,
        KernelRuntimeException;
}