Class AbstractRegistry<E extends Identifiable<K>,​K,​P extends Provider<E>>

  • Type Parameters:
    E - type of the element
    All Implemented Interfaces:
    ProviderChangeListener<E>, Registry<E,​K>
    Direct Known Subclasses:
    AbstractLinkRegistry

    @NonNullByDefault
    public abstract class AbstractRegistry<E extends Identifiable<K>,​K,​P extends Provider<E>>
    extends Object
    implements ProviderChangeListener<E>, Registry<E,​K>
    The AbstractRegistry is an abstract implementation of the Registry interface, that can be used as base class for Registry implementations.
    Author:
    Dennis Nobel - Initial contribution, Stefan Bußweiler - Migration to new event mechanism, Victor Toni - provide elements as Stream, Kai Kreuzer - switched to parameterized logging, Hilbrand Bouwkamp - Made protected fields private and added new methods to give access., Markus Rathgeb - Use separate collections to improve performance
    • Constructor Detail

      • AbstractRegistry

        protected AbstractRegistry​(Class<P> providerClazz)
        Constructor.
        Parameters:
        providerClazz - the class of the providers (see e.g. addProvider(Provider)), null if no providers should be tracked automatically after activation
    • Method Detail

      • activate

        protected void activate​(org.osgi.framework.BundleContext context)
      • deactivate

        protected void deactivate()
      • added

        public void added​(Provider<E> provider,
                          E element)
        Description copied from interface: ProviderChangeListener
        Notifies the listener that a single element has been added.
        Specified by:
        added in interface ProviderChangeListener<E extends Identifiable<K>>
        Parameters:
        provider - the provider that provides the element
        element - the element that has been added
      • getAll

        public Collection<@NonNull E> getAll()
        Description copied from interface: Registry
        Returns a collection of all elements in the registry.
        Specified by:
        getAll in interface Registry<E extends Identifiable<K>,​K>
        Returns:
        collection of all elements in the registry
      • stream

        public Stream<E> stream()
        Description copied from interface: Registry
        Returns a stream of all elements in the registry.
        Specified by:
        stream in interface Registry<E extends Identifiable<K>,​K>
        Returns:
        stream of all elements in the registry
      • removed

        public void removed​(Provider<E> provider,
                            E element)
        Description copied from interface: ProviderChangeListener
        Notifies the listener that a single element has been removed.
        Specified by:
        removed in interface ProviderChangeListener<E extends Identifiable<K>>
        Parameters:
        provider - the provider that provides the element
        element - the element that has been removed
      • updated

        public void updated​(Provider<E> provider,
                            E oldElement,
                            E element)
        Description copied from interface: ProviderChangeListener
        Notifies the listener that a single element has been updated.
        Specified by:
        updated in interface ProviderChangeListener<E extends Identifiable<K>>
        Parameters:
        provider - the provider that provides the element
        element - the element that has been updated
      • get

        public @Nullable E get​(K key)
        Description copied from interface: Registry
        This method retrieves a single element from the registry.
        Specified by:
        get in interface Registry<E extends Identifiable<K>,​K>
        Parameters:
        key - key of the element
        Returns:
        element or null if no element was found
      • getValueAndProvider

        protected @Nullable Map.Entry<Provider<E>,​E> getValueAndProvider​(K key)
        This method retrieves an Entry with the provider and the element for the key from the registry.
        Parameters:
        key - key of the element
        Returns:
        provider and element entry or null if no element was found
      • add

        public E add​(E element)
        Description copied from interface: Registry
        Adds the given element to the according ManagedProvider.
        Specified by:
        add in interface Registry<E extends Identifiable<K>,​K>
        Parameters:
        element - element to be added (must not be null)
        Returns:
        the added element or newly created object of the same type
      • update

        public E update​(E element)
        Description copied from interface: Registry
        Updates the given element at the according ManagedProvider.
        Specified by:
        update in interface Registry<E extends Identifiable<K>,​K>
        Parameters:
        element - element to be updated (must not be null)
        Returns:
        returns the old element or null if no element with the same key exists
      • remove

        public @Nullable E remove​(K key)
        Description copied from interface: Registry
        Removes the given element from the according ManagedProvider.
        Specified by:
        remove in interface Registry<E extends Identifiable<K>,​K>
        Parameters:
        key - key of the element (must not be null)
        Returns:
        element that was removed, or null if no element with the given key exists
      • notifyListeners

        protected void notifyListeners​(E element,
                                       org.eclipse.smarthome.core.common.registry.AbstractRegistry.EventType eventType)
      • notifyListeners

        protected void notifyListeners​(E oldElement,
                                       E element,
                                       org.eclipse.smarthome.core.common.registry.AbstractRegistry.EventType eventType)
      • notifyListenersAboutAddedElement

        protected void notifyListenersAboutAddedElement​(E element)
      • notifyListenersAboutRemovedElement

        protected void notifyListenersAboutRemovedElement​(E element)
      • notifyListenersAboutUpdatedElement

        protected void notifyListenersAboutUpdatedElement​(E oldElement,
                                                          E element)
      • addProvider

        protected void addProvider​(Provider<E> provider)
      • getProvider

        protected @Nullable Provider<E> getProvider​(K key)
        This method retrieves the provider of an element from the registry.
        Parameters:
        key - key of the element
        Returns:
        provider or null if no provider was found
      • getProvider

        public @Nullable Provider<E> getProvider​(E element)
        This method retrieves the provider of an element from the registry.
        Parameters:
        element - the element
        Returns:
        provider or null if no provider was found
      • forEach

        protected void forEach​(Provider<E> provider,
                               Consumer<E> consumer)
        This method traverses over all elements of a provider in the registry and calls the consumer with each element.

        The traversal over the elements is done while holding a lock for the respective internal collections. If you use this method, please ensure not execution time consuming stuff as it will block any other usage of that collections. You should also not call third party code that could e.g. access the registry itself again. This could lead to a dead lock and hard finding bugs. The getAll() and stream() method will operate on a copy and so no lock is hold.

        Parameters:
        provider - provider to traverse elements of
        consumer - function to call with element
      • forEach

        protected void forEach​(Consumer<E> consumer)
        This method traverses over all elements in the registry and calls the consumer with each element.

        The traversal over the elements is done while holding a lock for the respective internal collections. If you use this method, please ensure not execution time consuming stuff as it will block any other usage of that collections. You should also not call third party code that could e.g. access the registry itself again. This could lead to a dead lock and hard finding bugs. The getAll() and stream() method will operate on a copy and so no lock is hold.

        Parameters:
        consumer - function to call with element
      • forEach

        protected void forEach​(BiConsumer<Provider<E>,​E> consumer)
        This method traverses over all elements in the registry and calls the consumer with the provider of the element as the first parameter and the element as the second argument.

        The traversal over the elements is done while holding a lock for the respective internal collections. If you use this method, please ensure not execution time consuming stuff as it will block any other usage of that collections. You should also not call third party code that could e.g. access the registry itself again. This could lead to a dead lock and hard finding bugs. The getAll() and stream() method will operate on a copy and so no lock is hold.

        Parameters:
        consumer - function to call with the provider and element
      • setManagedProvider

        protected void setManagedProvider​(ManagedProvider<E,​K> provider)
      • unsetManagedProvider

        protected void unsetManagedProvider​(ManagedProvider<E,​K> provider)
      • onAddElement

        protected void onAddElement​(E element)
                             throws IllegalArgumentException
        This method is called before an element is added. The implementing class can override this method to perform initialization logic or check the validity of the element.

        To keep custom logic on the inheritance chain, you must call always the super implementation first.

        If the method throws an IllegalArgumentException the element will not be added.

        Parameters:
        element - element to be added
        Throws:
        IllegalArgumentException - if the element is invalid and should not be added
      • onRemoveElement

        protected void onRemoveElement​(E element)
        This method is called before an element is removed. The implementing class can override this method to perform specific logic.

        To keep custom logic on the inheritance chain, you must call always the super implementation first.

        Parameters:
        element - element to be removed
      • beforeUpdateElement

        protected void beforeUpdateElement​(E existingElement)
        This method is called before an element is updated. The implementing class can override this method to perform specific logic.
        Parameters:
        existingElement - the previously existing element (as held in the element cache)
      • onUpdateElement

        protected void onUpdateElement​(E oldElement,
                                       E element)
                                throws IllegalArgumentException
        This method is called before an element is updated. The implementing class can override this method to perform specific logic or check the validity of the updated element.

        To keep custom logic on the inheritance chain, you must call always the super implementation first.

        Parameters:
        oldElement - old element (before update, as given by the provider)
        element - updated element (after update)

        If the method throws an IllegalArgumentException the element will not be updated.

        Throws:
        IllegalArgumentException - if the updated element is invalid and should not be updated
      • removeProvider

        protected void removeProvider​(Provider<E> provider)
      • getEventPublisher

        protected @Nullable EventPublisher getEventPublisher()
      • setEventPublisher

        protected void setEventPublisher​(EventPublisher eventPublisher)
      • unsetEventPublisher

        protected void unsetEventPublisher​(EventPublisher eventPublisher)
      • postEvent

        protected void postEvent​(Event event)
        This method can be used in a subclass in order to post events through the openHAB events bus. A common use case is to notify event subscribers about an element which has been added/removed/updated to the registry.
        Parameters:
        event - the event