org.webmacro.servlet
Class WMServlet

java.lang.Object
  extended byjavax.servlet.GenericServlet
      extended byjavax.servlet.http.HttpServlet
          extended byorg.webmacro.servlet.WMServlet
All Implemented Interfaces:
java.io.Serializable, javax.servlet.Servlet, javax.servlet.ServletConfig, WebMacro

public abstract class WMServlet
extends javax.servlet.http.HttpServlet
implements WebMacro

This is the abstract base class used by all WebMacro servlets. You can either subclass from it directly, or make use of one of the generic subclasses provided.

It's primary function is to create a WebContext and manage a Broker. It also provides a couple of convenience functions that access the Broker and/or WebContext to make some commonly accessed services more readily available.

See Also:
Broker, Serialized Form

Field Summary
 
Fields inherited from interface org.webmacro.WebMacro
BUILD_DATE, VERSION
 
Constructor Summary
WMServlet()
           
 
Method Summary
 void destroy()
          This method is called by the servlet runner--do not call it.
 void destroyContext(WebContext wc)
          This method is called at the end of a request and is responsible for cleaning up the Context at the end of the request.
protected  void doGet(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Process an incoming GET request: Builds a WebContext up and then passes it to the handle() method.
protected  void doPost(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Behaves exactly like doGet() except that it reads data from POST before doing exactly the same thing.
protected  Template error(WebContext context, java.lang.String error)
          Create an error template using the built in error handler.
protected  void execute(Template tmpl, WebContext c)
          This method takes a populated context and a template and writes out the interpreted template to the context's output stream.
 Broker getBroker()
          This object is used to access components that have been plugged into WebMacro; it is shared between all instances of this class and its subclasses.
 java.lang.String getConfig(java.lang.String key)
          Retrieve configuration information from the "config" provider.
 java.lang.String getConfig(java.lang.String key, java.lang.String defaultValue)
          Retrieve configuration information from the "config" provider.
 Context getContext()
          Create a new Context object
 Template getErrorTemplate()
          Gets a template for displaying an error message.
 FastWriter getFastWriter(java.io.OutputStream out, java.lang.String enctype)
          Retrieve a FastWriter from WebMacro's internal pool of FastWriters.
 Log getLog(java.lang.String type)
          Get a Log object which can be used to write to the log file.
 Log getLog(java.lang.String type, java.lang.String description)
          Get a Log object which can be used to write to the log file.
 Template getTemplate(java.lang.String key)
          Retrieve a template from the "template" provider.
 java.lang.String getURL(java.lang.String url)
          Retrieve a URL.
 WebContext getWebContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse res)
          Create a new WebContext object
abstract  Template handle(WebContext context)
          This method is called to handle the processing of a request.
 void init()
          This method is called by the servlet runner--do not call it.
 void init(javax.servlet.ServletConfig sc)
          This is the old-style init method, it just calls init(), after handing the ServletConfig object to the superclass
 WebContext initWebContext()
          This method must return a cloneable WebContext which can be cloned for use in responding to individual requests.
 WebMacro initWebMacro()
          This method returns the WebMacro object which will be used to load, access, and manage the Broker.
 boolean isDestroyed()
          Check whether or not the broker we are using has been shut down
 WebContext newContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          This method is called at the beginning of a request and is responsible for providing a Context for the request.
protected  void start()
          Override this method to implement any startup/init code you require.
protected  void stop()
          Override this method to implement any shutdown code you require.
 void writeTemplate(java.lang.String templateName, java.io.OutputStream out, Context context)
          Convenience method for writing a template to an OutputStream.
 void writeTemplate(java.lang.String templateName, java.io.OutputStream out, java.lang.String encoding, Context context)
          Convienence method for writing a template to an OutputStream.
 
Methods inherited from class javax.servlet.http.HttpServlet
doDelete, doHead, doOptions, doPut, doTrace, getLastModified, service, service
 
Methods inherited from class javax.servlet.GenericServlet
getInitParameter, getInitParameterNames, getServletConfig, getServletContext, getServletInfo, getServletName, log, log
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

WMServlet

public WMServlet()
Method Detail

init

public final void init(javax.servlet.ServletConfig sc)
                throws javax.servlet.ServletException
This is the old-style init method, it just calls init(), after handing the ServletConfig object to the superclass

Specified by:
init in interface javax.servlet.Servlet
Throws:
javax.servlet.ServletException - if it failed to initialize

init

public final void init()
This method is called by the servlet runner--do not call it. It must not be overidden because it manages a shared instance of the broker--you can overide the start() method instead, which is called just after the broker is initialized.


destroy

public final void destroy()
This method is called by the servlet runner--do not call it. It must not be overidden because it manages a shared instance of the broker--you can overide the stop() method instead, which will be called just before the broker is shut down.

Specified by:
destroy in interface WebMacro

isDestroyed

public final boolean isDestroyed()
Check whether or not the broker we are using has been shut down

Specified by:
isDestroyed in interface WebMacro

doGet

protected void doGet(javax.servlet.http.HttpServletRequest req,
                     javax.servlet.http.HttpServletResponse resp)
              throws javax.servlet.ServletException,
                     java.io.IOException
Process an incoming GET request: Builds a WebContext up and then passes it to the handle() method. You can overide this if you want, though for most purposes you are expected to overide handle() instead.

Parameters:
req - the request we got
resp - the response we are generating
Throws:
javax.servlet.ServletException - if we can't get our configuration
java.io.IOException - if we can't write to the output stream

doPost

protected void doPost(javax.servlet.http.HttpServletRequest req,
                      javax.servlet.http.HttpServletResponse resp)
               throws javax.servlet.ServletException,
                      java.io.IOException
Behaves exactly like doGet() except that it reads data from POST before doing exactly the same thing. This means that you can use GET and POST interchangeably with WebMacro. You can overide this if you want, though for most purposes you are expected to overide handle() instead.

Parameters:
req - the request we got
resp - the response we are generating
Throws:
javax.servlet.ServletException - if we can't get our configuration
java.io.IOException - if we can't read/write to the streams we got

error

protected final Template error(WebContext context,
                               java.lang.String error)
Create an error template using the built in error handler. This is useful for returning error messages on failure; it is used by WMServlet to display errors resulting from any exception that you may throw from the handle() method.

Parameters:
context - will add error variable to context (see Config)
error - a string explaining what went wrong

getBroker

public final Broker getBroker()
This object is used to access components that have been plugged into WebMacro; it is shared between all instances of this class and its subclasses. It is created when the first instance is initialized, and deleted when the last instance is shut down. If you attempt to access it after the last servlet has been shutdown, it will either be in a shutdown state or else null.

Specified by:
getBroker in interface WebMacro

getLog

public final Log getLog(java.lang.String type,
                        java.lang.String description)
Get a Log object which can be used to write to the log file. Messages to the logfile will be associated with the supplied type. The type name should be short as it may be printed on every log line. The description is a longer explanation of the type of messages you intend to write to this Log.

Specified by:
getLog in interface WebMacro

getLog

public final Log getLog(java.lang.String type)
Get a Log object which can be used to write to the log file. Messages to the logfile will be associated with the supplied type. The type will be used as the description.

Specified by:
getLog in interface WebMacro

getTemplate

public final Template getTemplate(java.lang.String key)
                           throws ResourceException
Retrieve a template from the "template" provider. Equivalent to getBroker().get(TemplateProvider.TYPE,key)

Specified by:
getTemplate in interface WebMacro
Throws:
NotFoundException - if the template was not found
ResourceException - if the template coult not be loaded

getURL

public final java.lang.String getURL(java.lang.String url)
                              throws ResourceException
Retrieve a URL. This is largely equivalent to creating a URL object and requesting its content, though it will sit in WebMacro's cache rather than re-requesting each time. The content will be returned as an Object.

Specified by:
getURL in interface WebMacro
Throws:
ResourceException

getConfig

public final java.lang.String getConfig(java.lang.String key)
                                 throws NotFoundException
Retrieve configuration information from the "config" provider. Equivalent to getBroker().get(Config.TYPE,key)

Specified by:
getConfig in interface WebMacro
Throws:
NotFoundException - could not locate requested information

getConfig

public final java.lang.String getConfig(java.lang.String key,
                                        java.lang.String defaultValue)
Retrieve configuration information from the "config" provider. Return specified default if key could not be found


getContext

public final Context getContext()
Create a new Context object

Specified by:
getContext in interface WebMacro

getWebContext

public final WebContext getWebContext(javax.servlet.http.HttpServletRequest req,
                                      javax.servlet.http.HttpServletResponse res)
Create a new WebContext object

Specified by:
getWebContext in interface WebMacro

writeTemplate

public void writeTemplate(java.lang.String templateName,
                          java.io.OutputStream out,
                          Context context)
                   throws java.io.IOException,
                          ResourceException,
                          PropertyException
Convenience method for writing a template to an OutputStream. This method takes care of all the typical work involved in writing a template.

This method uses the default TemplateOutputEncoding specified in WebMacro.defaults or your custom WebMacro.properties.

Specified by:
writeTemplate in interface WebMacro
Parameters:
templateName - name of Template to write. Must be accessible via TemplatePath
out - where the output of the template should go
context - The Context (can be a WebContext too) used during the template evaluation phase
Throws:
java.io.IOException - if the template cannot be written to the specified output stream
ResourceException - if the template name specified cannot be found
PropertyException - if a fatal error occured during the Template evaluation phase

writeTemplate

public void writeTemplate(java.lang.String templateName,
                          java.io.OutputStream out,
                          java.lang.String encoding,
                          Context context)
                   throws java.io.IOException,
                          ResourceException,
                          PropertyException
Convienence method for writing a template to an OutputStream. This method takes care of all the typical work involved in writing a template.

Specified by:
writeTemplate in interface WebMacro
Parameters:
templateName - name of Template to write. Must be accessible via TemplatePath
out - where the output of the template should go
encoding - character encoding to use when writing the template if the encoding is null, the default TemplateOutputEncoding is used
context - The Context (can be a WebContext too) used during the template evaluation phase
Throws:
java.io.IOException - if the template cannot be written to the specified output stream
ResourceException - if the template name specified cannot be found
PropertyException - if a fatal error occured during the Template evaluation phase

execute

protected final void execute(Template tmpl,
                             WebContext c)
                      throws java.io.IOException
This method takes a populated context and a template and writes out the interpreted template to the context's output stream.

Throws:
java.io.IOException

newContext

public WebContext newContext(javax.servlet.http.HttpServletRequest req,
                             javax.servlet.http.HttpServletResponse resp)
                      throws HandlerException
This method is called at the beginning of a request and is responsible for providing a Context for the request. The default implementation calls WebContext.newInstance(req,resp) on the WebContext prototype returned by the initWebContext() method. This is probably suitable for most servlets, though you can override it and do something different if you like. You can throw a HandlerException if something goes wrong.

Throws:
HandlerException

handle

public abstract Template handle(WebContext context)
                         throws HandlerException
This method is called to handle the processing of a request. It should analyze the data in the request, put whatever values are required into the context, and return the appropriate view.

Parameters:
context - contains all relevant data structures, incl builtins.
Returns:
the template to be rendered by the WebMacro engine
Throws:
HandlerException - throw this to produce vanilla error messages
See Also:
getTemplate

destroyContext

public void destroyContext(WebContext wc)
                    throws HandlerException
This method is called at the end of a request and is responsible for cleaning up the Context at the end of the request. You may not need to do anything here, but it is sometimes important if you have an open database connection in your context that you need to close. The default implementation calls wc.clear().

Throws:
HandlerException

start

protected void start()
              throws javax.servlet.ServletException
Override this method to implement any startup/init code you require. The broker will have been created before this method is called; the default implementation does nothing. This is called when the servlet environment initializes the servlet for use via the init() method.

Throws:
javax.servlet.ServletException - to indicate initialization failed

stop

protected void stop()
Override this method to implement any shutdown code you require. The broker may be destroyed just after this method exits. This is called when the servlet environment shuts down the servlet via the shutdown() method. The default implementation does nothing.


initWebMacro

public WebMacro initWebMacro()
                      throws InitException
This method returns the WebMacro object which will be used to load, access, and manage the Broker. The default implementation is to return a new WM() object. You could override it and return a WM object constructed with a particular configuration file, or some other implementation of the WebMacro interface.

Throws:
InitException

initWebContext

public WebContext initWebContext()
                          throws InitException
This method must return a cloneable WebContext which can be cloned for use in responding to individual requests. Each incoming request will receive a clone of the returned object as its context. The default implementation is to return a new WebContext(getBroker());

Throws:
InitException

getFastWriter

public FastWriter getFastWriter(java.io.OutputStream out,
                                java.lang.String enctype)
                         throws java.io.UnsupportedEncodingException
Retrieve a FastWriter from WebMacro's internal pool of FastWriters. A FastWriter is used when writing templates to an output stream

Specified by:
getFastWriter in interface WebMacro
Parameters:
out - The output stream the FastWriter should write to. Typically this will be your ServletOutputStream
enctype - the Encoding type to use
Throws:
java.io.UnsupportedEncodingException - if the encoding type specified is not supported by your JVM.

getErrorTemplate

public Template getErrorTemplate()
Gets a template for displaying an error message. Tries to get configured template, then default template and lastly constructs a string template.

Returns:
A Template which can be used to format an error message