org.opentcs.components.kernel.PeripheralJobDispatcher Maven / Gradle / Ivy

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

import jakarta.annotation.Nonnull;
import org.opentcs.components.Lifecycle;
import org.opentcs.data.model.Location;
import org.opentcs.data.peripherals.PeripheralJob;

/**
 * This interface declares the methods a peripheral job dispatcher module for the openTCS kernel
 * must implement.
 * 
 * A peripheral job dispatcher manages the distribution of peripheral jobs among the peripheral
 * devices represented by locations in a system. It is basically event-driven, where an event can
 * be a new peripheral job being introduced into the system or a peripheral device becoming
 * available for processing existing jobs.
 * 
 */
public interface PeripheralJobDispatcher
    extends
      Lifecycle {

  /**
   * Notifies the dispatcher that it should start the dispatching process.
   * 
   * This method is supposed to be called only from the kernel executor thread.
   * 
   */
  void dispatch();

  /**
   * Notifies the dispatcher that any job a peripheral device (represented by the given location)
   * might be processing is to be withdrawn.
   * 
   * This method is supposed to be called only from the kernel executor thread.
   * 
   *
   * @param location The location representing a peripheral device whose job is withdrawn.
   * @throws IllegalArgumentException If the given peripheral's current job is already in a final
   * state, or if it is related to a transport order and this transport order is not in a final
   * state.
   */
  void withdrawJob(
      @Nonnull
      Location location
  )
      throws IllegalArgumentException;

  /**
   * Notifies the dispatcher that the given peripheral job is to be withdrawn.
   * 
   * This method is supposed to be called only from the kernel executor thread.
   * 
   *
   * @param job The job to be withdrawn.
   * @throws IllegalArgumentException If the given peripheral job is already in a final state, or if
   * it is related to a transport order and this transport order is not in a final state.
   */
  void withdrawJob(
      @Nonnull
      PeripheralJob job
  )
      throws IllegalArgumentException;
}