1 /* 2 * $Source$ 3 * $Revision$ 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 * @throws TemplateEngineException if any problem occurs with the engine 75 * @return a {@link TemplateContext} 76 */ 77 TemplateContext getTemplateContext() 78 throws TemplateEngineException; 79 80 /** 81 * The name of the template engine (used to find the templets). 82 * @return the name of the current configured template engine 83 */ 84 String getName(); 85 86 /** 87 * @return the extension of the templates used by this template engine, 88 * including the dot. 89 */ 90 String templateExtension(); 91 92 /** 93 * A root should not end in a slash. 94 * 95 * @return an Enumeration of string roots, always at least the empty string 96 */ 97 Enumeration<String> getRoots(); 98 99 /** 100 * Add a template root directory. 101 * NOTE A root should not start or end in a slash. 102 * 103 * @param root the root to add 104 */ 105 void addRoot(String root); 106 107 /** 108 * Get a template given it's full name. 109 * 110 * @param templateName the name of the template to find 111 * @throws NotFoundException if template not found 112 * @return a template 113 */ 114 Template template(String templateName) 115 throws NotFoundException; 116 117 /** 118 * The name of a template which exists. 119 * 120 * @param key short name, without path or extension 121 * @param classifier a purpose or database name or similar qualifier 122 * @return the name of a template, null if none found 123 */ 124 String getTemplateName(String key, String classifier); 125 126 /** 127 * Expand the Template against the context. 128 * 129 * @param out a {@link MelatiWriter} to output on 130 * @param templateName the name of the template to expand 131 * @param templateContext the {@link ServletTemplateContext} to expand 132 * the template against 133 * @throws NotFoundException if template not found 134 */ 135 void expandTemplate(MelatiWriter out, String templateName, 136 TemplateContext templateContext) throws NotFoundException; 137 138 /** 139 * Expand the Template against the context, unwrapping any Access Exceptions. 140 * 141 * @param out a {@link MelatiWriter} to output on 142 * @param template the {@link Template} to expand 143 * @param templateContext the {@link ServletTemplateContext} to expand 144 * the template against 145 */ 146 void expandTemplate(MelatiWriter out, Template template, 147 TemplateContext templateContext); 148 149 /** 150 * Expand the Template against the context and return the expansion as a string. 151 * 152 * @param template the {@link Template} to expand 153 * @param templateContext the {@link ServletTemplateContext} to expand 154 * the template against 155 * @return the interpolated template as a String 156 */ 157 String expandedTemplate(Template template, TemplateContext templateContext); 158 159 /** 160 * @return a {@link MelatiStringWriter}. 161 * @see Melati#getStringWriter() 162 */ 163 MelatiStringWriter getStringWriter(); 164 165 /** 166 * Get the underlying engine. 167 * 168 * @return the configured template engine 169 */ 170 Object getEngine(); 171 172 } 173