org.fourthline.cling

## Class DefaultUpnpServiceConfiguration

- java.lang.Object
- - org.fourthline.cling.DefaultUpnpServiceConfiguration

- All Implemented Interfaces:
    UpnpServiceConfiguration
  Direct Known Subclasses:
    AndroidUpnpServiceConfiguration, MockUpnpServiceConfiguration

      @Alternative
      public class DefaultUpnpServiceConfiguration
      extends Object
      implements UpnpServiceConfiguration

  Default configuration data of a typical UPnP stack.

  This configuration utilizes the default network transport implementation found in `org.fourthline.cling.transport.impl`.

  This configuration utilizes the DOM default descriptor binders found in `org.fourthline.cling.binding.xml`.

  The thread `Executor` is an `Executors.newCachedThreadPool()` with a custom `DefaultUpnpServiceConfiguration.ClingThreadFactory` (it only sets a thread name).

  Note that this pool is effectively unlimited, so the number of threads will grow (and shrink) as needed - or restricted by your JVM.

  The default `Namespace` is configured without any base path or prefix.

  Author:
    Christian Bauer

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Class and Description
    --- | ---
    `static class` | `DefaultUpnpServiceConfiguration.ClingExecutor`
    `static class` | `DefaultUpnpServiceConfiguration.ClingThreadFactory`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `` | `DefaultUpnpServiceConfiguration()` Defaults to port '0', ephemeral.
    `protected` | `DefaultUpnpServiceConfiguration(boolean checkRuntime)`
    `` | `DefaultUpnpServiceConfiguration(int streamListenPort)`
    `protected` | `DefaultUpnpServiceConfiguration(int streamListenPort, boolean checkRuntime)`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `DatagramIO` | `createDatagramIO(NetworkAddressFactory networkAddressFactory)`
    `protected DatagramProcessor` | `createDatagramProcessor()`
    `protected ExecutorService` | `createDefaultExecutorService()`
    `protected DeviceDescriptorBinder` | `createDeviceDescriptorBinderUDA10()`
    `protected GENAEventProcessor` | `createGENAEventProcessor()`
    `MulticastReceiver` | `createMulticastReceiver(NetworkAddressFactory networkAddressFactory)`
    `protected Namespace` | `createNamespace()`
    `NetworkAddressFactory` | `createNetworkAddressFactory()`
    `protected NetworkAddressFactory` | `createNetworkAddressFactory(int streamListenPort)`
    `protected ServiceDescriptorBinder` | `createServiceDescriptorBinderUDA10()`
    `protected SOAPActionProcessor` | `createSOAPActionProcessor()`
    `StreamClient` | `createStreamClient()`
    `StreamServer` | `createStreamServer(NetworkAddressFactory networkAddressFactory)`
    `int` | `getAliveIntervalMillis()` Optional setting for flooding alive NOTIFY messages for local devices.
    `Executor` | `getAsyncProtocolExecutor()`
    `Executor` | `getDatagramIOExecutor()`
    `DatagramProcessor` | `getDatagramProcessor()`
    `protected ExecutorService` | `getDefaultExecutorService()`
    `UpnpHeaders` | `getDescriptorRetrievalHeaders(RemoteDeviceIdentity identity)` Optional extra headers for device descriptor retrieval HTTP requests.
    `DeviceDescriptorBinder` | `getDeviceDescriptorBinderUDA10()`
    `UpnpHeaders` | `getEventSubscriptionHeaders(RemoteService service)` Optional extra headers for event subscription (almost HTTP) messages.
    `ServiceType[]` | `getExclusiveServiceTypes()` Returns service types that can be handled by this UPnP stack, all others will be ignored.
    `GENAEventProcessor` | `getGenaEventProcessor()`
    `Executor` | `getMulticastReceiverExecutor()`
    `Namespace` | `getNamespace()`
    `Executor` | `getRegistryListenerExecutor()`
    `Executor` | `getRegistryMaintainerExecutor()`
    `int` | `getRegistryMaintenanceIntervalMillis()`
    `Integer` | `getRemoteDeviceMaxAgeSeconds()` Returns the time in seconds a remote device will be registered until it is expired.
    `ServiceDescriptorBinder` | `getServiceDescriptorBinderUDA10()`
    `SOAPActionProcessor` | `getSoapActionProcessor()`
    `ExecutorService` | `getStreamServerExecutorService()`
    `ExecutorService` | `getSyncProtocolExecutorService()`
    `boolean` | `isReceivedSubscriptionTimeoutIgnored()` Ignore the received event subscription timeout from remote control points.
    `void` | `shutdown()` Called by the `UpnpService` on shutdown, useful to e.g.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### DefaultUpnpServiceConfiguration

          public DefaultUpnpServiceConfiguration()

      Defaults to port '0', ephemeral.

    - #### DefaultUpnpServiceConfiguration

          public DefaultUpnpServiceConfiguration(int streamListenPort)

    - #### DefaultUpnpServiceConfiguration

          protected DefaultUpnpServiceConfiguration(boolean checkRuntime)

    - #### DefaultUpnpServiceConfiguration

          protected DefaultUpnpServiceConfiguration(int streamListenPort,
                                         boolean checkRuntime)

  - ### Method Detail

    - #### getDatagramProcessor

          public DatagramProcessor getDatagramProcessor()

      Specified by:
        `getDatagramProcessor` in interface `UpnpServiceConfiguration`
      Returns:
        The shared implementation of `DatagramProcessor`.

    - #### getSoapActionProcessor

          public SOAPActionProcessor getSoapActionProcessor()

      Specified by:
        `getSoapActionProcessor` in interface `UpnpServiceConfiguration`
      Returns:
        The shared implementation of `SOAPActionProcessor`.

    - #### getGenaEventProcessor

          public GENAEventProcessor getGenaEventProcessor()

      Specified by:
        `getGenaEventProcessor` in interface `UpnpServiceConfiguration`
      Returns:
        The shared implementation of `GENAEventProcessor`.

    - #### createStreamClient

          public StreamClient createStreamClient()

      Specified by:
        `createStreamClient` in interface `UpnpServiceConfiguration`
      Returns:
        A new instance of the `StreamClient` interface.

    - #### createMulticastReceiver

          public MulticastReceiver createMulticastReceiver(NetworkAddressFactory networkAddressFactory)

      Specified by:
        `createMulticastReceiver` in interface `UpnpServiceConfiguration`
      Parameters:
        `networkAddressFactory` - The configured `NetworkAddressFactory`.
      Returns:
        A new instance of the `MulticastReceiver` interface.

    - #### createDatagramIO

          public DatagramIO createDatagramIO(NetworkAddressFactory networkAddressFactory)

      Specified by:
        `createDatagramIO` in interface `UpnpServiceConfiguration`
      Parameters:
        `networkAddressFactory` - The configured `NetworkAddressFactory`.
      Returns:
        A new instance of the `DatagramIO` interface.

    - #### createStreamServer

          public StreamServer createStreamServer(NetworkAddressFactory networkAddressFactory)

      Specified by:
        `createStreamServer` in interface `UpnpServiceConfiguration`
      Parameters:
        `networkAddressFactory` - The configured `NetworkAddressFactory`.
      Returns:
        A new instance of the `StreamServer` interface.

    - #### getMulticastReceiverExecutor

          public Executor getMulticastReceiverExecutor()

      Specified by:
        `getMulticastReceiverExecutor` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the listening background threads for multicast datagrams.

    - #### getDatagramIOExecutor

          public Executor getDatagramIOExecutor()

      Specified by:
        `getDatagramIOExecutor` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the listening background threads for unicast datagrams.

    - #### getStreamServerExecutorService

          public ExecutorService getStreamServerExecutorService()

      Specified by:
        `getStreamServerExecutorService` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the listening background threads for HTTP requests.

    - #### getDeviceDescriptorBinderUDA10

          public DeviceDescriptorBinder getDeviceDescriptorBinderUDA10()

      Specified by:
        `getDeviceDescriptorBinderUDA10` in interface `UpnpServiceConfiguration`
      Returns:
        The shared implementation of `DeviceDescriptorBinder` for the UPnP 1.0 Device Architecture..

    - #### getServiceDescriptorBinderUDA10

          public ServiceDescriptorBinder getServiceDescriptorBinderUDA10()

      Specified by:
        `getServiceDescriptorBinderUDA10` in interface `UpnpServiceConfiguration`
      Returns:
        The shared implementation of `ServiceDescriptorBinder` for the UPnP 1.0 Device Architecture..

    - #### getExclusiveServiceTypes

          public ServiceType[] getExclusiveServiceTypes()

      Description copied from interface: `UpnpServiceConfiguration`
      Returns service types that can be handled by this UPnP stack, all others will be ignored.

      Return `null` to completely disable remote device and service discovery. All incoming notifications and search responses will then be dropped immediately. This is mostly useful in applications that only provide services with no (remote) control point functionality.

      Note that a discovered service type with version 2 or 3 will match an exclusive service type with version 1. UPnP services are required to be backwards compatible, version 2 is a superset of version 1, and version 3 is a superset of version 2, etc.

      Specified by:
        `getExclusiveServiceTypes` in interface `UpnpServiceConfiguration`
      Returns:
        An array of service types that are exclusively discovered, no other service will be discovered. A `null` return value will disable discovery! An empty array means all services will be discovered.

    - #### isReceivedSubscriptionTimeoutIgnored

          public boolean isReceivedSubscriptionTimeoutIgnored()

      Description copied from interface: `UpnpServiceConfiguration`
      Ignore the received event subscription timeout from remote control points.

      Some control points have trouble renewing subscriptions properly; enabling this option in conjunction with a high value for `UserConstants.DEFAULT_SUBSCRIPTION_DURATION_SECONDS` ensures that your devices will not disappear on such control points.

      Specified by:
        `isReceivedSubscriptionTimeoutIgnored` in interface `UpnpServiceConfiguration`
      Returns:
        Defaults to `false`.

    - #### getDescriptorRetrievalHeaders

          public UpnpHeaders getDescriptorRetrievalHeaders(RemoteDeviceIdentity identity)

      Description copied from interface: `UpnpServiceConfiguration`
      Optional extra headers for device descriptor retrieval HTTP requests.

      Some devices might require extra headers to recognize your control point, use this method to set these headers. They will be used for every descriptor (XML) retrieval HTTP request by Cling. See `ClientInfo` for action request messages.

      Specified by:
        `getDescriptorRetrievalHeaders` in interface `UpnpServiceConfiguration`
      Parameters:
        `identity` - The (so far) discovered identity of the remote device.
      Returns:
        `null` or extra HTTP headers.

    - #### getEventSubscriptionHeaders

          public UpnpHeaders getEventSubscriptionHeaders(RemoteService service)

      Description copied from interface: `UpnpServiceConfiguration`
      Optional extra headers for event subscription (almost HTTP) messages.

      Some devices might require extra headers to recognize your control point, use this method to set these headers for GENA subscriptions. Note that the headers will not be applied to actual event messages, only subscribe, unsubscribe, and renewal.

      Specified by:
        `getEventSubscriptionHeaders` in interface `UpnpServiceConfiguration`
      Returns:
        `null` or extra HTTP headers.

    - #### getRegistryMaintenanceIntervalMillis

          public int getRegistryMaintenanceIntervalMillis()

      Specified by:
        `getRegistryMaintenanceIntervalMillis` in interface `UpnpServiceConfiguration`
      Returns:
        Defaults to 1000 milliseconds.

    - #### getAliveIntervalMillis

          public int getAliveIntervalMillis()

      Description copied from interface: `UpnpServiceConfiguration`
      Optional setting for flooding alive NOTIFY messages for local devices.

      Use this to advertise local devices at the specified interval, independent of its `DeviceIdentity.maxAgeSeconds` value. Note that this will increase network traffic.

      Some control points (XBMC and other Platinum UPnP SDK based devices, OPPO-93) seem to not properly receive SSDP M-SEARCH replies sent by Cling, but will handle NOTIFY alive messages just fine.

      Specified by:
        `getAliveIntervalMillis` in interface `UpnpServiceConfiguration`
      Returns:
        Defaults to zero, disabling ALIVE flooding.

    - #### getRemoteDeviceMaxAgeSeconds

          public Integer getRemoteDeviceMaxAgeSeconds()

      Description copied from interface: `UpnpServiceConfiguration`
      Returns the time in seconds a remote device will be registered until it is expired.

      This setting is useful on systems which do not support multicast networking (Android on HTC phones, for example). On such a system you will not receive messages when a remote device disappears from the network and you will not receive its periodic heartbeat alive messages. Only an initial search response (UDP unicast) has been received from the remote device, with its proposed maximum age. To avoid (early) expiration of the remote device, you can override its maxium age with this configuration setting, ignoring the initial maximum age sent by the device. You most likely want to return `0` in this case, so that the remote device is never expired unless you manually remove it from the `Registry`. You typically remove the device when an action or GENA subscription request to the remote device failed.

      Specified by:
        `getRemoteDeviceMaxAgeSeconds` in interface `UpnpServiceConfiguration`
      Returns:
        `null` (the default) to accept the remote device's proposed maximum age, or `0` for unlimited age, or a value in seconds.

    - #### getAsyncProtocolExecutor

          public Executor getAsyncProtocolExecutor()

      Specified by:
        `getAsyncProtocolExecutor` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the processing of asynchronous aspects of the UPnP stack (discovery).

    - #### getSyncProtocolExecutorService

          public ExecutorService getSyncProtocolExecutorService()

      Specified by:
        `getSyncProtocolExecutorService` in interface `UpnpServiceConfiguration`
      Returns:
        The executor service which runs the processing of synchronous aspects of the UPnP stack (description, control, GENA).

    - #### getNamespace

          public Namespace getNamespace()

      Specified by:
        `getNamespace` in interface `UpnpServiceConfiguration`
      Returns:
        An instance of `Namespace` for this UPnP stack.

    - #### getRegistryMaintainerExecutor

          public Executor getRegistryMaintainerExecutor()

      Specified by:
        `getRegistryMaintainerExecutor` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the background thread for maintaining the registry.

    - #### getRegistryListenerExecutor

          public Executor getRegistryListenerExecutor()

      Specified by:
        `getRegistryListenerExecutor` in interface `UpnpServiceConfiguration`
      Returns:
        The executor which runs the notification threads of registry listeners.

    - #### createNetworkAddressFactory

          public NetworkAddressFactory createNetworkAddressFactory()

      Specified by:
        `createNetworkAddressFactory` in interface `UpnpServiceConfiguration`
      Returns:
        A new instance of the `NetworkAddressFactory` interface.

    - #### shutdown

          public void shutdown()

      Description copied from interface: `UpnpServiceConfiguration`
      Called by the `UpnpService` on shutdown, useful to e.g. shutdown thread pools.
      Specified by:
        `shutdown` in interface `UpnpServiceConfiguration`

    - #### createNetworkAddressFactory

          protected NetworkAddressFactory createNetworkAddressFactory(int streamListenPort)

    - #### createDatagramProcessor

          protected DatagramProcessor createDatagramProcessor()

    - #### createSOAPActionProcessor

          protected SOAPActionProcessor createSOAPActionProcessor()

    - #### createGENAEventProcessor

          protected GENAEventProcessor createGENAEventProcessor()

    - #### createDeviceDescriptorBinderUDA10

          protected DeviceDescriptorBinder createDeviceDescriptorBinderUDA10()

    - #### createServiceDescriptorBinderUDA10

          protected ServiceDescriptorBinder createServiceDescriptorBinderUDA10()

    - #### createNamespace

          protected Namespace createNamespace()

    - #### getDefaultExecutorService

          protected ExecutorService getDefaultExecutorService()

    - #### createDefaultExecutorService

          protected ExecutorService createDefaultExecutorService()

Copyright © 2014 4th Line GmbH, Switzerland. All Rights Reserved.