Interface Inbox
Inbox
is a service interface providing a container for discovered Thing
s
(e.g. found by a DiscoveryService
) as DiscoveryResult
s.
A DiscoveryResult
entry in this container is not a full configured Thing
and therefore no
Thing
exists for it. A DiscoveryResult
can be marked to be ignored, so that a specific Thing
is not considered to get part of the system.
This container offers a listener registry for InboxListener
s which are notified if a DiscoveryResult
is added, updated or removed.
- Author:
- Michael Grammling - Initial contribution, Laurent Garnier - Added parameter newThingId to method approve
- See Also:
-
Method Summary
Modifier and TypeMethodDescriptionadd
(@Nullable DiscoveryResult result) Adds the specifiedDiscoveryResult
to thisInbox
and sends an ADDED event to any registeredInboxListener
.void
addInboxListener
(@Nullable InboxListener listener) Adds anInboxListener
to the listeners' registry.@Nullable Thing
Creates newThing
and adds it to theThingRegistry
.getAll()
Returns allDiscoveryResult
s in thisInbox
.boolean
Removes theDiscoveryResult
associated with the specifiedThing
ID from thisInbox
and sends a REMOVED event to any registeredInboxListener
.void
removeInboxListener
(@Nullable InboxListener listener) Removes anInboxListener
from the listeners' registry.void
setFlag
(ThingUID thingUID, @Nullable DiscoveryResultFlag flag) Sets the flag for a given thingUID result.
The flag signals e.g.stream()
Returns a stream of allDiscoveryResult
s in thisInbox
.
-
Method Details
-
add
Adds the specifiedDiscoveryResult
to thisInbox
and sends an ADDED event to any registeredInboxListener
.If there is already a
DiscoveryResult
with the sameThing
ID in thisInbox
, the specifiedDiscoveryResult
is synchronized with the existing one, while keeping theDiscoveryResultFlag
and overriding the specific properties. In that case an UPDATED event is sent to any registeredInboxListener
.This method returns silently, if the specified
DiscoveryResult
isnull
.- Parameters:
result
- the discovery result to be added to this inbox (could be null)- Returns:
CompletableFuture
future that completes totrue
if the specified discovery result could be added or updated, otherwise tofalse
-
remove
Removes theDiscoveryResult
associated with the specifiedThing
ID from thisInbox
and sends a REMOVED event to any registeredInboxListener
.This method returns silently, if the specified
Thing
ID isnull
, empty, invalid, or no associatedDiscoveryResult
exists in thisInbox
.- Parameters:
thingUID
- the Thing UID pointing to the discovery result to be removed from this inbox (could be null or invalid)- Returns:
- true if the specified discovery result could be removed, otherwise false
-
getAll
List<DiscoveryResult> getAll()Returns allDiscoveryResult
s in thisInbox
.- Returns:
- all discovery results in this inbox (not null, could be empty)
-
stream
Stream<DiscoveryResult> stream()Returns a stream of allDiscoveryResult
s in thisInbox
.- Returns:
- stream of all discovery results in this inbox
-
setFlag
Sets the flag for a given thingUID result.
The flag signals e.g. if the result isDiscoveryResultFlag.NEW
or has been marked asDiscoveryResultFlag.IGNORED
. In the latter case the result object should be regarded as known by the system so that further processing should be skipped.If the specified flag is
null
,DiscoveryResultFlag.NEW
is set by default.- Parameters:
flag
- the flag of the given thingUID result to be set (could be null)
-
addInboxListener
Adds anInboxListener
to the listeners' registry.When a
DiscoveryResult
is ADDED, UPDATED or REMOVED, the specified listener is notified.This method returns silently if the specified listener is
null
or has already been registered before.- Parameters:
listener
- the listener to be added (could be null)
-
removeInboxListener
Removes anInboxListener
from the listeners' registry.When this method returns, the specified listener is no longer notified about an ADDED, UPDATED or REMOVED
DiscoveryResult
.This method returns silently if the specified listener is
null
or has not been registered before.- Parameters:
listener
- the listener to be removed (could be null)
-
approve
Creates newThing
and adds it to theThingRegistry
.- Parameters:
thingUID
- the UID of the Thinglabel
- the label of the ThingnewThingId
- the thing ID of the Thing to be created; if not null, it will replace the thing ID from parameter thingUID- Returns:
- the approved Thing
-