All Packages  Class Hierarchy  This Package  Previous  Next  Index

Class org.webmacro.servlet.WMServlet

java.lang.Object
   |
   +----javax.servlet.GenericServlet
           |
           +----javax.servlet.http.HttpServlet
                   |
                   +----org.webmacro.servlet.WMServlet

public abstract class WMServlet
extends HttpServlet
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 ResourceBroker. It also provides a couple of convenience functions that access the ResourceBroker and/or WebContext to make some commonly accessed services more readily available.

See Also:
Handler, ResourceBroker

Constructor Index

 o WMServlet()

Method Index

 o destroy()
This method is called by the servlet runner--do not call it.
 o doGet(HttpServletRequest, HttpServletResponse)
Process an incoming GET request: Builds a WebContext up and then passes it to the handle() method.
 o doPost(HttpServletRequest, HttpServletResponse)
Behaves exactly like doGet() except that it reads data from POST before doing exactly the same thing.
 o error(WebContext, String)
Create an error template using the built in error handler.
 o execute(Template, WebContext)
This method takes a populated context and a template and writes out the interpreted template to the context's output stream.
 o 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.
 o getConfig(String)
Retrieve configuration information from the "config" provider.
 o getHandler(String)
Retrieve a handler from the "handler" provider.
 o getTemplate(String)
Retrieve a template from the "template" provider.
 o handle(WebContext)
Override this method and put your controller code here.
 o init()
This method is called by the servlet runner--do not call it.
 o init(ServletConfig)
This is the old-style init method, it just calls init(), after handing the ServletConfig object to the superclass
 o start()
Override this method to implement any startup/init code you require.
 o stop()
Override this method to implement any shutdown code you require.

Constructors

 o WMServlet
 public WMServlet()

Methods

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

Throws: ServletException
if it failed to initialize
Overrides:
init in class GenericServlet
 o init
 public final synchronized 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.

Throws: ServletException
if it failed to initialize
 o destroy
 public final synchronized 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.

Overrides:
destroy in class GenericServlet
 o doGet
 protected final void doGet(HttpServletRequest req,
                            HttpServletResponse resp) throws ServletException, 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: ServletException
if we can't get our configuration
Throws: IOException
if we can't write to the output stream
Overrides:
doGet in class HttpServlet
 o doPost
 protected final void doPost(HttpServletRequest req,
                             HttpServletResponse resp) throws ServletException, 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: ServletException
if we can't get our configuration
Throws: IOException
if we can't read/write to the streams we got
Overrides:
doPost in class HttpServlet
 o error
 protected final Template error(WebContext context,
                                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
 o getBroker
 protected final ResourceBroker 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.

 o getTemplate
 protected final Template getTemplate(String key) throws ResourceUnavailableException
Retrieve a template from the "template" provider. Equivalent to getBroker().getValue(TemplateProvider.TYPE,key)

Throws: ResourceUnavailableException
if the template was not found
 o getHandler
 protected final Handler getHandler(String key) throws ResourceUnavailableException
Retrieve a handler from the "handler" provider. Equivalent to getBroker().getValue(HandlerProvider.TYPE,key)

Throws: ResourceUnavailableException
if the handler was not found
 o getConfig
 protected final String getConfig(String key) throws ResourceUnavailableException
Retrieve configuration information from the "config" provider. Equivalent to getBrker().getValue(Config.TYPE,key)

Throws: ResourceUnavailableException
could not locate requested information
 o execute
 protected final 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.

 o handle
 protected abstract Template handle(WebContext context) throws HandlerException
Override this method and put your controller code here. This is the primary method that you will write. Use the many other methods on this object to assist you. Your job is to process the input, put whatever will be needed into the WebContext hash, locate the appropriate template, and return it.

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, getConfig, getBroker
 o start
 protected void start() throws 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: ServletException
to indicate initialization failed
 o 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.


All Packages  Class Hierarchy  This Package  Previous  Next  Index