Default implementation of Registry. More...

Inheritance diagram for org.fourthline.cling.registry.RegistryImpl:

Collaboration diagram for org.fourthline.cling.registry.RegistryImpl:

Public Member Functions
	RegistryImpl (UpnpService upnpService)
	Starts background maintenance immediately.

UpnpService	getUpnpService ()

UpnpServiceConfiguration	getConfiguration ()

ProtocolFactory	getProtocolFactory ()

synchronized void	addListener (RegistryListener listener)

synchronized void	removeListener (RegistryListener listener)

synchronized Collection< RegistryListener >	getListeners ()

synchronized boolean	notifyDiscoveryStart (final RemoteDevice device)
	Called internally by the UPnP stack when the discovery protocol starts.

synchronized void	notifyDiscoveryFailure (final RemoteDevice device, final Exception ex)
	Called internally by the UPnP stack when the discovery protocol stopped abnormally.

synchronized void	addDevice (LocalDevice localDevice)
	Call this method to add your local device metadata.

synchronized void	addDevice (LocalDevice localDevice, DiscoveryOptions options)
	Call this method to add your local device metadata.

synchronized void	setDiscoveryOptions (UDN udn, DiscoveryOptions options)
	Change the active `DiscoveryOptions` for the given (local device) UDN.

synchronized DiscoveryOptions	getDiscoveryOptions (UDN udn)
	Get the currently active `DiscoveryOptions` for the given (local device) UDN.

synchronized void	addDevice (RemoteDevice remoteDevice)
	Called internally by the UPnP discovery protocol.

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

synchronized boolean	removeDevice (LocalDevice localDevice)
	Call this to remove your local device metadata.

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

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

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

synchronized boolean	removeDevice (UDN udn)
	Call this to remove any device metadata with the given UDN.

synchronized Device	getDevice (UDN udn, boolean rootOnly)

synchronized LocalDevice	getLocalDevice (UDN udn, boolean rootOnly)

synchronized RemoteDevice	getRemoteDevice (UDN udn, boolean rootOnly)

synchronized Collection< LocalDevice >	getLocalDevices ()

synchronized Collection< RemoteDevice >	getRemoteDevices ()

synchronized Collection< Device<?, ?, ?> >	getDevices ()

synchronized Collection< Device<?, ?, ?> >	getDevices (DeviceType deviceType)

synchronized Collection< Device<?, ?, ?> >	getDevices (ServiceType serviceType)

synchronized Service	getService (ServiceReference serviceReference)

synchronized Resource	getResource (URI pathQuery) throws IllegalArgumentException

synchronized Collection< Resource >	getResources ()

synchronized void	addResource (Resource resource)
	Stores an arbitrary resource in the registry.

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

synchronized boolean	removeResource (Resource resource)
	Removes a resource from the registry.

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

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

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

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

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

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

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

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

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

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

synchronized void	pause ()
	Stops background maintenance (thread) of registered items.

synchronized void	resume ()
	Resumes background maintenance (thread) of registered items.

synchronized boolean	isPaused ()

void	printDebugLog ()

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

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

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

Protected Member Functions
RegistryMaintainer	createRegistryMaintainer ()

Protected Attributes
final Set< RemoteGENASubscription >	pendingSubscriptionsLock = new HashSet<>()

final Set< RegistryListener >	registryListeners = new HashSet<>()

final Set< RegistryItem< URI, Resource > >	resourceItems = new HashSet<>()

final List< Runnable >	pendingExecutions = new ArrayList<>()

final RemoteItems	remoteItems = new RemoteItems(this)

final LocalItems	localItems = new LocalItems(this)

UpnpService	upnpService

RegistryMaintainer	registryMaintainer

Detailed Description

Default implementation of Registry.

Author: Christian Bauer

Member Function Documentation

◆ addDevice() [1/3]

synchronized void org.fourthline.cling.registry.RegistryImpl.addDevice ( LocalDevice localDevice )

Call this method to add your local device metadata.

