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
    See Also:
    InboxListener
    • Method Detail

      • add

        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:
        true if the specified discovery result could be added or updated, otherwise 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
      • 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)
        Creates new Thing and adds it to the ThingRegistry.
        Parameters:
        thingUID - the UID of the Thing
        label - the label of the Thing
        Returns:
        the approved Thing