com.arsdigita.dispatcher
Class MapDispatcher

java.lang.Object
  extended bycom.arsdigita.dispatcher.MapDispatcher
All Implemented Interfaces:
Dispatcher
Direct Known Subclasses:
BebopMapDispatcher

public class MapDispatcher
extends Object
implements Dispatcher

Base class for a generic URL-to-Dispatcher mapping dispatch. This class may be used directly by applications, or it may be subclassed to be coded with a specific map or override the map lookup for certain sets of URLs.

URLs are mapped to Dispatcher objects. When the dispatch method is called, this first looks up the remainingURL (from the request context) in the map and dispatches to the target object. Then we call the dispatch method on the target.

A configurable "not found" dispatcher is available to handle the case where no target is mapped for a URL. By default, this is set to JSPApplicationDispatcher. URLs that are not explicitly handled by a dispatcher in the map will be directed to assets in the file system.

Note: The MapDispatcher does not automatically set the status code to 404 when there is no exact mapping. If a not-found handler is specified, it is up to this specified dispatcher to set the status code appropriately.

Note that any URLs that do not have a file extension will automatically be required to have a trailing slash. Your relative links must compensate for this.

Example: Assume we set up a map dispatcher as follows:

 MapDispatcher mapDisp = new MapDispatcher();
 // default not-found dispatcher is JSPApplicationDispatcher
 Map m = new HashMap();
 m.put("page1", page1Dispatcher);
 m.put("page2", page2Dispatcher);
 mapDisp.setMap(m);
 
If this map dispatcher is associated with a package type "map-app" mounted on the site node "map", then request URLs will be mapped to actions as follows:
request URL action
/map/page1 redirected automatically to /map/page1/
/map/page1/ page1Dispatcher.dispatch(...);
/map/page2.ext page2Dispatcher.dispatch(...);
/map/image.gif serve file /packages/map-app/www/image.gif
/map/page.jsp serve file /packages/map-app/www/page.jsp
/map redirected to /map/
/map/ serve file /packages/map-app/www/index.jsp

Author:
Bill Schneider

Nested Class Summary
protected static class MapDispatcher.ParseConfigHandler
          SAX event handler class for parsing a dispatcher configuration file.
 
Field Summary
static String versionId
           
 
Constructor Summary
MapDispatcher()
           
 
Method Summary
 void addPage(String url, Dispatcher d)
          Adds a new dispatcher to the page map to handle a particular URL.
 void dispatch(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, RequestContext ctx)
          Looks up a target in the page map based on the remaining URL.
protected  Map getMap()
          Returns the page map for this dispatcher.
protected  org.xml.sax.helpers.DefaultHandler newParseConfigHandler(MapDispatcher md)
          Expirimental Returns a SAX event handler object for setting up a MapDispatcher using an XML config file.
protected  void preprocessRequest(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp, RequestContext ctx, String url)
          Provides the opportunity for subclasses to do some preprocessing of a given url, before it is handed off to the main dispatcher.
 void readFromFile(File file)
          Initializes URL-to-Page/Dispatcher/Servlet mappings from a file.
 void requireTrailingSlash(String url)
          Deprecated. Any URL in the map that does not end in an extension will be treated as a virtual directory and required to have a trailing slash.
 void setMap(Map m)
          Sets the page map for this dispatcher.
 void setNotFoundDispatcher(Dispatcher d)
          Sets the default page to display if no page can be found for the URL in the page map on dispatch.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

versionId

public static final String versionId
See Also:
Constant Field Values
Constructor Detail

MapDispatcher

public MapDispatcher()
Method Detail

dispatch

public void dispatch(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp,
                     RequestContext ctx)
              throws IOException,
                     javax.servlet.ServletException
Looks up a target in the page map based on the remaining URL. If that page is found, serves it. Otherwise serves a default not-found page.

Specified by:
dispatch in interface Dispatcher
Parameters:
req - the servlet request object
resp - the servlet response object
ctx - the request context
Throws:
javax.servlet.ServletException - may be thrown by the dispatcher to propagate a generic error to its caller
IOException - may be thrown by the dispatcher to indicate an I/O error

setMap

public void setMap(Map m)
Sets the page map for this dispatcher.

Parameters:
m - the page map (maps URLs to Pages).

preprocessRequest

protected void preprocessRequest(javax.servlet.http.HttpServletRequest req,
                                 javax.servlet.http.HttpServletResponse resp,
                                 RequestContext ctx,
                                 String url)
Provides the opportunity for subclasses to do some preprocessing of a given url, before it is handed off to the main dispatcher. The typical action is to set the cache control policy.


getMap

protected Map getMap()
Returns the page map for this dispatcher. Because it exposes the dispatcher to external mutation, this method is protected so that it may only be called by subclasses and other classes in com.arsdigita.dispatcher.

Returns:
the URL-target page map for this dispatcher.

addPage

public final void addPage(String url,
                          Dispatcher d)
Adds a new dispatcher to the page map to handle a particular URL.

Parameters:
url - dispatch to this handler when url == requestContext.remainingURL()
d - the dispatcher

setNotFoundDispatcher

public final void setNotFoundDispatcher(Dispatcher d)
Sets the default page to display if no page can be found for the URL in the page map on dispatch.

Parameters:
d - the dispatcher to use when no other handler can be found for a URL in the page map.

requireTrailingSlash

public void requireTrailingSlash(String url)
Deprecated. Any URL in the map that does not end in an extension will be treated as a virtual directory and required to have a trailing slash.


readFromFile

public final void readFromFile(File file)
Initializes URL-to-Page/Dispatcher/Servlet mappings from a file. Format of the file is XML:
 <dispatcher-configuration>
   <url-mapping
     <url>my-page</url>
     <dispatcher-class>com.arsdigita.Dispatcher.class</dispatcher-class>
     OR <page-class>com.arsdigita.Page.class</page-class>
     OR <servlet-name>servlet-pretty-name-from-web.xml</servlet-name>

   <url-mapping
   ...
   <default-handler>
     (same options as above: dispatcher-class, page-class, servlet-name)
   </default-handler>
 </dispatcher-url-map>
 


newParseConfigHandler

protected org.xml.sax.helpers.DefaultHandler newParseConfigHandler(MapDispatcher md)
Expirimental Returns a SAX event handler object for setting up a MapDispatcher using an XML config file.

Parameters:
md - the MapDispatcher to configure
Returns:
a SAX DefaultHandler object for handling SAX events


Copyright (c) 2004 Red Hat, Inc. Corporation. All Rights Reserved. Generated at July 20 2004:2337 UTC