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) StreamRequestMessages, sending (UDP) datagram OutgoingDatagramMessages, 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 UpnpStreams. 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

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.