public final class TraitReading

Object
TraitReading

One trait’s value at one moment, or the reason there isn’t one.

Three outcomes, not two

A reading can carry a value, carry an error, or carry neither. The third is the one that catches people: an accessory can legitimately have nothing to report. Matter marks a temperature it has not measured with a null sentinel, a light in colour-temperature mode has no meaningful hue, and an illuminance sensor in the dark reports “too dark to measure”. None of those is a failure and none of them is a value.

So hasValue() is asked first, and getValue() answers null when it is false. There is no zero standing in for a missing measurement anywhere in this API – a thermostat reading 0 degrees and a thermostat that has not measured are different facts, and conflating them is how a UI comes to display a freezing living room.

A batch read produces one of these per requested trait, so a partial success is the normal case: three readings with values and one unreachable accessory is a successful read, not a failed one.

Methods

`public static` `TraitReading of(String accessoryId, String serviceId, Trait trait, TraitValue value, long timestampMillis)`	A reading that carries a value.
`public static` `TraitReading absent(String accessoryId, String serviceId, Trait trait)`	A reading with nothing to report and nothing wrong – the accessory has no value for this trait right now.
`public static` `TraitReading failed(String accessoryId, String serviceId, Trait trait, HomeError error, String message)`	A reading that failed.
`public` `String getAccessoryId()`	The accessory this was read from.
`public` `String getServiceId()`	The service on that accessory.
`public` `Trait getTrait()`	The trait read.
`public boolean hasValue()`	Whether there is a value to read.
`public` `TraitValue getValue()`	The value.
`public long getTimestampMillis()`	When this value was current, in milliseconds since the epoch.
`public boolean isFailed()`	Whether this reading failed, as opposed to succeeding with no value.
`public` `HomeError getError()`	Why this reading failed.
`public` `String getErrorMessage()`	The platform’s own text for a failure.
`public` `String toString()`	Returns a string representation of the object.

Inherited methods

From Object

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

Method details

of

public static TraitReading of(String accessoryId, String serviceId, Trait trait, TraitValue value, long timestampMillis)

A reading that carries a value.

Parameters

accessoryId String: the accessory read
serviceId String: the service on it
trait Trait: the trait read
value TraitValue: the value
timestampMillis long: when the value was current, in milliseconds since the epoch; zero when the backend did not say

Returns

the reading

Throws

IllegalArgumentException: when trait or value is null, or when the value’s kind does not match the trait’s

absent

public static TraitReading absent(String accessoryId, String serviceId, Trait trait)

A reading with nothing to report and nothing wrong – the accessory has no value for this trait right now.

Parameters

accessoryId String: the accessory read
serviceId String: the service on it
trait Trait: the trait read

Returns

the reading

Throws

IllegalArgumentException: when trait is null

failed

public static TraitReading failed(String accessoryId, String serviceId, Trait trait, HomeError error, String message)

A reading that failed.

Parameters

accessoryId String: the accessory read
serviceId String: the service on it
trait Trait: the trait read
error HomeError: why it failed; null becomes HomeError.UNKNOWN
message String: the platform’s own text, or null

Returns

the reading

Throws

IllegalArgumentException: when trait is null

getAccessoryId

public String getAccessoryId()

The accessory this was read from.

Returns

the accessory identifier, or null

getServiceId

public String getServiceId()

The service on that accessory.

Returns

the service identifier, or null

getTrait

public Trait getTrait()

The trait read.

Returns

the trait, never null

hasValue

public boolean hasValue()

Whether there is a value to read.

Ask this before getValue(). See the class note for why a missing value is a normal outcome rather than an error.

Returns

true when getValue() is not null

getValue

public TraitValue getValue()

The value.

Returns

the value, or null when the accessory had none or the read failed

getTimestampMillis

public long getTimestampMillis()

When this value was current, in milliseconds since the epoch.

Zero when the backend did not say, which is common – most accessory reads are answered from a cache the platform keeps and do not carry a timestamp. Do not render an age from zero.

Returns

the timestamp, or zero

isFailed

public boolean isFailed()

Whether this reading failed, as opposed to succeeding with no value.

Returns

true when getError() is not null

getError

public HomeError getError()

Why this reading failed.

Returns

the error, or null when the read succeeded

getErrorMessage

public String getErrorMessage()

The platform’s own text for a failure.

Returns

the message, or null

toString

public String toString()

Returns a string representation of the object. In general, the toString method returns a string that “textually represents” this object. The result should be a concise but informative representation that is easy for a person to read. It is recommended that all subclasses override this method. The toString method for class Object returns a string consisting of the name of the class of which the object is an instance, the at-sign character `@’, and the unsigned hexadecimal representation of the hash code of the object. In other words, this method returns a string equal to the value of: getClass().getName() + ‘@’ + Integer.toHexString(hashCode())