Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## org.teleal.cling.transport
Class SwitchableRouterImpl

    java.lang.Object
      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.

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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