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 javax.servlet.Servlet;
19 import java.io.IOException;
20 import java.util.concurrent.ExecutorService;
21
22 /**
23 * Implement this to provide your own servlet container (instance),
24 * <p>
25 * It's OK if you don't start or stop your container when this adapter is
26 * called. You can treat the {@link #startIfNotRunning()} and
27 * {@link #stopIfRunning()} methods as suggestions, they only indicate what
28 * the UPnP stack wants to do. If your servlet container handles other
29 * services, keep it running all the time.
30 * </p>
31 * <p>
32 * An implementation must be thread-safe, all methods might be called concurrently
33 * by several threads.
34 * </p>
35 *
36 * @author Christian Bauer
37 */
38 public interface ServletContainerAdapter {
39
40 /**
41 * Might be called several times to integrate the servlet container with Cling's executor
42 * configuration. You can ignore this call if you want to configure the container's thread
43 * pooling independently from Cling. If you use the given Cling <code>ExecutorService</code>,
44 * make sure the Jetty container won't shut it down when {@link #stopIfRunning()} is called!
45 *
46 * @param executorService The service to use when spawning new servlet execution threads.
47 */
48 void setExecutorService(ExecutorService executorService);
49
50 /**
51 * Might be called several times to set up the connectors. This is the host/address
52 * and the port Cling expects to receive HTTP requests on. If you set up your HTTP
53 * server connectors elsewhere and ignore when Cling calls this method, make sure
54 * you configure Cling with the correct host/port of your servlet container.
55 *
56 * @param host The host address for the socket.
57 * @param port The port, might be <code>-1</code> to bind to an ephemeral port.
58 * @return The actual registered local port.
59 * @throws IOException If the connector couldn't be opened to retrieve the registered local port.
60 */
61 int addConnector(String host, int port) throws IOException;
62
63 /**
64 * Removes a previously added connector. Implementation should close the corresponding
65 * listening server socket. It may stop the server when the last connector is removed.
66 *
67 * @param host The host address of the socket.
68 * @param port The port of the connector
69 */
70 void removeConnector(String host, int port);
71
72 /**
73 * Might be called several times to register (the same) handler for UPnP
74 * requests, should only register it once.
75 *
76 * @param contextPath The context path prefix for all UPnP requests.
77 * @param servlet The servlet handling all UPnP requests.
78 */
79 void registerServlet(String contextPath, Servlet servlet);
80
81 /**
82 * Start your servlet container if it isn't already running, might be called multiple times.
83 */
84 void startIfNotRunning();
85
86 /**
87 * Stop your servlet container if it's still running, might be called multiple times.
88 */
89 void stopIfRunning();
90
91 }