org.webmacro.servlet
Class WMServlet

java.lang.Object
  javax.servlet.GenericServlet
      javax.servlet.http.HttpServlet
          org.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 an abstract base class which can be used to implement a kind of WebMacro servlet. 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

protected Log

_log Log object used to write out messages

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.
protected java.lang.String	getErrorTemplateName()
protected java.lang.String	getErrorVariableName() Returns the name of the error variable, as per the config.
FastWriter	getFastWriter(java.io.OutputStream out, java.lang.String enctype) Deprecated.
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; can be overridden
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() Deprecated.
WebMacro	initWebMacro() This method returns the WebMacro object which will be used to load, access, and manage the Broker.
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.
WebContext	newWebContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
protected void	setLocale(javax.servlet.http.HttpServletResponse resp, java.util.Locale locale) Set the locale on the response.
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

Field Detail

_log

protected Log _log

Log object used to write out messages

Constructor Detail

WMServlet

public WMServlet()

Method Detail

init

public 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 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 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. Once the stop() method has been called, the nested WM will be destroyed and then the parent destroy() method will be invoked.

Specified by:

destroy in interface WebMacro

See Also:

WM.destroy()

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 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

getErrorVariableName

protected java.lang.String getErrorVariableName()

Returns the name of the error variable, as per the config.

Returns:

Name to use for the error variable in templates

getBroker

public 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 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 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 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 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 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 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 Context getContext()

Create a new Context object

Specified by:

getContext in interface WebMacro

getWebContext

public WebContext getWebContext(javax.servlet.http.HttpServletRequest req,
                                javax.servlet.http.HttpServletResponse res)

Create a new WebContext object; can be overridden

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 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

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 final WebContext initWebContext()
                                throws InitException

Deprecated.

NO LONGER USED Exists only to catch implementations that use it. Use newWebContext instead.

Throws:

InitException

newWebContext

public WebContext newWebContext(javax.servlet.http.HttpServletRequest req,
                                javax.servlet.http.HttpServletResponse resp)

setLocale

protected void setLocale(javax.servlet.http.HttpServletResponse resp,
                         java.util.Locale locale)

Set the locale on the response. The reflection trickery is because this is only defined for JSDK 2.2+

getFastWriter

public FastWriter getFastWriter(java.io.OutputStream out,
                                java.lang.String enctype)
                         throws java.io.UnsupportedEncodingException

Deprecated.

Get a new FastWriter. 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

getErrorTemplateName

protected java.lang.String getErrorTemplateName()