# 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 Summary

  Constructors
  Constructor
  Description
  `TraitReadRequest()`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `TraitReadRequest`
  `add(Accessory accessory, AccessoryService service, Trait trait)`
  Adds one trait on one service.
  `TraitReadRequest`
  `add(String accessoryId, String serviceId, Trait trait)`
  Adds one trait on one service, by identifier.
  `TraitReadRequest`
  `addAll(Accessory accessory, AccessoryService service)`
  Adds every trait one service exposes.
  `List<String>`
  `getAccessoryIds()`
  The accessory ids, positionally aligned with `getServiceIds()` and `getTraits()`.
  `List<String>`
  `getServiceIds()`
  The service ids, positionally aligned with `getAccessoryIds()` and `getTraits()`.
  `List<Trait>`
  `getTraits()`
  The traits, positionally aligned with `getAccessoryIds()` and `getServiceIds()`.
  `boolean`
  `isAllowCached()`
  Whether the platform may answer from its own cache.
  `boolean`
  `isEmpty()`
  Whether this request asks for nothing.
  `TraitReadRequest`
  `setAllowCached(boolean allowCached)`
  Whether the platform may answer from its own cache.
  `int`
  `size()`
  How many traits this request asks for.

  ### Methods inherited from class Object

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

- ## 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