Classes in this File | Line Coverage | Branch Coverage | Complexity | ||||
Template |
|
| 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 java.io.IOException; | |
27 | import java.io.OutputStream; | |
28 | import java.util.Map; | |
29 | ||
30 | ||
31 | /** | |
32 | * Defines the type of object which contains | |
33 | * WebMacro script, text, blocks to be evaluated. | |
34 | * | |
35 | * @author lane | |
36 | */ | |
37 | public interface Template extends Visitable | |
38 | { | |
39 | ||
40 | /** | |
41 | * Force the template to parse now. Normally the template will not parse | |
42 | * the supplied file until the data is actually needed. However if you | |
43 | * want to parse all of your templates at the start of the application | |
44 | * to avoid incurring this call during an interactive session, you can | |
45 | * call the parse() function at an appropriate time. Once a template has | |
46 | * been parsed, subsequent calls to this method do not have an effect. If | |
47 | * you want to reparse the template, because you know it has been changed, you | |
48 | * have to create a new Template object and leave this one to the garbage collector. | |
49 | * | |
50 | * @exception TemplateException if the syntax was invalid and we could not recover | |
51 | * @exception IOException if we could not successfully read the parseTool | |
52 | */ | |
53 | public void parse () throws IOException, TemplateException; | |
54 | ||
55 | /** | |
56 | * A template may contain parameters, set by the #param directive. | |
57 | * These are statically evaluated during the parse phase of the | |
58 | * template and shared between all users of the template. They | |
59 | * are present so that the template can provide some meta information | |
60 | * to its user as to what kind of data it expects to find in the Context, | |
61 | * or other information about its use. | |
62 | * <p> | |
63 | * If the template has not already been parsed, it will be parsed. Thus | |
64 | * this method may throw ParseException or IOException if there is some | |
65 | * failure in accessing or parsing the template. | |
66 | * @exception IOException if an error occurred reading the template | |
67 | * @exception TemplateException if an error occurred parsing the template | |
68 | */ | |
69 | public Object getParam (String name) throws IOException, TemplateException; | |
70 | ||
71 | /** | |
72 | * This method can be used to get a list of all the parameters | |
73 | * that have been set in the template. getParam(Object) can be used | |
74 | * to look up any particular parameter. | |
75 | */ | |
76 | ||
77 | /** | |
78 | * Set a parameter. Occasionally it's necessary to provide parameters | |
79 | * externally. Although these might be considered of a different nature to | |
80 | * those set by #param, they can be stored as such. | |
81 | * | |
82 | * One example might be the output character encoding which is needed | |
83 | * when the template is played. | |
84 | */ | |
85 | ||
86 | public void setParam (String key, Object value); | |
87 | ||
88 | public Map getParameters (); | |
89 | ||
90 | public String getName (); | |
91 | ||
92 | public void setName (String name); | |
93 | ||
94 | /** | |
95 | * Get a Map containing all #macros defined for this template. | |
96 | * The returned Map can be <code>null</code> if this Template | |
97 | * does not contain Macros, or if this Template has not been | |
98 | * parsed yet. | |
99 | * @return The map of macros defined. | |
100 | */ | |
101 | public Map getMacros (); | |
102 | ||
103 | public void write (OutputStream out, Context context) | |
104 | throws PropertyException, IOException; | |
105 | ||
106 | public void write (OutputStream out, String encoding, Context context) | |
107 | throws PropertyException, IOException; | |
108 | ||
109 | public void write (FastWriter out, Context context) | |
110 | throws PropertyException, IOException; | |
111 | ||
112 | public String evaluateAsString(Context context) | |
113 | throws PropertyException; | |
114 | ||
115 | public byte[] evaluateAsBytes(String encoding, Context context) | |
116 | throws PropertyException; | |
117 | ||
118 | ||
119 | } | |
120 |