Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.teleal.cling.registry
Interface Registry

All Known Implementing Classes:
  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 continously (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.

TODO: Unify all "items" the registry is keeping track of, this API should be narrowed.

Author:
  Christian Bauer

Method Summary
`void` | `addDevice(LocalDevice localDevice)` 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.
`UpnpServiceConfiguration` | `getConfiguration()`
`Device` | `getDevice(UDN udn, boolean rootOnly)`
`Collection<Device>` | `getDevices()`
`Collection<Device>` | `getDevices(DeviceType deviceType)`
`Collection<Device>` | `getDevices(ServiceType serviceType)`
`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()`
`void` | `notifyDiscoveryFailure(RemoteDevice device, Exception ex)` Called internally by the UPnP stack when the discovery protocol stopped abnormaly.
`boolean` | `notifyDiscoveryStart(RemoteDevice device)` Called internally by the UPnP stack when the discovery protocol starts.
`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` | `shutdown()` Typically called internally when the UPnP stack is stopping.
`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.

Method Detail

### 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.

### 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.

  Parameters:
    `device` - The half-hydrated (without services) metadata of the discovered device.
  Returns:
    `false` if the device was already registered.

### notifyDiscoveryFailure

    void notifyDiscoveryFailure(RemoteDevice device,
                                Exception ex)

  Called internally by the UPnP stack when the discovery protocol stopped abnormaly.

  The registry will notify all registered listeners of this event.

  Parameters:
    `device` - The half-hydrated (without services) metadata of the discovered device.
    `ex` - 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.

  Parameters:
    `localDevice` - The device to add and maintain.
  Throws:
    `RegistrationException` - If a conflict with an already registered device was detected.

### addDevice

    void addDevice(RemoteDevice remoteDevice)
                   throws RegistrationException

  Called internally by the UPnP discovery protocol.

  Throws:
    `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.

  Returns:
    `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.

  Returns:
    `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)

  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

    LocalDevice getLocalDevice(UDN udn,
                               boolean rootOnly)

  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

    RemoteDevice getRemoteDevice(UDN udn,
                                 boolean rootOnly)

  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

    Collection<LocalDevice> getLocalDevices()

  Returns:
    All locally registered device metadata, in no particular order, or an empty collection.

### getRemoteDevices

    Collection<RemoteDevice> getRemoteDevices()

  Returns:
    All discovered remote device metadata, in no particular order, or an empty collection.

### getDevices

    Collection<Device> getDevices()

  Returns:
    All device metadata, in no particular order, or an empty collection.

### getDevices

    Collection<Device> getDevices(DeviceType deviceType)

  Returns:
    All device metadata of devices which implement the given type, in no particular order, or an empty collection.

### getDevices

    Collection<Device> getDevices(ServiceType serviceType)

  Returns:
    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)

  Returns:
    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.

  Parameters:
    `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.

  Parameters:
    `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.

  Parameters:
    `resource` - The resource to remove.
  Returns:
    `true` if the resource was registered and has been removed.

### getResource

    Resource getResource(URI pathQuery)
                         throws IllegalArgumentException

  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

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

  Type Parameters:
    `T` - The required subtype of the `Resource`.
  Parameters:
    `pathQuery` - The path and optional query string of the resource's registration URI (e.g. `/dev/somefile.xml?param=value`)
    `resourceType` - The required subtype of the `Resource`.
  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

    Collection<Resource> getResources()

  Returns:
    All registered resources, in no particular order, or an empty collection.

### getResources

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

  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.

### 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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2010 Teleal GmbH, Switzerland. All Rights Reserved.