org.fourthline.cling.registry

## Class RegistryImpl

- java.lang.Object
- - org.fourthline.cling.registry.RegistryImpl

- All Implemented Interfaces:
    Registry

      @ApplicationScoped
      public class RegistryImpl
      extends Object
      implements Registry

  Default implementation of `Registry`.
  Author:
    Christian Bauer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected org.fourthline.cling.registry.LocalItems` | `localItems`
    `protected List<Runnable>` | `pendingExecutions`
    `protected Set<RemoteGENASubscription>` | `pendingSubscriptionsLock`
    `protected Set<RegistryListener>` | `registryListeners`
    `protected RegistryMaintainer` | `registryMaintainer`
    `protected org.fourthline.cling.registry.RemoteItems` | `remoteItems`
    `protected Set<org.fourthline.cling.registry.RegistryItem<URI,Resource>>` | `resourceItems`
    `protected UpnpService` | `upnpService`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `RegistryImpl()`
    `RegistryImpl(UpnpService upnpService)` Starts background maintenance immediately.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addDevice(LocalDevice localDevice)` Call this method to add your local device metadata.
    `void` | `addDevice(LocalDevice localDevice, DiscoveryOptions options)` Call this method to add your local device metadata.
    `void` | `addDevice(RemoteDevice remoteDevice)` Called internally by the UPnP discovery protocol.
    `void` | `addListener(RegistryListener listener)`
    `void` | `addLocalSubscription(LocalGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `void` | `addRemoteSubscription(RemoteGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `void` | `addResource(Resource resource)` Stores an arbitrary resource in the registry.
    `void` | `addResource(Resource resource, int maxAgeSeconds)` Stores an arbitrary resource in the registry.
    `void` | `advertiseLocalDevices()` Manually trigger advertisement messages for all local devices.
    `protected RegistryMaintainer` | `createRegistryMaintainer()`
    `UpnpServiceConfiguration` | `getConfiguration()`
    `Device` | `getDevice(UDN udn, boolean rootOnly)`
    `Collection<Device>` | `getDevices()`
    `Collection<Device>` | `getDevices(DeviceType deviceType)`
    `Collection<Device>` | `getDevices(ServiceType serviceType)`
    `DiscoveryOptions` | `getDiscoveryOptions(UDN udn)` Get the currently active `DiscoveryOptions` for the given (local device) UDN.
    `Collection<RegistryListener>` | `getListeners()`
    `LocalDevice` | `getLocalDevice(UDN udn, boolean rootOnly)`
    `Collection<LocalDevice>` | `getLocalDevices()`
    `LocalGENASubscription` | `getLocalSubscription(String subscriptionId)` Called internally by the UPnP stack, during GENA protocol execution.
    `ProtocolFactory` | `getProtocolFactory()`
    `RemoteDevice` | `getRemoteDevice(UDN udn, boolean rootOnly)`
    `Collection<RemoteDevice>` | `getRemoteDevices()`
    `RemoteGENASubscription` | `getRemoteSubscription(String subscriptionId)` Called internally by the UPnP stack, during GENA protocol execution.
    `<T extends Resource> T` | `getResource(Class<T> resourceType, URI pathQuery)`
    `Resource` | `getResource(URI pathQuery)`
    `Collection<Resource>` | `getResources()`
    `<T extends Resource> Collection<T>` | `getResources(Class<T> resourceType)`
    `Service` | `getService(ServiceReference serviceReference)`
    `UpnpService` | `getUpnpService()`
    `RemoteGENASubscription` | `getWaitRemoteSubscription(String subscriptionId)` Called internally by the UPnP stack, during GENA protocol execution.
    `boolean` | `isPaused()`
    `void` | `notifyDiscoveryFailure(RemoteDevice device, Exception ex)` Called internally by the UPnP stack when the discovery protocol stopped abnormally.
    `boolean` | `notifyDiscoveryStart(RemoteDevice device)` Called internally by the UPnP stack when the discovery protocol starts.
    `void` | `pause()` Stops background maintenance (thread) of registered items.
    `void` | `printDebugLog()`
    `void` | `registerPendingRemoteSubscription(RemoteGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `void` | `removeAllLocalDevices()` Clear the registry of all locally registered device metadata.
    `void` | `removeAllRemoteDevices()` Clear the registry of all discovered remote device metadata.
    `boolean` | `removeDevice(LocalDevice localDevice)` Call this to remove your local device metadata.
    `boolean` | `removeDevice(RemoteDevice remoteDevice)` Called internally by the UPnP discovery protocol.
    `boolean` | `removeDevice(UDN udn)` Call this to remove any device metadata with the given UDN.
    `void` | `removeListener(RegistryListener listener)`
    `boolean` | `removeLocalSubscription(LocalGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `void` | `removeRemoteSubscription(RemoteGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `boolean` | `removeResource(Resource resource)` Removes a resource from the registry.
    `void` | `resume()` Resumes background maintenance (thread) of registered items.
    `void` | `setDiscoveryOptions(UDN udn, DiscoveryOptions options)` Change the active `DiscoveryOptions` for the given (local device) UDN.
    `void` | `shutdown()` Typically called internally when the UPnP stack is stopping.
    `void` | `unregisterPendingRemoteSubscription(RemoteGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `boolean` | `update(RemoteDeviceIdentity rdIdentity)` Called internally by the UPnP discovery protocol.
    `boolean` | `updateLocalSubscription(LocalGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.
    `void` | `updateRemoteSubscription(RemoteGENASubscription subscription)` Called internally by the UPnP stack, during GENA protocol execution.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### upnpService

          protected UpnpService upnpService

    - #### registryMaintainer

          protected RegistryMaintainer registryMaintainer

    - #### pendingSubscriptionsLock

          protected final Set<RemoteGENASubscription> pendingSubscriptionsLock

    - #### registryListeners

          protected final Set<RegistryListener> registryListeners

    - #### resourceItems

          protected final Set<org.fourthline.cling.registry.RegistryItem<URI,Resource>> resourceItems

    - #### pendingExecutions

          protected final List<Runnable> pendingExecutions

    - #### remoteItems

          protected final org.fourthline.cling.registry.RemoteItems remoteItems

    - #### localItems

          protected final org.fourthline.cling.registry.LocalItems localItems

  - ### Constructor Detail

    - #### RegistryImpl

          public RegistryImpl()

    - #### RegistryImpl

          @Inject
          public RegistryImpl(UpnpService upnpService)

      Starts background maintenance immediately.

  - ### Method Detail

    - #### getUpnpService

          public UpnpService getUpnpService()

      Specified by:
        `getUpnpService` in interface `Registry`

    - #### getConfiguration

          public UpnpServiceConfiguration getConfiguration()

      Specified by:
        `getConfiguration` in interface `Registry`

    - #### getProtocolFactory

          public ProtocolFactory getProtocolFactory()

      Specified by:
        `getProtocolFactory` in interface `Registry`

    - #### createRegistryMaintainer

          protected RegistryMaintainer createRegistryMaintainer()

    - #### addListener

          public void addListener(RegistryListener listener)

      Specified by:
        `addListener` in interface `Registry`

    - #### removeListener

          public void removeListener(RegistryListener listener)

      Specified by:
        `removeListener` in interface `Registry`

    - #### getListeners

          public Collection<RegistryListener> getListeners()

      Specified by:
        `getListeners` in interface `Registry`

    - #### notifyDiscoveryStart

          public boolean notifyDiscoveryStart(RemoteDevice device)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack when the discovery protocol starts.

      The registry will notify all registered listeners of this event, unless the given device was already in the registry.

      Specified by:
        `notifyDiscoveryStart` in interface `Registry`
      Parameters:
        `device` - The half-hydrated (without services) metadata of the discovered device.
      Returns:
        `false` if the device was already registered.

    - #### notifyDiscoveryFailure

          public void notifyDiscoveryFailure(RemoteDevice device,
                                    Exception ex)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack when the discovery protocol stopped abnormally.

      The registry will notify all registered listeners of this event.

      Specified by:
        `notifyDiscoveryFailure` in interface `Registry`
      Parameters:
        `device` - The half-hydrated (without services) metadata of the discovered device.
        `ex` - The cause for the interruption of the discovery protocol.

    - #### addDevice

          public void addDevice(LocalDevice localDevice)

      Description copied from interface: `Registry`
      Call this method to add your local device metadata.
      Specified by:
        `addDevice` in interface `Registry`
      Parameters:
        `localDevice` - The device to add and maintain.

    - #### addDevice

          public void addDevice(LocalDevice localDevice,
                       DiscoveryOptions options)

      Description copied from interface: `Registry`
      Call this method to add your local device metadata.
      Specified by:
        `addDevice` in interface `Registry`
      Parameters:
        `localDevice` - The device to add and maintain.
        `options` - Immediately effective when this device is registered.

    - #### setDiscoveryOptions

          public void setDiscoveryOptions(UDN udn,
                                 DiscoveryOptions options)

      Description copied from interface: `Registry`
      Change the active `DiscoveryOptions` for the given (local device) UDN.
      Specified by:
        `setDiscoveryOptions` in interface `Registry`
        `options` - Set to `null` to disable any options.

    - #### getDiscoveryOptions

          public DiscoveryOptions getDiscoveryOptions(UDN udn)

      Description copied from interface: `Registry`
      Get the currently active `DiscoveryOptions` for the given (local device) UDN.
      Specified by:
        `getDiscoveryOptions` in interface `Registry`
      Returns:
        `null` if there are no active discovery options for the given UDN.

    - #### addDevice

          public void addDevice(RemoteDevice remoteDevice)

      Description copied from interface: `Registry`
      Called internally by the UPnP discovery protocol.
      Specified by:
        `addDevice` in interface `Registry`

    - #### update

          public boolean update(RemoteDeviceIdentity rdIdentity)

      Description copied from interface: `Registry`
      Called internally by the UPnP discovery protocol.
      Specified by:
        `update` in interface `Registry`

    - #### removeDevice

          public boolean removeDevice(LocalDevice localDevice)

      Description copied from interface: `Registry`
      Call this to remove your local device metadata.
      Specified by:
        `removeDevice` in interface `Registry`
      Returns:
        `true` if the device was registered and has been removed.

    - #### removeDevice

          public boolean removeDevice(RemoteDevice remoteDevice)

      Description copied from interface: `Registry`
      Called internally by the UPnP discovery protocol.
      Specified by:
        `removeDevice` in interface `Registry`

    - #### removeAllLocalDevices

          public void removeAllLocalDevices()

      Description copied from interface: `Registry`
      Clear the registry of all locally registered device metadata.
      Specified by:
        `removeAllLocalDevices` in interface `Registry`

    - #### removeAllRemoteDevices

          public void removeAllRemoteDevices()

      Description copied from interface: `Registry`
      Clear the registry of all discovered remote device metadata.
      Specified by:
        `removeAllRemoteDevices` in interface `Registry`

    - #### removeDevice

          public boolean removeDevice(UDN udn)

      Description copied from interface: `Registry`
      Call this to remove any device metadata with the given UDN.
      Specified by:
        `removeDevice` in interface `Registry`
      Returns:
        `true` if the device was registered and has been removed.

    - #### getDevice

          public Device getDevice(UDN udn,
                         boolean rootOnly)

      Specified by:
        `getDevice` in interface `Registry`
      Parameters:
        `udn` - The device name to lookup.
        `rootOnly` - If `true`, only matches of root devices are returned.
      Returns:
        The registered root or embedded device metadata, or `null`.

    - #### getLocalDevice

          public LocalDevice getLocalDevice(UDN udn,
                                   boolean rootOnly)

      Specified by:
        `getLocalDevice` in interface `Registry`
      Parameters:
        `udn` - The device name to lookup.
        `rootOnly` - If `true`, only matches of root devices are returned.
      Returns:
        The registered root or embedded device metadata, or `null`.

    - #### getRemoteDevice

          public RemoteDevice getRemoteDevice(UDN udn,
                                     boolean rootOnly)

      Specified by:
        `getRemoteDevice` in interface `Registry`
      Parameters:
        `udn` - The device name to lookup.
        `rootOnly` - If `true`, only matches of root devices are returned.
      Returns:
        The registered root or embedded device metadata, or `null`.

    - #### getLocalDevices

          public Collection<LocalDevice> getLocalDevices()

      Specified by:
        `getLocalDevices` in interface `Registry`
      Returns:
        All locally registered device metadata, in no particular order, or an empty collection.

    - #### getRemoteDevices

          public Collection<RemoteDevice> getRemoteDevices()

      Specified by:
        `getRemoteDevices` in interface `Registry`
      Returns:
        All discovered remote device metadata, in no particular order, or an empty collection.

    - #### getDevices

          public Collection<Device> getDevices()

      Specified by:
        `getDevices` in interface `Registry`
      Returns:
        All device metadata, in no particular order, or an empty collection.

    - #### getDevices

          public Collection<Device> getDevices(DeviceType deviceType)

      Specified by:
        `getDevices` in interface `Registry`
      Returns:
        All device metadata of devices which implement the given type, in no particular order, or an empty collection.

    - #### getDevices

          public Collection<Device> getDevices(ServiceType serviceType)

      Specified by:
        `getDevices` in interface `Registry`
      Returns:
        All device metadata of devices which have a service that implements the given type, in no particular order, or an empty collection.

    - #### getService

          public Service getService(ServiceReference serviceReference)

      Specified by:
        `getService` in interface `Registry`
      Returns:
        Complete service metadata for a service reference or `null` if no service for the given reference has been registered.

    - #### getResource

          public Resource getResource(URI pathQuery)
                               throws IllegalArgumentException

      Specified by:
        `getResource` in interface `Registry`
      Parameters:
        `pathQuery` - The path and optional query string of the resource's registration URI (e.g. `/dev/somefile.xml?param=value`)
      Returns:
        Any registered resource that matches the given URI path.
      Throws:
        `IllegalArgumentException` - If the given URI was absolute, only path and query are allowed.

    - #### getResource

          public <T extends Resource> T getResource(Class<T> resourceType,
                                           URI pathQuery)
                                         throws IllegalArgumentException

      Specified by:
        `getResource` in interface `Registry`
      Type Parameters:
        `T` - The required subtype of the `Resource`.
      Parameters:
        `resourceType` - The required subtype of the `Resource`.
        `pathQuery` - The path and optional query string of the resource's registration URI (e.g. `/dev/somefile.xml?param=value`)
      Returns:
        Any registered resource that matches the given URI path and subtype.
      Throws:
        `IllegalArgumentException` - If the given URI was absolute, only path and query are allowed.

    - #### getResources

          public Collection<Resource> getResources()

      Specified by:
        `getResources` in interface `Registry`
      Returns:
        All registered resources, in no particular order, or an empty collection.

    - #### getResources

          public <T extends Resource> Collection<T> getResources(Class<T> resourceType)

      Specified by:
        `getResources` in interface `Registry`
      Type Parameters:
        `T` - The required subtype of the `Resource`.
      Parameters:
        `resourceType` - The required subtype of the `Resource`.
      Returns:
        Any registered resource that matches the given subtype.

    - #### addResource

          public void addResource(Resource resource)

      Description copied from interface: `Registry`
      Stores an arbitrary resource in the registry.
      Specified by:
        `addResource` in interface `Registry`
      Parameters:
        `resource` - The resource to maintain indefinitely (until it is manually removed).

    - #### addResource

          public void addResource(Resource resource,
                         int maxAgeSeconds)

      Description copied from interface: `Registry`
      Stores an arbitrary resource in the registry.

      Call this method repeatedly to refresh and prevent expiration of the resource.

      Specified by:
        `addResource` in interface `Registry`
      Parameters:
        `resource` - The resource to maintain.
        `maxAgeSeconds` - The time after which the registry will automatically remove the resource.

    - #### removeResource

          public boolean removeResource(Resource resource)

      Description copied from interface: `Registry`
      Removes a resource from the registry.
      Specified by:
        `removeResource` in interface `Registry`
      Parameters:
        `resource` - The resource to remove.
      Returns:
        `true` if the resource was registered and has been removed.

    - #### addLocalSubscription

          public void addLocalSubscription(LocalGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `addLocalSubscription` in interface `Registry`

    - #### getLocalSubscription

          public LocalGENASubscription getLocalSubscription(String subscriptionId)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `getLocalSubscription` in interface `Registry`

    - #### updateLocalSubscription

          public boolean updateLocalSubscription(LocalGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `updateLocalSubscription` in interface `Registry`

    - #### removeLocalSubscription

          public boolean removeLocalSubscription(LocalGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `removeLocalSubscription` in interface `Registry`

    - #### addRemoteSubscription

          public void addRemoteSubscription(RemoteGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `addRemoteSubscription` in interface `Registry`

    - #### getRemoteSubscription

          public RemoteGENASubscription getRemoteSubscription(String subscriptionId)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `getRemoteSubscription` in interface `Registry`

    - #### updateRemoteSubscription

          public void updateRemoteSubscription(RemoteGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `updateRemoteSubscription` in interface `Registry`

    - #### removeRemoteSubscription

          public void removeRemoteSubscription(RemoteGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.
      Specified by:
        `removeRemoteSubscription` in interface `Registry`

    - #### advertiseLocalDevices

          public void advertiseLocalDevices()

      Description copied from interface: `Registry`
      Manually trigger advertisement messages for all local devices.

      No messages will be send for devices with disabled advertisements, see `DiscoveryOptions`!

      Specified by:
        `advertiseLocalDevices` in interface `Registry`

    - #### shutdown

          public void shutdown()

      Description copied from interface: `Registry`
      Typically called internally when the UPnP stack is stopping.

      Unsubscribe all local devices and GENA subscriptions.

      Specified by:
        `shutdown` in interface `Registry`

    - #### pause

          public void pause()

      Description copied from interface: `Registry`
      Stops background maintenance (thread) of registered items.

      When paused, the registry will no longer remove expired remote devices if their discovery announcements stop for some reason (device was turned off). Your local control point will now see potentially unavailable remote devices. Outbound GENA subscriptions from your local control point to remote services will not be renewed automatically anymore, a remote service might drop your subscriptions if you don't resume maintenance within the subscription's expiration timeout.

      Local devices and services will not be announced periodically anymore to remote control points, only when they are manually added are removed from the registry. The registry will also no longer remove expired inbound GENA subscriptions to local service from remote control points, if that control point for some reason stops sending subscription renewal messages.

      Specified by:
        `pause` in interface `Registry`

    - #### resume

          public void resume()

      Description copied from interface: `Registry`
      Resumes background maintenance (thread) of registered items.

      A local control point has to handle the following situations when resuming registry maintenance:

      A remote device registration might have expired. This is the case when the remote device stopped sending announcements while the registry was paused (maybe because the device was switched off) and the registry was paused longer than the device advertisement's maximum age. The registry will not know if the device is still available when it resumes maintenance. However, it will simply assume that the remote device is still available and restart its expiration check cycle. That means a device will finally be removed from the registry, if no further announcements from the device are received, when the maximum age of the device has elapsed after the registry resumed operation.

      Secondly, a remote device registration might not have expired but some of your outbound GENA subscriptions to its services have not been renewed within the expected renewal period. Therefore your outbound subscriptions might be invalid, because the remote service can drop subscriptions when you don't renew them. On resume, the registry will attempt to send renewals for all outbound GENA subscriptions that require renewal, on devices that still haven't expired. If renewal fails, your subscription will end with `CancelReason.RENEWAL_FAILED`. Although you then might conclude that the remote device is no longer available, a GENA renewal can also fail for other reasons. The remote device will be kept and maintained in the registry until it announces itself or it expires, even after a failed GENA renewal.

      If you are providing local devices and services, resuming registry maintenance has the following effects:

      Local devices and their services are announced again immediately if the registry has been paused for longer than half of the device's maximum age. Remote control points will either see this as a new device advertisement (if they have dropped your device while you paused maintenance) or as a regular update if you didn't pause longer than the device's maximum age/expiration timeout.

      Inbound GENA subscriptions to your local services are active, even in paused state - remote control points should continue renewing the subscription. If a remote control point stopped renewing a subscription without unsubscribing (hard power off), an outdated inbound subscription will be detected when you resume maintenance. This subscription will be cleaned up immediately on resume.

      Specified by:
        `resume` in interface `Registry`

    - #### isPaused

          public boolean isPaused()

      Specified by:
        `isPaused` in interface `Registry`
      Returns:
        `true` if the registry has currently no running background maintenance (thread).

    - #### printDebugLog

          public void printDebugLog()

    - #### registerPendingRemoteSubscription

          public void registerPendingRemoteSubscription(RemoteGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.

      When subscribing with a remote host, the remote host might send the initial event message faster than the response for the subscription request. This method register that the subscription procedure is executing.

      Specified by:
        `registerPendingRemoteSubscription` in interface `Registry`

    - #### unregisterPendingRemoteSubscription

          public void unregisterPendingRemoteSubscription(RemoteGENASubscription subscription)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.

      Notify that the subscription procedure has terminated.

      Specified by:
        `unregisterPendingRemoteSubscription` in interface `Registry`

    - #### getWaitRemoteSubscription

          public RemoteGENASubscription getWaitRemoteSubscription(String subscriptionId)

      Description copied from interface: `Registry`
      Called internally by the UPnP stack, during GENA protocol execution.

      Get a remote subscription from its subscriptionId. If the subscription can't be found, wait for one of the pending remote subscription procedures from the registry background maintainer to terminate, until the subscription has been found or until there are no more pending subscription procedures.

      Specified by:
        `getWaitRemoteSubscription` in interface `Registry`

Copyright © 2014 4th Line GmbH, Switzerland. All Rights Reserved.