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 |