View Javadoc

1   package org.apache.velocity.tools;
2   
3   /*
4    * Licensed to the Apache Software Foundation (ASF) under one
5    * or more contributor license agreements.  See the NOTICE file
6    * distributed with this work for additional information
7    * regarding copyright ownership.  The ASF licenses this file
8    * to you under the Apache License, Version 2.0 (the
9    * "License"); you may not use this file except in compliance
10   * with the License.  You may obtain a copy of the License at
11   *
12   *   http://www.apache.org/licenses/LICENSE-2.0
13   *
14   * Unless required by applicable law or agreed to in writing,
15   * software distributed under the License is distributed on an
16   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
17   * KIND, either express or implied.  See the License for the
18   * specific language governing permissions and limitations
19   * under the License.
20   */
21  
22  import java.util.Map;
23  import org.apache.velocity.app.VelocityEngine;
24  import org.apache.velocity.runtime.log.Log;
25  import org.apache.velocity.tools.Scope;
26  import org.apache.velocity.tools.config.ConfigurationUtils;
27  import org.apache.velocity.tools.config.FactoryConfiguration;
28  
29  /**
30   * Manages tools for non-web applications. This simplifies the process
31   * of getting a tool-populated Velocity context for merging with templates.
32   * It allows for both direct configuration by passing in a {@link FactoryConfiguration}
33   * as well as configuration via a tools.xml or tools.properties file in
34   * either the classpath or the local file system.
35   *
36   * @author Nathan Bubna
37   * @version $Id: ToolManager.java 511959 2007-02-26 19:24:39Z nbubna $
38   */
39  public class ToolManager
40  {
41      protected VelocityEngine velocity;
42      protected ToolboxFactory factory;
43      private Toolbox application;
44      private boolean userOverwrite = true;
45  
46      /**
47       * Constructs an instance already configured to use the 
48       * {@link ConfigurationUtils#getAutoLoaded()} configuration
49       * and any configuration specified via a "org.apache.velocity.tools"
50       * system property.
51       */
52      public ToolManager()
53      {
54          this(true, true);
55      }
56  
57      public ToolManager(boolean includeDefaults)
58      {
59          this(true, includeDefaults);
60      }
61  
62      public ToolManager(boolean autoConfig, boolean includeDefaults)
63      {
64          this.factory = new ToolboxFactory();
65          
66          if (autoConfig)
67          {
68              autoConfigure(includeDefaults);
69          }
70      }
71  
72      public void autoConfigure(boolean includeDefaults)
73      {
74          FactoryConfiguration config =
75              ConfigurationUtils.getAutoLoaded(includeDefaults);
76  
77          // look for any specified via system property
78          FactoryConfiguration sys = ConfigurationUtils.findFromSystemProperty();
79          if (sys != null)
80          {
81              config.addConfiguration(sys);
82          }
83          configure(config);
84      }
85  
86      public void configure(FactoryConfiguration config)
87      {
88          // clear the cached application toolbox
89          this.application = null;
90          this.factory.configure(config);
91      }
92  
93      public void configure(String path)
94      {
95          FactoryConfiguration config = findConfig(path);
96          if (config != null)
97          {
98              configure(config);
99          }
100         else
101         {
102             throw new RuntimeException("Could not find any configuration at "+path);
103         }
104     }
105 
106     protected FactoryConfiguration findConfig(String path)
107     {
108         return ConfigurationUtils.find(path);
109     }
110 
111     /**
112      * Returns the underlying {@link ToolboxFactory} being used.
113      */
114     public ToolboxFactory getToolboxFactory()
115     {
116         return this.factory;
117     }
118 
119     /**
120      * Sets the underlying ToolboxFactory being used.
121      * <b>If you use this, be sure that your ToolboxFactory
122      * is already properly configured.</b>
123      */
124     public void setToolboxFactory(ToolboxFactory factory)
125     {
126         if (this.factory != factory)
127         {
128             if (factory == null)
129             {
130                 throw new NullPointerException("ToolboxFactory cannot be null");
131             }
132             debug("ToolboxFactory instance was changed to %s", factory);
133             this.factory = factory;
134         }
135     }
136 
137     /**
138      * Sets the underlying VelocityEngine being used.
139      * <b>If you use this, be sure that your VelocityEngine
140      * is already properly configured and initialized.</b>
141      */
142     public void setVelocityEngine(VelocityEngine engine)
143     {
144         if (velocity != engine)
145         {
146             debug("VelocityEngine instance was changed to %s", engine);
147             this.velocity = engine;
148         }
149     }
150 
151     public VelocityEngine getVelocityEngine()
152     {
153         return this.velocity;
154     }
155 
156     public void setUserCanOverwriteTools(boolean overwrite)
157     {
158         this.userOverwrite = overwrite;
159     }
160 
161     public boolean getUserCanOverwriteTools()
162     {
163         return this.userOverwrite;
164     }
165 
166     public Log getLog()
167     {
168         if (velocity == null)
169         {
170             return null;
171         }
172         return velocity.getLog();
173     }
174 
175     protected final void debug(String msg, Object... args)
176     {
177         Log log = getLog();
178         if (log != null && log.isDebugEnabled())
179         {
180             log.debug(String.format(msg, args));
181         }
182     }
183 
184     public ToolContext createContext()
185     {
186         return createContext(null);
187     }
188 
189     public ToolContext createContext(Map<String,Object> toolProps)
190     {
191         ToolContext context = new ToolContext(toolProps);
192         prepareContext(context);
193         return context;
194     }
195 
196     protected void prepareContext(ToolContext context)
197     {
198         context.setUserCanOverwriteTools(this.userOverwrite);
199         if (this.velocity != null)
200         {
201             context.putVelocityEngine(this.velocity);
202         }
203         addToolboxes(context);
204     }
205 
206     protected void addToolboxes(ToolContext context)
207     {
208         if (hasApplicationTools())
209         {
210             context.addToolbox(getApplicationToolbox());
211         }
212         if (hasRequestTools())
213         {
214             context.addToolbox(getRequestToolbox());
215         }
216     }
217 
218     protected boolean hasTools(String scope)
219     {
220         return this.factory.hasTools(scope);
221     }
222 
223     protected Toolbox createToolbox(String scope)
224     {
225         return this.factory.createToolbox(scope);
226     }
227 
228     protected boolean hasRequestTools()
229     {
230         return hasTools(Scope.REQUEST);
231     }
232 
233     protected Toolbox getRequestToolbox()
234     {
235         return createToolbox(Scope.REQUEST);
236     }
237 
238     protected boolean hasApplicationTools()
239     {
240         return hasTools(Scope.APPLICATION);
241     }
242 
243     protected Toolbox getApplicationToolbox()
244     {
245         if (this.application == null && hasApplicationTools())
246         {
247             this.application = createToolbox(Scope.APPLICATION);
248         }
249         return this.application;
250     }
251 
252 }