public final class SubscriptionRequest

Object
SubscriptionRequest

Which traits to watch, and how often you are willing to hear about them.

SubscriptionRequest req = new SubscriptionRequest()
        .add(lamp, lamp.getPrimaryService(), Trait.ON_OFF)
        .add(lamp, lamp.getPrimaryService(), Trait.BRIGHTNESS)
        .setDeliverInitialValues(true);
TraitSubscription sub = SmartHome.getInstance().subscribe(req, listener);

Fields

public static final int DEFAULT_MIN_INTERVAL_MILLIS = 200 The default coalescing window, in milliseconds.

Constructors

public SubscriptionRequest()

Methods

`public` `SubscriptionRequest add(Accessory accessory, AccessoryService service, Trait trait)`	Watches one trait on one service.
`public` `SubscriptionRequest add(String accessoryId, String serviceId, Trait trait)`	Watches one trait on one service, by identifier.
`public` `SubscriptionRequest setMinIntervalMillis(int minIntervalMillis)`	How long to gather changes before delivering them, in milliseconds.
`public int getMinIntervalMillis()`	The coalescing window in milliseconds.
`public` `SubscriptionRequest setDeliverInitialValues(boolean deliverInitialValues)`	Whether to deliver each watched trait’s current value once, up front, as though it had just changed.
`public boolean isDeliverInitialValues()`	Whether current values are delivered up front.
`public int size()`	How many traits this subscription watches.
`public boolean isEmpty()`	Whether this request watches 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

Field details

DEFAULT_MIN_INTERVAL_MILLIS

public static final int DEFAULT_MIN_INTERVAL_MILLIS = 200

The default coalescing window, in milliseconds.

A fifth of a second: fast enough that a light responding to a switch looks instant, slow enough that dragging a dimmer does not put a hundred deliveries through the EDT.

Constructor details

SubscriptionRequest

public SubscriptionRequest()

Method details

add

public SubscriptionRequest add(Accessory accessory, AccessoryService service, Trait trait)

Watches one trait on one service.

Parameters

accessory Accessory: the accessory to watch
service AccessoryService: the service on it
trait Trait: the trait to watch

Returns

this request, for chaining

Throws

IllegalArgumentException: when any argument is null

add

public SubscriptionRequest add(String accessoryId, String serviceId, Trait trait)

Watches one trait on one service, by identifier.

Parameters

accessoryId String: the accessory to watch
serviceId String: the service on it
trait Trait: the trait to watch

Returns

this request, for chaining

Throws

IllegalArgumentException: when any argument is null or empty

setMinIntervalMillis

public SubscriptionRequest setMinIntervalMillis(int minIntervalMillis)

How long to gather changes before delivering them, in milliseconds.

Within the window, changes are coalesced per accessory, service and trait, keeping only the newest value; the batch then crosses to the EDT once. Dragging a dimmer emits a notification per step, and a home with a hundred watched accessories can produce a steady stream, so the window is what keeps the event loop usable.

Zero delivers every change as it arrives. That is occasionally right – a diagnostic view, a trace – and is a decision to make deliberately rather than a default to inherit.

Parameters

minIntervalMillis int: the window; zero to deliver everything

Returns

this request, for chaining

Throws

IllegalArgumentException: when the value is negative

getMinIntervalMillis

public int getMinIntervalMillis()

The coalescing window in milliseconds.

Returns

the window, DEFAULT_MIN_INTERVAL_MILLIS unless set

setDeliverInitialValues

public SubscriptionRequest setDeliverInitialValues(boolean deliverInitialValues)

Whether to deliver each watched trait’s current value once, up front, as though it had just changed.

false by default. Turn it on when the subscription is what populates a screen, so the same listener that keeps the screen live also fills it, and there is no separate read whose result can race the first change. The batch is marked with TraitChangeBatch.isInitialDelivery().

Parameters

deliverInitialValues boolean: whether to send current values first

Returns

this request, for chaining

isDeliverInitialValues

public boolean isDeliverInitialValues()

Whether current values are delivered up front.

Returns

true when they are

size

public int size()

How many traits this subscription watches.

Returns

the count, zero for an empty request

isEmpty

public boolean isEmpty()

Whether this request watches 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