Source code: com/lutris/appserver/server/Application.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: Application.java,v 1.24.14.1 2000/10/19 17:59:06 jasona Exp $
22 */
23
24
25
26
27 package com.lutris.appserver.server;
28
29 import com.lutris.appserver.server.httpPresentation.*;
30 import com.lutris.appserver.server.session.SessionManager;
31 import com.lutris.appserver.server.session.SessionException;
32 import com.lutris.appserver.server.sql.DatabaseManager;
33 import com.lutris.appserver.server.*;
34 import com.lutris.logging.LogChannel;
35 import com.lutris.util.Config;
36 import org.enhydra.xml.xmlc.XMLCFactory;
37
38 import java.io.IOException;
39 import javax.servlet.*;
40 import javax.servlet.http.*;
41
42 /**
43 * Interface used to define a Lutris server application. Each application
44 * defines a class that implements this interface. The specific application
45 * class serves as an entry and control point for the application. This
46 * class is responsible for initializing any application specific resources,
47 * including instance of standard services that are needed. The class
48 * must have a constructor with a configuration file argument.
49 * <P>
50 * The class is instantiated from a presentation manager and is used to
51 * start and stop the application. This structure allows applications to be
52 * started on demand by URL reference, as is required for applications
53 * running under servlets in HTTPD virtual machines. If remote threads are
54 * part of the application, they are normally started from this object.
55 * <P>
56 * The application is in one of several states, documented below. The
57 * application state is used to determine what actions are take when a
58 * request is made for the application.
59 * <P>
60 * The following states are possible:
61 * <UL>
62 * <LI> <CODE>STOPPED</CODE> - The application is not running and maybe
63 * started. This is the initial state and the state normally
64 * entered on a <CODE>shutdown()</CODE>.
65 * <LI> <CODE>RUNNING</CODE> - The application is currently running.
66 * <LI> <CODE>INCOMPLETE</CODE> - The application is not completely running
67 * and the restartup() method maybe called to attempt to bring it into the
68 * <CODE>RUNNING</CODE> state. This state is normally used when a
69 * remote server that is required by the application is not available
70 * when <CODE>startup()</CODE> is called. Partial initialization will
71 * take place, but the request that caused the startup will fail.
72 * A subsequent requests will results in calls to <CODE>restartup()</CODE>
73 * until the application can be fully started. This eliminates startup
74 * order dependencies when initializing a distributed application.
75 * The state may also be entered by the application when a remote server
76 * fails.
77 * <LI> <CODE>DEAD</CODE> - The application is in an fatal error state and
78 * can not be restarted.
79 * <LI> <CODE>HALTED</CODE> - shutdown was called on the application and
80 * the application is not designed so that in can be restarted.
81 * </UL>
82 * The state is under control of the application. Its is used by the
83 * server to know what actions are allowed, but never modified by
84 * the server. The simplest application enters the <CODE>RUNNING</CODE> state
85 * when <CODE>startup()</CODE> is called and the <CODE>STOPPED</CODE> state
86 * when <CODE>shutdown()</CODE> is called.
87 * <P>
88 * The server provides synchronization on state changes to the application;
89 * however multiple requests threats may enter the application at the same
90 * time.
91 * <P>
92 * Two configuration parameters are required to start an application. Under
93 * servlets, these are specified as init args for the presentation
94 * servlet. They are:
95 * <UL>
96 * <LI> <CODE>appClass</CODE> - This is the class name of the application
97 * class. If not specified, the presentation servlet will run
98 * without an application object.
99 * <LI> <CODE>appConfig</CODE> - An arbitrary string to pass to the
100 * <CODE>startup(0</CODE> method. It normally contains the path or URL
101 * of a Config or properties file containing the application configuration.
102 * If not specified, <CODE>null</CODE> is passed to <CODE>startup</CODE>.
103 * </UL>
104 *
105 * @version $Revision: 1.24.14.1 $
106 * @author Mark Diekhans
107 */
108 public interface Application {
109
110 /**
111 * Stopped state code.
112 */
113 public static final int STOPPED = 1;
114
115 /**
116 * Running state code.
117 */
118 public static final int RUNNING = 2;
119
120 /**
121 * Incomplete state code.
122 */
123 public static final int INCOMPLETE = 3;
124
125 /**
126 * Dead state code.
127 */
128 public static final int DEAD = 4;
129
130 /*
131 * Halted state code.
132 */
133 public static final int HALTED = 5;
134
135 /**
136 * Get the application state.
137 *
138 * @return The application's state code.
139 */
140 public int getState();
141
142 /**
143 * Application Data accessible through Jolt Fields.
144 */
145 public ApplicationData getApplicationData();
146
147 /**
148 * Set the application symbolic name.
149 *
150 * @param name The application's name.
151 */
152 public void setName(String name);
153
154 /**
155 * Get the application symbolic name.
156 *
157 * @return The symbolic name.
158 */
159 public String getName();
160
161 /**
162 * Get the application's config object.
163 *
164 * @return The config object.
165 */
166 public Config getConfig();
167
168 /**
169 * Start the application. The default method sets the state to
170 * <CODE>RUNNING</CODE>.
171 *
172 * @param appConfig Application configuration object.
173 * @exception ApplicationException If an error occurs starting the
174 * application.
175 */
176 public void startup(Config appConfig) throws ApplicationException;
177
178 /**
179 * Continue the startup up process with the application is in the
180 * <CODE>INCOMPLETE</CODE> state. The default method generates an
181 * error, as the application should never be in the <CODE>INCOMPLETE</CODE>
182 * state if it doesn't implement this method.
183 *
184 * @param appConfig
185 * The same <CODE>appConfig</CODE> object that was passed to
186 * <CODE>startup</CODE>.
187 * @exception ApplicationException
188 * If an error occurs starting the application.
189 */
190 public void restartup(Config appConfig) throws ApplicationException;
191
192 /**
193 * Shutdown the application. The default method sets the state to
194 * <CODE>STOPPED</CODE>.
195 */
196 public void shutdown();
197
198 /**
199 * Request preprocessing method. All requests for URLs associated
200 * with this application go through this function. It may do any
201 * preprocessing desired, including handling the request or generating
202 * a page redirect. It can be used to force login, allocate session
203 * objects, restrict access, etc.<P>
204 *
205 * Page redirect requests also go through this method, so care must be
206 * taken not to generate an endless page redirect loop. ErrorHandler
207 * presentation objects do not go through this method if they are invoked
208 * from within the presentation manager. However, direct URL requests to
209 * ErrorHandler presentation objects will go through this function. <P>
210 *
211 * Note: unlike the method servletRequestPreprocessor(), this method
212 * is commonly used in most applications. It is the only place that
213 * the application has where all requests come through. So you could,
214 * for example, put a check for HTTP basic authentication here, and that
215 * would automatically protect your entire application. Or, if you
216 * were so inclined, you could have a counter that counts the total
217 * pages served by your application.
218 *
219 * @param comms
220 * Object containing request, response and redirect objects.
221 * @return
222 * true if the request has been handled, false if normal request
223 * handling should continue.
224 * @exception Exception
225 * Any exception can be thrown.
226 * PageRedirectExceptions are handled as with presentation object.
227 * Other exceptions are handled by searching for an error handler
228 * starting at the requested presentation object.
229 */
230 public boolean requestPreprocessor(HttpPresentationComms comms)
231 throws Exception;
232
233
234 /**
235 * Request post-processing method. All requests for URLs associated
236 * with this application go through this function. It may do any
237 * post-processing desired (e.g. saving sessions to persistent store). <P>
238 *
239 * @param comms
240 * Object containing request, response and redirect objects.
241 * @exception Exception
242 * Any exception can be thrown.
243 * PageRedirectExceptions are handled as with presentation object.
244 * Other exceptions are handled by searching for an error handler
245 * starting at the requested presentation object.
246 */
247 public void requestPostProcessor(HttpPresentationComms comms)
248 throws Exception;
249
250
251 /**
252 * This preprocessor hook is called before the request/response pair
253 * is processed by the HttpPresentationServlet. It gives the
254 * application a chance to work with the raw request/response pair
255 * before they are wrapped by HttpPresentationRequest and
256 * HttpPresentationResponse objects. Return false to indicate
257 * that the request should continue to be processed normally
258 * or true to indicate that this method has handled the request,
259 * and all processing of the request should stop, in which case
260 * it will not be passed on to the presentation manager etc...
261 * The default method in StandardApplication always returns false.<P>
262 *
263 * <B>Almost all applications should not override this!</B> The
264 * version provided by StandardApplication simply returns false.
265 * Currently the debugger is the only application that used this,
266 * to support the flow-through debugging of non-Enhydra servlets,
267 * it needs to pass the raw request/response pair to the target
268 * servlet.
269 *
270 * @param servlet
271 * The servlet we are running in.
272 * @param context
273 * The ServletContext that was used to initialize our servlet.
274 * @param request
275 * The incomming request object.
276 * @param response
277 * The incomming response object.
278 * @return
279 * True if this method handled the request, in which case no
280 * further action will be taken. Or false if normal processing
281 * should continue.
282 * @exception ServletException
283 * You are allowed to throw the same exceptions that the servlet's
284 * service() method throws.
285 * @exception IOException
286 * You are allowed to throw the same exceptions that the servlet's
287 * service() method throws.
288 */
289 public boolean servletRequestPreprocessor(Servlet servlet,
290 ServletContext context,
291 HttpServletRequest request,
292 HttpServletResponse response)
293 throws ServletException, IOException;
294
295
296 /**
297 * Set the <CODE>LogChannel</CODE> associated with this application.
298 *
299 * @param The <CODE>LogChannel</CODE> to write to.
300 */
301 public void setLogChannel(LogChannel chan);
302
303 /**
304 * Get the <CODE>LogChannel</CODE> associated with this application.
305 *
306 * @return The log channel or <CODE>null</CODE> if this application
307 * does not have one.
308 */
309 public LogChannel getLogChannel();
310
311 /**
312 * Get the <CODE>SessionManager</CODE> associated with this application.
313 *
314 * @return The session manager or <CODE>null</CODE> if the application
315 * doesn't have a <CODE>SessionManager</CODE>.
316 */
317 public SessionManager getSessionManager();
318
319 /**
320 * Get the <CODE>DatabaseManager</CODE> associated with this application.
321 *
322 * @return
323 * The database manager or <CODE>null</CODE> if the application
324 * doesn't have a <CODE>DatabaseManager</CODE>.
325 */
326 public DatabaseManager getDatabaseManager();
327
328 /**
329 * Get the <CODE>HttpPresentationManager</CODE> associated with this
330 * application.
331 *
332 * @return
333 * The presentation manager used by this application.
334 */
335 public HttpPresentationManager getHttpPresentationManager();
336
337 /**
338 * Called to tell the application about the presentation manager
339 * instance. This is necessary because the Presentation Manager is
340 * created in parallel with the application by the
341 * HttpPresentationServlet.
342 *
343 * @param pm
344 * The presentation manager responsible for running this application.
345 */
346 public void setHttpPresentationManager(HttpPresentationManager pm);
347
348 /**
349 * Get the XMLC factory object being used by the application.
350 * If one was not configured, a default one is created on the
351 * first call to this method.
352 */
353 public XMLCFactory getXMLCFactory();
354
355 /**
356 * Set the XMLC factory based on the recload and recompilation options.
357 */
358 public void setXMLCFactory(boolean enableReload,
359 boolean enableRecompilation);
360 }