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