1. Project Clover database Sat Feb 2 2019 06:45:20 CET
  2. Package org.xwiki.velocity

File VelocityFactory.java

 

Code metrics

0
0
0
1
85
11
0
-
-
0
-

Classes

Class Line # Actions
VelocityFactory 35 0 - 0 0
-1.0 -
 

Contributing tests

No tests hitting this source file were found.

Source view

1    /*
2    * See the NOTICE file distributed with this work for additional
3    * information regarding copyright ownership.
4    *
5    * This is free software; you can redistribute it and/or modify it
6    * under the terms of the GNU Lesser General Public License as
7    * published by the Free Software Foundation; either version 2.1 of
8    * the License, or (at your option) any later version.
9    *
10    * This software is distributed in the hope that it will be useful,
11    * but WITHOUT ANY WARRANTY; without even the implied warranty of
12    * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13    * Lesser General Public License for more details.
14    *
15    * You should have received a copy of the GNU Lesser General Public
16    * License along with this software; if not, write to the Free
17    * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
18    * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
19    */
20    package org.xwiki.velocity;
21   
22    import java.util.Properties;
23   
24    import org.xwiki.component.annotation.Role;
25   
26    /**
27    * Allows creating different Velocity engine instances. This is useful when you need to have different Velocity engines
28    * running in the same JVM but with different configurations. Since global templates in Velocity are part of the
29    * configuration the only solution to use different global templates is to use different Velocity engines. As an example
30    * we need this in XWiki since we want to allow each Skin to provide its own global macros.
31    *
32    * @version $Id: 4f6fc106ff0e87c9283e40b973c6836374061586 $
33    */
34    @Role
 
35    public interface VelocityFactory
36    {
37    /**
38    * Check if an engine was already created for a certain key.
39    *
40    * @param key the key under which the Velocity engine has been saved in cache. This is the key used when the
41    * Velocity engine was created using {@link #createVelocityEngine(String, java.util.Properties)}
42    * @return <code>true</code> if there is a cached Velocity Engine matching the passed key, <code>false</code>
43    * otherwise.
44    */
45    boolean hasVelocityEngine(String key);
46   
47    /**
48    * Retrieves from the cache the Velocity engine corresponding to a specific key, if such an engine was already
49    * created.
50    *
51    * @param key the key under which the Velocity engine has been saved in cache. This is the key used when the
52    * Velocity engine was created using {@link #createVelocityEngine(String, java.util.Properties)}
53    * @return the cached Velocity engine instance corresponding to the passed key or <code>null</code> if not found
54    */
55    VelocityEngine getVelocityEngine(String key);
56   
57    /**
58    * Creates a new Velocity engine instance, which will be cached using a specific key for later reuse. The key allows
59    * having different Velocity Engines, so that each one can have its own special configuration. This is especially
60    * handy for having different sets of global Velocity libraries (such as for different XWiki Skins for example). If
61    * another engine was previously created for the same key, then that instance is returned instead, without creating
62    * any other instance.
63    *
64    * @param key the key used to cache the Velocity engine instance to return
65    * @param properties the list of properties that will override the default properties when creating the engine. For
66    * example it's possible to define a list of global velocimacros by passing the
67    * <code>RuntimeConstants.VM_LIBRARY</code> property key.
68    * @return the newly created Velocity Engine, or an existing one, if an engine was previously created for the same
69    * key.
70    * @throws XWikiVelocityException if the Velocity Engine cannot be initialized for some reason
71    */
72    // TODO: How to create a new engine instance when parameters have changed? Shouldn't this discard the old instance
73    // and create a new one, instead?
74    VelocityEngine createVelocityEngine(String key, Properties properties) throws XWikiVelocityException;
75   
76    /**
77    * Remove from the cache a Velocity engine corresponding to a specific key, if such an engine was already created.
78    *
79    * @param key the key under which the Velocity engine has been saved in cache. This is the key used when the
80    * Velocity engine was created using {@link #createVelocityEngine(String, java.util.Properties)}
81    * @return the cached Velocity engine instance corresponding to the passed key or <code>null</code> if not found
82    * @since 6.4M1
83    */
84    VelocityEngine removeVelocityEngine(String key);
85    }