1 package com.ericsson.research.trap;
2
3 /*
4 * ##_BEGIN_LICENSE_##
5 * Transport Abstraction Package (trap)
6 * ----------
7 * Copyright (C) 2014 Ericsson AB
8 * ----------
9 * Redistribution and use in source and binary forms, with or without modification,
10 * are permitted provided that the following conditions are met:
11 *
12 * 1. Redistributions of source code must retain the above copyright notice, this
13 * list of conditions and the following disclaimer.
14 *
15 * 2. Redistributions in binary form must reproduce the above copyright notice,
16 * this list of conditions and the following disclaimer in the documentation
17 * and/or other materials provided with the distribution.
18 *
19 * 3. Neither the name of the Ericsson AB nor the names of its contributors
20 * may be used to endorse or promote products derived from this software without
21 * specific prior written permission.
22 *
23 * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
24 * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
25 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
26 * IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
27 * INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING,
28 * BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
29 * DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
30 * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
31 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
32 * OF THE POSSIBILITY OF SUCH DAMAGE.
33 * ##_END_LICENSE_##
34 */
35
36
37
38 import com.ericsson.research.trap.auth.TrapAuthentication;
39 import com.ericsson.research.trap.delegates.OnAccept;
40 import com.ericsson.research.trap.delegates.OnClose;
41 import com.ericsson.research.trap.delegates.OnStateChange;
42
43 /**
44 * A TrapListener is a special kind of Trap node capable of listening for incoming connections. It is employed by
45 * servers, to await incoming Trap connections. A TrapListener is not an endpoint, despite being created by TrapFactory.
46 * TrapListener instances will spawn TrapEndpoints on incoming connections, however.
47 * <p>
48 * Any configuration set using the {@link TrapSettings} interface on a TrapListener will carry over to spawned
49 * TrapEndpoints. Additionally, authentication set here will carry over.
50 *
51 * @author Vladimir Katardjiev
52 * @since 1.0
53 */
54 public interface TrapListener extends TrapSettings
55 {
56 /**
57 * Stops the Trap Listener. This will close all listening transports, which may affect existing connections. For
58 * example, the HTTP transport relies on the listening socket for "established" connections, so any HTTP connections
59 * will be terminated.
60 */
61 public abstract void close();
62
63 /**
64 * Asks the server to generate a client configuration string, in order to configure the transports to properly
65 * connect to this TrapServer instance. Each TrapTransport that supports listening will generate this configuration,
66 * and the entire string can then be supplied as-is to the TrapClient.
67 *
68 * @return The client configuration string needed to connect here.
69 */
70 public abstract String getClientConfiguration();
71
72 /**
73 * Asks the server to generate a client configuration string, in order to configure the transports to properly
74 * connect to this TrapServer instance. Each TrapTransport that supports listening will generate this configuration,
75 * and the entire string can then be supplied as-is to the TrapClient.
76 *
77 * @param hostname
78 * The hostname to use for this host. This hostname will be used for any transport that has not been
79 * explicitly configured.
80 * @return The client configuration string needed to connect here
81 * @since 1.2.0
82 */
83 public abstract String getClientConfiguration(String hostname);
84
85 /**
86 * Starts the TrapListener.
87 * <p>
88 * Associates a given {@link OnAccept} deelgate to listen for incoming requests, and handle them. The delegate is
89 * responsible for initialising the TrapEndoints it receives, by means of configuring them to fit the current
90 * server's requirements on blocking, threading, etc.
91 *
92 * @param delegate
93 * The object that will be called to handle incoming connections. The delegate MAY implement further
94 * TrapDelegate methods; however, a listener endpoint will not call any other (except
95 * {@link OnStateChange}/{@link OnClose}).
96 * @throws TrapException
97 * If an error occurred during the initialization stage of the listeners.
98 * @since 1.1
99 */
100 public abstract void listen(OnAccept delegate) throws TrapException;
101
102 /**
103 * Starts the TrapListener.
104 * <p>
105 * Associates a given {@link TrapListenerDelegate} to listen for incoming requests, and handle them. The delegate is
106 * responsible for initialising the TrapEndoints it receives, by means of configuring them to fit the current
107 * server's requirements on blocking, threading, etc.
108 *
109 * @param delegate
110 * The object that will be called to handle incoming connections
111 * @param context
112 * An optional object that will be passed to the delegate on each callback
113 * @throws TrapException
114 * If an error occurred during the initialization stage of the listeners.
115 * @deprecated Use {@link #listen(OnAccept)} instead.
116 */
117 public abstract void listen(OnAccept delegate, Object context) throws TrapException;
118
119 /**
120 * Sets an authenticator for this listener. Effectively requires any incoming connection to be authenticated.
121 * <p>
122 * Note that the instance will be shared between any endpoint. This is only good for static authentication types.
123 * For most use cases, authentication should be applied on an individual basis.
124 *
125 * @param authenticator
126 * The authenticator to verify incoming authentication
127 * @throws TrapException
128 * If the authentication was not acceptable.
129 */
130 public abstract void setAuthentication(TrapAuthentication authenticator) throws TrapException;
131 }