com.arsdigita.dispatcher
Class BaseDispatcherServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          com.arsdigita.dispatcher.BaseDispatcherServlet

All Implemented Interfaces:

Dispatcher, com.arsdigita.dispatcher.DispatcherConstants, Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig

Direct Known Subclasses:

JSPApplicationDispatcher, KernelDispatcherServlet

public abstract class BaseDispatcherServlet

extends javax.servlet.http.HttpServlet

implements Dispatcher, com.arsdigita.dispatcher.DispatcherConstants

Contains functions common to all entry-point dispatcher servlets in the core. Any dispatcher that is the first in its chain to handle an HTTP request must also be a servlet and should extend this class.

You do not need to extend this class unless your dispatcher is also a servlet and is mounted in web.xml. In any given ACS installation, you generally only have one servlet that is mounted through web.xml, and that is usually the com.arsdigita.sitenode.SiteNodeDispatcher, mapped to URL "/".

When a request comes in:

• first we try to serve a concrete file that matches the URL (for example, if the URL is /dir/image.gif, try to serve $docroot/dir/image.gif)
• if the URL has no extension we assume it is a virtual directory. if there is no trailing slash, redirect to URL + "/".
• if the URL has no extension and a trailing slash, it is treated as a directory. If the directory exists as a concrete directory on disk, and has a welcome file (index.*) then serve as a directory by forwarding to the "default" servlet.
• if there is no concrete match for the URL on disk, we set up a RequestContext object that acts as a request wrapper storing metadata about the request; and call the dispatch method.

Since:

4.5

Version:

ACS 4.5

Author:

Bill Schneider

See Also:

Serialized Form

Field Summary

static String	DISPATCHER_PREFIX_ATTR
static String	ERROR_REQUEST_ATTRIBUTE Attribute name for the URI that caused an error when the servlet container forwards to an error page.
static String	INCLUDE_URI The attribute name for an included resource URI after a servlet include (nesting).
static String	JSP_EXCEPTION_ATTRIBUTE Attribute name for the Throwable object saved when a JSP handles an error with the errorPage directive.
static String	ORIGINAL_REQUEST_ATTR The attribute where we store the original HttpServletRequest object when we need to wrap the servlet request.
static String	REDIRECT_SEMAPHORE The session attribute where we store an identifier for the previous request that made a redirect.
static String	REENTRANCE_ATTRIBUTE Attribute name to indicate that the dispatcher is within a request--that is, request start listeners have run but request end listeners haven't yet.
static String	REQUEST_CONTEXT_ATTR The attribute where we store the current RequestContext object.
static String	versionId
static String	WELCOME_FILES The application attribute (in ServletContext) where we store the list of welcome files from web.xml.
static String	WRAPPED_REQUEST_ATTR The attribute where we store the wrapped servlet request object when we need to restore the original request object for a forward/include.

Constructor Summary

BaseDispatcherServlet()

Method Summary

static void	addRequestListener(RequestListener rl) Adds a request listener to this.
protected abstract RequestContext	authenticateUser(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, RequestContext ctx) A placeholder method for performing user authentication during request processing.
protected void	fireFinishedListener(RequestEvent evt) Fires all finished listeners.
protected void	fireStartListener(RequestEvent evt) Fires all start listeners.
void	init() Reads web.xml to get the configured list of welcome files.
void	service(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp) Called directly by the servlet container when this servlet is invoked from a URL request.

Methods inherited from class javax.servlet.http.HttpServlet

doDelete, doGet, doHead, doOptions, doPost, doPut, doTrace, getLastModified, service

Methods inherited from class javax.servlet.GenericServlet

destroy, getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, init, log, log

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.arsdigita.dispatcher.Dispatcher

dispatch

Field Detail

versionId

public static final String versionId

See Also:

Constant Field Values

JSP_EXCEPTION_ATTRIBUTE

public static final String JSP_EXCEPTION_ATTRIBUTE

Attribute name for the Throwable object saved when a JSP handles an error with the errorPage directive.

