Package org.jupnp.registry

Schnittstelle Registry

Alle bekannten Implementierungsklassen:
RegistryImpl
public interface Registry
The core of the UPnP stack, keeping track of known devices and resources.

A running UPnP stack has one Registry. Any discovered device is added to this registry, as well as any exposed local device. The registry then maintains these devices continuously (see RegistryMaintainer) and when needed refreshes their announcements on the network or removes them when they have expired. The registry also keeps track of GENA event subscriptions.

UPnP client applications typically monitor activity of the registry via RegistryListener, they are inherently asynchronous.

The registry has to be shutdown() properly, so it can notify all participants on the network that local devices will no longer be available and cancel all GENA subscriptions.

An implementation has to be thread-safe.

Autor:
Christian Bauer

  • Methodendetails

    • getUpnpService

      UpnpService getUpnpService()

    • getConfiguration

      UpnpServiceConfiguration getConfiguration()

    • getProtocolFactory

      ProtocolFactory getProtocolFactory()

    • shutdown

      void shutdown()
      Typically called internally when the UPnP stack is stopping.

      Unsubscribes all local devices and GENA subscriptions.

    • pause

      void pause()
      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.

    • resume

      void resume()
      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.

    • isPaused

      boolean isPaused()
      Gibt zurück:
      true if the registry has currently no running background maintenance (thread).

    • addListener

      void addListener(RegistryListener listener)

    • removeListener

      void removeListener(RegistryListener listener)

    • getListeners

      Collection<RegistryListener> getListeners()

    • notifyDiscoveryStart

      boolean notifyDiscoveryStart(RemoteDevice device)
      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 been present in the registry.

      Parameter:
      device - The half-hydrated (without services) metadata of the discovered device.
      Gibt zurück:
      false if the device was already registered.

    • notifyDiscoveryFailure

      void notifyDiscoveryFailure(RemoteDevice device, Exception e)
      Called internally by the UPnP stack when the discovery protocol stopped abnormaly.

      The registry will notify all registered listeners of this event.

      Parameter:
      device - The half-hydrated (without services) metadata of the discovered device.
      e - The cause for the interruption of the discovery protocol.

    • addDevice

      void addDevice(LocalDevice localDevice) throws RegistrationException
      Call this method to add your local device metadata.
      Parameter:
      localDevice - The device to add and maintain.
      Löst aus:
      RegistrationException - If a conflict with an already registered device was detected.

    • addDevice

      void addDevice(LocalDevice localDevice, DiscoveryOptions options) throws RegistrationException
      Call this method to add your local device metadata.
      Parameter:
      localDevice - The device to add and maintain.
      options - Immediately effective when this device is registered.
      Löst aus:
      RegistrationException - If a conflict with an already registered device was detected.

    • setDiscoveryOptions

      void setDiscoveryOptions(UDN udn, DiscoveryOptions options)
      Change the active DiscoveryOptions for the given (local device) UDN.
      Parameter:
      options - Set to null to disable any options.

    • getDiscoveryOptions

      DiscoveryOptions getDiscoveryOptions(UDN udn)
      Get the currently active DiscoveryOptions for the given (local device) UDN.
      Gibt zurück:
      null if there are no active discovery options for the given UDN.

    • addDevice

      void addDevice(RemoteDevice remoteDevice) throws RegistrationException
      Called internally by the UPnP discovery protocol.
      Löst aus:
      RegistrationException - If a conflict with an already registered device was detected.

    • update

      boolean update(RemoteDeviceIdentity rdIdentity)
      Called internally by the UPnP discovery protocol.

    • removeDevice

      boolean removeDevice(LocalDevice localDevice)
      Call this to remove your local device metadata.
      Gibt zurück:
      true if the device was registered and has been removed.

    • removeDevice

      boolean removeDevice(RemoteDevice remoteDevice)
      Called internally by the UPnP discovery protocol.

    • removeDevice

      boolean removeDevice(UDN udn)
      Call this to remove any device metadata with the given UDN.
      Gibt zurück:
      true if the device was registered and has been removed.

    • removeAllLocalDevices

      void removeAllLocalDevices()
      Clear the registry of all locally registered device metadata.

    • removeAllRemoteDevices

      void removeAllRemoteDevices()
      Clear the registry of all discovered remote device metadata.

    • getDevice

      Device getDevice(UDN udn, boolean rootOnly)
      Parameter:
      udn - The device name to lookup.
      rootOnly - If true, only matches of root devices are returned.
      Gibt zurück:
      The registered root or embedded device metadata, or null.

    • getLocalDevice

      LocalDevice getLocalDevice(UDN udn, boolean rootOnly)
      Parameter:
      udn - The device name to lookup.
      rootOnly - If true, only matches of root devices are returned.
      Gibt zurück:
      The registered root or embedded device metadata, or null.

    • getRemoteDevice

      RemoteDevice getRemoteDevice(UDN udn, boolean rootOnly)
      Parameter:
      udn - The device name to lookup.
      rootOnly - If true, only matches of root devices are returned.
      Gibt zurück:
      The registered root or embedded device metadata, or null.

    • getLocalDevices

      Collection<LocalDevice> getLocalDevices()
      Gibt zurück:
      All locally registered device metadata, in no particular order, or an empty collection.

    • getRemoteDevices

      Collection<RemoteDevice> getRemoteDevices()
      Gibt zurück:
      All discovered remote device metadata, in no particular order, or an empty collection.

    • getDevices

      Collection<Device> getDevices()
      Gibt zurück:
      All device metadata, in no particular order, or an empty collection.

    • getDevices

      Collection<Device> getDevices(DeviceType deviceType)
      Gibt zurück:
      All device metadata of devices which implement the given type, in no particular order, or an empty collection.

    • getDevices

      Collection<Device> getDevices(ServiceType serviceType)
      Gibt zurück:
      All device metadata of devices which have a service that implements the given type, in no particular order, or an empty collection.

    • getService

      Service getService(ServiceReference serviceReference)
      Gibt zurück:
      Complete service metadata.for a service reference or null if no service for the given reference has been registered.

    • addResource

      void addResource(Resource resource)
      Stores an arbitrary resource in the registry.
      Parameter:
      resource - The resource to maintain indefinitely (until it is manually removed).

    • addResource

      void addResource(Resource resource, int maxAgeSeconds)
      Stores an arbitrary resource in the registry.

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

      Parameter:
      resource - The resource to maintain.
      maxAgeSeconds - The time after which the registry will automatically remove the resource.

    • removeResource

      boolean removeResource(Resource resource)
      Removes a resource from the registry.
      Parameter:
      resource - The resource to remove.
      Gibt zurück:
      true if the resource was registered and has been removed.

    • getResource

      Resource getResource(URI pathQuery) throws IllegalArgumentException
      Parameter:
      pathQuery - The path and optional query string of the resource's registration URI (e.g. /dev/somefile.xml?param=value)
      Gibt zurück:
      Any registered resource that matches the given URI path.
      Löst aus:
      IllegalArgumentException - If the given URI was absolute, only path and query are allowed.

    • getResource

      <T extends Resource> T getResource(Class<T> resourceType, URI pathQuery) throws IllegalArgumentException
      Typparameter:
      T - The required subtype of the Resource.
      Parameter:
      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)
      Gibt zurück:
      Any registered resource that matches the given URI path and subtype.
      Löst aus:
      IllegalArgumentException - If the given URI was absolute, only path and query are allowed.

    • getResources

      Collection<Resource> getResources()
      Gibt zurück:
      All registered resources, in no particular order, or an empty collection.

    • getResources

      <T extends Resource> Collection<T> getResources(Class<T> resourceType)
      Typparameter:
      T - The required subtype of the Resource.
      Parameter:
      resourceType - The required subtype of the Resource.
      Gibt zurück:
      Any registered resource that matches the given subtype.

    • addLocalSubscription

      void addLocalSubscription(LocalGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • getLocalSubscription

      LocalGENASubscription getLocalSubscription(String subscriptionId)
      Called internally by the UPnP stack, during GENA protocol execution.

    • updateLocalSubscription

      boolean updateLocalSubscription(LocalGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • removeLocalSubscription

      boolean removeLocalSubscription(LocalGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • addRemoteSubscription

      void addRemoteSubscription(RemoteGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • getRemoteSubscription

      RemoteGENASubscription getRemoteSubscription(String subscriptionId)
      Called internally by the UPnP stack, during GENA protocol execution.

    • updateRemoteSubscription

      void updateRemoteSubscription(RemoteGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • removeRemoteSubscription

      void removeRemoteSubscription(RemoteGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

    • registerPendingRemoteSubscription

      void registerPendingRemoteSubscription(RemoteGENASubscription subscription)
      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.

    • unregisterPendingRemoteSubscription

      void unregisterPendingRemoteSubscription(RemoteGENASubscription subscription)
      Called internally by the UPnP stack, during GENA protocol execution.

      Notify that the subscription procedure has terminated.

    • getWaitRemoteSubscription

      RemoteGENASubscription getWaitRemoteSubscription(String subscriptionId)
      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 pending remote subscription procedures to terminate, until the subscription has been found or until there are no more pending subscription procedures.

    • advertiseLocalDevices

      void advertiseLocalDevices()
      Manually trigger advertisement messages for all local devices.

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