##### Coverage Report - org.melati.template.TemplateEngine

Classes in this File | Line Coverage | Branch Coverage | Complexity
TemplateEngine |
N/A | N/A
N/A | N/A
| 1.0;1

1 |  |
     /*
2 |  |
      * $Source: /usr/cvsroot/melati/melati/src/site/resources/withWebmacro/org.melati.template.TemplateEngine.html,v $
3 |  |
      * $Revision: 1.1 $
4 |  |
      *
5 |  |
      * Copyright (C) 2005 Tim Pizey
6 |  |
      *
7 |  |
      * Part of Melati (http://melati.org), a framework for the rapid
8 |  |
      * development of clean, maintainable web applications.
9 |  |
      *
10 |  |
      * Melati is free software; Permission is granted to copy, distribute
11 |  |
      * and/or modify this software under the terms either:
12 |  |
      *
13 |  |
      * a) the GNU General Public License as published by the Free Software
14 |  |
      *    Foundation; either version 2 of the License, or (at your option)
15 |  |
      *    any later version,
16 |  |
      *
17 |  |
      *    or
18 |  |
      *
19 |  |
      * b) any version of the Melati Software License, as published
20 |  |
      *    at http://melati.org
21 |  |
      *
22 |  |
      * You should have received a copy of the GNU General Public License and
23 |  |
      * the Melati Software License along with this program;
24 |  |
      * if not, write to the Free Software Foundation, Inc.,
25 |  |
      * 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA to obtain the
26 |  |
      * GNU General Public License and visit http://melati.org to obtain the
27 |  |
      * Melati Software License.
28 |  |
      *
29 |  |
      * Feel free to contact the Developers of Melati (http://melati.org),
30 |  |
      * if you would like to work out a different arrangement than the options
31 |  |
      * outlined here.  It is our intention to allow Melati to be used by as
32 |  |
      * wide an audience as possible.
33 |  |
      *
34 |  |
      * This program is distributed in the hope that it will be useful,
35 |  |
      * but WITHOUT ANY WARRANTY; without even the implied warranty of
36 |  |
      * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
37 |  |
      * GNU General Public License for more details.
38 |  |
      *
39 |  |
      * Contact details for copyright holder:
40 |  |
      *
41 |  |
      *     Tim Pizey <timp At paneris.org>
42 |  |
      *     http://paneris.org/~timp
43 |  |
      */
44 |  |
     package org.melati.template;
45 |  |
46 |  |
     import java.util.Enumeration;
47 |  |
48 |  |
     import org.melati.Melati;
49 |  |
     import org.melati.MelatiConfig;
50 |  |
     import org.melati.util.MelatiStringWriter;
51 |  |
     import org.melati.util.MelatiWriter;
52 |  |
53 |  |
     /**
54 |  |
      * A TemplateEngine typically evaluates a template containing variables
55 |  |
      * against a context containing values for those variables.
56 |  |
      *
57 |  |
      * The canonical java Template Engines are WebMacro and Velocity.
58 |  |
      *
59 |  |
      * @author timp At paneris.org
60 |  |
      */
61 |  |
     public interface TemplateEngine {
62 |  |
63 |  |
       /**
64 |  |
        * Initialise the Engine.
65 |  |
        *
66 |  |
        * @param melatiConfig a {@link MelatiConfig}
67 |  |
        * @throws TemplateEngineException if any problem occurs with the engine
68 |  |
        */
69 |  |
       void init(MelatiConfig melatiConfig) throws TemplateEngineException;
70 |  |
71 |  |
       /**
72 |  |
        * Create a new Context for this engine.
73 |  |
        *
74 |  |
        * @param melati the {@link Melati}
75 |  |
        * @throws TemplateEngineException if any problem occurs with the engine
76 |  |
        * @return a {@link TemplateContext}
77 |  |
        */
78 |  |
       TemplateContext getTemplateContext(Melati melati)
79 |  |
           throws TemplateEngineException;
80 |  |
81 |  |
       /**
82 |  |
        * The name of the template engine (used to find the templets).
83 |  |
        * @return the name of the current configured template engine
84 |  |
        */
85 |  |
       String getName();
86 |  |
87 |  |
       /**
88 |  |
        * @return the extension of the templates used by this template engine,
89 |  |
        * including the dot.
90 |  |
        */
91 |  |
       String templateExtension();
92 |  |
93 |  |
       /**
94 |  |
        * A root should not end in a slash.
95 |  |
        *
96 |  |
        * @return an Enumeration of string roots, always at least the empty string
97 |  |
        */
98 |  |
       Enumeration<String> getRoots();
99 |  |
100 |  |
       /**
101 |  |
        * Add a template root directory.
102 |  |
        * NOTE A root should not start or end in a slash.
103 |  |
        *
104 |  |
        * @param root the root to add
105 |  |
        */
106 |  |
       void addRoot(String root);
107 |  |
108 |  |
       /**
109 |  |
        * Get a template given it's full name.
110 |  |
        *
111 |  |
        * @param templateName the name of the template to find
112 |  |
        * @throws NotFoundException if template not found
113 |  |
        * @return a template
114 |  |
        */
115 |  |
       Template template(String templateName)
116 |  |
         throws NotFoundException;
117 |  |
118 |  |
       /**
119 |  |
        * The name of a template which exists.
120 |  |
        *
121 |  |
        * @param key short name, without path or extension
122 |  |
        * @param classifier a purpose or database name or similar qualifier
123 |  |
        * @return the name of a template, null if none found
124 |  |
        */
125 |  |
       String getTemplateName(String key, String classifier);
126 |  |
127 |  |
       /**
128 |  |
        * Expand the Template against the context.
129 |  |
        *
130 |  |
        * @param out             a {@link MelatiWriter} to output on
131 |  |
        * @param templateName    the name of the template to expand
132 |  |
        * @param templateContext the {@link ServletTemplateContext} to expand
133 |  |
        *                        the template against
134 |  |
        * @throws NotFoundException if template not found
135 |  |
        */
136 |  |
       void expandTemplate(MelatiWriter out, String templateName,
137 |  |
           TemplateContext templateContext) throws NotFoundException;
138 |  |
139 |  |
       /**
140 |  |
        * Expand the Template against the context, unwrapping any Access Exceptions.
141 |  |
        *
142 |  |
        * @param out             a {@link MelatiWriter} to output on
143 |  |
        * @param template        the {@link Template} to expand
144 |  |
        * @param templateContext the {@link ServletTemplateContext} to expand
145 |  |
        *                        the template against
146 |  |
        */
147 |  |
       void expandTemplate(MelatiWriter out, Template template,
148 |  |
           TemplateContext templateContext);
149 |  |
150 |  |
       /**
151 |  |
        * Expand the Template against the context and return the expansion as a string.
152 |  |
        *
153 |  |
        * @param template        the {@link Template} to expand
154 |  |
        * @param templateContext the {@link ServletTemplateContext} to expand
155 |  |
        *                        the template against
156 |  |
        * @return the interpolated template as a String
157 |  |
        */
158 |  |
       String expandedTemplate(Template template, TemplateContext templateContext);
159 |  |
160 |  |
       /**
161 |  |
        * @return a {@link MelatiStringWriter}.
162 |  |
        * @see Melati#getStringWriter()
163 |  |
        */
164 |  |
       MelatiStringWriter getStringWriter();
165 |  |
166 |  |
       /**
167 |  |
        * Get the underlying engine.
168 |  |
        *
169 |  |
        * @return the configured template engine
170 |  |
        */
171 |  |
       Object getEngine();
172 |  |
173 |  |
     }
174 |  |