public final class TraitSubscription

Object
TraitSubscription

A live watch on a set of traits, returned by SmartHome.subscribe(SubscriptionRequest, HomeChangeListener).

Hold on to it and stop() it. A subscription the caller has dropped keeps its listener reachable and keeps the platform delivering, so a form that subscribes on show and never unsubscribes leaks a listener per visit and eventually delivers the same change a dozen times. Stopping on Form.removeNotify or in the screen’s teardown is the habit to build.

Unlike a health subscription, this does not survive the process: it lives entirely in memory and is gone when the app is. There is no cursor to persist because there is nothing to catch up on – see isPushDelivery().

Methods

`public` `String getId()`	The identifier this subscription is known by, matching `TraitChangeBatch.getSubscriptionId()`.
`public boolean isActive()`	Whether this subscription is still delivering.
`public boolean isPushDelivery()`	Whether the platform pushes changes as they happen, or whether they only arrive when you ask.
`public void stop()`	Stops delivering, detaches the listener and releases the platform registration.
`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

getId

public String getId()

The identifier this subscription is known by, matching TraitChangeBatch.getSubscriptionId().

Returns

the identifier, never null

isActive

public boolean isActive()

Whether this subscription is still delivering.

Returns

true until stop() is called

isPushDelivery

public boolean isPushDelivery()

Whether the platform pushes changes as they happen, or whether they only arrive when you ask.

true only on HomeKit, and only while your app is in the foreground. Everywhere else – Google Home, the local simulated home – changes are gathered and handed over when you call SmartHome.drainChanges(), and a subscription on its own will never fire.

So an app that watches a sensor has to do one of two things: call drainChanges() when it comes to the foreground and on whatever cadence suits it, or check this and tell the user plainly that live updates are not available here. Assuming push and getting none is the mistake this method exists to prevent, and it looks exactly like a sensor that never triggers.

Returns

true when changes arrive without being asked for

stop

public void stop()

Stops delivering, detaches the listener and releases the platform registration.

Idempotent; calling it on a stopped subscription does nothing.

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