| Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
| WebMacro |
|
| 1.0;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 |