Package org.opentcs.drivers.vehicle

# Class BasicVehicleCommAdapter

java.lang.Object
org.opentcs.drivers.vehicle.BasicVehicleCommAdapter

All Implemented Interfaces:
  `java.beans.PropertyChangeListener`, `java.util.EventListener`, `Lifecycle`, `VehicleCommAdapter`

    public abstract class BasicVehicleCommAdapter
    extends java.lang.Object
    implements VehicleCommAdapter, java.beans.PropertyChangeListener

A base class for communication adapters mainly providing command queue processing.

Implementation notes:

- Accessing the command queue/sent queue from outside should always be protected by synchronization on the BasicVehicleCommunicationAdapter instance.

- ## Constructor Summary

  Constructors
  Constructor | Description
  --- | ---
  `BasicVehicleCommAdapter​(VehicleProcessModel vehicleModel, int commandQueueCapacity, int sentQueueCapacity, java.lang.String rechargeOperation, java.util.concurrent.Executor executor)` | Deprecated. Use more specific constructor instead.
  `BasicVehicleCommAdapter​(VehicleProcessModel vehicleModel, int commandQueueCapacity, int sentQueueCapacity, java.lang.String rechargeOperation, java.util.concurrent.ScheduledExecutorService executor)` | Creates a new instance.

