EAF 7.6 API

com.lutris.appserver.server
Interface Application

All Known Implementing Classes:
StandardApplication

public interface Application

Interface used to define a Lutris server application. Each application defines a class that implements this interface. The specific application class serves as an entry and control point for the application. This class is responsible for initializing any application specific resources, including instance of standard services that are needed. The class must have a constructor with a configuration file argument.

The class is instantiated from a presentation manager and is used to start and stop the application. This structure allows applications to be started on demand by URL reference, as is required for applications running under servlets in HTTPD virtual machines. If remote threads are part of the application, they are normally started from this object.

The application is in one of several states, documented below. The application state is used to determine what actions are take when a request is made for the application.

The following states are possible:

The state is under control of the application. Its is used by the server to know what actions are allowed, but never modified by the server. The simplest application enters the RUNNING state when startup() is called and the STOPPED state when shutdown() is called.

The server provides synchronization on state changes to the application; however multiple requests threats may enter the application at the same time.

Two configuration parameters are required to start an application. Under servlets, these are specified as init args for the presentation servlet. They are:

Version:
$Revision: 1.2 $
Author:
Mark Diekhans

Field Summary
static int DEAD
          Dead state code.
static int HALTED
           
static int INCOMPLETE
          Incomplete state code.
static int RUNNING
          Running state code.
static int STOPPED
          Stopped state code.
 
Method Summary
 com.lutris.util.Config getConfig()
          Get the application's config object.
 DatabaseManager getDatabaseManager()
          Get the DatabaseManager associated with this application.
 com.lutris.appserver.server.httpPresentation.HttpPresentationManager getHttpPresentationManager()
          Get the HttpPresentationManager associated with this application.
 org.enhydra.util.jivan.JivanFactory getJivanFactory()
          Get the Jivan factory object being used by the application.
 LogChannel getLogChannel()
          Get the LogChannel associated with this application.
 java.lang.String getName()
          Get the application symbolic name.
 SessionManager getSessionManager()
          Get the SessionManager associated with this application.
 int getState()
          Get the application state.
 org.enhydra.xml.xmlc.XMLCFactory getXMLCFactory()
          Get the XMLC factory object being used by the application.
 void requestPostProcessor(com.lutris.appserver.server.httpPresentation.HttpPresentationComms comms)
          Request post-processing method.
 boolean requestPreprocessor(com.lutris.appserver.server.httpPresentation.HttpPresentationComms comms)
          Request preprocessing method.
 void restartup(com.lutris.util.Config appConfig)
          Continue the startup up process with the application is in the INCOMPLETE state.
 boolean servletRequestPreprocessor(javax.servlet.Servlet servlet, javax.servlet.ServletContext context, javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response)
          This preprocessor hook is called before the request/response pair is processed by the HttpPresentationServlet.
 void setHttpPresentationManager(com.lutris.appserver.server.httpPresentation.HttpPresentationManager pm)
          Called to tell the application about the presentation manager instance.
 void setJivanFactory(boolean reload)
          Initializes the Jivan factory object which can be used by application.
 void setLogChannel(LogChannel chan)
          Set the LogChannel associated with this application.
 void setName(java.lang.String name)
          Set the application symbolic name.
 void setXMLCFactory()
          Set the XMLC factory based on the deferred parsing option.
 void shutdown()
          Shutdown the application.
 void startup(com.lutris.util.Config appConfig)
          Start the application.
 

Field Detail

STOPPED

static final int STOPPED
Stopped state code.

See Also:
Constant Field Values

RUNNING

static final int RUNNING
Running state code.

See Also:
Constant Field Values

INCOMPLETE

static final int INCOMPLETE
Incomplete state code.

See Also:
Constant Field Values

DEAD

static final int DEAD
Dead state code.

See Also:
Constant Field Values

HALTED

static final int HALTED
See Also:
Constant Field Values
Method Detail

getState

int getState()
Get the application state.

Returns:
The application's state code.

setName

void setName(java.lang.String name)
Set the application symbolic name.

Parameters:
name - The application's name.

getName

java.lang.String getName()
Get the application symbolic name.

Returns:
The symbolic name.

getConfig

com.lutris.util.Config getConfig()
Get the application's config object.

Returns:
The config object.

startup

void startup(com.lutris.util.Config appConfig)
             throws ApplicationException
Start the application. The default method sets the state to RUNNING.

Parameters:
appConfig - Application configuration object.
Throws:
ApplicationException - If an error occurs starting the application.

restartup

void restartup(com.lutris.util.Config appConfig)
               throws ApplicationException
Continue the startup up process with the application is in the INCOMPLETE state. The default method generates an error, as the application should never be in the INCOMPLETE state if it doesn't implement this method.

Parameters:
appConfig - The same appConfig object that was passed to startup.
Throws:
ApplicationException - If an error occurs starting the application.

shutdown

void shutdown()
Shutdown the application. The default method sets the state to STOPPED.


requestPreprocessor

