org.jupnp.registry

Class RegistryImpl

java.lang.Object

org.jupnp.registry.RegistryImpl

All Implemented Interfaces:

Registry

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.jupnp.registry.LocalItems	localItems
protected ReentrantReadWriteLock	localItemsLock
protected Object	lock
protected List<Runnable>	pendingExecutions
protected Set<RemoteGENASubscription>	pendingSubscriptionsLock
protected Set<RegistryListener>	registryListeners
protected RegistryMaintainer	registryMaintainer
protected org.jupnp.registry.RemoteItems	remoteItems
protected ReentrantReadWriteLock	remoteItemsLock
protected Set<org.jupnp.registry.RegistryItem<URI,Resource>>	resourceItems
protected UpnpService	upnpService

Constructor Summary

Constructors

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

Method Summary

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

lock

protected Object lock

registryListeners

protected final Set<RegistryListener> registryListeners

resourceItems

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

pendingExecutions

protected final List<Runnable> pendingExecutions

remoteItemsLock

protected final ReentrantReadWriteLock remoteItemsLock

localItemsLock

protected final ReentrantReadWriteLock localItemsLock

remoteItems

protected final org.jupnp.registry.RemoteItems remoteItems

localItems

protected final org.jupnp.registry.LocalItems localItems

Constructor Detail

RegistryImpl

public RegistryImpl()

RegistryImpl

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 been present 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 abnormaly.

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.

Unsubscribes 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 pending remote subscription procedures to terminate, until the subscription has been found or until there are no more pending subscription procedures.

Specified by:

getWaitRemoteSubscription in interface Registry