Coverage Report - org.webmacro.WebMacro
 
Classes in this File Line Coverage Branch Coverage Complexity
WebMacro
N/A
N/A
1
 
 1  
 /*
 2  
  * Copyright (C) 1998-2000 Semiotek Inc.  All Rights Reserved.
 3  
  *
 4  
  * Redistribution and use in source and binary forms, with or without
 5  
  * modification, are permitted under the terms of either of the following
 6  
  * Open Source licenses:
 7  
  *
 8  
  * The GNU General Public License, version 2, or any later version, as
 9  
  * published by the Free Software Foundation
 10  
  * (http://www.fsf.org/copyleft/gpl.html);
 11  
  *
 12  
  *  or
 13  
  *
 14  
  * The Semiotek Public License (http://webmacro.org/LICENSE.)
 15  
  *
 16  
  * This software is provided "as is", with NO WARRANTY, not even the
 17  
  * implied warranties of fitness to purpose, or merchantability. You
 18  
  * assume all risks and liabilities associated with its use.
 19  
  *
 20  
  * See www.webmacro.org for more information on the WebMacro project.
 21  
  */
 22  
 
 23  
 
 24  
 package org.webmacro;
 25  
 
 26  
 import org.slf4j.Logger;
 27  
 
 28  
 import java.io.OutputStream;
 29  
 import java.io.UnsupportedEncodingException;
 30  
 
 31  
 /**
 32  
  * WebMacro Manager Interface
 33  
  *
 34  
  * This interface provides root access into the WebMacro system. Use it to
 35  
  * obtain references to other WebMacro objects which you might need.
 36  
  * <p>
 37  
  * Create a new instance of this object in each thread that intends to
 38  
  * use WebMacro, and destroy() it when you're done. It probably maintains
 39  
  * a static reference count of the number of users of the broker,
 40  
  * and automatically shuts down the underlying broker when the last
 41  
  * instance is destroyed.
 42  
  */
 43  
 public interface WebMacro
 44  
 {
 45  
 
 46  
     /**
 47  
      * The current version of WebMacro.  
 48  
      * No longer using ant filtering.
 49  
      */
 50  
     public static final String VERSION = "2.2";
 51  
     public static final String BUILD_DATE = "2010-02-22";
 52  
 
 53  
     /**
 54  
      * This object is used to access components that have been plugged
 55  
      * into WebMacro; it is shared between all instances of this class and
 56  
      * its subclasses. It is created when the first instance is initialized,
 57  
      * and deleted when the last instance is shut down. If you attempt to
 58  
      * access it after the last servlet has been shutdown, it will either
 59  
      * be in a shutdown state or else null.
 60  
      */
 61  
     public Broker getBroker ();
 62  
 
 63  
 
 64  
     /**
 65  
      * Get a new FastWriter
 66  
      * A FastWriter is used when writing templates to an output stream.<p>
 67  
      *
 68  
      * If using a FastWriter directly, <b>always</b> make sure to <code>flush()</code>
 69  
      * and <code>close()</code> it when you're finished.  
 70  
      *
 71  
      * @param out The output stream the FastWriter should write to.  Typically
 72  
      *            this will be your ServletOutputStream
 73  
      * @param enctype the Encoding type to use
 74  
      *
 75  
      * @throws java.io.UnsupportedEncodingException if the encoding type
 76  
      *         specified is not supported by your JVM.
 77  
      * @deprecated
 78  
      */
 79  
     public FastWriter getFastWriter (OutputStream out, String enctype)
 80  
             throws UnsupportedEncodingException;
 81  
 
 82  
     /**
 83  
      * Retrieve a template from the "template" provider. Equivalent to
 84  
      * getBroker().get(TemplateProvider.getType(),key)
 85  
      * @exception NotFoundException if the template was not found
 86  
      * @exception ResourceException if the template could not be loaded
 87  
      */
 88  
     public Template getTemplate (String key) throws ResourceException;
 89  
 
 90  
     /**
 91  
      * Retrieve the contents of a URL as a String. The only advantage of
 92  
      * using this instead of a regular URL object is that the result may
 93  
      * be cached for repeated use.
 94  
      */
 95  
     public String getURL (String url) throws ResourceException;
 96  
 
 97  
     /**
 98  
      * Retrieve configuration information from the "config" provider.
 99  
      * Equivalent to getBroker().get(Config.geType(),key)
 100  
      * @exception NotFoundException could not locate requested information
 101  
      */
 102  
     public String getConfig (String key) throws NotFoundException;
 103  
 
 104  
     /**
 105  
      * Create a new Context. You will likely call this method on every
 106  
      * request to create the Context you require for template execution.
 107  
      * Fill the Context up with the data you wish to display on the
 108  
      * template.
 109  
      */
 110  
     public Context getContext ();
 111  
 
 112  
     /**
 113  
      * Get a log to write information to. The log messages will
 114  
      * be output to one or more pre-configured log files. The
 115  
      * type you specify will be printed in the log next to
 116  
      * any message you log. See the WebMacro.properties (or other
 117  
      * configuration) for information on how to set up and
 118  
      * control logging.
 119  
      */
 120  
     //public Logger getLog (String type, String description);
 121  
 
 122  
     /**
 123  
      * Get a log using the type as the description
 124  
      */
 125  
     //public Logger getLog (String type);
 126  
 
 127  
     /**
 128  
      * Create a new WebContext object. This returns a Context object
 129  
      * with special knowledge of servlets (request and response)
 130  
      * thereby enabling some extra functionality. If you are using
 131  
      * WebMacro under a servlet this is the preferred method,
 132  
      * otherwise you ought to use getContext().
 133  
      */
 134  
     public org.webmacro.servlet.WebContext
 135  
             getWebContext (javax.servlet.http.HttpServletRequest req,
 136  
                            javax.servlet.http.HttpServletResponse resp);
 137  
 
 138  
 
 139  
     /**
 140  
      * Convienence method for writing a template to an OutputStream.
 141  
      * This method takes care of all the typical work involved
 142  
      * in writing a template.<p>
 143  
      *
 144  
      * This method uses the <code>TemplateOutputEncoding</code> defined in
 145  
      * WebMacro.defaults, or your custom WebMacro.properties.
 146  
      *
 147  
      * @param templateName name of Template to write.  Must be accessible
 148  
      *                     via TemplatePath
 149  
      * @param out          where the output of the template should go
 150  
      * @param context      The Context (can be a WebContext too) used
 151  
      *                     during the template evaluation phase
 152  
      * @throws java.io.IOException if the template cannot be written to the
 153  
      *                             specified output stream
 154  
      * @throws ResourceException if the template name specified cannot be found
 155  
      * @throws PropertyException if a fatal error occured during the Template
 156  
      *                           evaluation phase
 157  
      */
 158  
     public void writeTemplate (String templateName, java.io.OutputStream out,
 159  
                                Context context)
 160  
             throws java.io.IOException, ResourceException, PropertyException;
 161  
 
 162  
     /**
 163  
      * Convienence method for writing a template to an OutputStream.
 164  
      * This method takes care of all the typical work involved
 165  
      * in writing a template.
 166  
      *
 167  
      * @param templateName name of Template to write.  Must be accessible
 168  
      *                     via TemplatePath
 169  
      * @param out          where the output of the template should go
 170  
      * @param encoding     character encoding to use when writing the template
 171  
      *                     if the encoding is <code>null</code>, the default
 172  
      *                     <code>TemplateOutputEncoding</code> is used
 173  
      * @param context      The Context (can be a WebContext too) used
 174  
      *                     during the template evaluation phase
 175  
      * @throws java.io.IOException if the template cannot be written to the
 176  
      *                             specified output stream
 177  
      * @throws ResourceException if the template name specified cannot be found
 178  
      * @throws PropertyException if a fatal error occured during the Template
 179  
      *                           evaluation phase
 180  
      */
 181  
     public void writeTemplate (String templateName, java.io.OutputStream out,
 182  
                                String encoding, Context context)
 183  
             throws java.io.IOException, ResourceException, PropertyException;
 184  
 
 185  
 
 186  
     /**
 187  
      * Destroy this WebMacro implementation which should de-allocate
 188  
      * any resources that have been created inside the implementation
 189  
      * of WebMacro.
 190  
      **/
 191  
     public void destroy();
 192  
 }
 193