See Also:

Constant Field Values

ERROR_REQUEST_ATTRIBUTE

public static final String ERROR_REQUEST_ATTRIBUTE

Attribute name for the URI that caused an error when the servlet container forwards to an error page.

See Also:

Constant Field Values

REENTRANCE_ATTRIBUTE

public static final String REENTRANCE_ATTRIBUTE

Attribute name to indicate that the dispatcher is within a request--that is, request start listeners have run but request end listeners haven't yet.

See Also:

Constant Field Values

INCLUDE_URI

public static final String INCLUDE_URI

The attribute name for an included resource URI after a servlet include (nesting).

See Also:

Constant Field Values

REQUEST_CONTEXT_ATTR

public static final String REQUEST_CONTEXT_ATTR

The attribute where we store the current RequestContext object.

See Also:

Constant Field Values

ORIGINAL_REQUEST_ATTR

public static final String ORIGINAL_REQUEST_ATTR

The attribute where we store the original HttpServletRequest object when we need to wrap the servlet request.

See Also:

Constant Field Values

WRAPPED_REQUEST_ATTR

public static final String WRAPPED_REQUEST_ATTR

The attribute where we store the wrapped servlet request object when we need to restore the original request object for a forward/include.

See Also:

Constant Field Values

REDIRECT_SEMAPHORE

public static final String REDIRECT_SEMAPHORE

The session attribute where we store an identifier for the previous request that made a redirect. This prohibits us from following a redirect until after the request that generated the redirect commits its transaction.

See Also:

Constant Field Values

WELCOME_FILES

public static final String WELCOME_FILES

The application attribute (in ServletContext) where we store the list of welcome files from web.xml.

See Also:

Constant Field Values

DISPATCHER_PREFIX_ATTR

public static final String DISPATCHER_PREFIX_ATTR

See Also:

Constant Field Values

Constructor Detail

BaseDispatcherServlet

public BaseDispatcherServlet()

Method Detail

init

public void init()
          throws javax.servlet.ServletException

Reads web.xml to get the configured list of welcome files. We have to read web.xml ourselves because there is no public API to get this information from the ServletContext.

Throws:

javax.servlet.ServletException

addRequestListener

public static void addRequestListener(RequestListener rl)

Adds a request listener to this.

Parameters:

rl - the RequestListener to add to the listener list

authenticateUser

protected abstract RequestContext authenticateUser(javax.servlet.http.HttpServletRequest req,
                                                   javax.servlet.http.HttpServletResponse resp,
                                                   RequestContext ctx)
                                            throws RedirectException

A placeholder method for performing user authentication during request processing. Subclasses should override this method.

Parameters:

req - the current servlet request object

Returns:

the updated request context (which may be the same as the context context parameter).

Throws:

RedirectException - if the dispatcher should redirect the client to the page contained in the exception

service

public void service(javax.servlet.http.HttpServletRequest req,
                    javax.servlet.http.HttpServletResponse resp)
             throws javax.servlet.ServletException,
                    IOException

Called directly by the servlet container when this servlet is invoked from a URL request. First tries to dispatch the URL to a concrete file on disk, if there is a matching file. Otherwise, sets up an initial RequestContext, tries to identify the user/session, parses form variables, and wraps the request object to handle multipart forms if necessary. Calls the dispatch method as declared in implementing subclasses.

Parameters:

req - the servlet request

resp - the servlet response

Throws:

javax.servlet.ServletException - re-thrown when dispatch throws an exception

IOException - re-thrown when dispatch throws an IOException

fireFinishedListener

protected void fireFinishedListener(RequestEvent evt)

Fires all finished listeners. Collects and logs errors to ensure that all finished listeners run.

Parameters:

evt - the current RequestEvent to broadcast to all event listeners

fireStartListener

protected void fireStartListener(RequestEvent evt)

Fires all start listeners. Does not collect and log errors. Instead, a runtime failure in a start listener will inhibit further servicing of the request.

Parameters:

evt - the current RequestEvent to broadcast to all event listeners