Parameters

localDevice The device to add and maintain.

Exceptions

RegistrationException If a conflict with an already registered device was detected.

Implements org.fourthline.cling.registry.Registry.

◆ addDevice() [2/3]

synchronized void org.fourthline.cling.registry.RegistryImpl.addDevice	(	LocalDevice	localDevice,
		DiscoveryOptions	options
	)

Call this method to add your local device metadata.

Parameters

localDevice	The device to add and maintain.
options	Immediately effective when this device is registered.

Exceptions

RegistrationException If a conflict with an already registered device was detected.

Implements org.fourthline.cling.registry.Registry.

◆ addDevice() [3/3]

synchronized void org.fourthline.cling.registry.RegistryImpl.addDevice ( RemoteDevice remoteDevice )

Called internally by the UPnP discovery protocol.

Exceptions

RegistrationException If a conflict with an already registered device was detected.

Implements org.fourthline.cling.registry.Registry.

◆ addListener()

synchronized void org.fourthline.cling.registry.RegistryImpl.addListener ( RegistryListener listener )

Implements org.fourthline.cling.registry.Registry.

◆ addLocalSubscription()

synchronized void org.fourthline.cling.registry.RegistryImpl.addLocalSubscription ( LocalGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ addRemoteSubscription()

synchronized void org.fourthline.cling.registry.RegistryImpl.addRemoteSubscription ( RemoteGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ addResource() [1/2]

synchronized void org.fourthline.cling.registry.RegistryImpl.addResource ( Resource resource )

Stores an arbitrary resource in the registry.

Parameters

resource The resource to maintain indefinitely (until it is manually removed).

Implements org.fourthline.cling.registry.Registry.

Referenced by org.fourthline.cling.registry.RegistryImpl.addResource().

Here is the call graph for this function:

Here is the caller graph for this function:

◆ addResource() [2/2]

synchronized void org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ advertiseLocalDevices()

synchronized void org.fourthline.cling.registry.RegistryImpl.advertiseLocalDevices ( )

Manually trigger advertisement messages for all local devices.

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

Implements org.fourthline.cling.registry.Registry.

◆ getConfiguration()

UpnpServiceConfiguration org.fourthline.cling.registry.RegistryImpl.getConfiguration ( )

Implements org.fourthline.cling.registry.Registry.

◆ getDevice()

synchronized Device org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

Referenced by org.fourthline.cling.registry.RegistryImpl.getService(), and org.fourthline.cling.registry.RegistryImpl.removeDevice().

Here is the caller graph for this function:

◆ getDevices() [1/3]

synchronized Collection< Device<?, ?, ?> > org.fourthline.cling.registry.RegistryImpl.getDevices ( )

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

Implements org.fourthline.cling.registry.Registry.

◆ getDevices() [2/3]

synchronized Collection< Device<?, ?, ?> > org.fourthline.cling.registry.RegistryImpl.getDevices ( DeviceType deviceType )

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

Implements org.fourthline.cling.registry.Registry.

◆ getDevices() [3/3]

synchronized Collection< Device<?, ?, ?> > org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ getDiscoveryOptions()

synchronized DiscoveryOptions org.fourthline.cling.registry.RegistryImpl.getDiscoveryOptions ( UDN udn )

Get the currently active DiscoveryOptions for the given (local device) UDN.

Returns: null if there are no active discovery options for the given UDN.

Implements org.fourthline.cling.registry.Registry.

◆ getListeners()

synchronized Collection< RegistryListener > org.fourthline.cling.registry.RegistryImpl.getListeners ( )

Implements org.fourthline.cling.registry.Registry.

◆ getLocalDevice()

synchronized LocalDevice org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ getLocalDevices()

synchronized Collection< LocalDevice > org.fourthline.cling.registry.RegistryImpl.getLocalDevices ( )

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

Implements org.fourthline.cling.registry.Registry.

◆ getLocalSubscription()

synchronized LocalGENASubscription org.fourthline.cling.registry.RegistryImpl.getLocalSubscription ( String subscriptionId )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ getProtocolFactory()

ProtocolFactory org.fourthline.cling.registry.RegistryImpl.getProtocolFactory ( )

Implements org.fourthline.cling.registry.Registry.

◆ getRemoteDevice()

synchronized RemoteDevice org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

Referenced by org.fourthline.cling.registry.RegistryImpl.notifyDiscoveryStart().

Here is the caller graph for this function:

◆ getRemoteDevices()

synchronized Collection< RemoteDevice > org.fourthline.cling.registry.RegistryImpl.getRemoteDevices ( )

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

Implements org.fourthline.cling.registry.Registry.

◆ getRemoteSubscription()

synchronized RemoteGENASubscription org.fourthline.cling.registry.RegistryImpl.getRemoteSubscription ( String subscriptionId )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

Referenced by org.fourthline.cling.registry.RegistryImpl.getWaitRemoteSubscription().

Here is the caller graph for this function:

◆ getResource()

synchronized Resource org.fourthline.cling.registry.RegistryImpl.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.

Exceptions

IllegalArgumentException If the given URI was absolute, only path and query are allowed.

Implements org.fourthline.cling.registry.Registry.

◆ getResources()

synchronized Collection< Resource > org.fourthline.cling.registry.RegistryImpl.getResources ( )

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

Implements org.fourthline.cling.registry.Registry.

◆ getService()

synchronized Service org.fourthline.cling.registry.RegistryImpl.getService ( ServiceReference serviceReference )

Returns: Complete service metadata for a service reference or null if no service for the given reference has been registered.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ getUpnpService()

UpnpService org.fourthline.cling.registry.RegistryImpl.getUpnpService ( )

Implements org.fourthline.cling.registry.Registry.

◆ getWaitRemoteSubscription()

RemoteGENASubscription org.fourthline.cling.registry.RegistryImpl.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 the pending remote subscription procedures from the registry background maintainer to terminate, until the subscription has been found or until there are no more pending subscription procedures.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ isPaused()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.isPaused ( )

Returns: true if the registry has currently no running background maintenance (thread).

Implements org.fourthline.cling.registry.Registry.

◆ notifyDiscoveryFailure()

synchronized void org.fourthline.cling.registry.RegistryImpl.notifyDiscoveryFailure	(	final RemoteDevice	device,
		final Exception	ex
	)

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

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.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ notifyDiscoveryStart()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.notifyDiscoveryStart ( final 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 in the registry.

Parameters

device The half-hydrated (without services) metadata of the discovered device.

Returns: false if the device was already registered.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ pause()

synchronized void org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ registerPendingRemoteSubscription()

void org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ removeAllLocalDevices()

synchronized void org.fourthline.cling.registry.RegistryImpl.removeAllLocalDevices ( )

Clear the registry of all locally registered device metadata.

Implements org.fourthline.cling.registry.Registry.

◆ removeAllRemoteDevices()

synchronized void org.fourthline.cling.registry.RegistryImpl.removeAllRemoteDevices ( )

Clear the registry of all discovered remote device metadata.

Implements org.fourthline.cling.registry.Registry.

◆ removeDevice() [1/3]

synchronized boolean org.fourthline.cling.registry.RegistryImpl.removeDevice ( LocalDevice localDevice )

Call this to remove your local device metadata.

Returns: true if the device was registered and has been removed.

Implements org.fourthline.cling.registry.Registry.

Referenced by org.fourthline.cling.registry.RegistryImpl.removeDevice().

Here is the caller graph for this function:

◆ removeDevice() [2/3]

synchronized boolean org.fourthline.cling.registry.RegistryImpl.removeDevice ( RemoteDevice remoteDevice )

Called internally by the UPnP discovery protocol.

Implements org.fourthline.cling.registry.Registry.

◆ removeDevice() [3/3]

synchronized boolean org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ removeListener()

synchronized void org.fourthline.cling.registry.RegistryImpl.removeListener ( RegistryListener listener )

Implements org.fourthline.cling.registry.Registry.

◆ removeLocalSubscription()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.removeLocalSubscription ( LocalGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ removeRemoteSubscription()

synchronized void org.fourthline.cling.registry.RegistryImpl.removeRemoteSubscription ( RemoteGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ removeResource()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.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.

Implements org.fourthline.cling.registry.Registry.

◆ resume()

synchronized void org.fourthline.cling.registry.RegistryImpl.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 org.fourthline.cling.model.gena.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.

Implements org.fourthline.cling.registry.Registry.

Here is the call graph for this function:

◆ setDiscoveryOptions()

synchronized void org.fourthline.cling.registry.RegistryImpl.setDiscoveryOptions	(	UDN	udn,
		DiscoveryOptions	options
	)

Change the active DiscoveryOptions for the given (local device) UDN.

Parameters

options Set to null to disable any options.

Implements org.fourthline.cling.registry.Registry.

◆ shutdown()

synchronized void org.fourthline.cling.registry.RegistryImpl.shutdown ( )

Typically called internally when the UPnP stack is stopping.

Unsubscribe all local devices and GENA subscriptions.

Implements org.fourthline.cling.registry.Registry.

◆ unregisterPendingRemoteSubscription()

void org.fourthline.cling.registry.RegistryImpl.unregisterPendingRemoteSubscription ( RemoteGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Notify that the subscription procedure has terminated.

Implements org.fourthline.cling.registry.Registry.

◆ update()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.update ( RemoteDeviceIdentity rdIdentity )

Called internally by the UPnP discovery protocol.

Implements org.fourthline.cling.registry.Registry.

◆ updateLocalSubscription()

synchronized boolean org.fourthline.cling.registry.RegistryImpl.updateLocalSubscription ( LocalGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

◆ updateRemoteSubscription()

synchronized void org.fourthline.cling.registry.RegistryImpl.updateRemoteSubscription ( RemoteGENASubscription subscription )

Called internally by the UPnP stack, during GENA protocol execution.

Implements org.fourthline.cling.registry.Registry.

The documentation for this class was generated from the following file:

/github/workspace/yaacc/src/main/java/org/fourthline/cling/registry/RegistryImpl.java

Public Member Functions

Protected Member Functions

Protected Attributes

Detailed Description

Member Function Documentation

◆ addDevice() [1/3]

◆ addDevice() [2/3]

◆ addDevice() [3/3]

◆ addListener()

◆ addLocalSubscription()

◆ addRemoteSubscription()

◆ addResource() [1/2]

◆ addResource() [2/2]

◆ advertiseLocalDevices()

◆ getConfiguration()

◆ getDevice()

◆ getDevices() [1/3]

◆ getDevices() [2/3]

◆ getDevices() [3/3]

◆ getDiscoveryOptions()

◆ getListeners()

◆ getLocalDevice()

◆ getLocalDevices()

◆ getLocalSubscription()

◆ getProtocolFactory()

◆ getRemoteDevice()

◆ getRemoteDevices()

◆ getRemoteSubscription()

◆ getResource()

◆ getResources()

◆ getService()

◆ getUpnpService()

◆ getWaitRemoteSubscription()

◆ isPaused()

◆ notifyDiscoveryFailure()

◆ notifyDiscoveryStart()

◆ pause()

◆ registerPendingRemoteSubscription()

◆ removeAllLocalDevices()

◆ removeAllRemoteDevices()

◆ removeDevice() [1/3]

◆ removeDevice() [2/3]

◆ removeDevice() [3/3]

◆ removeListener()

◆ removeLocalSubscription()

◆ removeRemoteSubscription()

◆ removeResource()

◆ resume()

◆ setDiscoveryOptions()

◆ shutdown()

◆ unregisterPendingRemoteSubscription()

◆ update()

◆ updateLocalSubscription()

◆ updateRemoteSubscription()