Class DevicePolice

java.lang.Object
xbot.common.injection.DevicePolice

@Singleton public class DevicePolice extends Object
Reserves device addresses and enumerates owners by reference identity.

Registration is all-or-nothing, including multi-channel requests. Rejected requests are reported through RobotAssertionManager and leave the registry unchanged. With the competition-safe assertion policy, rejection returns normally without throwing. CAN reservations accept only native CANPort identities or the CANivore wildcard. Rejection does not prevent a hardware constructor from continuing or disable the rejected device.

Reserving addresses

Supply the actual device object as the owner, not its display name or null. Use DeviceAddress.can(CANPort, int) for CAN addresses, preserving the configured bus, and DeviceAddress.channel for other device types. Reserve all channels for one device in a single call, for example an encoder's A/B channels:
DevicePolice.RegistrationResult result = police.registerDevice(encoder, DeviceAddress.channel(DevicePolice.DeviceType.DigitalIO, 3),
        DeviceAddress.channel(DevicePolice.DeviceType.DigitalIO, 4));

The result is either DevicePolice.RegistrationResult.Registered or DevicePolice.RegistrationResult.Rejected. Inspect a returned rejection before treating the reservation as successful; it contains the diagnostic reported through RobotAssertionManager. Controlled tests may select a loud assertion policy that throws instead. Validation does not bypass the selected assertion policy.

An occupied address is rejected even for its current owner. The same owner can reserve additional unused addresses without a second enumeration entry. Owners are distinguished by reference identity, so equal but distinct objects remain separate devices. The single-address registerDevice(Object, DeviceAddress, int, int) overload enforces inclusive hardware-provided channel bounds.

Looking up owners

Use findDevice(DeviceAddress) for one address, getRegisteredChannels() for address ownership, and getRegisteredDevices() for owners in first-successful-registration order. Collection results are immutable snapshots, not live views; device objects themselves are not copied. Owners are reservation owners, not necessarily physical hardware devices.
  • Constructor Details

    • DevicePolice

      @Inject public DevicePolice()
  • Method Details

    • registerDevice

      public DevicePolice.RegistrationResult registerDevice(Object device, DeviceAddress... addresses)
      Reserves all addresses or none. An occupied address is rejected even for its current owner. The same owner may reserve additional unused channels without a second enumeration entry.
    • registerDevice

      public DevicePolice.RegistrationResult registerDevice(Object device, DeviceAddress address, int minChannel, int maxChannel)
      Reserves one address within an inclusive hardware-provided channel range.
    • findDevice

      public Optional<Object> findDevice(DeviceAddress address)
      Finds the owner, or returns empty when the address is unregistered. Null or structurally invalid addresses are reported through RobotAssertionManager and return empty when the selected policy returns normally. Registry state is unchanged.
    • getRegisteredChannels

      public Map<DeviceAddress, Object> getRegisteredChannels()
      Returns an immutable snapshot of address ownership, in registration order. The device objects themselves are not copied.
    • getRegisteredDevices

      public List<Object> getRegisteredDevices()
      Returns an immutable snapshot in first-successful-registration order. Owners are deduplicated by reference identity, not equals/hashCode.