- ## Method Summary

  Modifier and Type | Method | Description
  --- | --- | ---
  `boolean` | `canAcceptNextCommand()` | Checks whether this comm adapter can accept the next (i.e.
  `protected boolean` | `canSendNextCommand()` | Checks whether a new command can be sent to the vehicle.
  `void` | `clearCommandQueue()` | Clears this communication adapter's command queue.
  `protected abstract void` | `connectVehicle()` | Initiates a communication channel to the vehicle.
  `protected VehicleProcessModelTO` | `createCustomTransferableProcessModel()` | Creates a transferable process model with the specific attributes of this comm adapter's process model set.
  `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.
  `protected abstract void` | `disconnectVehicle()` | Closes the communication channel to the vehicle.
  `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.
  `java.util.concurrent.Executor` | `getExecutor()` | Returns the executor to run tasks on.
  `java.lang.String` | `getName()` | Returns this communication adapter's name.
  `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`.
  `void` | `initialize()` | (Re-)Initializes this component before it is being used.
  `boolean` | `isEnabled()` | Checks whether this communication adapter is enabled.
  `boolean` | `isInitialized()` | Checks whether this component is initialized.
  `protected abstract boolean` | `isVehicleConnected()` | Checks whether the communication channel to the vehicle is open.
  `void` | `propertyChange​(java.beans.PropertyChangeEvent evt)` | Processes updates of the `VehicleProcessModel`.
  `abstract void` | `sendCommand​(MovementCommand cmd)` | Converts the given command to something the vehicle can understand and sends the resulting data to the vehicle.
  `void` | `terminate()` | Terminates the instance and frees resources.

  ### Methods inherited from class java.lang.Object

  `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

  ### Methods inherited from interface org.opentcs.drivers.vehicle.VehicleCommAdapter

  `canProcess, canProcess, processMessage`

- ## Constructor Details

  - ### BasicVehicleCommAdapter

    @Deprecated @ScheduledApiChange(when="6.0", details="Will be removed") public BasicVehicleCommAdapter​(VehicleProcessModel vehicleModel, int commandQueueCapacity, int sentQueueCapacity, java.lang.String rechargeOperation, java.util.concurrent.Executor executor)
    Deprecated.
    Use more specific constructor instead.
    Creates a new instance.
    Parameters:
      `vehicleModel` - An observable model of the vehicle's and its comm adapter's attributes.
      `commandQueueCapacity` - The number of commands this comm adapter's command queue accepts. Must be at least 1.
      `sentQueueCapacity` - The maximum number of orders to be sent to a vehicle.
      `rechargeOperation` - The string to recognize as a recharge operation.
      `executor` - The executor to run tasks on.

  - ### BasicVehicleCommAdapter

    public BasicVehicleCommAdapter​(VehicleProcessModel vehicleModel, int commandQueueCapacity, int sentQueueCapacity, java.lang.String rechargeOperation, java.util.concurrent.ScheduledExecutorService executor)
    Creates a new instance.
    Parameters:
      `vehicleModel` - An observable model of the vehicle's and its comm adapter's attributes.
      `commandQueueCapacity` - The number of commands this comm adapter's command queue accepts. Must be at least 1.
      `sentQueueCapacity` - The maximum number of orders to be sent to a vehicle.
      `rechargeOperation` - The string to recognize as a recharge operation.
      `executor` - The executor to run tasks on.

- ## Method Details

  - ### initialize

    public void initialize()
    (Re-)Initializes this component before it is being used.

    Overriding methods are expected to call this implementation, too.

    Specified by:
      `initialize` in interface `Lifecycle`

  - ### terminate

    public void terminate()
    Terminates the instance and frees resources.

    Overriding methods are expected to call this implementation, too.

    Specified by:
      `terminate` in interface `Lifecycle`

  - ### isInitialized

    public boolean isInitialized()
    Description copied from interface: `Lifecycle`
    Checks whether this component is initialized.
    Specified by:
      `isInitialized` in interface `Lifecycle`
    Returns:
      `true` if, and only if, this component is initialized.

  - ### enable

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

    Overriding methods are expected to call this implementation, too.

    Specified by:
      `enable` in interface `VehicleCommAdapter`

  - ### disable

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

    Overriding methods are expected to call this implementation, too.

    Specified by:
      `disable` in interface `VehicleCommAdapter`

  - ### isEnabled

    public boolean isEnabled()
    Description copied from interface: `VehicleCommAdapter`
    Checks whether this communication adapter is enabled.
    Specified by:
      `isEnabled` in interface `VehicleCommAdapter`
    Returns:
      `true` if, and only if, this communication adapter is enabled.

  - ### getProcessModel

    public VehicleProcessModel getProcessModel()
    Description copied from interface: `VehicleCommAdapter`
    Returns an observable model of the vehicle's and its comm adapter's attributes.
    Specified by:
      `getProcessModel` in interface `VehicleCommAdapter`
    Returns:
      An observable model of the vehicle's and its comm adapter's attributes.

  - ### createTransferableProcessModel

    public VehicleProcessModelTO createTransferableProcessModel()
    Description copied from interface: `VehicleCommAdapter`
    Returns a transferable/serializable model of the vehicle's and its comm adapter's attributes.
    Specified by:
      `createTransferableProcessModel` in interface `VehicleCommAdapter`
    Returns:
      A transferable/serializable model of the vehicle's and its comm adapter's attributes.

  - ### getCommandQueueCapacity

    public int getCommandQueueCapacity()
    Description copied from interface: `VehicleCommAdapter`
    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.

    Specified by:
      `getCommandQueueCapacity` in interface `VehicleCommAdapter`
    Returns:
      The number of commands this comm adapter accepts.

  - ### getCommandQueue

    public java.util.Queue<MovementCommand> getCommandQueue()
    Description copied from interface: `VehicleCommAdapter`
    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`.

    Specified by:
      `getCommandQueue` in interface `VehicleCommAdapter`
    Returns:
      This adapter's command queue.
    See Also:
      `VehicleCommAdapter.getCommandQueueCapacity()`

  - ### canAcceptNextCommand

    public boolean canAcceptNextCommand()
    Description copied from interface: `VehicleCommAdapter`
    Checks whether this comm adapter can accept the next (i.e. one more) `command`.
    Specified by:
      `canAcceptNextCommand` in interface `VehicleCommAdapter`
    Returns:
      `true`, if this adapter can accept another command, otherwise `false`.

  - ### getSentQueueCapacity

    public int getSentQueueCapacity()
    Description copied from interface: `VehicleCommAdapter`
    Returns the capacity of this adapter's `sent queue`.
    Specified by:
      `getSentQueueCapacity` in interface `VehicleCommAdapter`
    Returns:
      The capacity of this adapter's sent queue.

  - ### getSentQueue

    public java.util.Queue<MovementCommand> getSentQueue()
    Description copied from interface: `VehicleCommAdapter`
    Returns a queue containing the commands that this adapter has sent to the vehicle already but which have not yet been processed by it.
    Specified by:
      `getSentQueue` in interface `VehicleCommAdapter`
    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:
      `VehicleCommAdapter.getSentQueueCapacity()`, `VehicleCommAdapter.getCommandQueueCapacity()`

  - ### getRechargeOperation

    public java.lang.String getRechargeOperation()
    Description copied from interface: `VehicleCommAdapter`
    Returns the string the comm adapter recognizes as a recharge operation.
    Specified by:
      `getRechargeOperation` in interface `VehicleCommAdapter`
    Returns:
      The string the comm adapter recognizes as a recharge operation.

  - ### enqueueCommand

    public boolean enqueueCommand​(MovementCommand newCommand)
    Description copied from interface: `VehicleCommAdapter`
    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.
    Specified by:
      `enqueueCommand` in interface `VehicleCommAdapter`
    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

    public void clearCommandQueue()
    Description copied from interface: `VehicleCommAdapter`
    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.
    Specified by:
      `clearCommandQueue` in interface `VehicleCommAdapter`

  - ### execute

    public void execute​(AdapterCommand command)
    Description copied from interface: `VehicleCommAdapter`
    Executes the given `AdapterCommand`.
    Specified by:
      `execute` in interface `VehicleCommAdapter`
    Parameters:
      `command` - The command to execute.

  - ### propertyChange

    public void propertyChange​(java.beans.PropertyChangeEvent evt)
    Processes updates of the `VehicleProcessModel`.

    Overriding methods should also call this.

    Specified by:
      `propertyChange` in interface `java.beans.PropertyChangeListener`
    Parameters:
      `evt` - The property change event published by the model.

  - ### getName

    public java.lang.String getName()
    Returns this communication adapter's name.
    Returns:
      This communication adapter's name.

  - ### getExecutor

    @ScheduledApiChange(when="6.0", details="Will return ScheduledExectorService instead") public java.util.concurrent.Executor getExecutor()
    Returns the executor to run tasks on.
    Returns:
      The executor to run tasks on.

  - ### sendCommand

    public abstract void sendCommand​(MovementCommand cmd) throws java.lang.IllegalArgumentException
    Converts the given command to something the vehicle can understand and sends the resulting data to the vehicle.

    Note that this method is called from the kernel executor and thus should not block.

    Parameters:
      `cmd` - The command to be sent.
    Throws:
      `java.lang.IllegalArgumentException` - If there was a problem with interpreting the command or communicating it to the vehicle.

  - ### canSendNextCommand

    protected boolean canSendNextCommand()
    Checks whether a new command can be sent to the vehicle. The default implementation of this method returns `true` only if the number of commands sent already is less than the vehicle's capacity and there is at least one command in the queue that is waiting to be sent.
    Returns:
      `true` if, and only if, a new command can be sent to the vehicle.

  - ### connectVehicle

    protected abstract void connectVehicle()
    Initiates a communication channel to the vehicle. This method should not block, i.e. it should not wait for the actual connection to be established, as the vehicle could be temporarily absent or not responding at all. If that's the case, the communication adapter should continue trying to establish a connection until successful or until `disconnectVehicle` is called.

  - ### disconnectVehicle

    protected abstract void disconnectVehicle()
    Closes the communication channel to the vehicle.

  - ### isVehicleConnected

    protected abstract boolean isVehicleConnected()
    Checks whether the communication channel to the vehicle is open.

    Note that the return value of this method does not indicate whether communication with the vehicle is currently alive and/or if the vehicle is considered to be working/responding correctly.

    Returns:
      `true` if, and only if, the communication channel to the vehicle is open.

  - ### createCustomTransferableProcessModel

    protected VehicleProcessModelTO createCustomTransferableProcessModel()
    Creates a transferable process model with the specific attributes of this comm adapter's process model set.

    This method should be overriden by implementing classes.

    Returns:
      A transferable process model.