org.webmacro
Interface WebMacro

All Known Implementing Classes:
WM, WMServlet

public interface WebMacro

WebMacro Manager Interface This interface provies root access into the WebMacro system. Use it to obtain references to other WebMacro objects which you might need.

Create a new instance of this object in each thread that intends to use WebMacro, and destroy() it when you're done. It probably maintains a static reference count of the number of users of the broker, and automatically shuts down the underlying broker when the last instance is destroyed.


Field Summary
static java.lang.String VERSION
          The current version of WebMacro.
 
Method Summary
 void destroy()
          Call this method when you are finished with WebMacro.
 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()
          Create a new Context.
 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 the contents of a URL as a String.
 WebContext getWebContext(javax.servlet.http.HttpServletRequest req, javax.servlet.http.HttpServletResponse resp)
          Create a new WebContext object.
 boolean isDestroyed()
          This message returns false until you destroy() this object, subsequently it returns true.
 void writeTemplate(java.lang.String templateName, java.io.OutputStream out, Context context)
          Convienence 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.
 

Field Detail

VERSION

public static final java.lang.String VERSION
The current version of WebMacro. The actual value is inserted by ANT during the "compile" process
Method Detail

destroy

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


isDestroyed

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

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.

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.

If using a FastWriter directly, always make sure to flush() and close() it when you're finished. Closing it automatically returns back to the pool for later reuse.

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.

getTemplate

public Template getTemplate(java.lang.String key)
                     throws ResourceException
Retrieve a template from the "template" provider. Equivalent to getBroker().get(TemplateProvider.getType(),key)
Throws:
NotFoundException - if the template was not found
ResourceException - if the template could not be loaded

getURL

public java.lang.String getURL(java.lang.String url)
                        throws ResourceException
Retrieve the contents of a URL as a String. The only advantage of using this instead of a regular URL object is that the result may be cached for repeated use.

getConfig

public java.lang.String getConfig(java.lang.String key)
                           throws NotFoundException
Retrieve configuration information from the "config" provider. Equivalent to getBroker().get(Config.geType(),key)
Throws:
NotFoundException - could not locate requested information

getContext

public Context getContext()
Create a new Context. You will likely call this method on every request to create the Context you require for template execution. Fill the Context up with the data you wish to display on the template.

getLog

public Log getLog(java.lang.String type,
                  java.lang.String description)
Get a log to write information to. The log messages will be output to one or more pre-configured log files. The type you specify will be printed in the log next to any message you log. See the WebMacro.properties (or other configuration) for information on how to set up and control logging.

getLog

public Log getLog(java.lang.String type)
Get a log using the type as the description

getWebContext

public WebContext getWebContext(javax.servlet.http.HttpServletRequest req,
                                javax.servlet.http.HttpServletResponse resp)
Create a new WebContext object. This returns a Context object with special knowledge of servlets (request and response) thereby enabling some extra functionality. If you are using WebMacro under a servlet this is the preferred method, otherwise you ought to use getContext().

writeTemplate

public void writeTemplate(java.lang.String templateName,
                          java.io.OutputStream out,
                          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.

This method uses the TemplateOutputEncoding defined in WebMacro.defaults, or your custom WebMacro.properties.

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