Application


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