| 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 and Description |
|---|
RegistryImpl() |
RegistryImpl(UpnpService upnpService)
Starts background maintenance immediately.
|
| 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> |
getResource(Class<T> resourceType,
URI pathQuery) |
Resource |
getResource(URI pathQuery) |
Collection<Resource> |
getResources() |
<T extends Resource> |
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.
|
protected UpnpService upnpService
protected RegistryMaintainer registryMaintainer
protected final Set<RemoteGENASubscription> pendingSubscriptionsLock
protected Object lock
protected final Set<RegistryListener> registryListeners
protected final ReentrantReadWriteLock remoteItemsLock
protected final ReentrantReadWriteLock localItemsLock
protected final org.jupnp.registry.RemoteItems remoteItems
protected final org.jupnp.registry.LocalItems localItems
public RegistryImpl()
public RegistryImpl(UpnpService upnpService)
public UpnpService getUpnpService()
getUpnpService in interface Registrypublic UpnpServiceConfiguration getConfiguration()
getConfiguration in interface Registrypublic ProtocolFactory getProtocolFactory()
getProtocolFactory in interface Registryprotected RegistryMaintainer createRegistryMaintainer()
public void addListener(RegistryListener listener)
addListener in interface Registrypublic void removeListener(RegistryListener listener)
removeListener in interface Registrypublic Collection<RegistryListener> getListeners()
getListeners in interface Registrypublic boolean notifyDiscoveryStart(RemoteDevice device)
RegistryThe registry will notify all registered listeners of this event, unless the given device was already been present in the registry.
notifyDiscoveryStart in interface Registrydevice - The half-hydrated (without services) metadata of the discovered device.false if the device was already registered.public void notifyDiscoveryFailure(RemoteDevice device, Exception ex)
RegistryThe registry will notify all registered listeners of this event.
notifyDiscoveryFailure in interface Registrydevice - The half-hydrated (without services) metadata of the discovered device.ex - The cause for the interruption of the discovery protocol.public void addDevice(LocalDevice localDevice)
Registrypublic void addDevice(LocalDevice localDevice, DiscoveryOptions options)
Registrypublic void setDiscoveryOptions(UDN udn, DiscoveryOptions options)
RegistryDiscoveryOptions for the given (local device) UDN.setDiscoveryOptions in interface Registryoptions - Set to null to disable any options.public DiscoveryOptions getDiscoveryOptions(UDN udn)
RegistryDiscoveryOptions for the given (local device) UDN.getDiscoveryOptions in interface Registrynull if there are no active discovery options for the given UDN.public void addDevice(RemoteDevice remoteDevice)
Registrypublic boolean update(RemoteDeviceIdentity rdIdentity)
Registrypublic boolean removeDevice(LocalDevice localDevice)
RegistryremoveDevice in interface Registrytrue if the device was registered and has been removed.public boolean removeDevice(RemoteDevice remoteDevice)
RegistryremoveDevice in interface Registrypublic void removeAllLocalDevices()
RegistryremoveAllLocalDevices in interface Registrypublic void removeAllRemoteDevices()
RegistryremoveAllRemoteDevices in interface Registrypublic boolean removeDevice(UDN udn)
RegistryremoveDevice in interface Registrytrue if the device was registered and has been removed.public LocalDevice getLocalDevice(UDN udn, boolean rootOnly)
getLocalDevice in interface Registryudn - The device name to lookup.rootOnly - If true, only matches of root devices are returned.null.public RemoteDevice getRemoteDevice(UDN udn, boolean rootOnly)
getRemoteDevice in interface Registryudn - The device name to lookup.rootOnly - If true, only matches of root devices are returned.null.public Collection<LocalDevice> getLocalDevices()
getLocalDevices in interface Registrypublic Collection<RemoteDevice> getRemoteDevices()
getRemoteDevices in interface Registrypublic Collection<Device> getDevices()
getDevices in interface Registrypublic Collection<Device> getDevices(DeviceType deviceType)
getDevices in interface Registrypublic Collection<Device> getDevices(ServiceType serviceType)
getDevices in interface Registrypublic Service getService(ServiceReference serviceReference)
getService in interface Registrynull if no service
for the given reference has been registered.public Resource getResource(URI pathQuery) throws IllegalArgumentException
getResource in interface RegistrypathQuery - The path and optional query string of the resource's
registration URI (e.g. /dev/somefile.xml?param=value)IllegalArgumentException - If the given URI was absolute, only path and query are allowed.public <T extends Resource> T getResource(Class<T> resourceType, URI pathQuery) throws IllegalArgumentException
getResource in interface RegistryT - The required subtype of the Resource.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)IllegalArgumentException - If the given URI was absolute, only path and query are allowed.public Collection<Resource> getResources()
getResources in interface Registrypublic <T extends Resource> Collection<T> getResources(Class<T> resourceType)
getResources in interface RegistryT - The required subtype of the Resource.resourceType - The required subtype of the Resource.public void addResource(Resource resource)
RegistryaddResource in interface Registryresource - The resource to maintain indefinitely (until it is manually removed).public void addResource(Resource resource, int maxAgeSeconds)
RegistryCall this method repeatedly to refresh and prevent expiration of the resource.
addResource in interface Registryresource - The resource to maintain.maxAgeSeconds - The time after which the registry will automatically remove the resource.public boolean removeResource(Resource resource)
RegistryremoveResource in interface Registryresource - The resource to remove.true if the resource was registered and has been removed.public void addLocalSubscription(LocalGENASubscription subscription)
RegistryaddLocalSubscription in interface Registrypublic LocalGENASubscription getLocalSubscription(String subscriptionId)
RegistrygetLocalSubscription in interface Registrypublic boolean updateLocalSubscription(LocalGENASubscription subscription)
RegistryupdateLocalSubscription in interface Registrypublic boolean removeLocalSubscription(LocalGENASubscription subscription)
RegistryremoveLocalSubscription in interface Registrypublic void addRemoteSubscription(RemoteGENASubscription subscription)
RegistryaddRemoteSubscription in interface Registrypublic RemoteGENASubscription getRemoteSubscription(String subscriptionId)
RegistrygetRemoteSubscription in interface Registrypublic void updateRemoteSubscription(RemoteGENASubscription subscription)
RegistryupdateRemoteSubscription in interface Registrypublic void removeRemoteSubscription(RemoteGENASubscription subscription)
RegistryremoveRemoteSubscription in interface Registrypublic void advertiseLocalDevices()
Registry
No messages will be send for devices with disabled advertisements, see
DiscoveryOptions!
advertiseLocalDevices in interface Registrypublic void shutdown()
RegistryUnsubscribes all local devices and GENA subscriptions.
public void pause()
RegistryWhen 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.
public void resume()
RegistryA 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.
public boolean isPaused()
public void printDebugLog()
public void registerPendingRemoteSubscription(RemoteGENASubscription subscription)
RegistryWhen 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.
registerPendingRemoteSubscription in interface Registrypublic void unregisterPendingRemoteSubscription(RemoteGENASubscription subscription)
RegistryNotify that the subscription procedure has terminated.
unregisterPendingRemoteSubscription in interface Registrypublic RemoteGENASubscription getWaitRemoteSubscription(String subscriptionId)
RegistryGet 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.
getWaitRemoteSubscription in interface RegistryCopyright © 2023 jUPnP.org. All rights reserved.