Package org.opentcs.drivers.vehicle

# Interface VehicleCommAdapter

All Superinterfaces:
  `Lifecycle`

All Known Subinterfaces:
  `SimVehicleCommAdapter`

All Known Implementing Classes:
  `BasicVehicleCommAdapter`

    public interface VehicleCommAdapter
    extends Lifecycle

This interface declares the methods that a driver communicating with and controlling a physical vehicle must implement.

A communication adapter is basically a driver that converts high-level commands sent by openTCS to a form that the controlled vehicles understand.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `default boolean` | `canAcceptNextCommand()` | Checks whether this comm adapter can accept the next (i.e.
  `default ExplainedBoolean` | `canProcess​(java.util.List<java.lang.String> operations)` | Deprecated. Use `canProcess(org.opentcs.data.order.TransportOrder)` instead.
  `default ExplainedBoolean` | `canProcess​(TransportOrder order)` | Checks if the vehicle would be able to process the given transport order, taking into account its current state.
  `void` | `clearCommandQueue()` | Clears this communication adapter's command queue.
  `VehicleProcessModelTO` | `createTransferableProcessModel()` | Returns a transferable/serializable model of the vehicle's and its comm adapter's attributes.
  `void` | `disable()` | Disables this comm adapter, i.e.
  `void` | `enable()` | Enables this comm adapter, i.e.
  `boolean` | `enqueueCommand​(MovementCommand newCommand)` | Appends a command to this communication adapter's command queue.
  `void` | `execute​(AdapterCommand command)` | Executes the given `AdapterCommand`.
  `java.util.Queue<MovementCommand>` | `getCommandQueue()` | Returns this adapter's command queue.
  `int` | `getCommandQueueCapacity()` | Indicates how many commands this comm adapter accepts.
  `VehicleProcessModel` | `getProcessModel()` | Returns an observable model of the vehicle's and its comm adapter's attributes.
  `java.lang.String` | `getRechargeOperation()` | Returns the string the comm adapter recognizes as a recharge operation.
  `java.util.Queue<MovementCommand>` | `getSentQueue()` | Returns a queue containing the commands that this adapter has sent to the vehicle already but which have not yet been processed by it.
  `int` | `getSentQueueCapacity()` | Returns the capacity of this adapter's `sent queue`.
  `boolean` | `isEnabled()` | Checks whether this communication adapter is enabled.
  `void` | `processMessage​(java.lang.Object message)` | Processes a generic message to the communication adapter.

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

  `initialize, isInitialized, terminate`

- ## Method Details

  - ### enable

    void enable()
    Enables this comm adapter, i.e. turns it on.

  - ### disable

    void disable()
    Disables this comm adapter, i.e. turns it off.

  - ### isEnabled

    boolean isEnabled()
    Checks whether this communication adapter is enabled.
    Returns:
      `true` if, and only if, this communication adapter is enabled.

  - ### getProcessModel

    @Nonnull VehicleProcessModel getProcessModel()
    Returns an observable model of the vehicle's and its comm adapter's attributes.
    Returns:
      An observable model of the vehicle's and its comm adapter's attributes.

  - ### createTransferableProcessModel

    @Nonnull VehicleProcessModelTO createTransferableProcessModel()
    Returns a transferable/serializable model of the vehicle's and its comm adapter's attributes.
    Returns:
      A transferable/serializable model of the vehicle's and its comm adapter's attributes.

  - ### getCommandQueueCapacity

    int getCommandQueueCapacity()
    Indicates how many commands this comm adapter accepts.

    This capacity considers both the `command queue` and the `sent queue`. This means that the number of elements in both queues combined must not exceed this number.

    Returns:
      The number of commands this comm adapter accepts.

  - ### getCommandQueue

    @Nonnull java.util.Queue<MovementCommand> getCommandQueue()
    Returns this adapter's command queue.

    This queue contains `MovementCommand`s that the comm adapter received from the `VehicleController` it's associated with. When a command is sent to the vehicle, the command is removed from this queue and added to the `sent queue`.

    Returns:
      This adapter's command queue.
    See Also:
      `getCommandQueueCapacity()`

  - ### canAcceptNextCommand

    @ScheduledApiChange(when="6.0", details="Default implementation will be removed.") default boolean canAcceptNextCommand()
    Checks whether this comm adapter can accept the next (i.e. one more) `command`.
    Returns:
      `true`, if this adapter can accept another command, otherwise `false`.

  - ### getSentQueueCapacity

    int getSentQueueCapacity()
    Returns the capacity of this adapter's `sent queue`.
    Returns:
      The capacity of this adapter's sent queue.

  - ### getSentQueue

    @Nonnull java.util.Queue<MovementCommand> getSentQueue()
    Returns a queue containing the commands that this adapter has sent to the vehicle already but which have not yet been processed by it.
    Returns:
      A queue containing the commands that this adapter has sent to the vehicle already but which have not yet been processed by it.
    See Also:
      `getSentQueueCapacity()`, `getCommandQueueCapacity()`

  - ### getRechargeOperation

    java.lang.String getRechargeOperation()
    Returns the string the comm adapter recognizes as a recharge operation.
    Returns:
      The string the comm adapter recognizes as a recharge operation.

  - ### enqueueCommand

    boolean enqueueCommand​(@Nonnull MovementCommand newCommand)
    Appends a command to this communication adapter's command queue. The return value of this method indicates whether the command was really added to the queue. The primary reason for a commmand not being added to the queue is that it would exceed its capacity.
    Parameters:
      `newCommand` - The command to be added to this adapter's command queue.
    Returns:
      `true` if, and only if, the new command was added to this adapter's command queue.

  - ### clearCommandQueue

    void clearCommandQueue()
    Clears this communication adapter's command queue. All commands in the queue that have not been sent to this adapter's vehicle, yet, will be removed from the command queue. Any operation the vehicle might currently be executing will still be completed, though.

  - ### canProcess

    @Nonnull @ScheduledApiChange(when="6.0", details="Default implementation will be removed.") default ExplainedBoolean canProcess​(@Nonnull TransportOrder order)
    Checks if the vehicle would be able to process the given transport order, taking into account its current state.
    Parameters:
      `order` - The transport order to be checked.
    Returns:
      An `ExplainedBoolean` indicating whether the vehicle would be able to process the given order.

  - ### canProcess

    @Nonnull @Deprecated @ScheduledApiChange(when="6.0", details="Will be removed.") default ExplainedBoolean canProcess​(@Nonnull java.util.List<java.lang.String> operations)
    Deprecated.
    Use `canProcess(org.opentcs.data.order.TransportOrder)` instead.
    Checks if the vehicle would be able to process the given sequence of operations, taking into account its current state.
    Parameters:
      `operations` - A sequence of operations that might have to be processed as part of a transport order.
    Returns:
      An `ExplainedBoolean` indicating whether the vehicle would be able to process every single operation in the list (in the given order).

  - ### processMessage

    void processMessage​(@Nullable java.lang.Object message)
    Processes a generic message to the communication adapter. This method provides a generic one-way communication channel to the comm adapter. The message can be anything, including `null`, and since `VehicleService.sendCommAdapterMessage(org.opentcs.data.TCSObjectReference, java.lang.Object)` provides a way to send a message from outside the kernel, it can basically originate from any source. The message thus does not necessarily have to be meaningful to the concrete comm adapter implementation at all.

    Implementation notes: Meaningless messages should simply be ignored and not result in exceptions being thrown. If a comm adapter implementation does not support processing messages, it should simply provide an empty implementation. A call to this method should return quickly, i.e. this method should not execute long computations directly but start them in a separate thread.

    Parameters:
      `message` - The message to be processed.

  - ### execute

    void execute​(@Nonnull AdapterCommand command)
    Executes the given `AdapterCommand`.
    Parameters:
      `command` - The command to execute.