public final class TraitReadRequest

Object
TraitReadRequest

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.

Constructors

public TraitReadRequest()

Methods

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

Inherited methods

From Object

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

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 Accessory: the accessory to read
service AccessoryService: the service on it
trait 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 String: the accessory to read
serviceId String: the service on it
trait 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 Accessory: the accessory to read
service AccessoryService: 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 boolean: 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