Source code: org/enhydra/servlet/connectionMethods/ConnectionMethod.java
1 /*
2 * Enhydra Java Application Server Project
3 *
4 * The contents of this file are subject to the Enhydra Public License
5 * Version 1.1 (the "License"); you may not use this file except in
6 * compliance with the License. You may obtain a copy of the License on
7 * the Enhydra web site ( http://www.enhydra.org/ ).
8 *
9 * Software distributed under the License is distributed on an "AS IS"
10 * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
11 * the License for the specific terms governing rights and limitations
12 * under the License.
13 *
14 * The Initial Developer of the Enhydra Application Server is Lutris
15 * Technologies, Inc. The Enhydra Application Server and portions created
16 * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
17 * All Rights Reserved.
18 *
19 * Contributor(s):
20 *
21 * $Id: ConnectionMethod.java,v 1.4.12.1 2000/10/19 17:59:09 jasona Exp $
22 */
23
24 package org.enhydra.servlet.connectionMethods;
25
26 import com.lutris.util.*;
27 import java.io.Serializable;
28 import org.enhydra.servlet.servletManager.ServletManager;
29 import org.enhydra.servlet.filter.FilterManager;
30
31 import org.apache.tomcat.core.*;
32
33 /**
34 *
35 * A ConnectionMethod is how requests get into the server from the
36 * outside world. This interface defines the API an object must
37 * implement in order to be administered by the server. <P>
38 *
39 * Each ConnectionMethod must maintain an ordered list of "channels".
40 * Each channel has an ID (a String), used to identify and refer to
41 * the channel. See <CODE>addChannel()</CODE>, below. <P>
42 *
43 * Each channel can be enabled or disabled. When disabled, connections
44 * must be refused, and not passed on to any servlets. When enabled,
45 * connections are allowed through to the destination servlet. <P>
46 *
47 * Each channel also contains an ordered list of TransactionFilters,
48 * which can be used for debugging and logging. <P>
49 *
50 * When a ConnectionMethod is being used as part of a server, the
51 * <CODE>initialize()</CODE> method will be called before any other methods.
52 * The servlet IDs in the channels are only valid in the ServletManager
53 * object provided to <CODE>initialize()</CODE>. Filter IDs are only
54 * valid in the FilterManager passed in to <CODE>initialize()</CODE>.<P>
55 *
56 * The <CODE>destroy()</CODE> method will be called when the
57 * ConnectionMethod should shut down. Any external network exposure should
58 * be eliminated, for example any ServerSockets should be closed, or any
59 * WAI registrations should be unregistered.
60 * After <CODE>destroy()</CODE> is called, no further calls will be
61 * made to the object. <P>
62 *
63 * HTTP, WAI and RMI are implementations of this interface. See
64 * StandardConnectionMethod for a sample implementation which mananges
65 * the channels, but does not actually recieve or generate requests.
66 * If you are implementing a ConnectionMethod, it is recommended that
67 * you extend StandardConnectionMethod.
68 *
69 * Connection methods must contain a running non-daemon thread. The
70 * thread must be started either in the constructor or (perfered)
71 * the <CODE>initialize()</CODE> method, and stopped in the
72 * <CODE>destroy()</CODE> method.
73 *
74 *
75 * @see org.enhydra.servlet.connectionMethods.ChannelStatus
76 * @see org.enhydra.servlet.servletManager.ServletManager
77 * @see org.enhydra.servlet.filter.TransactionFilter
78 * @see org.enhydra.servlet.connectionMethods.StandardConnectionMethod
79 * @author Andy John
80 */
81 public interface ConnectionMethod
82 extends Serializable {
83 /**
84 * Initialize the ConnectionMethod. The ServletManager to use is
85 * passed in. This ServletManager is used to look up Servlets
86 * based on their String servlet IDs. <P>
87 * <B>This will be called before any other method in this interface.</B>
88 *
89 * @param connectionConfig The portion of the config file relevant to
90 * this connection method
91 * @param id The id associated with this connection method
92 * @param servletManager The ServletManager to use to obtain servlets.
93 * Servlet ID strings given in <CODE>addChannel()</CODE> are valid only
94 * in this ServletManager.
95 * @param filterManager The FilterManager to use to get filters.
96 * Filter ID strings given in <CODE>addTransactionFilter()</CODE>
97 * are valid only in this FilterManager.
98 * @exception ConnectionMethodException If an error occurs.
99 */
100 public void initialize(Config connectionConfig,
101 String id,
102 ServletManager servletManager,
103 FilterManager filterManager)
104 throws ConnectionMethodException;
105
106 /**
107 * Initialize the ConnectionMethod. The ServletManager to use is
108 * passed in. This ServletManager is used to look up Servlets
109 * based on their String servlet IDs. <P>
110 *
111 * @param id The id associated with this connection method
112 * @param servletManager The ServletManager to use to obtain servlets.
113 * Servlet ID strings given in <CODE>addChannel()</CODE> are valid only
114 * in this ServletManager.
115 * @param filterManager The FilterManager to use to get filters.
116 * Filter ID strings given in <CODE>addTransactionFilter()</CODE>
117 * are valid only in this FilterManager.
118 * @exception ConnectionMethodException If an error occurs.
119 */
120 public void initialize(String id,
121 ServletManager servletManager,
122 FilterManager filterManager)
123 throws ConnectionMethodException;
124
125 /**
126 * Write out self into config fie
127 *
128 * @param config The config file
129 * @param base The base key string
130 **/
131 public void writeToConfig(Config connectionConfig,
132 String base)
133 throws ConfigException, KeywordValueException;
134
135
136 /**
137 * Add a new channel. The new channel is not enabled,
138 * and has no TransactionFilters.
139 * The Servlet ID is only valid in the
140 * ServletManager passed in to <CODE>initialize()</CODE>.
141 * When the Servlet ID
142 * is used to fetch the actual Servlet, the reference should only
143 * be kept in the ConnectionMethod for the duration of the request.
144 * After the request is finished, the ConnectionMehtod should eliminate
145 * all pointers to the Servlet. This will allow the ServletManager
146 * to destroy the Servlet and cause it to get garbage collected.
147 * The ServletManager's <CODE>get()</CODE> method should be called for
148 * every request.
149 *
150 * @param channelID The symbolic name to use for this channel.
151 * @param URLPrefix If a request's URL starts with this string,
152 * it should be sent to the servlet identified by servletID.
153 * To obtain the servlet, use the ServletManager's <CODE>get()</CODE>
154 * method.
155 * @param servletID The servlet to send requests to. Use the
156 * ServletManager's <CODE>get()</CODE> method to get the servlet.
157 * Call <CODE>get()</CODE> for each request, do not save a reference
158 * to the servlet.
159 * @exception ConnectionMethodException If an error occurs.
160 */
161 void addChannel(String channelID, String URLPrefix, String servletID)
162 throws ConnectionMethodException;
163
164
165 /**
166 * Delete a channel.
167 *
168 * @param channelID Which channel to remove.
169 * @exception ConnectionMethodException If an error occurs.
170 */
171 void deleteChannel(String channelID) throws ConnectionMethodException;
172
173
174 /**
175 * Get the current status of a channel.
176 * @param channelID Which channel.
177 * @return The status of the channel, stored in a ChannelStatus object.
178 * Null is returned if the given channelID cannot be found.
179 * @see org.enhydra.servlet.connectionMethods.ChannelStatus
180 */
181 ChannelStatus getChannelStatus(String channelID);
182
183
184 /**
185 * Returns the identifier names of all the channels currently in
186 * the ConnectionMethod.
187 *
188 * @return An array of Strings, the names of all the channels
189 * in the ConnectionMethod.
190 */
191 String[] getChannelIDs();
192
193
194 /**
195 * Turn on the channel. Allows requests to be sent to the servlet.
196 *
197 * @param channelID Which channel to enable.
198 * @exception ConnectionMethodException If an error occurs.
199 */
200 void enableChannel(String channelID) throws ConnectionMethodException;
201
202
203 /**
204 * Turn off the channel. Incomming requests should be refused.
205 * No requests should be allowd through to the servlet.
206 *
207 * @param channelID Which channel to disable.
208 * @exception ConnectionMethodException If an error occurs.
209 */
210 void disableChannel(String channelID) throws ConnectionMethodException;
211
212
213 /**
214 * Reset the specified channel's request count to zero.
215 * The counter measures the number of requests processed by this channel.
216 *
217 * @param channelID Which channel.
218 * @exception ConnectionMethodException If an error occurs.
219 */
220 void resetRequestCount(String channelID) throws ConnectionMethodException;
221
222
223 /**
224 * Add a new TransactionFilter to the specified channel.
225 * Use this ID to refer to the filter in
226 * <CODE>removeTransactionFilter()</CODE>. The filter will be
227 * fetched from the filter manager when a request comes in.
228 *
229 * @param channelID Which channel to add a TransactionFilter to.
230 * @param filterID The TransactionFilter to add.
231 * The filter is fetched from the FilterManager passed in to
232 * <CODE>initialize()</CODE> each time a request comes in.
233 * @exception ConnectionMethodException If an error occurs.
234 * @see org.enhydra.servlet.filter.TransactionFilter
235 */
236 void addTransactionFilter(String channelID, String filterID)
237 throws ConnectionMethodException;
238
239
240 /**
241 * Remove the given TransactionFilter from the specified channel.
242 *
243 * @param channelID Which channel to remove a TransactionFilter from.
244 * @param filter The TransactionFilter to remove.
245 * @exception ConnectionMethodException If an error occurs.
246 * @see org.enhydra.servlet.filter.TransactionFilter
247 */
248 void removeTransactionFilter(String channelID, String filterID)
249 throws ConnectionMethodException;
250
251
252 /**
253 * Get an array of all the current filter names for a given channel.
254 * If there are no filters, this will return a zero-length array.
255 *
256 * @return An array of filter names. You can pass these to
257 * <CODE>removeTransactionFilter()</CODE>.
258 * @exception ConnectionMethodException If an error occurs, for example
259 * if the channel does not exist.
260 */
261 public String[] getTransactionFilterIDs(String channelID)
262 throws ConnectionMethodException;
263
264
265 /**
266 * This returns a channel name that is not currently in use. Use this
267 * when you want to programatically create a channel, and you don't
268 * care what it's name is. The name returned will not be in the list
269 * of current channels, and will not be returned on any other calls
270 * to this function.
271 * @return A name that can be used with <CODE>addChannel()</CODE>.
272 */
273 public String getUniqueChannelName();
274
275
276 /**
277 * Returns the URL that a user would use to connect to this
278 * channel. For example, with an HTTP method on port 2000 on
279 * a machine called <CODE>enhydra.lutris.com</CODE>,
280 * and a url prefix of <CODE>/abalone/</CODE>, the
281 * returned string would be
282 * <CODE>"http://enhydra.lutris.com:2000/abalone/"</CODE>. <P>
283 *
284 * Note: it is not always possible for a connection method to
285 * know the exact URL a user should use, so the returned
286 * string may be an approximation. For example, the RMI
287 * connection method may be accessed from any host that has
288 * access to it.
289 *
290 * @return A URL string.
291 * @exception ConnectionMethodException If an error occurs,
292 * for example if the channel does not exist.
293 */
294 public String getChannelURL(String channelID)
295 throws ConnectionMethodException;
296
297
298 /**
299 * Is the string returned from <CODE>getChannelURL()</CODE> a valid
300 * url?
301 *
302 * @return True if the url returned from
303 * <CODE>getChannelURL()</CODE> is a valid url that users could
304 * sucessfully enter into their browsers.
305 * @exception ConnectionMethodException If an error occurs,
306 * for example if the channel does not exist.
307 */
308 public boolean channelURLIsValid(String channelID)
309 throws ConnectionMethodException;
310
311
312 /**
313 * Shut down the connection method. Any threads created in
314 * <CODE>initialize()</CODE> or any other mehtod must be terminated.<P>
315 * <B>After this call, none of these methods will be called again.</B>
316 * @exception ConnectionMethodException If an error occurs.
317 */
318 public void destroy() throws ConnectionMethodException;
319
320 /**
321 * Compares the connection specific attributes for equivalency
322 *
323 * @param compareObject The object to compare this to
324 * @exception ConnectionMethodException If an error occurs.
325 **/
326 public boolean equivalent(ConnectionMethod compareObject);
327
328 public String getType();
329
330 /*********************************************************************
331 * Error strings for common errors shared by all ConnectionMethods.
332 *********************************************************************/
333
334 /**
335 * Return this HTML when an incomming request does not match any
336 * of the channels. Suggested use:
337 * <CODE>response.sendError(HttpServletResponse.SC_NOT_FOUND,
338 * ConnectionMethod.noChannelHtml);</CODE>
339 */
340 public final static String noChannelHtml =
341 "<TITLE>Not Found</TITLE><H1>Not Found</H1>\n" +
342 "The requested object does not exist on this " +
343 "Enhydra Multiserver.<P>\n" +
344 "The link you followed is either outdated, inaccurate, " +
345 "or the server has been instructed not to let you have it.";
346
347 /**
348 * Return this HTML when an incomming request matches a channel,
349 * but that channel is disabled. Suggested use:
350 * <CODE>response.sendError(HttpServletResponse.SC_MOVED_TEMPORARILY,
351 * ConnectionMethod.disabledChannelHtml);</CODE>
352 */
353 public final static String disabledChannelHtml =
354 "<TITLE>Temporarily Unavailable</TITLE>\n" +
355 "<H1>Temporarily Unavailable</H1>\n" +
356 "The requested object is temporarily unavailable. " +
357 "Please try again later.\n";
358
359 /**
360 * Return this HTML if an unexpected exception is thrown.
361 * Suggested use:
362 * <CODE>response.sendError(HttpServletResponse.SC_SERVER_ERROR,
363 * ConnectionMethod.errorHtml);</CODE>
364 */
365 public final static String errorHtml =
366 "<TITLE>Server Error</TITLE><H1>Server Error</H1> " +
367 "This Enhydra Multiserver has encountered an internal " +
368 "error which prevents it from fulfilling your request. " +
369 "The most likely cause is a misconfiguration. Please ask " +
370 "the administrator to look for messages in the server's error log.";
371
372
373 }
374
375
376
377