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:

  • 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. Must be at least 1.
      rechargeOperation - The string to recognize as a recharge operation.
      executor - The executor to run tasks on.

    • 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.ScheduledExecutorService executor)
      Deprecated.
      Use constructor with commandsCapacity parameter 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. Must be at least 1.
      rechargeOperation - The string to recognize as a recharge operation.
      executor - The executor to run tasks on.

    • BasicVehicleCommAdapter

      public BasicVehicleCommAdapter​(VehicleProcessModel vehicleModel, int commandsCapacity, 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.
      commandsCapacity - The number of commands this comm adapter accepts. Must be at least 1.
      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.

    • getUnsentCommands

      public java.util.Queue<MovementCommand> getUnsentCommands()
      Description copied from interface: VehicleCommAdapter
      Returns this adapter's queue of unsent commands.

      Unsent MovementCommands are commands 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 queue of sent commands.

      Specified by:
      getUnsentCommands in interface VehicleCommAdapter
      Returns:
      This adapter's queue of unsent commands.
      See Also:
      VehicleCommAdapter.getCommandsCapacity()

    • getSentCommands

      public java.util.Queue<MovementCommand> getSentCommands()
      Description copied from interface: VehicleCommAdapter
      Returns this adapter's queue of sent commands.

      Sent MovementCommands are commands that the comm adapter has sent to the vehicle already but which have not yet been processed by it.

      Specified by:
      getSentCommands in interface VehicleCommAdapter
      Returns:
      This adapter's queue of sent commands.
      See Also:
      VehicleCommAdapter.getCommandQueueCapacity()

    • getCommandsCapacity

      public int getCommandsCapacity()
      Description copied from interface: VehicleCommAdapter
      Indicates how many commands this comm adapter accepts.

      This capacity considers both the queue of unsent commands and the queue of sent commands. This means that:

      • The number of elements in both queues combined must not exceed this number.
      • The vehicle will have at most this number of (not yet completed) commands at any given point of time.

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

    • getCommandQueueCapacity

      @Deprecated public int getCommandQueueCapacity()
      Deprecated.
      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

      @Deprecated public java.util.Queue<MovementCommand> getCommandQueue()
      Deprecated.
      Description copied from interface: VehicleCommAdapter
      Returns this adapter's command queue.

      This queue contains MovementCommands 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

      @Deprecated public int getSentQueueCapacity()
      Deprecated.
      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

      @Deprecated public java.util.Queue<MovementCommand> getSentQueue()
      Deprecated.
      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 queue of unsent commands.

      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 the adapter's commands capacity.

      Specified by:
      enqueueCommand in interface VehicleCommAdapter
      Parameters:
      newCommand - The command to be added to this adapter's queue of unsent commands.
      Returns:
      true if, and only if, the new command was added to the queue.

    • clearCommandQueue

      public void clearCommandQueue()
      Description copied from interface: VehicleCommAdapter
      Clears this communication adapter's command queues (i.e. the queues of unsent and sent commands).

      All commands in the queue that have not been sent to this adapter's vehicle, yet, will be removed. Whether commands the vehicle has already received are still executed is up to the implementation and/or the vehicle.

      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.

      This method returns true only if there is at least one command in the queue of unsent commands 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.