001: package org.apache.velocity.runtime;
002:
003: /*
004: * Licensed to the Apache Software Foundation (ASF) under one
005: * or more contributor license agreements. See the NOTICE file
006: * distributed with this work for additional information
007: * regarding copyright ownership. The ASF licenses this file
008: * to you under the Apache License, Version 2.0 (the
009: * "License"); you may not use this file except in compliance
010: * with the License. You may obtain a copy of the License at
011: *
012: * http://www.apache.org/licenses/LICENSE-2.0
013: *
014: * Unless required by applicable law or agreed to in writing,
015: * software distributed under the License is distributed on an
016: * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
017: * KIND, either express or implied. See the License for the
018: * specific language governing permissions and limitations
019: * under the License.
020: */
021:
022: import java.io.Reader;
023: import java.util.Properties;
024: import org.apache.commons.collections.ExtendedProperties;
025: import org.apache.velocity.Template;
026: import org.apache.velocity.app.event.EventCartridge;
027: import org.apache.velocity.exception.ParseErrorException;
028: import org.apache.velocity.exception.ResourceNotFoundException;
029: import org.apache.velocity.runtime.directive.Directive;
030: import org.apache.velocity.runtime.log.Log;
031: import org.apache.velocity.runtime.parser.ParseException;
032: import org.apache.velocity.runtime.parser.Parser;
033: import org.apache.velocity.runtime.parser.node.SimpleNode;
034: import org.apache.velocity.runtime.resource.ContentResource;
035: import org.apache.velocity.util.introspection.Introspector;
036: import org.apache.velocity.util.introspection.Uberspect;
037:
038: /**
039: * Interface for internal runtime services that are needed by the
040: * various components w/in Velocity. This was taken from the old
041: * Runtime singleton, and anything not necessary was removed.
042: *
043: * Currently implemented by RuntimeInstance.
044: *
045: * @author <a href="mailto:geirm@optonline.net">Geir Magusson Jr.</a>
046: * @version $Id: RuntimeServices.java 463298 2006-10-12 16:10:32Z henning $
047: */
048: public interface RuntimeServices extends RuntimeLogger {
049:
050: /**
051: * This is the primary initialization method in the Velocity
052: * Runtime. The systems that are setup/initialized here are
053: * as follows:
054: *
055: * <ul>
056: * <li>Logging System</li>
057: * <li>ResourceManager</li>
058: * <li>Parser Pool</li>
059: * <li>Global Cache</li>
060: * <li>Static Content Include System</li>
061: * <li>Velocimacro System</li>
062: * </ul>
063: * @throws Exception
064: */
065: public void init() throws Exception;
066:
067: /**
068: * Allows an external system to set a property in
069: * the Velocity Runtime.
070: *
071: * @param key property key
072: * @param value property value
073: */
074: public void setProperty(String key, Object value);
075:
076: /**
077: * Allow an external system to set an ExtendedProperties
078: * object to use. This is useful where the external
079: * system also uses the ExtendedProperties class and
080: * the velocity configuration is a subset of
081: * parent application's configuration. This is
082: * the case with Turbine.
083: *
084: * @param configuration
085: */
086: public void setConfiguration(ExtendedProperties configuration);
087:
088: /**
089: * Add a property to the configuration. If it already
090: * exists then the value stated here will be added
091: * to the configuration entry. For example, if
092: *
093: * resource.loader = file
094: *
095: * is already present in the configuration and you
096: *
097: * addProperty("resource.loader", "classpath")
098: *
099: * Then you will end up with a Vector like the
100: * following:
101: *
102: * ["file", "classpath"]
103: *
104: * @param key
105: * @param value
106: */
107: public void addProperty(String key, Object value);
108:
109: /**
110: * Clear the values pertaining to a particular
111: * property.
112: *
113: * @param key of property to clear
114: */
115: public void clearProperty(String key);
116:
117: /**
118: * Allows an external caller to get a property. The calling
119: * routine is required to know the type, as this routine
120: * will return an Object, as that is what properties can be.
121: *
122: * @param key property to return
123: * @return The value.
124: */
125: public Object getProperty(String key);
126:
127: /**
128: * Initialize the Velocity Runtime with a Properties
129: * object.
130: *
131: * @param p
132: * @throws Exception
133: */
134: public void init(Properties p) throws Exception;
135:
136: /**
137: * Initialize the Velocity Runtime with the name of
138: * ExtendedProperties object.
139: *
140: * @param configurationFile
141: * @throws Exception
142: */
143: public void init(String configurationFile) throws Exception;
144:
145: /**
146: * Parse the input and return the root of
147: * AST node structure.
148: * <br><br>
149: * In the event that it runs out of parsers in the
150: * pool, it will create and let them be GC'd
151: * dynamically, logging that it has to do that. This
152: * is considered an exceptional condition. It is
153: * expected that the user will set the
154: * PARSER_POOL_SIZE property appropriately for their
155: * application. We will revisit this.
156: *
157: * @param reader inputstream retrieved by a resource loader
158: * @param templateName name of the template being parsed
159: * @return The AST representing the template.
160: * @throws ParseException
161: */
162: public SimpleNode parse(Reader reader, String templateName)
163: throws ParseException;
164:
165: /**
166: * Parse the input and return the root of the AST node structure.
167: *
168: * @param reader inputstream retrieved by a resource loader
169: * @param templateName name of the template being parsed
170: * @param dumpNamespace flag to dump the Velocimacro namespace for this template
171: * @return The AST representing the template.
172: * @throws ParseException
173: */
174: public SimpleNode parse(Reader reader, String templateName,
175: boolean dumpNamespace) throws ParseException;
176:
177: /**
178: * Returns a <code>Template</code> from the resource manager.
179: * This method assumes that the character encoding of the
180: * template is set by the <code>input.encoding</code>
181: * property. The default is "ISO-8859-1"
182: *
183: * @param name The file name of the desired template.
184: * @return The template.
185: * @throws ResourceNotFoundException if template not found
186: * from any available source.
187: * @throws ParseErrorException if template cannot be parsed due
188: * to syntax (or other) error.
189: * @throws Exception if an error occurs in template initialization
190: */
191: public Template getTemplate(String name)
192: throws ResourceNotFoundException, ParseErrorException,
193: Exception;
194:
195: /**
196: * Returns a <code>Template</code> from the resource manager
197: *
198: * @param name The name of the desired template.
199: * @param encoding Character encoding of the template
200: * @return The template.
201: * @throws ResourceNotFoundException if template not found
202: * from any available source.
203: * @throws ParseErrorException if template cannot be parsed due
204: * to syntax (or other) error.
205: * @throws Exception if an error occurs in template initialization
206: */
207: public Template getTemplate(String name, String encoding)
208: throws ResourceNotFoundException, ParseErrorException,
209: Exception;
210:
211: /**
212: * Returns a static content resource from the
213: * resource manager. Uses the current value
214: * if INPUT_ENCODING as the character encoding.
215: *
216: * @param name Name of content resource to get
217: * @return parsed ContentResource object ready for use
218: * @throws ResourceNotFoundException if template not found
219: * from any available source.
220: * @throws ParseErrorException
221: * @throws Exception
222: */
223: public ContentResource getContent(String name)
224: throws ResourceNotFoundException, ParseErrorException,
225: Exception;
226:
227: /**
228: * Returns a static content resource from the
229: * resource manager.
230: *
231: * @param name Name of content resource to get
232: * @param encoding Character encoding to use
233: * @return parsed ContentResource object ready for use
234: * @throws ResourceNotFoundException if template not found
235: * from any available source.
236: * @throws ParseErrorException
237: * @throws Exception
238: */
239: public ContentResource getContent(String name, String encoding)
240: throws ResourceNotFoundException, ParseErrorException,
241: Exception;
242:
243: /**
244: * Determines is a template exists, and returns name of the loader that
245: * provides it. This is a slightly less hokey way to support
246: * the Velocity.templateExists() utility method, which was broken
247: * when per-template encoding was introduced. We can revisit this.
248: *
249: * @param resourceName Name of template or content resource
250: * @return class name of loader than can provide it
251: */
252: public String getLoaderNameForResource(String resourceName);
253:
254: /**
255: * String property accessor method with default to hide the
256: * configuration implementation.
257: *
258: * @param key property key
259: * @param defaultValue default value to return if key not
260: * found in resource manager.
261: * @return String value of key or default
262: */
263: public String getString(String key, String defaultValue);
264:
265: /**
266: * Returns the appropriate VelocimacroProxy object if strVMname
267: * is a valid current Velocimacro.
268: *
269: * @param vmName Name of velocimacro requested
270: * @param templateName Name of the namespace.
271: * @return VelocimacroProxy
272: */
273: public Directive getVelocimacro(String vmName, String templateName);
274:
275: /**
276: * Adds a new Velocimacro. Usually called by Macro only while parsing.
277: *
278: * @param name Name of velocimacro
279: * @param macro String form of macro body
280: * @param argArray Array of strings, containing the
281: * #macro() arguments. the 0th is the name.
282: * @param sourceTemplate
283: * @return boolean True if added, false if rejected for some
284: * reason (either parameters or permission settings)
285: */
286: public boolean addVelocimacro(String name, String macro,
287: String argArray[], String sourceTemplate);
288:
289: /**
290: * Checks to see if a VM exists
291: *
292: * @param vmName Name of velocimacro
293: * @param templateName
294: * @return boolean True if VM by that name exists, false if not
295: */
296: public boolean isVelocimacro(String vmName, String templateName);
297:
298: /**
299: * tells the vmFactory to dump the specified namespace. This is to support
300: * clearing the VM list when in inline-VM-local-scope mode
301: * @param namespace
302: * @return True if the Namespace was dumped.
303: */
304: public boolean dumpVMNamespace(String namespace);
305:
306: /**
307: * String property accessor method to hide the configuration implementation
308: * @param key property key
309: * @return value of key or null
310: */
311: public String getString(String key);
312:
313: /**
314: * Int property accessor method to hide the configuration implementation.
315: *
316: * @param key property key
317: * @return int value
318: */
319: public int getInt(String key);
320:
321: /**
322: * Int property accessor method to hide the configuration implementation.
323: *
324: * @param key property key
325: * @param defaultValue default value
326: * @return int value
327: */
328: public int getInt(String key, int defaultValue);
329:
330: /**
331: * Boolean property accessor method to hide the configuration implementation.
332: *
333: * @param key property key
334: * @param def default default value if property not found
335: * @return boolean value of key or default value
336: */
337: public boolean getBoolean(String key, boolean def);
338:
339: /**
340: * Return the velocity runtime configuration object.
341: *
342: * @return ExtendedProperties configuration object which houses
343: * the velocity runtime properties.
344: */
345: public ExtendedProperties getConfiguration();
346:
347: /**
348: * Return the specified application attribute.
349: *
350: * @param key The name of the attribute to retrieve.
351: * @return The value of the attribute.
352: */
353: public Object getApplicationAttribute(Object key);
354:
355: /**
356: * Set the specified application attribute.
357: *
358: * @param key The name of the attribute to set.
359: * @param value The attribute value to set.
360: * @return the displaced attribute value
361: */
362: public Object setApplicationAttribute(Object key, Object value);
363:
364: /**
365: * Returns the configured class introspection/reflection
366: * implemenation.
367: * @return The current Uberspect object.
368: */
369: public Uberspect getUberspect();
370:
371: /**
372: * Returns a convenient Log instance that wraps the current LogChute.
373: * @return A log object.
374: */
375: public Log getLog();
376:
377: /**
378: * Returns the event handlers for the application.
379: * @return The event handlers for the application.
380: */
381: public EventCartridge getApplicationEventCartridge();
382:
383: /**
384: * Returns the configured method introspection/reflection
385: * implementation.
386: * @return The configured method introspection/reflection
387: * implementation.
388: */
389: public Introspector getIntrospector();
390:
391: /**
392: * Returns true if the RuntimeInstance has been successfully initialized.
393: * @return True if the RuntimeInstance has been successfully initialized.
394: */
395: public boolean isInitialized();
396:
397: /**
398: * Create a new parser instance.
399: * @return A new parser instance.
400: */
401: public Parser createNewParser();
402: }
|