org.webmacro
Class WM

java.lang.Object
  |
  +--org.webmacro.WM
All Implemented Interfaces:
WebMacro

public class WM
extends java.lang.Object
implements WebMacro

This class implements the WebMacro Manager interface. You can instantiate this yourself if you want to use WebMacro in standalone mode, rather than subclassing from org.webmacro.servlet.WMServlet. This is actually the same class used by the servlet framework to manage access to the broker there, so you really don't lose much of anything by choosing to go standalone by using this object. All you have to do is come up with your own context objects.


Fields inherited from interface org.webmacro.WebMacro
VERSION
 
Constructor Summary
WM()
          Constructs a WM which gets its properties (optionally) from the file WebMacro.properties, as found on the class path.
WM(Broker broker)
          Constructs a WM from an arbitrary Broker.
WM(javax.servlet.Servlet s)
          Constructs a WM is tied to a Servlet broker.
WM(java.lang.String config)
          Constructs a WM which gets its properties from the file specified, which must exist on the class path or be an absolute path.
 
Method Summary
 void destroy()
          Call this method when you are finished with WebMacro.
protected  void finalize()
          You should never call this method, on any object.
 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.
 Context getContext()
          Instantiate a new context from a pool.
 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 using the type as the description
 Log getLog(java.lang.String type, java.lang.String description)
          Get a log to write information to.
 Template getTemplate(java.lang.String key)
          Retrieve a template from the "template" provider.
 java.lang.String getURL(java.lang.String url)
          Retrieve a URL from the "url" provider.
 WebContext getWebContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Instantiate a new webcontext from a pool.
 boolean isDestroyed()
          This message returns false until you destroy() this object, subsequently it returns true.
 java.lang.String toString()
           
 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 java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

WM

public WM()
   throws InitException
Constructs a WM which gets its properties (optionally) from the file WebMacro.properties, as found on the class path. No servlet integration. Templates will be loaded from the class path or from TemplatePath. Most users will want to use the WM(Servlet) constructor.

WM

public WM(java.lang.String config)
   throws InitException
Constructs a WM which gets its properties from the file specified, which must exist on the class path or be an absolute path. No servlet integration. Templates will be loaded from the class path or from TemplatePath. Most users will want to use the WM(Servlet) constructor.

WM

public WM(javax.servlet.Servlet s)
   throws InitException
Constructs a WM is tied to a Servlet broker. Depending on the servlet containers level of servlet support, property fetching, logging, and template fetching will be managed by the servlet broker.

WM

public WM(Broker broker)
   throws InitException
Constructs a WM from an arbitrary Broker. Don't use this unless you have very specific needs and know what you are doing; constructing a properly functioning broker is not obvious.
Method Detail

destroy

public final void destroy()
Call this method when you are finished with WebMacro. If you don't call this method, the Broker and all of WebMacro's caches may not be properly shut down, potentially resulting in loss of data, and wasted memory. This method is called in the finalizer, but it is best to call it as soon as you know you are done with WebMacro.

After a call to destroy() attempts to use this object may yield unpredicatble results.

Specified by:
destroy in interface WebMacro

toString

public java.lang.String toString()
Overrides:
toString in class java.lang.Object

isDestroyed

public final boolean isDestroyed()
This message returns false until you destroy() this object, subsequently it returns true. Do not attempt to use this object after it has been destroyed.
Specified by:
isDestroyed in interface WebMacro

finalize

protected void finalize()
                 throws java.lang.Throwable
You should never call this method, on any object. Leave it up to the garbage collector. If you want to shut this object down, call destroy() instead. If you subclass this message, be sure to call super.finalize() since this is one of the cases where it matters.
Overrides:
finalize in class java.lang.Object

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

getFastWriter

public final 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. It can be null if only want the fast writer to buffer the output.
enctype - the Encoding type to use

getContext

public final Context getContext()
Instantiate a new context from a pool. This method is more efficient, in terms of object creation, than creating a Context directly. The Context will return to the pool when Context.recycle() is called.
Specified by:
getContext in interface WebMacro

getWebContext

public final WebContext getWebContext(javax.servlet.http.HttpServletRequest req,
                                      javax.servlet.http.HttpServletResponse resp)
Instantiate a new webcontext from a pool. This method is more efficient, in terms of object creation, than creating a WebContext object directly. The WebContext will return to the pool when WebContext.recycle() is called.
Specified by:
getWebContext in interface WebMacro

getTemplate

public final Template getTemplate(java.lang.String key)
                           throws ResourceException
Retrieve a template from the "template" provider.
Specified by:
getTemplate in interface WebMacro
Throws:
NotFoundException - if the template could not be found
ResourceException - if the template could not be loaded

getURL

public final java.lang.String getURL(java.lang.String url)
                              throws ResourceException
Retrieve a URL from the "url" provider. Equivalent to getBroker().getValue("url",url)
Specified by:
getURL in interface WebMacro
Throws:
NotFoundException - if the template could not be found
ResourceException - if the template could not be loaded

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",key)
Specified by:
getConfig in interface WebMacro
Throws:
NotFoundException - could not locate requested information

getLog

public final Log getLog(java.lang.String type,
                        java.lang.String description)
Get a log to write information to. Log type names should be lower case and short. They may be printed on every line of the log file. The description is a longer explanation of the type of log messages you intend to produce with this Log object.
Specified by:
getLog in interface WebMacro

getLog

public final Log getLog(java.lang.String type)
Get a log using the type as the description
Specified by:
getLog in interface WebMacro

writeTemplate

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