001: /*
002: * Enhydra Java Application Server Project
003: *
004: * The contents of this file are subject to the Enhydra Public License
005: * Version 1.1 (the "License"); you may not use this file except in
006: * compliance with the License. You may obtain a copy of the License on
007: * the Enhydra web site ( http://www.enhydra.org/ ).
008: *
009: * Software distributed under the License is distributed on an "AS IS"
010: * basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
011: * the License for the specific terms governing rights and limitations
012: * under the License.
013: *
014: * The Initial Developer of the Enhydra Application Server is Lutris
015: * Technologies, Inc. The Enhydra Application Server and portions created
016: * by Lutris Technologies, Inc. are Copyright Lutris Technologies, Inc.
017: * All Rights Reserved.
018: *
019: * Contributor(s):
020: *
021: * $Id: Application.java,v 1.3 2007-10-19 10:05:39 sinisa Exp $
022: */
023:
024: package com.lutris.appserver.server;
025:
026: import java.io.IOException;
027:
028: import javax.servlet.Servlet;
029: import javax.servlet.ServletContext;
030: import javax.servlet.ServletException;
031: import javax.servlet.http.HttpServletRequest;
032: import javax.servlet.http.HttpServletResponse;
033:
034: import org.enhydra.util.jivan.JivanFactory;
035: import org.enhydra.xml.xmlc.XMLCFactory;
036:
037: import com.lutris.appserver.server.httpPresentation.HttpPresentationComms;
038: import com.lutris.appserver.server.httpPresentation.HttpPresentationManager;
039: import com.lutris.appserver.server.session.SessionManager;
040: import com.lutris.appserver.server.sql.DatabaseManager;
041: import com.lutris.logging.LogChannel;
042: import com.lutris.util.Config;
043:
044: /**
045: * Interface used to define a Lutris server application. Each application
046: * defines a class that implements this interface. The specific application
047: * class serves as an entry and control point for the application. This
048: * class is responsible for initializing any application specific resources,
049: * including instance of standard services that are needed. The class
050: * must have a constructor with a configuration file argument.
051: * <P>
052: * The class is instantiated from a presentation manager and is used to
053: * start and stop the application. This structure allows applications to be
054: * started on demand by URL reference, as is required for applications
055: * running under servlets in HTTPD virtual machines. If remote threads are
056: * part of the application, they are normally started from this object.
057: * <P>
058: * The application is in one of several states, documented below. The
059: * application state is used to determine what actions are take when a
060: * request is made for the application.
061: * <P>
062: * The following states are possible:
063: * <UL>
064: * <LI> <CODE>STOPPED</CODE> - The application is not running and maybe
065: * started. This is the initial state and the state normally
066: * entered on a <CODE>shutdown()</CODE>.
067: * <LI> <CODE>RUNNING</CODE> - The application is currently running.
068: * <LI> <CODE>INCOMPLETE</CODE> - The application is not completely running
069: * and the restartup() method maybe called to attempt to bring it into the
070: * <CODE>RUNNING</CODE> state. This state is normally used when a
071: * remote server that is required by the application is not available
072: * when <CODE>startup()</CODE> is called. Partial initialization will
073: * take place, but the request that caused the startup will fail.
074: * A subsequent requests will results in calls to <CODE>restartup()</CODE>
075: * until the application can be fully started. This eliminates startup
076: * order dependencies when initializing a distributed application.
077: * The state may also be entered by the application when a remote server
078: * fails.
079: * <LI> <CODE>DEAD</CODE> - The application is in an fatal error state and
080: * can not be restarted.
081: * <LI> <CODE>HALTED</CODE> - shutdown was called on the application and
082: * the application is not designed so that in can be restarted.
083: * </UL>
084: * The state is under control of the application. Its is used by the
085: * server to know what actions are allowed, but never modified by
086: * the server. The simplest application enters the <CODE>RUNNING</CODE> state
087: * when <CODE>startup()</CODE> is called and the <CODE>STOPPED</CODE> state
088: * when <CODE>shutdown()</CODE> is called.
089: * <P>
090: * The server provides synchronization on state changes to the application;
091: * however multiple requests threats may enter the application at the same
092: * time.
093: * <P>
094: * Two configuration parameters are required to start an application. Under
095: * servlets, these are specified as init args for the presentation
096: * servlet. They are:
097: * <UL>
098: * <LI> <CODE>appClass</CODE> - This is the class name of the application
099: * class. If not specified, the presentation servlet will run
100: * without an application object.
101: * <LI> <CODE>appConfig</CODE> - An arbitrary string to pass to the
102: * <CODE>startup(0</CODE> method. It normally contains the path or URL
103: * of a Config or properties file containing the application configuration.
104: * If not specified, <CODE>null</CODE> is passed to <CODE>startup</CODE>.
105: * </UL>
106: *
107: * @version $Revision: 1.3 $
108: * @author Mark Diekhans
109: */
110: public interface Application {
111:
112: /**
113: * Stopped state code.
114: */
115: public static final int STOPPED = 1;
116:
117: /**
118: * Running state code.
119: */
120: public static final int RUNNING = 2;
121:
122: /**
123: * Incomplete state code.
124: */
125: public static final int INCOMPLETE = 3;
126:
127: /**
128: * Dead state code.
129: */
130: public static final int DEAD = 4;
131:
132: /*
133: * Halted state code.
134: */
135: public static final int HALTED = 5;
136:
137: /**
138: * Get the application state.
139: *
140: * @return The application's state code.
141: */
142: public int getState();
143:
144: /**
145: * Set the application symbolic name.
146: *
147: * @param name The application's name.
148: */
149: public void setName(String name);
150:
151: /**
152: * Get the application symbolic name.
153: *
154: * @return The symbolic name.
155: */
156: public String getName();
157:
158: /**
159: * Get the application's config object.
160: *
161: * @return The config object.
162: */
163: public Config getConfig();
164:
165: /**
166: * Start the application. The default method sets the state to
167: * <CODE>RUNNING</CODE>.
168: *
169: * @param appConfig Application configuration object.
170: * @exception ApplicationException If an error occurs starting the
171: * application.
172: */
173: public void startup(Config appConfig) throws ApplicationException;
174:
175: /**
176: * Continue the startup up process with the application is in the
177: * <CODE>INCOMPLETE</CODE> state. The default method generates an
178: * error, as the application should never be in the <CODE>INCOMPLETE</CODE>
179: * state if it doesn't implement this method.
180: *
181: * @param appConfig
182: * The same <CODE>appConfig</CODE> object that was passed to
183: * <CODE>startup</CODE>.
184: * @exception ApplicationException
185: * If an error occurs starting the application.
186: */
187: public void restartup(Config appConfig) throws ApplicationException;
188:
189: /**
190: * Shutdown the application. The default method sets the state to
191: * <CODE>STOPPED</CODE>.
192: */
193: public void shutdown();
194:
195: /**
196: * Request preprocessing method. All requests for URLs associated
197: * with this application go through this function. It may do any
198: * preprocessing desired, including handling the request or generating
199: * a page redirect. It can be used to force login, allocate session
200: * objects, restrict access, etc.<P>
201: *
202: * Page redirect requests also go through this method, so care must be
203: * taken not to generate an endless page redirect loop. ErrorHandler
204: * presentation objects do not go through this method if they are invoked
205: * from within the presentation manager. However, direct URL requests to
206: * ErrorHandler presentation objects will go through this function. <P>
207: *
208: * Note: unlike the method servletRequestPreprocessor(), this method
209: * is commonly used in most applications. It is the only place that
210: * the application has where all requests come through. So you could,
211: * for example, put a check for HTTP basic authentication here, and that
212: * would automatically protect your entire application. Or, if you
213: * were so inclined, you could have a counter that counts the total
214: * pages served by your application.
215: *
216: * @param comms
217: * Object containing request, response and redirect objects.
218: * @return
219: * true if the request has been handled, false if normal request
220: * handling should continue.
221: * @exception Exception
222: * Any exception can be thrown.
223: * PageRedirectExceptions are handled as with presentation object.
224: * Other exceptions are handled by searching for an error handler
225: * starting at the requested presentation object.
226: */
227: public boolean requestPreprocessor(HttpPresentationComms comms)
228: throws Exception;
229:
230: /**
231: * Request post-processing method. All requests for URLs associated
232: * with this application go through this function. It may do any
233: * post-processing desired (e.g. saving sessions to persistent store). <P>
234: *
235: * @param comms
236: * Object containing request, response and redirect objects.
237: * @exception Exception
238: * Any exception can be thrown.
239: * PageRedirectExceptions are handled as with presentation object.
240: * Other exceptions are handled by searching for an error handler
241: * starting at the requested presentation object.
242: */
243: public void requestPostProcessor(HttpPresentationComms comms)
244: throws Exception;
245:
246: /**
247: * This preprocessor hook is called before the request/response pair
248: * is processed by the HttpPresentationServlet. It gives the
249: * application a chance to work with the raw request/response pair
250: * before they are wrapped by HttpPresentationRequest and
251: * HttpPresentationResponse objects. Return false to indicate
252: * that the request should continue to be processed normally
253: * or true to indicate that this method has handled the request,
254: * and all processing of the request should stop, in which case
255: * it will not be passed on to the presentation manager etc...
256: * The default method in StandardApplication always returns false.<P>
257: *
258: * <B>Almost all applications should not override this!</B> The
259: * version provided by StandardApplication simply returns false.
260: * Currently the debugger is the only application that used this,
261: * to support the flow-through debugging of non-Enhydra servlets,
262: * it needs to pass the raw request/response pair to the target
263: * servlet.
264: *
265: * @param servlet
266: * The servlet we are running in.
267: * @param context
268: * The ServletContext that was used to initialize our servlet.
269: * @param request
270: * The incomming request object.
271: * @param response
272: * The incomming response object.
273: * @return
274: * True if this method handled the request, in which case no
275: * further action will be taken. Or false if normal processing
276: * should continue.
277: * @exception ServletException
278: * You are allowed to throw the same exceptions that the servlet's
279: * service() method throws.
280: * @exception IOException
281: * You are allowed to throw the same exceptions that the servlet's
282: * service() method throws.
283: */
284: public boolean servletRequestPreprocessor(Servlet servlet,
285: ServletContext context, HttpServletRequest request,
286: HttpServletResponse response) throws ServletException,
287: IOException;
288:
289: /**
290: * Set the <CODE>LogChannel</CODE> associated with this application.
291: *
292: * @param The <CODE>LogChannel</CODE> to write to.
293: */
294: public void setLogChannel(LogChannel chan);
295:
296: /**
297: * Get the <CODE>LogChannel</CODE> associated with this application.
298: *
299: * @return The log channel or <CODE>null</CODE> if this application
300: * does not have one.
301: */
302: public LogChannel getLogChannel();
303:
304: /**
305: * Get the <CODE>SessionManager</CODE> associated with this application.
306: *
307: * @return The session manager or <CODE>null</CODE> if the application
308: * doesn't have a <CODE>SessionManager</CODE>.
309: */
310: public SessionManager getSessionManager();
311:
312: /**
313: * Get the <CODE>DatabaseManager</CODE> associated with this application.
314: *
315: * @return
316: * The database manager or <CODE>null</CODE> if the application
317: * doesn't have a <CODE>DatabaseManager</CODE>.
318: */
319: public DatabaseManager getDatabaseManager();
320:
321: /**
322: * Get the <CODE>HttpPresentationManager</CODE> associated with this
323: * application.
324: *
325: * @return
326: * The presentation manager used by this application.
327: */
328: public HttpPresentationManager getHttpPresentationManager();
329:
330: /**
331: * Called to tell the application about the presentation manager
332: * instance. This is necessary because the Presentation Manager is
333: * created in parallel with the application by the
334: * HttpPresentationServlet.
335: *
336: * @param pm
337: * The presentation manager responsible for running this application.
338: */
339: public void setHttpPresentationManager(HttpPresentationManager pm);
340:
341: /**
342: * Get the XMLC factory object being used by the application.
343: * If one was not configured, a default one is created on the
344: * first call to this method.
345: */
346: public XMLCFactory getXMLCFactory();
347:
348: /**
349: * Set the XMLC factory based on the deferred parsing option.
350: */
351: public void setXMLCFactory();
352:
353: // vr 16.05.2004
354: /**
355: * Initializes the Jivan factory object which can be used by application.
356: * @param reload switch which indicates reloading status of Jivan generated
357: * pages in presentation layer (true = reload is on, false = reload is off)
358: */
359: public void setJivanFactory(boolean reload);
360:
361: /**
362: * Get the Jivan factory object being used by the application.
363: */
364: public JivanFactory getJivanFactory();
365:
366: }
|