org.fourthline.cling.registry

## Interface RegistryListener

- All Known Implementing Classes:
    DefaultRegistryListener

      public interface RegistryListener

  Notification of discovered device additions, removals, updates.

  Add an instance of this interface to the registry to be notified when a device is discovered on your UPnP network, or when it is updated, or when it disappears.

  Implementations will be called concurrently by several threads, they should be thread-safe.

  Listener methods are called in a separate thread, so you can execute expensive procedures without spawning a new thread. The `beforeShutdown(Registry)` and `afterShutdown()` methods are however called in the thread that is stopping the registry and should not be blocking, unless you want to delay the shutdown procedure.

  Author:
    Christian Bauer

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `afterShutdown()` Called after the registry has been cleared on shutdown.
    `void` | `beforeShutdown(Registry registry)` Called after registry maintenance stops but before the registry is cleared.
    `void` | `localDeviceAdded(Registry registry, LocalDevice device)` Called after you add your own device to the `Registry`.
    `void` | `localDeviceRemoved(Registry registry, LocalDevice device)` Called after you remove your own device from the `Registry`.
    `void` | `remoteDeviceAdded(Registry registry, RemoteDevice device)` Called when complete metadata of a newly discovered device is available.
    `void` | `remoteDeviceDiscoveryFailed(Registry registry, RemoteDevice device, Exception ex)` Called when service metadata couldn't be initialized.
    `void` | `remoteDeviceDiscoveryStarted(Registry registry, RemoteDevice device)` Called as soon as possible after a device has been discovered.
    `void` | `remoteDeviceRemoved(Registry registry, RemoteDevice device)` Called when a previously discovered device disappears.
    `void` | `remoteDeviceUpdated(Registry registry, RemoteDevice device)` Called when a discovered device's expiration timestamp is updated.

- - ### Method Detail

    - #### remoteDeviceDiscoveryStarted

          void remoteDeviceDiscoveryStarted(Registry registry,
                                          RemoteDevice device)

      Called as soon as possible after a device has been discovered.

      This method will be called after SSDP notification datagrams of a new alive UPnP device have been received and processed. The announced device XML descriptor will be retrieved and parsed. The given `RemoteDevice` metadata is validated and partial `Service` metadata is available. The services are unhydrated, they have no actions or state variable metadata because the service descriptors of the device model have not been retrieved at this point.

      You typically do not use this method on a regular machine, this is an optimization for slower UPnP hosts (such as Android handsets).

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - A validated and hydrated device metadata graph, with anemic service metadata.

    - #### remoteDeviceDiscoveryFailed

          void remoteDeviceDiscoveryFailed(Registry registry,
                                         RemoteDevice device,
                                         Exception ex)

      Called when service metadata couldn't be initialized.

      If you override the `remoteDeviceDiscoveryStarted(Registry, org.fourthline.cling.model.meta.RemoteDevice)` method, you might want to override this method as well.

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - A validated and hydrated device metadata graph, with anemic service metadata.
        `ex` - The reason why service metadata could not be initialized, or `null` if service descriptors couldn't be retrieved at all.

    - #### remoteDeviceAdded

          void remoteDeviceAdded(Registry registry,
                               RemoteDevice device)

      Called when complete metadata of a newly discovered device is available.
      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - A validated and hydrated device metadata graph, with complete service metadata.

    - #### remoteDeviceUpdated

          void remoteDeviceUpdated(Registry registry,
                                 RemoteDevice device)

      Called when a discovered device's expiration timestamp is updated.

      This is a signal that a device is still alive and you typically don't have to react to this event. You will be notified when a device disappears through timeout.

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - A validated and hydrated device metadata graph, with complete service metadata.

    - #### remoteDeviceRemoved

          void remoteDeviceRemoved(Registry registry,
                                 RemoteDevice device)

      Called when a previously discovered device disappears.

      This method will also be called when a discovered device did not update its expiration timeout and has been been removed automatically by the local registry. This method will not be called when the UPnP stack is shutting down.

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - A validated and hydrated device metadata graph, with complete service metadata.

    - #### localDeviceAdded

          void localDeviceAdded(Registry registry,
                              LocalDevice device)

      Called after you add your own device to the `Registry`.
      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - The local device added to the `Registry`.

    - #### localDeviceRemoved

          void localDeviceRemoved(Registry registry,
                                LocalDevice device)

      Called after you remove your own device from the `Registry`.

      This method will not be called when the UPnP stack is shutting down.

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.
        `device` - The local device removed from the `Registry`.

    - #### beforeShutdown

          void beforeShutdown(Registry registry)

      Called after registry maintenance stops but before the registry is cleared.

      This method should typically not block, it executes in the thread that shuts down the UPnP stack.

      Parameters:
        `registry` - The Cling registry of all devices and services know to the local UPnP stack.

    - #### afterShutdown

          void afterShutdown()

      Called after the registry has been cleared on shutdown.

      This method should typically not block, it executes in the thread that shuts down the UPnP stack.

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