Class TraitReadRequest

java.lang.Object
com.codename1.home.TraitReadRequest
public final class TraitReadRequest extends Object

Which traits to read, and how fresh they have to be.

TraitReadRequest req = new TraitReadRequest()
        .add(lamp, lamp.getPrimaryService(), Trait.ON_OFF)
        .add(lamp, lamp.getPrimaryService(), Trait.BRIGHTNESS);
SmartHome.getInstance().read(req).onResult((readings, err) -> { ... });
Batch, because the boundary is the cost

Reading four traits off one lamp as four calls is four round trips to the platform and, on Matter, potentially four radio exchanges with a battery-powered device. One request carrying four traits is one of each. Where a request exceeds SmartHome.getMaxReadBatchSize() it is split for you and the readings are recombined, so there is no size a caller has to stay under -- but there is a real reason to fill it.

  • Constructor Details

    • TraitReadRequest

      public TraitReadRequest()

  • Method Details

    • add

      public TraitReadRequest add(Accessory accessory, AccessoryService service, Trait trait)

      Adds one trait on one service.

      Parameters

      • accessory: the accessory to read

      • service: the service on it

      • trait: the trait to read

      Returns

      this request, for chaining

      Throws
      • IllegalArgumentException: when any argument is null

    • add

      public TraitReadRequest add(String accessoryId, String serviceId, Trait trait)

      Adds one trait on one service, by identifier.

      The identifier form exists for code working from persisted ids that has not re-fetched the graph. It skips the AccessoryService.supports(Trait) check the snapshot would have allowed, so an unsupported trait surfaces as a HomeError.TRAIT_NOT_SUPPORTED reading rather than as an argument error.

      Parameters

      • accessoryId: the accessory to read

      • serviceId: the service on it

      • trait: the trait to read

      Returns

      this request, for chaining

      Throws
      • IllegalArgumentException: when any argument is null or empty

    • addAll

      public TraitReadRequest addAll(Accessory accessory, AccessoryService service)

      Adds every trait one service exposes.

      Parameters

      • accessory: the accessory to read

      • service: the service whose traits to read

      Returns

      this request, for chaining

      Throws
      • IllegalArgumentException: when either argument is null

    • setAllowCached

      public TraitReadRequest setAllowCached(boolean allowCached)

      Whether the platform may answer from its own cache.

      true by default, which is almost always right: both platforms keep a current view of accessory state and answering from it is instant and costs a battery-powered accessory nothing. Set false only when you genuinely need to force the radio -- a diagnostic screen, a "refresh" the user explicitly asked for -- and expect it to be slower and to fail more often, because it can no longer paper over an accessory that is briefly unreachable.

      Backends that have no cache to bypass ignore this.

      Parameters
      • allowCached: whether cached values are acceptable
      Returns

      this request, for chaining

    • isAllowCached

      public boolean isAllowCached()

      Whether the platform may answer from its own cache.

      Returns

      true when cached values are acceptable

    • size

      public int size()

      How many traits this request asks for.

      Returns

      the count, zero for an empty request

    • isEmpty

      public boolean isEmpty()

      Whether this request asks for nothing.

      Returns

      true when nothing has been added

    • getAccessoryIds

      public List<String> getAccessoryIds()

      The accessory ids, positionally aligned with getServiceIds() and getTraits().

      Returns

      an immutable list

    • getServiceIds

      public List<String> getServiceIds()

      The service ids, positionally aligned with getAccessoryIds() and getTraits().

      Returns

      an immutable list

    • getTraits

      public List<Trait> getTraits()

      The traits, positionally aligned with getAccessoryIds() and getServiceIds().

      Returns

      an immutable list