# Class TraitReading

java.lang.Object
com.codename1.home.TraitReading

public final class TraitReading extends Object

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.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `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.
  `static TraitReading`
  `failed(String accessoryId, String serviceId, Trait trait, HomeError error, String message)`
  A reading that failed.
  `String`
  `getAccessoryId()`
  The accessory this was read from.
  `HomeError`
  `getError()`
  Why this reading failed.
  `String`
  `getErrorMessage()`
  The platform's own text for a failure.
  `String`
  `getServiceId()`
  The service on that accessory.
  `long`
  `getTimestampMillis()`
  When this value was current, in milliseconds since the epoch.
  `Trait`
  `getTrait()`
  The trait read.
  `TraitValue`
  `getValue()`
  The value.
  `boolean`
  `hasValue()`
  Whether there is a value to read.
  `boolean`
  `isFailed()`
  Whether this reading failed, as opposed to succeeding with no value.
  `static TraitReading`
  `of(String accessoryId, String serviceId, Trait trait, TraitValue value, long timestampMillis)`
  A reading that carries a value.
  `String`
  `toString()`
  Returns a string representation of the object.

  ### Methods inherited from class Object

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

- ## 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`: the accessory read

    - `serviceId`: the service on it

    - `trait`: the trait read

    - `value`: the value

    - `timestampMillis`: 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`: the accessory read

    - `serviceId`: the service on it

    - `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`: the accessory read

    - `serviceId`: the service on it

    - `trait`: the trait read

    - `error`: why it failed; `null` becomes `HomeError.UNKNOWN`

    - `message`: 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()
    Description copied from class: `Object`
    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())
    Overrides:
      `toString` in class `Object`