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 }