KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > apache > velocity > runtime > RuntimeServices


1 package org.apache.velocity.runtime;
2
3 /*
4  * Copyright 2001,2004 The Apache Software Foundation.
5  *
6  * Licensed under the Apache License, Version 2.0 (the "License");
7  * you may not use this file except in compliance with the License.
8  * You may obtain a copy of the License at
9  *
10  * http://www.apache.org/licenses/LICENSE-2.0
11  *
12  * Unless required by applicable law or agreed to in writing, software
13  * distributed under the License is distributed on an "AS IS" BASIS,
14  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15  * See the License for the specific language governing permissions and
16  * limitations under the License.
17  */

18
19 import java.io.Reader JavaDoc;
20
21 import java.util.Properties JavaDoc;
22
23 import org.apache.velocity.Template;
24
25 import org.apache.velocity.runtime.parser.ParseException;
26 import org.apache.velocity.runtime.parser.node.SimpleNode;
27
28 import org.apache.velocity.runtime.directive.Directive;
29 import org.apache.velocity.runtime.resource.ContentResource;
30
31 import org.apache.velocity.util.introspection.Introspector;
32 import org.apache.velocity.util.introspection.Uberspect;
33
34 import org.apache.velocity.exception.ResourceNotFoundException;
35 import org.apache.velocity.exception.ParseErrorException;
36
37 import org.apache.commons.collections.ExtendedProperties;
38
39
40 /**
41  * Interface for internal runtime services that are needed by the
42  * various components w/in Velocity. This was taken from the old
43  * Runtime singleton, and anything not necessary was removed.
44  *
45  * Currently implemented by RuntimeInstance.
46  *
47  * @author <a HREF="mailto:geirm@optonline.net">Geir Magusson Jr.</a>
48  * @version $Id: RuntimeServices.java,v 1.7.4.1 2004/03/03 23:22:55 geirm Exp $
49  */

