Package org.openhab.core.config.discovery.inbox

Interface Inbox

@NonNullByDefault public interface Inbox
The Inbox is a service interface providing a container for discovered Things (e.g. found by a DiscoveryService) as DiscoveryResults.

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

    • add

      CompletableFuture<Boolean> add(@Nullable DiscoveryResult result)
      Adds the specified DiscoveryResult to this Inbox and sends an ADDED event to any registered InboxListener.

      If there is already a DiscoveryResult with the same Thing ID in this Inbox, the specified DiscoveryResult is synchronized with the existing one, while keeping the DiscoveryResultFlag and overriding the specific properties. In that case an UPDATED event is sent to any registered InboxListener.

      This method returns silently, if the specified DiscoveryResult is null.

      Parameters:
      result - the discovery result to be added to this inbox (could be null)
      Returns:
      CompletableFuture future that completes to true if the specified discovery result could be added or updated, otherwise to false

    • remove

      boolean remove(@Nullable ThingUID thingUID)
      Removes the DiscoveryResult associated with the specified Thing ID from this Inbox and sends a REMOVED event to any registered InboxListener.

      This method returns silently, if the specified Thing ID is null, empty, invalid, or no associated DiscoveryResult exists in this Inbox.

      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 all DiscoveryResults in this Inbox.
      Returns:
      all discovery results in this inbox (not null, could be empty)

    • stream

      Stream<DiscoveryResult> stream()
      Returns a stream of all DiscoveryResults in this Inbox.
      Returns:
      stream of all discovery results in this inbox

    • setFlag

      void setFlag(ThingUID thingUID, @Nullable DiscoveryResultFlag flag)
      Sets the flag for a given thingUID result.
      The flag signals e.g. if the result is DiscoveryResultFlag.NEW or has been marked as DiscoveryResultFlag.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

      void addInboxListener(@Nullable InboxListener listener)
      Adds an InboxListener 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

      void removeInboxListener(@Nullable InboxListener listener)
      Removes an InboxListener 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

      @Nullable Thing approve(ThingUID thingUID, @Nullable String label, @Nullable String newThingId)
      Creates new Thing and adds it to the ThingRegistry.
      Parameters:
      thingUID - the UID of the Thing
      label - the label of the Thing
      newThingId - 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