Package trclib.robotcore

Class TrcOwnershipMgr

java.lang.Object
trclib.robotcore.TrcOwnershipMgr
public class TrcOwnershipMgr extends Object
This class implements the Exclusive Ownership Manager. The Exclusive Ownership Manager is a singleton. Only one instance will be created. To get the instance of Ownership manager, one must call the static method getInstance(). It provides methods for owners to acquire exclusive ownership of a subsystem so nobody else can access it while the owner is controlling the subsystem. This avoid other components from interfering with an operation in progress. Once the operation is completed, the owner should call the release method to release ownership.

  • Field Details

  • Constructor Details

    • TrcOwnershipMgr

      private TrcOwnershipMgr()
      Constructor: Create an instance of the object and initialize it.

  • Method Details

    • getInstance

      public static TrcOwnershipMgr getInstance()
      This method is called to get the instance of the Ownership manager.
      Returns:
      instance of the ownership manager.

    • getOwner

      public String getOwner(TrcExclusiveSubsystem subsystem)
      This method returns the current owner of the subsystem.
      Returns:
      owner ID string, null if the subsystem has no owner.

    • hasOwnership

      public boolean hasOwnership(String owner, TrcExclusiveSubsystem subsystem)
      This method checks if the caller has exclusive ownership of the subsystem. For backward compatibility with older code that's not aware of subsystem exclusive ownership, the owner parameter can be null. If the subsystem has no owner currently and the caller is not aware of exclusive ownership, the caller is considered to have acquired ownership. This means the caller is allowed to proceed with controlling the subsystem but if a new caller comes in and acquires the ownership of the subsystem while an operation is in progress, the operation will be interrupted and preempted by the new caller's operation. Therefore, callers unaware of exclusive ownership can start an operation on the subsystem but their operations are not guaranteed exclusive ownership.
      Parameters:
      owner - specifies the ID string of the caller, can be null if caller is unaware of exclusive ownership.
      Returns:
      true if caller has exclusive ownership of the subsystem, false otherwise.

    • validateOwnership

      public boolean validateOwnership(String owner, TrcExclusiveSubsystem subsystem)
      This method checks if the caller has exclusive ownership of the subsystem. If not, it throws an exception. It throws an exception only if the caller is aware of exclusive ownership and the it doesn't currently own the subsystem. If the caller is unaware of exclusive ownership and the subsystem is owned by somebody else, it will just return false and not throw an exception. This is to ensure older code that's unaware of exclusive ownership will not hit an unexpected exception and will just fail quietly.
      Parameters:
      owner - specifies the ID string of the caller, can be null if caller is unaware of exclusive ownership.
      subsystem - specifies the subsystem to be checked of its ownership.`
      Returns:
      true if the caller currently owns the subsystem, false otherwise.
      Throws:
      IllegalStateException - if caller is not the owner of the subsystem.

    • acquireOwnership

      public boolean acquireOwnership(String owner, TrcExclusiveSubsystem subsystem)
      This method acquires exclusive ownership of the subsystem if it's not already owned by somebody else.
      Parameters:
      owner - specifies the ID string of the caller requesting ownership.
      subsystem - specifies the subsystem to acquire its ownership.
      Returns:
      true if successfully acquired ownership, false otherwise.

    • releaseOwnership

      public boolean releaseOwnership(String owner, TrcExclusiveSubsystem subsystem)
      This method releases exclusive ownership of the subsystem if the caller is indeed the owner.
      Parameters:
      owner - specifies the ID string of the caller releasing ownership.
      subsystem - specifies the subsystem to release its ownership.
      Returns:
      true if successfully releasing ownership, false otherwise.

    • cancelOwnership

      public boolean cancelOwnership(TrcExclusiveSubsystem subsystem)
      This method releases exclusive ownership of the subsystem regardless who owns it.
      Parameters:
      subsystem - specifies the subsystem to release its ownership.
      Returns:
      true if successfully releasing ownership, false if no owner.