50 public interface RuntimeServices extends RuntimeLogger
51 {
52
53    /*
54      * This is the primary initialization method in the Velocity
55      * Runtime. The systems that are setup/initialized here are
56      * as follows:
57      *
58      * <ul>
59      * <li>Logging System</li>
60      * <li>ResourceManager</li>
61      * <li>Parser Pool</li>
62      * <li>Global Cache</li>
63      * <li>Static Content Include System</li>
64      * <li>Velocimacro System</li>
65      * </ul>
66      */

67     public void init() throws Exception JavaDoc;
68
69     /**
70      * Allows an external system to set a property in
71      * the Velocity Runtime.
72      *
73      * @param String property key
74      * @param String property value
75      */

76     public void setProperty(String JavaDoc key, Object JavaDoc value);
77
78     /**
79      * Allow an external system to set an ExtendedProperties
80      * object to use. This is useful where the external
81      * system also uses the ExtendedProperties class and
82      * the velocity configuration is a subset of
83      * parent application's configuration. This is
84      * the case with Turbine.
85      *
86      * @param ExtendedProperties configuration
87      */

88     public void setConfiguration( ExtendedProperties configuration);
89
90     /**
91      * Add a property to the configuration. If it already
92      * exists then the value stated here will be added
93      * to the configuration entry. For example, if
94      *
95      * resource.loader = file
96      *
97      * is already present in the configuration and you
98      *
99      * addProperty("resource.loader", "classpath")
100      *
101      * Then you will end up with a Vector like the
102      * following:
103      *
104      * ["file", "classpath"]
105      *
106      * @param String key
107      * @param String value
108      */

109     public void addProperty(String JavaDoc key, Object JavaDoc value);
110     
111     /**
112      * Clear the values pertaining to a particular
113      * property.
114      *
115      * @param String key of property to clear
116      */

117     public void clearProperty(String JavaDoc key);
118     
119     /**
120      * Allows an external caller to get a property. The calling
121      * routine is required to know the type, as this routine
122      * will return an Object, as that is what properties can be.
123      *
124      * @param key property to return
125      */

126     public Object JavaDoc getProperty( String JavaDoc key );
127
128     /**
129      * Initialize the Velocity Runtime with a Properties
130      * object.
131      *
132      * @param Properties
133      */

134     public void init(Properties JavaDoc p) throws Exception JavaDoc;
135     
136     /**
137      * Initialize the Velocity Runtime with the name of
138      * ExtendedProperties object.
139      *
140      * @param Properties
141      */

142     public void init(String JavaDoc configurationFile) throws Exception JavaDoc;
143
144     /**
145      * Parse the input and return the root of
146      * AST node structure.
147      * <br><br>
148      * In the event that it runs out of parsers in the
149      * pool, it will create and let them be GC'd
150      * dynamically, logging that it has to do that. This
151      * is considered an exceptional condition. It is
152      * expected that the user will set the
153      * PARSER_POOL_SIZE property appropriately for their
154      * application. We will revisit this.
155      *
156      * @param InputStream inputstream retrieved by a resource loader
157      * @param String name of the template being parsed
158      */

159     public SimpleNode parse( Reader JavaDoc reader, String JavaDoc templateName )
160         throws ParseException;
161
162     /**
163      * Parse the input and return the root of the AST node structure.
164      *
165      * @param InputStream inputstream retrieved by a resource loader
166      * @param String name of the template being parsed
167      * @param dumpNamespace flag to dump the Velocimacro namespace for this template
168      */

169     public SimpleNode parse( Reader JavaDoc reader, String JavaDoc templateName, boolean dumpNamespace )
170         throws ParseException;
171     
172     /**
173      * Returns a <code>Template</code> from the resource manager.
174      * This method assumes that the character encoding of the
175      * template is set by the <code>input.encoding</code>
176      * property. The default is "ISO-8859-1"
177      *
178      * @param name The file name of the desired template.
179      * @return The template.
180      * @throws ResourceNotFoundException if template not found
181      * from any available source.
182      * @throws ParseErrorException if template cannot be parsed due
183      * to syntax (or other) error.
184      * @throws Exception if an error occurs in template initialization
185      */

186     public Template getTemplate(String JavaDoc name)
187         throws ResourceNotFoundException, ParseErrorException, Exception JavaDoc;
188
189     /**
190      * Returns a <code>Template</code> from the resource manager
191      *
192      * @param name The name of the desired template.
193      * @param encoding Character encoding of the template
194      * @return The template.
195      * @throws ResourceNotFoundException if template not found
196      * from any available source.
197      * @throws ParseErrorException if template cannot be parsed due
198      * to syntax (or other) error.
199      * @throws Exception if an error occurs in template initialization
200      */

201     public Template getTemplate(String JavaDoc name, String JavaDoc encoding)
202         throws ResourceNotFoundException, ParseErrorException, Exception JavaDoc;
203
204     /**
205      * Returns a static content resource from the
206      * resource manager. Uses the current value
207      * if INPUT_ENCODING as the character encoding.
208      *
209      * @param name Name of content resource to get
210      * @return parsed ContentResource object ready for use
211      * @throws ResourceNotFoundException if template not found
212      * from any available source.
213      */

214     public ContentResource getContent(String JavaDoc name)
215         throws ResourceNotFoundException, ParseErrorException, Exception JavaDoc;
216
217     /**
218      * Returns a static content resource from the
219      * resource manager.
220      *
221      * @param name Name of content resource to get
222      * @param encoding Character encoding to use
223      * @return parsed ContentResource object ready for use
224      * @throws ResourceNotFoundException if template not found
225      * from any available source.
226      */

227     public ContentResource getContent( String JavaDoc name, String JavaDoc encoding )
228         throws ResourceNotFoundException, ParseErrorException, Exception JavaDoc;
229
230     /**
231      * Determines is a template exists, and returns name of the loader that
232      * provides it. This is a slightly less hokey way to support
233      * the Velocity.templateExists() utility method, which was broken
234      * when per-template encoding was introduced. We can revisit this.
235      *
236      * @param resourceName Name of template or content resource
237      * @return class name of loader than can provide it
238      */

239     public String JavaDoc getLoaderNameForResource( String JavaDoc resourceName );
240
241     /**
242      * String property accessor method with default to hide the
243      * configuration implementation.
244      *
245      * @param String key property key
246      * @param String defaultValue default value to return if key not
247      * found in resource manager.
248      * @return String value of key or default
249      */

250     public String JavaDoc getString( String JavaDoc key, String JavaDoc defaultValue);
251
252     /**
253      * Returns the appropriate VelocimacroProxy object if strVMname
254      * is a valid current Velocimacro.
255      *
256      * @param String vmName Name of velocimacro requested
257      * @return String VelocimacroProxy
258      */

259     public Directive getVelocimacro( String JavaDoc vmName, String JavaDoc templateName );
260
261    /**
262      * Adds a new Velocimacro. Usually called by Macro only while parsing.
263      *
264      * @param String name Name of velocimacro
265      * @param String macro String form of macro body
266      * @param String argArray Array of strings, containing the
267      * #macro() arguments. the 0th is the name.
268      * @return boolean True if added, false if rejected for some
269      * reason (either parameters or permission settings)
270      */

271     public boolean addVelocimacro( String JavaDoc name,
272                                           String JavaDoc macro,
273                                           String JavaDoc argArray[],
274                                           String JavaDoc sourceTemplate );
275  
276     /**
277      * Checks to see if a VM exists
278      *
279      * @param name Name of velocimacro
280      * @return boolean True if VM by that name exists, false if not
281      */

282     public boolean isVelocimacro( String JavaDoc vmName, String JavaDoc templateName );
283
284     /**
285      * tells the vmFactory to dump the specified namespace. This is to support
286      * clearing the VM list when in inline-VM-local-scope mode
287      */

288     public boolean dumpVMNamespace( String JavaDoc namespace );
289
290     /**
291      * String property accessor method to hide the configuration implementation
292      * @param key property key
293      * @return value of key or null
294      */

295     public String JavaDoc getString(String JavaDoc key);
296
297     /**
298      * Int property accessor method to hide the configuration implementation.
299      *
300      * @param String key property key
301      * @return int value
302      */

303     public int getInt( String JavaDoc key );
304
305     /**
306      * Int property accessor method to hide the configuration implementation.
307      *
308      * @param key property key
309      * @param int default value
310      * @return int value
311      */

312     public int getInt( String JavaDoc key, int defaultValue );
313
314     /**
315      * Boolean property accessor method to hide the configuration implementation.
316      *
317      * @param String key property key
318      * @param boolean default default value if property not found
319      * @return boolean value of key or default value
320      */

321     public boolean getBoolean( String JavaDoc key, boolean def );
322
323     /**
324      * Return the velocity runtime configuration object.
325      *
326      * @return ExtendedProperties configuration object which houses
327      * the velocity runtime properties.
328      */

329     public ExtendedProperties getConfiguration();
330
331     /**
332      * Return the specified applcation attribute.
333      *
334      * @param key The name of the attribute to retrieve.
335      */

336     public Object JavaDoc getApplicationAttribute( Object JavaDoc key );
337
338     /**
339      * Returns the configured class introspection/reflection
340      * implemenation.
341      */

342     public Uberspect getUberspect();
343
344     /**
345      * Returns the configured method introspection/reflection
346      * implemenation.
347      */

348     public Introspector getIntrospector();
349 }
350
Popular Tags