View Javadoc

1   package org.apache.velocity.tools.view;
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.io.IOException;
23  import javax.servlet.Filter;
24  import javax.servlet.FilterChain;
25  import javax.servlet.FilterConfig;
26  import javax.servlet.ServletContext;
27  import javax.servlet.ServletException;
28  import javax.servlet.ServletRequest;
29  import javax.servlet.ServletResponse;
30  import javax.servlet.http.HttpServletRequest;
31  import javax.servlet.http.HttpServletResponse;
32  import org.apache.velocity.context.Context;
33  import org.apache.velocity.tools.Toolbox;
34  import org.apache.velocity.tools.view.VelocityView;
35  import org.apache.velocity.tools.view.ViewToolContext;
36  
37  /**
38   * <p>A filter to ensure VelocityTools {@link Toolbox}es are
39   * available in the request/session/application scopes. This
40   * can simplify the process of integration with other frameworks.</p>
41   *
42   * <p>VelocityViewFilter supports the following configuration parameters
43   * in web.xml:</p>
44   * <dl>
45   *   <dt>org.apache.velocity.tools</dt>
46   *   <dd>Path and name of the toolbox configuration file. The path must be
47   *     relative to the web application root directory. If this parameter is
48   *     not found, the servlet will check for a toolbox file at
49   *     '/WEB-INF/tools.xml'.</dd>
50   *   <dt>org.apache.velocity.properties</dt>
51   *   <dd>Path and name of the Velocity configuration file. The path must be
52   *     relative to the web application root directory. If this parameter
53   *     is not present, Velocity will check for a properties file at
54   *     '/WEB-INF/velocity.properties'.  If no file is found there, then
55   *     Velocity is initialized with the settings in the classpath at
56   *     'org.apache.velocity.tools.view.velocity.properties'.</dd>
57   *   <dt>org.apache.velocity.tools.loadDefaults</dt>
58   *   <dd>By default, this is {@code true}. If set to {@code false}, then
59   *     the default toolbox configuration will not be added to your (if any)
60   *     custom configuration.  NOTE: The default configuration will also be
61   *     suppressed if you are using a deprecated toolbox.xml format and do not
62   *     explicitly set this to {@code true}.</dd>
63   *   <dt>org.apache.velocity.tools.cleanConfiguration</dt>
64   *   <dd>By default, this is {@code false}. If set to {@code true}, then
65   *     then the final toolbox configuration (the combination of any custom
66   *     one(s) provided by yourself and/or the default configuration(s))
67   *     will have all invalid tools, properties, and/or data removed prior to
68   *     configuring the ToolboxFactory for this servlet by a
69   *     {@link org.apache.velocity.tools.config.ConfigurationCleaner}</dd>
70   *   <dt>org.apache.velocity.tools.shared.config</dt>
71   *   <dd>By default, this is {@code true}. If set to {@code false}, then
72   *     the {@link VelocityView} used by this filter will not be shared
73   *     with other VelocityViewFilters, {@link VelocityViewServlet}s or 
74   *     {@link org.apache.velocity.tools.view.jsp.VelocityViewTag}s in the
75   *     application.</dd>
76   *   <dt>org.apache.velocity.tools.context.key</dt>
77   *   <dd>If you set a value for this property, this filter will create
78   *     and prepare a {@link ViewToolContext} for each request, and then
79   *     place it into the request attributes under the key you set. This
80   *     is primarily for those who have this filter NOT share a config
81   *     (i.e. non-shared VelocityView) and thus will find it easier to
82   *     retrieve a working context from the request attributes than it
83   *     would be to get the VelocityView for this filter and have it
84   *     create the context for them.  Most users will have no trouble
85   *     getting a shared VelocityView and creating the context themselves.</dd>
86   * </dl>
87   *
88   * @version $Id: VelocityViewFilter.java 611011 2008-01-11 01:32:59Z nbubna $
89   */
90  public class VelocityViewFilter implements Filter
91  {
92      public static final String CONTEXT_KEY =
93          "org.apache.velocity.tools.context.key";
94  
95      private VelocityView view;
96      private FilterConfig config;
97      private String contextKey = null;
98  
99      /**
100      * <p>Initializes VelocityView used to process requests.
101      * Called by the servlet container on loading.</p>
102      *
103      * @param config filter configuation
104      */
105     public void init(FilterConfig config) throws ServletException
106     {
107         this.config = config;
108 
109         // init the VelocityView (if it hasn't been already)
110         getVelocityView();
111 
112         // look for a context key
113         contextKey = findInitParameter(CONTEXT_KEY);
114     }
115 
116     protected FilterConfig getFilterConfig()
117     {
118         return this.config;
119     }
120 
121     protected VelocityView getVelocityView()
122     {
123         if (this.view == null)
124         {
125             this.view = ServletUtils.getVelocityView(getFilterConfig());
126             assert (view != null);
127         }
128         return this.view;
129     }
130 
131     protected String getContextKey()
132     {
133         return this.contextKey;
134     }
135 
136     /**
137      * Looks up an init parameter with the specified key in either the
138      * FilterConfig or, failing that, in the ServletContext.
139      */
140     protected String findInitParameter(String key)
141     {
142         FilterConfig conf = getFilterConfig();
143         String param = conf.getInitParameter(key);
144         if (param == null || param.length() == 0)
145         {
146             param = conf.getServletContext().getInitParameter(key);
147         }
148         return param;
149     }
150 
151     /**
152      * Simply prepares the request (and/or session) toolbox(es)
153      * for other filters, servlets or whatnot to use.  If a context key
154      * has been provided in the init-params of the filter or webapp,
155      * then this will also create a {@link ViewToolContext} and put
156      * it in the request attributes under that key.
157      */
158     public void doFilter(ServletRequest request,
159                          ServletResponse response,
160                          FilterChain chain)
161         throws java.io.IOException, ServletException
162     {
163         // can/should we create the context for the request?
164         if (contextKey != null && request instanceof HttpServletRequest)
165         {
166             Context context = createContext((HttpServletRequest)request,
167                                             (HttpServletResponse)response);
168             request.setAttribute(contextKey, context);
169         }
170         else
171         {
172             // just publish the toolboxes
173             getVelocityView().publishToolboxes(request);
174         }
175 
176         // move down the chain
177         chain.doFilter(request, response);
178     }
179 
180     protected Context createContext(HttpServletRequest request,
181                                     HttpServletResponse response)
182     {
183         return getVelocityView().createContext(request, response);
184     }
185 
186     public void destroy()
187     {
188         // do anything else?
189         this.view = null;
190         this.config = null;
191         this.contextKey = null;
192     }
193 
194 }