org.fourthline.cling.transport

## Interface Router

- All Known Implementing Classes:
    AndroidRouter, MockRouter, RouterImpl

      public interface Router

  Interface of the network transport layer.

  Encapsulates the transport layer and provides methods to the upper layers for sending UPnP stream (HTTP) `StreamRequestMessage`s, sending (UDP) datagram `OutgoingDatagramMessage`s, as well as broadcasting bytes to all LAN participants.

  A router also maintains listening sockets and services, for incoming UDP unicast/multicast `IncomingDatagramMessage` and TCP `UpnpStream`s. An implementation of this interface handles these messages, e.g. by selecting and executing the right protocol.

  An implementation must be thread-safe, and can be accessed concurrently. If the Router is disabled, it doesn't listen on the network for incoming messages and does not send outgoing messages.

  Author:
    Christian Bauer
  See Also:
    `ProtocolFactory`

- - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `broadcast(byte[] bytes)` Call this method to broadcast a UDP message to all hosts on the network.
    `boolean` | `disable()` Unbinds all sockets and stops all listening threads for datagrams and streams.
    `boolean` | `enable()` Starts all sockets and listening threads for datagrams and streams.
    `List<NetworkAddress>` | `getActiveStreamServers(InetAddress preferredAddress)`
    `UpnpServiceConfiguration` | `getConfiguration()`
    `ProtocolFactory` | `getProtocolFactory()`
    `void` | `handleStartFailure(InitializationException ex)` Called by the `enable()` method before it returns.
    `boolean` | `isEnabled()`
    `void` | `received(IncomingDatagramMessage msg)` This method is called internally by the transport layer when a datagram, either unicast or multicast, has been received.
    `void` | `received(UpnpStream stream)` This method is called internally by the transport layer when a TCP stream connection has been made and a response has to be returned to the sender.
    `void` | `send(OutgoingDatagramMessage msg)` Call this method to send a UDP datagram message.
    `StreamResponseMessage` | `send(StreamRequestMessage msg)` Call this method to send a TCP (HTTP) stream message.
    `void` | `shutdown()` Disables the router and releases all other resources.

- - ### Method Detail

    - #### getConfiguration

          UpnpServiceConfiguration getConfiguration()

      Returns:
        The configuration used by this router.

    - #### getProtocolFactory

          ProtocolFactory getProtocolFactory()

      Returns:
        The protocol factory used by this router.

    - #### enable

          boolean enable()
                         throws RouterException

      Starts all sockets and listening threads for datagrams and streams.
      Returns:
        `true` if the router was enabled. `false` if it's already running.
      Throws:
        `RouterException`

    - #### disable

          boolean disable()
                          throws RouterException

      Unbinds all sockets and stops all listening threads for datagrams and streams.
      Returns:
        `true` if the router was disabled. `false` if it wasn't running.
      Throws:
        `RouterException`

    - #### shutdown

          void shutdown()
                        throws RouterException

      Disables the router and releases all other resources.
      Throws:
        `RouterException`

    - #### isEnabled

          boolean isEnabled()
                            throws RouterException

      Returns:
        `true` if the router is currently enabled.
      Throws:
        `RouterException`

    - #### handleStartFailure

          void handleStartFailure(InitializationException ex)
                                  throws InitializationException

      Called by the `enable()` method before it returns.
      Parameters:
        `ex` - The cause of the failure.
      Throws:
        `InitializationException` - if the exception was not recoverable.

    - #### getActiveStreamServers

          List<NetworkAddress> getActiveStreamServers(InetAddress preferredAddress)
                                                      throws RouterException

      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

          void received(IncomingDatagramMessage msg)

      This method is called internally by the transport layer when a datagram, either unicast or multicast, has been received. An implementation of this interface has to handle the received message, e.g. selecting and executing a UPnP protocol. This method should not block until the execution completes, the calling thread should be free to handle the next reception as soon as possible.

      Parameters:
        `msg` - The received datagram message.

    - #### received

          void received(UpnpStream stream)

      This method is called internally by the transport layer when a TCP stream connection has been made and a response has to be returned to the sender. An implementation of this interface has to handle the received stream connection and return a response, e.g. selecting and executing a UPnP protocol. This method should not block until the execution completes, the calling thread should be free to process the next reception as soon as possible. Typically this means starting a new thread of execution in this method.

      Parameters:
        `stream` -

    - #### send

          void send(OutgoingDatagramMessage msg)
                    throws RouterException

      Call this method to send a UDP datagram message.

      Parameters:
        `msg` - The UDP datagram message to send.
      Throws:
        `RouterException` - if a recoverable error, such as thread interruption, occurs.

    - #### send

          StreamResponseMessage send(StreamRequestMessage msg)
                                     throws RouterException

      Call this method to send a TCP (HTTP) stream message.

      Parameters:
        `msg` - The TCP (HTTP) stream message to send.
      Returns:
        The response received from the server.
      Throws:
        `RouterException` - if a recoverable error, such as thread interruption, occurs.

    - #### broadcast

          void broadcast(byte[] bytes)
                         throws RouterException

      Call this method to broadcast a UDP message to all hosts on the network.

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

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