1 /*
2 * Copyright (C) 2013 4th Line GmbH, Switzerland
3 *
4 * The contents of this file are subject to the terms of either the GNU
5 * Lesser General Public License Version 2 or later ("LGPL") or the
6 * Common Development and Distribution License Version 1 or later
7 * ("CDDL") (collectively, the "License"). You may not use this file
8 * except in compliance with the License. See LICENSE.txt for more
9 * information.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
14 */
15
16 package org.fourthline.cling.transport;
17
18 import org.fourthline.cling.UpnpServiceConfiguration;
19 import org.fourthline.cling.model.NetworkAddress;
20 import org.fourthline.cling.model.message.IncomingDatagramMessage;
21 import org.fourthline.cling.model.message.OutgoingDatagramMessage;
22 import org.fourthline.cling.model.message.StreamRequestMessage;
23 import org.fourthline.cling.model.message.StreamResponseMessage;
24 import org.fourthline.cling.protocol.ProtocolFactory;
25 import org.fourthline.cling.transport.spi.InitializationException;
26 import org.fourthline.cling.transport.spi.UpnpStream;
27
28 import java.net.InetAddress;
29 import java.util.List;
30
31 /**
32 * Interface of the network transport layer.
33 * <p>
34 * Encapsulates the transport layer and provides methods to the upper layers for
35 * sending UPnP stream (HTTP) {@link org.fourthline.cling.model.message.StreamRequestMessage}s,
36 * sending (UDP) datagram {@link org.fourthline.cling.model.message.OutgoingDatagramMessage}s,
37 * as well as broadcasting bytes to all LAN participants.
38 * </p>
39 * <p>
40 * A router also maintains listening sockets and services, for incoming UDP unicast/multicast
41 * {@link org.fourthline.cling.model.message.IncomingDatagramMessage} and TCP
42 * {@link org.fourthline.cling.transport.spi.UpnpStream}s. An implementation of this interface
43 * handles these messages, e.g. by selecting and executing the right protocol.
44 * </p>
45 * <p>
46 * An implementation must be thread-safe, and can be accessed concurrently. If the Router is
47 * disabled, it doesn't listen on the network for incoming messages and does not send outgoing
48 * messages.
49 * </p>
50 *
51 * @see org.fourthline.cling.protocol.ProtocolFactory
52 *
53 * @author Christian Bauer
54 */
55 public interface Router {
56
57 /**
58 * @return The configuration used by this router.
59 */
60 public UpnpServiceConfiguration getConfiguration();
61
62 /**
63 * @return The protocol factory used by this router.
64 */
65 public ProtocolFactory getProtocolFactory();
66
67 /**
68 * Starts all sockets and listening threads for datagrams and streams.
69 *
70 * @return <code>true</code> if the router was enabled. <code>false</code> if it's already running.
71 */
72 boolean enable() throws RouterException;
73
74 /**
75 * Unbinds all sockets and stops all listening threads for datagrams and streams.
76 *
77 * @return <code>true</code> if the router was disabled. <code>false</code> if it wasn't running.
78 */
79 boolean disable() throws RouterException;
80
81 /**
82 * Disables the router and releases all other resources.
83 */
84 void shutdown() throws RouterException ;
85
86 /**
87 *
88 * @return <code>true</code> if the router is currently enabled.
89 */
90 boolean isEnabled() throws RouterException;
91
92 /**
93 * Called by the {@link #enable()} method before it returns.
94 *
95 * @param ex The cause of the failure.
96 * @throws InitializationException if the exception was not recoverable.
97 */
98 void handleStartFailure(InitializationException ex) throws InitializationException;
99
100 /**
101 * @param preferredAddress A preferred stream server bound address or <code>null</code>.
102 * @return An empty list if no stream server is currently active, otherwise a single network
103 * address if the preferred address is active, or a list of all active bound
104 * stream servers.
105 */
106 public List<NetworkAddress> getActiveStreamServers(InetAddress preferredAddress) throws RouterException;
107
108 /**
109 * <p>
110 * This method is called internally by the transport layer when a datagram, either unicast or
111 * multicast, has been received. An implementation of this interface has to handle the received
112 * message, e.g. selecting and executing a UPnP protocol. This method should not block until
113 * the execution completes, the calling thread should be free to handle the next reception as
114 * soon as possible.
115 * </p>
116 * @param msg The received datagram message.
117 */
118 public void received(IncomingDatagramMessage msg);
119
120 /**
121 * <p>
122 * This method is called internally by the transport layer when a TCP stream connection has
123 * been made and a response has to be returned to the sender. An implementation of this interface
124 * has to handle the received stream connection and return a response, e.g. selecting and executing
125 * a UPnP protocol. This method should not block until the execution completes, the calling thread
126 * should be free to process the next reception as soon as possible. Typically this means starting
127 * a new thread of execution in this method.
128 * </p>
129 * @param stream
130 */
131 public void received(UpnpStream stream);
132
133 /**
134 * <p>
135 * Call this method to send a UDP datagram message.
136 * </p>
137 * @param msg The UDP datagram message to send.
138 * @throws RouterException if a recoverable error, such as thread interruption, occurs.
139 */
140 public void send(OutgoingDatagramMessage msg) throws RouterException;
141
142 /**
143 * <p>
144 * Call this method to send a TCP (HTTP) stream message.
145 * </p>
146 * @param msg The TCP (HTTP) stream message to send.
147 * @return The response received from the server.
148 * @throws RouterException if a recoverable error, such as thread interruption, occurs.
149 */
150 public StreamResponseMessage send(StreamRequestMessage msg) throws RouterException;
151
152 /**
153 * <p>
154 * Call this method to broadcast a UDP message to all hosts on the network.
155 * </p>
156 * @param bytes The byte payload of the UDP datagram.
157 * @throws RouterException if a recoverable error, such as thread interruption, occurs.
158 */
159 public void broadcast(byte[] bytes) throws RouterException;
160
161 }