org.fourthline.cling.transport

## Class RouterImpl

- java.lang.Object
- - org.fourthline.cling.transport.RouterImpl

- All Implemented Interfaces:
    Router
  Direct Known Subclasses:
    AndroidRouter

      @ApplicationScoped
      public class RouterImpl
      extends Object
      implements Router

  Default implementation of network message router.

  Initializes and starts listening for data on the network when enabled.

  Author:
    Christian Bauer

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected UpnpServiceConfiguration` | `configuration`
    `protected Map<InetAddress,DatagramIO>` | `datagramIOs`
    `protected boolean` | `enabled`
    `protected Map<NetworkInterface,MulticastReceiver>` | `multicastReceivers`
    `protected NetworkAddressFactory` | `networkAddressFactory`
    `protected ProtocolFactory` | `protocolFactory`
    `protected Lock` | `readLock`
    `protected ReentrantReadWriteLock` | `routerLock`
    `protected StreamClient` | `streamClient`
    `protected Map<InetAddress,StreamServer>` | `streamServers`
    `protected Lock` | `writeLock`

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `RouterImpl()`
    `` | `RouterImpl(UpnpServiceConfiguration configuration, ProtocolFactory protocolFactory)`

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `broadcast(byte[] bytes)` Sends the given bytes as a broadcast on all bound `DatagramIO`s, using source port 9.
    `boolean` | `disable()` Unbinds all sockets and stops all listening threads for datagrams and streams.
    `boolean` | `disable(DisableRouter event)`
    `boolean` | `enable()` Initializes listening services: First an instance of `MulticastReceiver` is bound to each network interface.
    `boolean` | `enable(EnableRouter event)`
    `List<NetworkAddress>` | `getActiveStreamServers(InetAddress preferredAddress)`
    `UpnpServiceConfiguration` | `getConfiguration()`
    `protected int` | `getLockTimeoutMillis()`
    `ProtocolFactory` | `getProtocolFactory()`
    `void` | `handleStartFailure(InitializationException ex)` Called by the `Router.enable()` method before it returns.
    `boolean` | `isEnabled()`
    `protected void` | `lock(Lock lock)`
    `protected void` | `lock(Lock lock, int timeoutMilliseconds)`
    `void` | `received(IncomingDatagramMessage msg)` Obtains the asynchronous protocol `Executor` and runs the protocol created by the `ProtocolFactory` for the given message.
    `void` | `received(UpnpStream stream)` Obtains the synchronous protocol `Executor` and runs the `UpnpStream` directly.
    `void` | `send(OutgoingDatagramMessage msg)` Sends the UDP datagram on all bound `DatagramIO`s.
    `StreamResponseMessage` | `send(StreamRequestMessage msg)` Sends the TCP stream request with the `StreamClient`.
    `void` | `shutdown()` Disables the router and releases all other resources.
    `protected void` | `startAddressBasedTransports(Iterator<InetAddress> addresses)`
    `protected void` | `startInterfaceBasedTransports(Iterator<NetworkInterface> interfaces)`
    `protected void` | `unlock(Lock lock)`

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

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

- - ### Field Detail

    - #### configuration

          protected UpnpServiceConfiguration configuration

    - #### protocolFactory

          protected ProtocolFactory protocolFactory

    - #### enabled

          protected volatile boolean enabled

    - #### routerLock

          protected ReentrantReadWriteLock routerLock

    - #### readLock

          protected Lock readLock

    - #### writeLock

          protected Lock writeLock

    - #### networkAddressFactory

          protected NetworkAddressFactory networkAddressFactory

    - #### streamClient

          protected StreamClient streamClient

    - #### multicastReceivers

          protected final Map<NetworkInterface,MulticastReceiver> multicastReceivers

    - #### datagramIOs

          protected final Map<InetAddress,DatagramIO> datagramIOs

    - #### streamServers

          protected final Map<InetAddress,StreamServer> streamServers

  - ### Constructor Detail

    - #### RouterImpl

          protected RouterImpl()

    - #### RouterImpl

          @Inject
          public RouterImpl(UpnpServiceConfiguration configuration,
                                    ProtocolFactory protocolFactory)

      Parameters:
        `configuration` - The configuration used by this router.
        `protocolFactory` - The protocol factory used by this router.

  - ### Method Detail

    - #### enable

          public boolean enable(@Observes @Default
                                EnableRouter event)
                         throws RouterException

      Throws:
        `RouterException`

    - #### disable

          public boolean disable(@Observes @Default
                                 DisableRouter event)
                          throws RouterException

      Throws:
        `RouterException`

    - #### getConfiguration

          public UpnpServiceConfiguration getConfiguration()

      Specified by:
        `getConfiguration` in interface `Router`
      Returns:
        The configuration used by this router.

    - #### getProtocolFactory

          public ProtocolFactory getProtocolFactory()

      Specified by:
        `getProtocolFactory` in interface `Router`
      Returns:
        The protocol factory used by this router.

    - #### enable

          public boolean enable()
                         throws RouterException

      Initializes listening services: First an instance of `MulticastReceiver` is bound to each network interface. Then an instance of `DatagramIO` and `StreamServer` is bound to each bind address returned by the network address factory, respectively. There is only one instance of `StreamClient` created and managed by this router.
      Specified by:
        `enable` in interface `Router`
      Returns:
        `true` if the router was enabled. `false` if it's already running.
      Throws:
        `RouterException`

    - #### disable

          public boolean disable()
                          throws RouterException

      Description copied from interface: `Router`
      Unbinds all sockets and stops all listening threads for datagrams and streams.
      Specified by:
        `disable` in interface `Router`
      Returns:
        `true` if the router was disabled. `false` if it wasn't running.
      Throws:
        `RouterException`

    - #### shutdown

          public void shutdown()
                        throws RouterException

      Description copied from interface: `Router`
      Disables the router and releases all other resources.
      Specified by:
        `shutdown` in interface `Router`
      Throws:
        `RouterException`

    - #### isEnabled

          public boolean isEnabled()

      Specified by:
        `isEnabled` in interface `Router`
      Returns:
        `true` if the router is currently enabled.

    - #### handleStartFailure

          public void handleStartFailure(InitializationException ex)
                                  throws InitializationException

      Description copied from interface: `Router`
      Called by the `Router.enable()` method before it returns.
      Specified by:
        `handleStartFailure` in interface `Router`
      Parameters:
        `ex` - The cause of the failure.
      Throws:
        `InitializationException` - if the exception was not recoverable.

    - #### getActiveStreamServers

          public List<NetworkAddress> getActiveStreamServers(InetAddress preferredAddress)
                                                      throws RouterException

      Specified by:
        `getActiveStreamServers` in interface `Router`
      Parameters:
        `preferredAddress` - A preferred stream server bound address or `null`.
      Returns:
        An empty list if no stream server is currently active, otherwise a single network address if the preferred address is active, or a list of all active bound stream servers.
      Throws:
        `RouterException`

    - #### received

          public void received(IncomingDatagramMessage msg)

      Obtains the asynchronous protocol `Executor` and runs the protocol created by the `ProtocolFactory` for the given message.

      If the factory doesn't create a protocol, the message is dropped immediately without creating another thread or consuming further resources. This means we can filter the datagrams in the protocol factory and e.g. completely disable discovery or only allow notification message from some known services we'd like to work with.

      Specified by:
        `received` in interface `Router`
      Parameters:
        `msg` - The received datagram message.

    - #### received

          public void received(UpnpStream stream)

      Obtains the synchronous protocol `Executor` and runs the `UpnpStream` directly.
      Specified by:
        `received` in interface `Router`
      Parameters:
        `stream` - The received `UpnpStream`.

    - #### send

          public void send(OutgoingDatagramMessage msg)
                    throws RouterException

      Sends the UDP datagram on all bound `DatagramIO`s.
      Specified by:
        `send` in interface `Router`
      Parameters:
        `msg` - The UDP datagram message to send.
      Throws:
        `RouterException` - if a recoverable error, such as thread interruption, occurs.

    - #### send

          public StreamResponseMessage send(StreamRequestMessage msg)
                                     throws RouterException

      Sends the TCP stream request with the `StreamClient`.
      Specified by:
        `send` in interface `Router`
      Parameters:
        `msg` - The TCP (HTTP) stream message to send.
      Returns:
        The return value of the `StreamClient.sendRequest(StreamRequestMessage)` method or `null` if no `StreamClient` is available.
      Throws:
        `RouterException` - if a recoverable error, such as thread interruption, occurs.

    - #### broadcast

          public void broadcast(byte[] bytes)
                         throws RouterException

      Sends the given bytes as a broadcast on all bound `DatagramIO`s, using source port 9.

      TODO: Support source port parameter

      Specified by:
        `broadcast` in interface `Router`
      Parameters:
        `bytes` - The byte payload of the UDP datagram.
      Throws:
        `RouterException` - if a recoverable error, such as thread interruption, occurs.

    - #### startInterfaceBasedTransports

          protected void startInterfaceBasedTransports(Iterator<NetworkInterface> interfaces)
                                                throws InitializationException

      Throws:
        `InitializationException`

    - #### startAddressBasedTransports

          protected void startAddressBasedTransports(Iterator<InetAddress> addresses)
                                              throws InitializationException

      Throws:
        `InitializationException`

    - #### lock

          protected void lock(Lock lock,
                              int timeoutMilliseconds)
                       throws RouterException

      Throws:
        `RouterException`

    - #### lock

          protected void lock(Lock lock)
                       throws RouterException

      Throws:
        `RouterException`

    - #### unlock

          protected void unlock(Lock lock)

    - #### getLockTimeoutMillis

          protected int getLockTimeoutMillis()

      Returns:
        Defaults to 6 seconds, should be longer than it takes the router to be enabled/disabled.

Copyright © 2016 4th Line GmbH, Switzerland. All rights reserved.