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  ;
20  
21  import java.util.Properties  ;
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  ;
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   key, Object   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   key, Object   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   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   getProperty( String   key );
127 
128     /**
129      * Initialize the Velocity Runtime with a Properties
130      * object.
131      *
132      * @param Properties
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 Properties
141      */
142     public void init(String   configurationFile) throws Exception  ;
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   reader, String   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   reader, String   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   name)
187         throws ResourceNotFoundException, ParseErrorException, Exception  ;
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   name, String    encoding)
202         throws ResourceNotFoundException, ParseErrorException, Exception  ;
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   name)
215         throws ResourceNotFoundException, ParseErrorException, Exception  ;
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   name, String   encoding )
228         throws ResourceNotFoundException, ParseErrorException, Exception  ;
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   getLoaderNameForResource( String   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   getString( String   key, String   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   vmName, String   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   name, 
272                                           String   macro, 
273                                           String   argArray[], 
274                                           String   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   vmName, String   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   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   getString(String   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   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   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   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   getApplicationAttribute( Object   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags