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.spi;
17
18 import org.fourthline.cling.transport.Router;
19
20 import java.net.InetAddress;
21
22 /**
23 * Service for receiving TCP (HTTP) streams, one per bound IP address.
24 * <p>
25 * This service typically listens on a socket for TCP connections.
26 * <p>
27 * This listening loop is started with the <code>run()</code> method, this service is
28 * <code>Runnable</code>. Then {@link Router#received(UpnpStream)} is called with a custom
29 * {@link UpnpStream}. This will start processing of the request and <code>run()</code> the
30 * {@link UpnpStream} (which is also <code>Runnable</code>) in a separate thread,
31 * freeing up the receiving thread immediately.
32 * </p>
33 * <p>
34 * The {@link UpnpStream} then creates a {@link org.fourthline.cling.model.message.StreamRequestMessage}
35 * and calls the {@link UpnpStream#process(org.fourthline.cling.model.message.StreamRequestMessage)}
36 * method. The {@link UpnpStream} then returns the response to the network client.
37 * </p>
38 * <p>
39 * In pseudo-code:
40 * </p>
41 * <pre>
42 * MyStreamServer implements StreamServer {
43 * run() {
44 * while (not stopped) {
45 * Connection con = listenToSocketAndBlock();
46 * router.received( new MyUpnpStream(con) );
47 * }
48 * }
49 * }
50 *
51 * MyUpnpStream(con) extends UpnpStream {
52 * run() {
53 * try {
54 * StreamRequestMessage request = // ... Read request
55 * StreamResponseMessage response = process(request);
56 * // ... Send response
57 * responseSent(response))
58 * } catch (Exception ex) {
59 * responseException(ex);
60 * }
61 * }
62 * }
63 * </pre>
64 * <p>
65 * An implementation has to be thread-safe.
66 * </p>
67 *
68 * @param <C> The type of the service's configuration.
69 *
70 * @author Christian Bauer
71 */
72 public interface StreamServer<C extends StreamServerConfiguration> extends Runnable {
73
74 /**
75 * Configures the service and starts any listening sockets.
76 *
77 * @param bindAddress The address to bind any sockets on.
78 * @param router The router which handles the incoming {@link org.fourthline.cling.transport.spi.UpnpStream}.
79 * @throws InitializationException If the service could not be initialized or started.
80 */
81 public void init(InetAddress bindAddress, Router router) throws InitializationException;
82
83 /**
84 * This method will be called potentially right after
85 * {@link #init(java.net.InetAddress, org.fourthline.cling.transport.Router)}, the
86 * actual assigned local port must be available before the server is started.
87 *
88 * @return The TCP port this service is listening on, e.g. the actual ephemeral port.
89 */
90 public int getPort();
91
92 /**
93 * Stops the service, closes any listening sockets.
94 */
95 public void stop();
96
97 /**
98 * @return This service's configuration.
99 */
100 public C getConfiguration();
101
102 }