boolean requestPreprocessor(com.lutris.appserver.server.httpPresentation.HttpPresentationComms comms)
                            throws java.lang.Exception
Request preprocessing method. All requests for URLs associated with this application go through this function. It may do any preprocessing desired, including handling the request or generating a page redirect. It can be used to force login, allocate session objects, restrict access, etc.

Page redirect requests also go through this method, so care must be taken not to generate an endless page redirect loop. ErrorHandler presentation objects do not go through this method if they are invoked from within the presentation manager. However, direct URL requests to ErrorHandler presentation objects will go through this function.

Note: unlike the method servletRequestPreprocessor(), this method is commonly used in most applications. It is the only place that the application has where all requests come through. So you could, for example, put a check for HTTP basic authentication here, and that would automatically protect your entire application. Or, if you were so inclined, you could have a counter that counts the total pages served by your application.

Parameters:
comms - Object containing request, response and redirect objects.
Returns:
true if the request has been handled, false if normal request handling should continue.
Throws:
java.lang.Exception - Any exception can be thrown. PageRedirectExceptions are handled as with presentation object. Other exceptions are handled by searching for an error handler starting at the requested presentation object.

requestPostProcessor

void requestPostProcessor(com.lutris.appserver.server.httpPresentation.HttpPresentationComms comms)
                          throws java.lang.Exception
Request post-processing method. All requests for URLs associated with this application go through this function. It may do any post-processing desired (e.g. saving sessions to persistent store).

Parameters:
comms - Object containing request, response and redirect objects.
Throws:
java.lang.Exception - Any exception can be thrown. PageRedirectExceptions are handled as with presentation object. Other exceptions are handled by searching for an error handler starting at the requested presentation object.

servletRequestPreprocessor

boolean servletRequestPreprocessor(javax.servlet.Servlet servlet,
                                   javax.servlet.ServletContext context,
                                   javax.servlet.http.HttpServletRequest request,
                                   javax.servlet.http.HttpServletResponse response)
                                   throws javax.servlet.ServletException,
                                          java.io.IOException
This preprocessor hook is called before the request/response pair is processed by the HttpPresentationServlet. It gives the application a chance to work with the raw request/response pair before they are wrapped by HttpPresentationRequest and HttpPresentationResponse objects. Return false to indicate that the request should continue to be processed normally or true to indicate that this method has handled the request, and all processing of the request should stop, in which case it will not be passed on to the presentation manager etc... The default method in StandardApplication always returns false.

Almost all applications should not override this! The version provided by StandardApplication simply returns false. Currently the debugger is the only application that used this, to support the flow-through debugging of non-Enhydra servlets, it needs to pass the raw request/response pair to the target servlet.

Parameters:
servlet - The servlet we are running in.
context - The ServletContext that was used to initialize our servlet.
request - The incomming request object.
response - The incomming response object.
Returns:
True if this method handled the request, in which case no further action will be taken. Or false if normal processing should continue.
Throws:
javax.servlet.ServletException - You are allowed to throw the same exceptions that the servlet's service() method throws.
java.io.IOException - You are allowed to throw the same exceptions that the servlet's service() method throws.

setLogChannel

void setLogChannel(LogChannel chan)
Set the LogChannel associated with this application.

Parameters:
The - LogChannel to write to.

getLogChannel

LogChannel getLogChannel()
Get the LogChannel associated with this application.

Returns:
The log channel or null if this application does not have one.

getSessionManager

SessionManager getSessionManager()
Get the SessionManager associated with this application.

Returns:
The session manager or null if the application doesn't have a SessionManager.

getDatabaseManager

DatabaseManager getDatabaseManager()
Get the DatabaseManager associated with this application.

Returns:
The database manager or null if the application doesn't have a DatabaseManager.

getHttpPresentationManager

com.lutris.appserver.server.httpPresentation.HttpPresentationManager getHttpPresentationManager()
Get the HttpPresentationManager associated with this application.

Returns:
The presentation manager used by this application.

setHttpPresentationManager

void setHttpPresentationManager(com.lutris.appserver.server.httpPresentation.HttpPresentationManager pm)
Called to tell the application about the presentation manager instance. This is necessary because the Presentation Manager is created in parallel with the application by the HttpPresentationServlet.

Parameters:
pm - The presentation manager responsible for running this application.

getXMLCFactory

org.enhydra.xml.xmlc.XMLCFactory getXMLCFactory()
Get the XMLC factory object being used by the application. If one was not configured, a default one is created on the first call to this method.


setXMLCFactory

void setXMLCFactory()
Set the XMLC factory based on the deferred parsing option.


setJivanFactory

void setJivanFactory(boolean reload)
Initializes the Jivan factory object which can be used by application.

Parameters:
reload - switch which indicates reloading status of Jivan generated pages in presentation layer (true = reload is on, false = reload is off)

getJivanFactory

org.enhydra.util.jivan.JivanFactory getJivanFactory()
Get the Jivan factory object being used by the application.


EAF 7.6 API