##### Coverage Report - org.webmacro.WebMacro

Classes in this File | Line Coverage | Branch Coverage | Complexity
WebMacro |
N/A | N/A
N/A | N/A
| 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 |  |