org.teleal.cling.transport
Class SwitchableRouterImpl

java.lang.Object
  extended by org.teleal.cling.transport.SwitchableRouterImpl
All Implemented Interfaces:
Router, SwitchableRouter
Direct Known Subclasses:
AndroidWifiSwitchableRouter

public class SwitchableRouterImpl
extends Object
implements SwitchableRouter

Default implementation of switchable network message router.

This implementation is actually wrapping a regular RouterImpl, making it on/off switchable.

If the router can't be enabled (e.g. an exception occurs during socket binding), a warning log message will be printed. You can customize this behavior by overriding handleStartFailure(org.teleal.cling.transport.spi.InitializationException).

You have to expect that disable() and @{link #enable()} will throw a SwitchableRouterImpl.RouterLockAcquisitionException. We do not manually abort ongoing HTTP stream connections, they might block access to the underlying synchronized router instance when you try to disable/enable it. However, the only situation in which you should get this exception is when an the response from an HTTP server is taking longer than the timeout of this classes' lock acquisition routine, see getLockTimeoutMillis(). This might be the case if the response is large and/or the network connection is slow, but not slow enough to run into connection/data read timeouts.

Author:
Christian Bauer

Nested Class Summary
static class SwitchableRouterImpl.RouterLockAcquisitionException
           
 
Field Summary
protected  Lock readLock
           
protected  ReentrantReadWriteLock routerLock
           
protected  Lock writeLock
           
 
Constructor Summary
SwitchableRouterImpl(UpnpServiceConfiguration configuration, ProtocolFactory protocolFactory)
           
 
Method Summary
 void broadcast(byte[] bytes)
           Call this method to broadcast a UDP message to all hosts on the network.
 boolean disable()
           
 boolean enable()
           
 List<NetworkAddress> getActiveStreamServers(InetAddress preferredAddress)
           
 UpnpServiceConfiguration getConfiguration()
           
protected  int getLockTimeoutMillis()
           
 NetworkAddressFactory getNetworkAddressFactory()
           
 ProtocolFactory getProtocolFactory()
           
 void handleStartFailure(InitializationException ex)
          Called by the SwitchableRouter.enable() method before it returns.
 boolean isEnabled()
           
protected  void lock(Lock lock)
           
protected  void lock(Lock lock, int timeoutMilliseconds)
           
 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()
          Unbinds all sockets and stops all listening threads for datagrams and streams.
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

routerLock

protected ReentrantReadWriteLock routerLock

readLock

protected Lock readLock

writeLock

protected Lock writeLock
Constructor Detail

SwitchableRouterImpl

public SwitchableRouterImpl(UpnpServiceConfiguration configuration,
                            ProtocolFactory protocolFactory)
Method Detail

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.

isEnabled

public boolean isEnabled()
                  throws SwitchableRouterImpl.RouterLockAcquisitionException
Specified by:
isEnabled in interface SwitchableRouter
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

enable

public boolean enable()
               throws SwitchableRouterImpl.RouterLockAcquisitionException
Specified by:
enable in interface SwitchableRouter
Returns:
true if the router was enabled. false if it's already running.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

handleStartFailure

public void handleStartFailure(InitializationException ex)
Description copied from interface: SwitchableRouter
Called by the SwitchableRouter.enable() method before it returns.

Specified by:
handleStartFailure in interface SwitchableRouter
Parameters:
ex - The cause of the failure.

disable

public boolean disable()
                throws SwitchableRouterImpl.RouterLockAcquisitionException
Specified by:
disable in interface SwitchableRouter
Returns:
true if the router was disabled. false if it wasn't running.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

getNetworkAddressFactory

public NetworkAddressFactory getNetworkAddressFactory()
                                               throws SwitchableRouterImpl.RouterLockAcquisitionException
Specified by:
getNetworkAddressFactory in interface Router
Returns:
The network interface and address binding configuration of this router.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

getActiveStreamServers

public List<NetworkAddress> getActiveStreamServers(InetAddress preferredAddress)
                                            throws SwitchableRouterImpl.RouterLockAcquisitionException
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:
SwitchableRouterImpl.RouterLockAcquisitionException

shutdown

public void shutdown()
              throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router
Unbinds all sockets and stops all listening threads for datagrams and streams.

Specified by:
shutdown in interface Router
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

received

public void received(IncomingDatagramMessage msg)
              throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router

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.

Specified by:
received in interface Router
Parameters:
msg - The received datagram message.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

received

public void received(UpnpStream stream)
              throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router

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.

Specified by:
received in interface Router
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

send

public void send(OutgoingDatagramMessage msg)
          throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router

Call this method to send a UDP datagram message.

Specified by:
send in interface Router
Parameters:
msg - The UDP datagram message to send.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

send

public StreamResponseMessage send(StreamRequestMessage msg)
                           throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router

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

Specified by:
send in interface Router
Parameters:
msg - The TCP (HTTP) stream message to send.
Returns:
The response received from the server.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

broadcast

public void broadcast(byte[] bytes)
               throws SwitchableRouterImpl.RouterLockAcquisitionException
Description copied from interface: Router

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

Specified by:
broadcast in interface Router
Parameters:
bytes - The byte payload of the UDP datagram.
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

lock

protected void lock(Lock lock,
                    int timeoutMilliseconds)
             throws SwitchableRouterImpl.RouterLockAcquisitionException
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

lock

protected void lock(Lock lock)
             throws SwitchableRouterImpl.RouterLockAcquisitionException
Throws:
SwitchableRouterImpl.RouterLockAcquisitionException

unlock

protected void unlock(Lock lock)

getLockTimeoutMillis

protected int getLockTimeoutMillis()
Returns:
Defaults to 6 seconds, should be longer than the HTTP client request connection/data read timeouts. Should be longer than it takes the router to be started/shutdown.


Copyright © 2011 Teleal GmbH, Switzerland. All Rights Reserved.