1 package org.apache.velocity.servlet; 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.FileNotFoundException; 23 import java.io.IOException; 24 import java.io.OutputStreamWriter; 25 import java.io.PrintWriter; 26 import java.io.StringWriter; 27 import java.io.UnsupportedEncodingException; 28 import java.util.Properties; 29 30 import javax.servlet.ServletConfig; 31 import javax.servlet.ServletContext; 32 import javax.servlet.ServletException; 33 import javax.servlet.ServletOutputStream; 34 import javax.servlet.http.HttpServlet; 35 import javax.servlet.http.HttpServletRequest; 36 import javax.servlet.http.HttpServletResponse; 37 38 import org.apache.velocity.Template; 39 import org.apache.velocity.VelocityContext; 40 import org.apache.velocity.app.Velocity; 41 import org.apache.velocity.context.Context; 42 import org.apache.velocity.exception.MethodInvocationException; 43 import org.apache.velocity.exception.ParseErrorException; 44 import org.apache.velocity.exception.ResourceNotFoundException; 45 import org.apache.velocity.io.VelocityWriter; 46 import org.apache.velocity.runtime.RuntimeConstants; 47 import org.apache.velocity.runtime.RuntimeSingleton; 48 import org.apache.velocity.util.SimplePool; 49 50 /** 51 * Base class which simplifies the use of Velocity with Servlets. 52 * Extend this class, implement the <code>handleRequest()</code> method, 53 * and add your data to the context. Then call 54 * <code>getTemplate("myTemplate.wm")</code>. 55 * 56 * This class puts some things into the context object that you should 57 * be aware of: 58 * <pre> 59 * "req" - The HttpServletRequest object 60 * "res" - The HttpServletResponse object 61 * </pre> 62 * 63 * There are other methods you can override to access, alter or control 64 * any part of the request processing chain. Please see the javadocs for 65 * more information on : 66 * <ul> 67 * <li> loadConfiguration() : for setting up the Velocity runtime 68 * <li> createContext() : for creating and loading the Context 69 * <li> setContentType() : for changing the content type on a request 70 * by request basis 71 * <li> handleRequest() : you <b>must</b> implement this 72 * <li> mergeTemplate() : the template rendering process 73 * <li> requestCleanup() : post rendering resource or other cleanup 74 * <li> error() : error handling 75 * </ul> 76 * <br> 77 * If you put a String with key "contentType" object into the context within either your 78 * servlet or within your template, then that will be used to override 79 * the default content type specified in the properties file. 80 * 81 * @deprecated This servlet has been replaced by VelocityViewServlet, 82 * available from the Velocity-Tools sub-project. VelocityViewServlet 83 * provides support for quick, clean MVC web development. 84 * VelocityServlet will be removed in a future version of Velocity. 85 * 86 * @author Dave Bryson 87 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a> 88 * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a> 89 * @author <a href="kjohnson@transparent.com">Kent Johnson</a> 90 * @author <a href="dlr@finemaltcoding.com">Daniel Rall</a> 91 * $Id: VelocityServlet.java 463298 2006-10-12 16:10:32Z henning $ 92 */ 93 public abstract class VelocityServlet extends HttpServlet 94 { 95 /** 96 * The context key for the HTTP request object. 97 */ 98 public static final String REQUEST = "req"; 99 100 /** 101 * The context key for the HTTP response object. 102 */ 103 public static final String RESPONSE = "res"; 104 105 /** 106 * The HTTP content type context key. 107 */ 108 public static final String CONTENT_TYPE = "default.contentType"; 109 110 /** 111 * The default content type for the response 112 */ 113 public static final String DEFAULT_CONTENT_TYPE = "text/html"; 114 115 116 /** 117 * Encoding for the output stream 118 */ 119 public static final String DEFAULT_OUTPUT_ENCODING = "ISO-8859-1"; 120 121 /** 122 * The default content type, itself defaulting to {@link 123 * #DEFAULT_CONTENT_TYPE} if not configured. 124 */ 125 private static String defaultContentType; 126 127 /** 128 * This is the string that is looked for when getInitParameter is 129 * called (<code>org.apache.velocity.properties</code>). 130 */ 131 protected static final String INIT_PROPS_KEY = 132 "org.apache.velocity.properties"; 133 134 /** 135 * Use of this properties key has been deprecated, and will be 136 * removed in Velocity version 1.5. 137 */ 138 private static final String OLD_INIT_PROPS_KEY = "properties"; 139 140 /** 141 * Cache of writers 142 */ 143 144 private static SimplePool writerPool = new SimplePool(40); 145 146 /** 147 * Performs initialization of this servlet. Called by the servlet 148 * container on loading. 149 * 150 * @param config The servlet configuration to apply. 151 * 152 * @exception ServletException 153 */ 154 public void init( ServletConfig config ) 155 throws ServletException 156 { 157 super.init( config ); 158 159 /* 160 * do whatever we have to do to init Velocity 161 */ 162 initVelocity( config ); 163 164 /* 165 * Now that Velocity is initialized, cache some config. 166 */ 167 VelocityServlet.defaultContentType = 168 RuntimeSingleton.getString(CONTENT_TYPE, DEFAULT_CONTENT_TYPE); 169 } 170 171 /** 172 * Initializes the Velocity runtime, first calling 173 * loadConfiguration(ServletConvig) to get a 174 * java.util.Properties of configuration information 175 * and then calling Velocity.init(). Override this 176 * to do anything to the environment before the 177 * initialization of the singelton takes place, or to 178 * initialize the singleton in other ways. 179 * @param config 180 * @throws ServletException 181 */ 182 protected void initVelocity( ServletConfig config ) 183 throws ServletException 184 { 185 try 186 { 187 /* 188 * call the overridable method to allow the 189 * derived classes a shot at altering the configuration 190 * before initializing Runtime 191 */ 192 193 Properties props = loadConfiguration( config ); 194 195 Velocity.init( props ); 196 } 197 catch( Exception e ) 198 { 199 throw new ServletException("Error initializing Velocity: " + e, e); 200 } 201 } 202 203 /** 204 * Loads the configuration information and returns that 205 * information as a Properties, which will be used to 206 * initialize the Velocity runtime. 207 * <br><br> 208 * Currently, this method gets the initialization parameter 209 * VelocityServlet.INIT_PROPS_KEY, which should be a file containing 210 * the configuration information. 211 * <br><br> 212 * To configure your Servlet Spec 2.2 compliant servlet runner to pass 213 * this to you, put the following in your WEB-INF/web.xml file 214 * <br> 215 * <pre> 216 * <servlet> 217 * <servlet-name> YourServlet </servlet-name> 218 * <servlet-class> your.package.YourServlet </servlet-class> 219 * <init-param> 220 * <param-name> org.apache.velocity.properties </param-name> 221 * <param-value> velocity.properties </param-value> 222 * </init-param> 223 * </servlet> 224 * </pre> 225 * 226 * Alternately, if you wish to configure an entire context in this 227 * fashion, you may use the following: 228 * <br> 229 * <pre> 230 * <context-param> 231 * <param-name> org.apache.velocity.properties </param-name> 232 * <param-value> velocity.properties </param-value> 233 * <description> Path to Velocity configuration </description> 234 * </context-param> 235 * </pre> 236 * 237 * Derived classes may do the same, or take advantage of this code to do the loading for them via : 238 * <pre> 239 * Properties p = super.loadConfiguration( config ); 240 * </pre> 241 * and then add or modify the configuration values from the file. 242 * <br> 243 * 244 * @param config ServletConfig passed to the servlets init() function 245 * Can be used to access the real path via ServletContext (hint) 246 * @return java.util.Properties loaded with configuration values to be used 247 * to initialize the Velocity runtime. 248 * @throws FileNotFoundException if a specified file is not found. 249 * @throws IOException I/O problem accessing the specified file, if specified. 250 * @deprecated Use VelocityViewServlet from the Velocity Tools 251 * library instead. 252 */ 253 protected Properties loadConfiguration(ServletConfig config) 254 throws IOException, FileNotFoundException 255 { 256 // This is a little overly complex because of legacy support 257 // for the initialization properties key "properties". 258 // References to OLD_INIT_PROPS_KEY should be removed at 259 // Velocity version 1.5. 260 String propsFile = config.getInitParameter(INIT_PROPS_KEY); 261 if (propsFile == null || propsFile.length() == 0) 262 { 263 ServletContext sc = config.getServletContext(); 264 propsFile = config.getInitParameter(OLD_INIT_PROPS_KEY); 265 if (propsFile == null || propsFile.length() == 0) 266 { 267 propsFile = sc.getInitParameter(INIT_PROPS_KEY); 268 if (propsFile == null || propsFile.length() == 0) 269 { 270 propsFile = sc.getInitParameter(OLD_INIT_PROPS_KEY); 271 if (propsFile != null && propsFile.length() > 0) 272 { 273 sc.log("Use of the properties initialization " + 274 "parameter '" + OLD_INIT_PROPS_KEY + "' has " + 275 "been deprecated by '" + INIT_PROPS_KEY + '\''); 276 } 277 } 278 } 279 else 280 { 281 sc.log("Use of the properties initialization parameter '" + 282 OLD_INIT_PROPS_KEY + "' has been deprecated by '" + 283 INIT_PROPS_KEY + '\''); 284 } 285 } 286 287 /* 288 * This will attempt to find the location of the properties 289 * file from the relative path to the WAR archive (ie: 290 * docroot). Since JServ returns null for getRealPath() 291 * because it was never implemented correctly, then we know we 292 * will not have an issue with using it this way. I don't know 293 * if this will break other servlet engines, but it probably 294 * shouldn't since WAR files are the future anyways. 295 */ 296 297 Properties p = new Properties(); 298 299 if ( propsFile != null ) 300 { 301 p.load(getServletContext().getResourceAsStream(propsFile)); 302 } 303 304 return p; 305 } 306 307 /** 308 * Handles HTTP <code>GET</code> requests by calling {@link 309 * #doRequest(HttpServletRequest, HttpServletResponse)}. 310 * @param request 311 * @param response 312 * @throws ServletException 313 * @throws IOException 314 */ 315 public void doGet( HttpServletRequest request, HttpServletResponse response ) 316 throws ServletException, IOException 317 { 318 doRequest(request, response); 319 } 320 321 /** 322 * Handles HTTP <code>POST</code> requests by calling {@link 323 * #doRequest(HttpServletRequest, HttpServletResponse)}. 324 * @param request 325 * @param response 326 * @throws ServletException 327 * @throws IOException 328 */ 329 public void doPost( HttpServletRequest request, HttpServletResponse response ) 330 throws ServletException, IOException 331 { 332 doRequest(request, response); 333 } 334 335 /** 336 * Handles all requests (by default). 337 * 338 * @param request HttpServletRequest object containing client request 339 * @param response HttpServletResponse object for the response 340 * @throws ServletException 341 * @throws IOException 342 */ 343 protected void doRequest(HttpServletRequest request, HttpServletResponse response ) 344 throws ServletException, IOException 345 { 346 Context context = null; 347 try 348 { 349 /* 350 * first, get a context 351 */ 352 353 context = createContext( request, response ); 354 355 /* 356 * set the content type 357 */ 358 359 setContentType( request, response ); 360 361 /* 362 * let someone handle the request 363 */ 364 365 Template template = handleRequest( request, response, context ); 366 /* 367 * bail if we can't find the template 368 */ 369 370 if ( template == null ) 371 { 372 return; 373 } 374 375 /* 376 * now merge it 377 */ 378 379 mergeTemplate( template, context, response ); 380 } 381 catch (Exception e) 382 { 383 /* 384 * call the error handler to let the derived class 385 * do something useful with this failure. 386 */ 387 388 error( request, response, e); 389 } 390 finally 391 { 392 /* 393 * call cleanup routine to let a derived class do some cleanup 394 */ 395 396 requestCleanup( request, response, context ); 397 } 398 } 399 400 /** 401 * A cleanup routine which is called at the end of the {@link 402 * #doRequest(HttpServletRequest, HttpServletResponse)} 403 * processing sequence, allowing a derived class to do resource 404 * cleanup or other end of process cycle tasks. 405 * 406 * @param request servlet request from client 407 * @param response servlet reponse 408 * @param context context created by the createContext() method 409 */ 410 protected void requestCleanup( HttpServletRequest request, HttpServletResponse response, Context context ) 411 { 412 } 413 414 /** 415 * merges the template with the context. Only override this if you really, really 416 * really need to. (And don't call us with questions if it breaks :) 417 * 418 * @param template template object returned by the handleRequest() method 419 * @param context context created by the createContext() method 420 * @param response servlet reponse (use this to get the output stream or Writer 421 * @throws ResourceNotFoundException 422 * @throws ParseErrorException 423 * @throws MethodInvocationException 424 * @throws IOException 425 * @throws UnsupportedEncodingException 426 * @throws Exception 427 */ 428 protected void mergeTemplate( Template template, Context context, HttpServletResponse response ) 429 throws ResourceNotFoundException, ParseErrorException, 430 MethodInvocationException, IOException, UnsupportedEncodingException, Exception 431 { 432 ServletOutputStream output = response.getOutputStream(); 433 VelocityWriter vw = null; 434 // ASSUMPTION: response.setContentType() has been called. 435 String encoding = response.getCharacterEncoding(); 436 437 try 438 { 439 vw = (VelocityWriter) writerPool.get(); 440 441 if (vw == null) 442 { 443 vw = new VelocityWriter(new OutputStreamWriter(output, 444 encoding), 445 4 * 1024, true); 446 } 447 else 448 { 449 vw.recycle(new OutputStreamWriter(output, encoding)); 450 } 451 452 template.merge(context, vw); 453 } 454 finally 455 { 456 if (vw != null) 457 { 458 try 459 { 460 /* 461 * flush and put back into the pool 462 * don't close to allow us to play 463 * nicely with others. 464 */ 465 vw.flush(); 466 } 467 catch (IOException e) 468 { 469 // do nothing 470 } 471 472 /* 473 * Clear the VelocityWriter's reference to its 474 * internal OutputStreamWriter to allow the latter 475 * to be GC'd while vw is pooled. 476 */ 477 vw.recycle(null); 478 writerPool.put(vw); 479 } 480 } 481 } 482 483 /** 484 * Sets the content type of the response, defaulting to {@link 485 * #defaultContentType} if not overriden. Delegates to {@link 486 * #chooseCharacterEncoding(HttpServletRequest)} to select the 487 * appropriate character encoding. 488 * 489 * @param request The servlet request from the client. 490 * @param response The servlet reponse to the client. 491 */ 492 protected void setContentType(HttpServletRequest request, 493 HttpServletResponse response) 494 { 495 String contentType = VelocityServlet.defaultContentType; 496 int index = contentType.lastIndexOf(';') + 1; 497 if (index <= 0 || (index < contentType.length() && 498 contentType.indexOf("charset", index) == -1)) 499 { 500 // Append the character encoding which we'd like to use. 501 String encoding = chooseCharacterEncoding(request); 502 //RuntimeSingleton.debug("Chose output encoding of '" + 503 // encoding + '\''); 504 if (!DEFAULT_OUTPUT_ENCODING.equalsIgnoreCase(encoding)) 505 { 506 contentType += "; charset=" + encoding; 507 } 508 } 509 response.setContentType(contentType); 510 //RuntimeSingleton.debug("Response Content-Type set to '" + 511 // contentType + '\''); 512 } 513 514 /** 515 * Chooses the output character encoding to be used as the value 516 * for the "charset=" portion of the HTTP Content-Type header (and 517 * thus returned by <code>response.getCharacterEncoding()</code>). 518 * Called by {@link #setContentType(HttpServletRequest, 519 * HttpServletResponse)} if an encoding isn't already specified by 520 * Content-Type. By default, chooses the value of 521 * RuntimeSingleton's <code>output.encoding</code> property. 522 * 523 * @param request The servlet request from the client. 524 * @return The chosen character encoding. 525 */ 526 protected String chooseCharacterEncoding(HttpServletRequest request) 527 { 528 return RuntimeSingleton.getString(RuntimeConstants.OUTPUT_ENCODING, 529 DEFAULT_OUTPUT_ENCODING); 530 } 531 532 /** 533 * Returns a context suitable to pass to the handleRequest() method 534 * <br><br> 535 * Default implementation will create a VelocityContext object, 536 * put the HttpServletRequest and HttpServletResponse 537 * into the context accessable via the keys VelocityServlet.REQUEST and 538 * VelocityServlet.RESPONSE, respectively. 539 * 540 * @param request servlet request from client 541 * @param response servlet reponse to client 542 * 543 * @return context 544 */ 545 protected Context createContext(HttpServletRequest request, HttpServletResponse response ) 546 { 547 /* 548 * create a new context 549 */ 550 551 VelocityContext context = new VelocityContext(); 552 553 /* 554 * put the request/response objects into the context 555 * wrap the HttpServletRequest to solve the introspection 556 * problems 557 */ 558 559 context.put( REQUEST, request ); 560 context.put( RESPONSE, response ); 561 562 return context; 563 } 564 565 /** 566 * Retrieves the requested template. 567 * 568 * @param name The file name of the template to retrieve relative to the 569 * template root. 570 * @return The requested template. 571 * @throws ResourceNotFoundException if template not found 572 * from any available source. 573 * @throws ParseErrorException if template cannot be parsed due 574 * to syntax (or other) error. 575 * @throws Exception if an error occurs in template initialization 576 */ 577 public Template getTemplate( String name ) 578 throws ResourceNotFoundException, ParseErrorException, Exception 579 { 580 return RuntimeSingleton.getTemplate(name); 581 } 582 583 /** 584 * Retrieves the requested template with the specified 585 * character encoding. 586 * 587 * @param name The file name of the template to retrieve relative to the 588 * template root. 589 * @param encoding the character encoding of the template 590 * 591 * @return The requested template. 592 * @throws ResourceNotFoundException if template not found 593 * from any available source. 594 * @throws ParseErrorException if template cannot be parsed due 595 * to syntax (or other) error. 596 * @throws Exception if an error occurs in template initialization 597 * 598 * @since Velocity v1.1 599 */ 600 public Template getTemplate( String name, String encoding ) 601 throws ResourceNotFoundException, ParseErrorException, Exception 602 { 603 return RuntimeSingleton.getTemplate( name, encoding ); 604 } 605 606 /** 607 * Implement this method to add your application data to the context, 608 * calling the <code>getTemplate()</code> method to produce your return 609 * value. 610 * <br><br> 611 * In the event of a problem, you may handle the request directly 612 * and return <code>null</code> or throw a more meaningful exception 613 * for the error handler to catch. 614 * 615 * @param request servlet request from client 616 * @param response servlet reponse 617 * @param ctx The context to add your data to. 618 * @return The template to merge with your context or null, indicating 619 * that you handled the processing. 620 * @throws Exception 621 * 622 * @since Velocity v1.1 623 */ 624 protected Template handleRequest( HttpServletRequest request, HttpServletResponse response, Context ctx ) 625 throws Exception 626 { 627 /* 628 * invoke handleRequest 629 */ 630 631 Template t = handleRequest( ctx ); 632 633 /* 634 * if it returns null, this is the 'old' deprecated 635 * way, and we want to mimic the behavior for a little 636 * while anyway 637 */ 638 639 if (t == null) 640 { 641 throw new Exception ("handleRequest(Context) returned null - no template selected!" ); 642 } 643 644 return t; 645 } 646 647 /** 648 * Implement this method to add your application data to the context, 649 * calling the <code>getTemplate()</code> method to produce your return 650 * value. 651 * <br><br> 652 * In the event of a problem, you may simple return <code>null</code> 653 * or throw a more meaningful exception. 654 * 655 * @deprecated Use 656 * {@link #handleRequest( HttpServletRequest request, 657 * HttpServletResponse response, Context ctx )} 658 * 659 * @param ctx The context to add your data to. 660 * @return The template to merge with your context. 661 * @throws Exception 662 */ 663 protected Template handleRequest( Context ctx ) 664 throws Exception 665 { 666 throw new Exception ("You must override VelocityServlet.handleRequest( Context) " 667 + " or VelocityServlet.handleRequest( HttpServletRequest, " 668 + " HttpServletResponse, Context)" ); 669 } 670 671 /** 672 * Invoked when there is an error thrown in any part of doRequest() processing. 673 * <br><br> 674 * Default will send a simple HTML response indicating there was a problem. 675 * 676 * @param request original HttpServletRequest from servlet container. 677 * @param response HttpServletResponse object from servlet container. 678 * @param cause Exception that was thrown by some other part of process. 679 * @throws ServletException 680 * @throws IOException 681 */ 682 protected void error( HttpServletRequest request, HttpServletResponse response, Exception cause ) 683 throws ServletException, IOException 684 { 685 StringBuffer html = new StringBuffer(); 686 html.append("<html>"); 687 html.append("<title>Error</title>"); 688 html.append("<body bgcolor=\"#ffffff\">"); 689 html.append("<h2>VelocityServlet: Error processing the template</h2>"); 690 html.append("<pre>"); 691 String why = cause.getMessage(); 692 if (why != null && why.trim().length() > 0) 693 { 694 html.append(why); 695 html.append("<br>"); 696 } 697 698 StringWriter sw = new StringWriter(); 699 cause.printStackTrace( new PrintWriter( sw ) ); 700 701 html.append( sw.toString() ); 702 html.append("</pre>"); 703 html.append("</body>"); 704 html.append("</html>"); 705 response.getOutputStream().print( html.toString() ); 706 } 707 }
1 package org.apache.velocity.servlet; 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.FileNotFoundException; 23 import java.io.IOException; 24 import java.io.OutputStreamWriter; 25 import java.io.PrintWriter; 26 import java.io.StringWriter; 27 import java.io.UnsupportedEncodingException; 28 import java.util.Properties; 29 30 import javax.servlet.ServletConfig; 31 import javax.servlet.ServletContext; 32 import javax.servlet.ServletException; 33 import javax.servlet.ServletOutputStream; 34 import javax.servlet.http.HttpServlet; 35 import javax.servlet.http.HttpServletRequest; 36 import javax.servlet.http.HttpServletResponse; 37 38 import org.apache.velocity.Template; 39 import org.apache.velocity.VelocityContext; 40 import org.apache.velocity.app.Velocity; 41 import org.apache.velocity.context.Context; 42 import org.apache.velocity.exception.MethodInvocationException; 43 import org.apache.velocity.exception.ParseErrorException; 44 import org.apache.velocity.exception.ResourceNotFoundException; 45 import org.apache.velocity.io.VelocityWriter; 46 import org.apache.velocity.runtime.RuntimeConstants; 47 import org.apache.velocity.runtime.RuntimeSingleton; 48 import org.apache.velocity.util.SimplePool; 49 50 /** 51 * Base class which simplifies the use of Velocity with Servlets. 52 * Extend this class, implement the <code>handleRequest()</code> method, 53 * and add your data to the context. Then call 54 * <code>getTemplate("myTemplate.wm")</code>. 55 * 56 * This class puts some things into the context object that you should 57 * be aware of: 58 * <pre> 59 * "req" - The HttpServletRequest object 60 * "res" - The HttpServletResponse object 61 * </pre> 62 * 63 * There are other methods you can override to access, alter or control 64 * any part of the request processing chain. Please see the javadocs for 65 * more information on : 66 * <ul> 67 * <li> loadConfiguration() : for setting up the Velocity runtime 68 * <li> createContext() : for creating and loading the Context 69 * <li> setContentType() : for changing the content type on a request 70 * by request basis 71 * <li> handleRequest() : you <b>must</b> implement this 72 * <li> mergeTemplate() : the template rendering process 73 * <li> requestCleanup() : post rendering resource or other cleanup 74 * <li> error() : error handling 75 * </ul> 76 * <br> 77 * If you put a String with key "contentType" object into the context within either your 78 * servlet or within your template, then that will be used to override 79 * the default content type specified in the properties file. 80 * 81 * @deprecated This servlet has been replaced by VelocityViewServlet, 82 * available from the Velocity-Tools sub-project. VelocityViewServlet 83 * provides support for quick, clean MVC web development. 84 * VelocityServlet will be removed in a future version of Velocity. 85 * 86 * @author Dave Bryson 87 * @author <a href="mailto:jon@latchkey.com">Jon S. Stevens</a> 88 * @author <a href="mailto:geirm@optonline.net">Geir Magnusson Jr.</a> 89 * @author <a href="kjohnson@transparent.com">Kent Johnson</a> 90 * @author <a href="dlr@finemaltcoding.com">Daniel Rall</a> 91 * $Id: VelocityServlet.java 463298 2006-10-12 16:10:32Z henning $ 92 */ 93 public abstract class VelocityServlet extends HttpServlet 94 { 95 /** 96 * The context key for the HTTP request object. 97 */ 98 public static final String REQUEST = "req"; 99 100 /** 101 * The context key for the HTTP response object. 102 */ 103 public static final String RESPONSE = "res"; 104 105 /** 106 * The HTTP content type context key. 107 */ 108 public static final String CONTENT_TYPE = "default.contentType"; 109 110 /** 111 * The default content type for the response 112 */ 113 public static final String DEFAULT_CONTENT_TYPE = "text/html"; 114 115 116 /** 117 * Encoding for the output stream 118 */ 119 public static final String DEFAULT_OUTPUT_ENCODING = "ISO-8859-1"; 120 121 /** 122 * The default content type, itself defaulting to {@link 123 * #DEFAULT_CONTENT_TYPE} if not configured. 124 */ 125 private static String defaultContentType; 126 127 /** 128 * This is the string that is looked for when getInitParameter is 129 * called (<code>org.apache.velocity.properties</code>). 130 */ 131 protected static final String INIT_PROPS_KEY = 132 "org.apache.velocity.properties"; 133 134 /** 135 * Use of this properties key has been deprecated, and will be 136 * removed in Velocity version 1.5. 137 */ 138 private static final String OLD_INIT_PROPS_KEY = "properties"; 139 140 /** 141 * Cache of writers 142 */ 143 144 private static SimplePool writerPool = new SimplePool(40); 145 146 /** 147 * Performs initialization of this servlet. Called by the servlet 148 * container on loading. 149 * 150 * @param config The servlet configuration to apply. 151 * 152 * @exception ServletException 153 */ 154 public void init( ServletConfig config ) 155 throws ServletException 156 { 157 super.init( config ); 158 159 /* 160 * do whatever we have to do to init Velocity 161 */ 162 initVelocity( config ); 163 164 /* 165 * Now that Velocity is initialized, cache some config. 166 */ 167 VelocityServlet.defaultContentType = 168 RuntimeSingleton.getString(CONTENT_TYPE, DEFAULT_CONTENT_TYPE); 169 } 170 171 /** 172 * Initializes the Velocity runtime, first calling 173 * loadConfiguration(ServletConvig) to get a 174 * java.util.Properties of configuration information 175 * and then calling Velocity.init(). Override this 176 * to do anything to the environment before the 177 * initialization of the singelton takes place, or to 178 * initialize the singleton in other ways. 179 * @param config 180 * @throws ServletException 181 */ 182 protected void initVelocity( ServletConfig config ) 183 throws ServletException 184 { 185 try 186 { 187 /* 188 * call the overridable method to allow the 189 * derived classes a shot at altering the configuration 190 * before initializing Runtime 191 */ 192 193 Properties props = loadConfiguration( config ); 194 195 Velocity.init( props ); 196 } 197 catch( Exception e ) 198 { 199 throw new ServletException("Error initializing Velocity: " + e, e); 200 } 201 } 202 203 /** 204 * Loads the configuration information and returns that 205 * information as a Properties, which will be used to 206 * initialize the Velocity runtime. 207 * <br><br> 208 * Currently, this method gets the initialization parameter 209 * VelocityServlet.INIT_PROPS_KEY, which should be a file containing 210 * the configuration information. 211 * <br><br> 212 * To configure your Servlet Spec 2.2 compliant servlet runner to pass 213 * this to you, put the following in your WEB-INF/web.xml file 214 * <br> 215 * <pre> 216 * <servlet> 217 * <servlet-name> YourServlet </servlet-name> 218 * <servlet-class> your.package.YourServlet </servlet-class> 219 * <init-param> 220 * <param-name> org.apache.velocity.properties </param-name> 221 * <param-value> velocity.properties </param-value> 222 * </init-param> 223 * </servlet> 224 * </pre> 225 * 226 * Alternately, if you wish to configure an entire context in this 227 * fashion, you may use the following: 228 * <br> 229 * <pre> 230 * <context-param> 231 * <param-name> org.apache.velocity.properties </param-name> 232 * <param-value> velocity.properties </param-value> 233 * <description> Path to Velocity configuration </description> 234 * </context-param> 235 * </pre> 236 * 237 * Derived classes may do the same, or take advantage of this code to do the loading for them via : 238 * <pre> 239 * Properties p = super.loadConfiguration( config ); 240 * </pre> 241 * and then add or modify the configuration values from the file. 242 * <br> 243 * 244 * @param config ServletConfig passed to the servlets init() function 245 * Can be used to access the real path via ServletContext (hint) 246 * @return java.util.Properties loaded with configuration values to be used 247 * to initialize the Velocity runtime. 248 * @throws FileNotFoundException if a specified file is not found. 249 * @throws IOException I/O problem accessing the specified file, if specified. 250 * @deprecated Use VelocityViewServlet from the Velocity Tools 251 * library instead. 252 */ 253 protected Properties loadConfiguration(ServletConfig config) 254 throws IOException, FileNotFoundException 255 { 256 // This is a little overly complex because of legacy support 257 // for the initialization properties key "properties". 258 // References to OLD_INIT_PROPS_KEY should be removed at 259 // Velocity version 1.5. 260 String propsFile = config.getInitParameter(INIT_PROPS_KEY); 261 if (propsFile == null || propsFile.length() == 0) 262 { 263 ServletContext sc = config.getServletContext(); 264 propsFile = config.getInitParameter(OLD_INIT_PROPS_KEY); 265 if (propsFile == null || propsFile.length() == 0) 266 { 267 propsFile = sc.getInitParameter(INIT_PROPS_KEY); 268 if (propsFile == null || propsFile.length() == 0) 269 { 270 propsFile = sc.getInitParameter(OLD_INIT_PROPS_KEY); 271 if (propsFile != null && propsFile.length() > 0) 272 { 273 sc.log("Use of the properties initialization " + 274 "parameter '" + OLD_INIT_PROPS_KEY + "' has " + 275 "been deprecated by '" + INIT_PROPS_KEY + '\''); 276 } 277 } 278 } 279 else 280 { 281 sc.log("Use of the properties initialization parameter '" + 282 OLD_INIT_PROPS_KEY + "' has been deprecated by '" + 283 INIT_PROPS_KEY + '\''); 284 } 285 } 286 287 /* 288 * This will attempt to find the location of the properties 289 * file from the relative path to the WAR archive (ie: 290 * docroot). Since JServ returns null for getRealPath() 291 * because it was never implemented correctly, then we know we 292 * will not have an issue with using it this way. I don't know 293 * if this will break other servlet engines, but it probably 294 * shouldn't since WAR files are the future anyways. 295 */ 296 297 Properties p = new Properties(); 298 299 if ( propsFile != null ) 300 { 301 p.load(getServletContext().getResourceAsStream(propsFile)); 302 } 303 304 return p; 305 } 306 307 /** 308 * Handles HTTP <code>GET</code> requests by calling {@link 309 * #doRequest(HttpServletRequest, HttpServletResponse)}. 310 * @param request 311 * @param response 312 * @throws ServletException 313 * @throws IOException 314 */ 315 public void doGet( HttpServletRequest request, HttpServletResponse response ) 316 throws ServletException, IOException 317 { 318 doRequest(request, response); 319 } 320 321 /** 322 * Handles HTTP <code>POST</code> requests by calling {@link 323 * #doRequest(HttpServletRequest, HttpServletResponse)}. 324 * @param request 325 * @param response 326 * @throws ServletException 327 * @throws IOException 328 */ 329 public void doPost( HttpServletRequest request, HttpServletResponse response ) 330 throws ServletException, IOException 331 { 332 doRequest(request, response); 333 } 334 335 /** 336 * Handles all requests (by default). 337 * 338 * @param request HttpServletRequest object containing client request 339 * @param response HttpServletResponse object for the response 340 * @throws ServletException 341 * @throws IOException 342 */ 343 protected void doRequest(HttpServletRequest request, HttpServletResponse response ) 344 throws ServletException, IOException 345 { 346 Context context = null; 347 try 348 { 349 /* 350 * first, get a context 351 */ 352 353 context = createContext( request, response ); 354 355 /* 356 * set the content type 357 */ 358 359 setContentType( request, response ); 360 361 /* 362 * let someone handle the request 363 */ 364 365 Template template = handleRequest( request, response, context ); 366 /* 367 * bail if we can't find the template 368 */ 369 370 if ( template == null ) 371 { 372 return; 373 } 374 375 /* 376 * now merge it 377 */ 378 379 mergeTemplate( template, context, response ); 380 } 381 catch (Exception e) 382 { 383 /* 384 * call the error handler to let the derived class 385 * do something useful with this failure. 386 */ 387 388 error( request, response, e); 389 } 390 finally 391 { 392 /* 393 * call cleanup routine to let a derived class do some cleanup 394 */ 395 396 requestCleanup( request, response, context ); 397 } 398 } 399 400 /** 401 * A cleanup routine which is called at the end of the {@link 402 * #doRequest(HttpServletRequest, HttpServletResponse)} 403 * processing sequence, allowing a derived class to do resource 404 * cleanup or other end of process cycle tasks. 405 * 406 * @param request servlet request from client 407 * @param response servlet reponse 408 * @param context context created by the createContext() method 409 */ 410 protected void requestCleanup( HttpServletRequest request, HttpServletResponse response, Context context ) 411 { 412 } 413 414 /** 415 * merges the template with the context. Only override this if you really, really 416 * really need to. (And don't call us with questions if it breaks :) 417 * 418 * @param template template object returned by the handleRequest() method 419 * @param context context created by the createContext() method 420 * @param response servlet reponse (use this to get the output stream or Writer 421 * @throws ResourceNotFoundException 422 * @throws ParseErrorException 423 * @throws MethodInvocationException 424 * @throws IOException 425 * @throws UnsupportedEncodingException 426 * @throws Exception 427 */ 428 protected void mergeTemplate( Template template, Context context, HttpServletResponse response ) 429 throws ResourceNotFoundException, ParseErrorException, 430 MethodInvocationException, IOException, UnsupportedEncodingException, Exception 431 { 432 ServletOutputStream output = response.getOutputStream(); 433 VelocityWriter vw = null; 434 // ASSUMPTION: response.setContentType() has been called. 435 String encoding = response.getCharacterEncoding(); 436 437 try 438 { 439 vw = (VelocityWriter) writerPool.get(); 440 441 if (vw == null) 442 { 443 vw = new VelocityWriter(new OutputStreamWriter(output, 444 encoding), 445 4 * 1024, true); 446 } 447 else 448 { 449 vw.recycle(new OutputStreamWriter(output, encoding)); 450 } 451 452 template.merge(context, vw); 453 } 454 finally 455 { 456 if (vw != null) 457 { 458 try 459 { 460 /* 461 * flush and put back into the pool 462 * don't close to allow us to play 463 * nicely with others. 464 */ 465 vw.flush(); 466 } 467 catch (IOException e) 468 { 469 // do nothing 470 } 471 472 /* 473 * Clear the VelocityWriter's reference to its 474 * internal OutputStreamWriter to allow the latter 475 * to be GC'd while vw is pooled. 476 */ 477 vw.recycle(null); 478 writerPool.put(vw); 479 } 480 } 481 } 482 483 /** 484 * Sets the content type of the response, defaulting to {@link 485 * #defaultContentType} if not overriden. Delegates to {@link 486 * #chooseCharacterEncoding(HttpServletRequest)} to select the 487 * appropriate character encoding. 488 * 489 * @param request The servlet request from the client. 490 * @param response The servlet reponse to the client. 491 */ 492 protected void setContentType(HttpServletRequest request, 493 HttpServletResponse response) 494 { 495 String contentType = VelocityServlet.defaultContentType; 496 int index = contentType.lastIndexOf(';') + 1; 497 if (index <= 0 || (index < contentType.length() && 498 contentType.indexOf("charset", index) == -1)) 499 { 500 // Append the character encoding which we'd like to use. 501 String encoding = chooseCharacterEncoding(request); 502 //RuntimeSingleton.debug("Chose output encoding of '" + 503 // encoding + '\''); 504 if (!DEFAULT_OUTPUT_ENCODING.equalsIgnoreCase(encoding)) 505 { 506 contentType += "; charset=" + encoding; 507 } 508 } 509 response.setContentType(contentType); 510 //RuntimeSingleton.debug("Response Content-Type set to '" + 511 // contentType + '\''); 512 } 513 514 /** 515 * Chooses the output character encoding to be used as the value 516 * for the "charset=" portion of the HTTP Content-Type header (and 517 * thus returned by <code>response.getCharacterEncoding()</code>). 518 * Called by {@link #setContentType(HttpServletRequest, 519 * HttpServletResponse)} if an encoding isn't already specified by 520 * Content-Type. By default, chooses the value of 521 * RuntimeSingleton's <code>output.encoding</code> property. 522 * 523 * @param request The servlet request from the client. 524 * @return The chosen character encoding. 525 */ 526 protected String chooseCharacterEncoding(HttpServletRequest request) 527 { 528 return RuntimeSingleton.getString(RuntimeConstants.OUTPUT_ENCODING, 529 DEFAULT_OUTPUT_ENCODING); 530 } 531 532 /** 533 * Returns a context suitable to pass to the handleRequest() method 534 * <br><br> 535 * Default implementation will create a VelocityContext object, 536 * put the HttpServletRequest and HttpServletResponse 537 * into the context accessable via the keys VelocityServlet.REQUEST and 538 * VelocityServlet.RESPONSE, respectively. 539 * 540 * @param request servlet request from client 541 * @param response servlet reponse to client 542 * 543 * @return context 544 */ 545 protected Context createContext(HttpServletRequest request, HttpServletResponse response ) 546 { 547 /* 548 * create a new context 549 */ 550 551 VelocityContext context = new VelocityContext(); 552 553 /* 554 * put the request/response objects into the context 555 * wrap the HttpServletRequest to solve the introspection 556 * problems 557 */ 558 559 context.put( REQUEST, request ); 560 context.put( RESPONSE, response ); 561 562 return context; 563 } 564 565 /** 566 * Retrieves the requested template. 567 * 568 * @param name The file name of the template to retrieve relative to the 569 * template root. 570 * @return The requested template. 571 * @throws ResourceNotFoundException if template not found 572 * from any available source. 573 * @throws ParseErrorException if template cannot be parsed due 574 * to syntax (or other) error. 575 * @throws Exception if an error occurs in template initialization 576 */ 577 public Template getTemplate( String name ) 578 throws ResourceNotFoundException, ParseErrorException, Exception 579 { 580 return RuntimeSingleton.getTemplate(name); 581 } 582 583 /** 584 * Retrieves the requested template with the specified 585 * character encoding. 586 * 587 * @param name The file name of the template to retrieve relative to the 588 * template root. 589 * @param encoding the character encoding of the template 590 * 591 * @return The requested template. 592 * @throws ResourceNotFoundException if template not found 593 * from any available source. 594 * @throws ParseErrorException if template cannot be parsed due 595 * to syntax (or other) error. 596 * @throws Exception if an error occurs in template initialization 597 * 598 * @since Velocity v1.1 599 */ 600 public Template getTemplate( String name, String encoding ) 601 throws ResourceNotFoundException, ParseErrorException, Exception 602 { 603 return RuntimeSingleton.getTemplate( name, encoding ); 604 } 605 606 /** 607 * Implement this method to add your application data to the context, 608 * calling the <code>getTemplate()</code> method to produce your return 609 * value. 610 * <br><br> 611 * In the event of a problem, you may handle the request directly 612 * and return <code>null</code> or throw a more meaningful exception 613 * for the error handler to catch. 614 * 615 * @param request servlet request from client 616 * @param response servlet reponse 617 * @param ctx The context to add your data to. 618 * @return The template to merge with your context or null, indicating 619 * that you handled the processing. 620 * @throws Exception 621 * 622 * @since Velocity v1.1 623 */ 624 protected Template handleRequest( HttpServletRequest request, HttpServletResponse response, Context ctx ) 625 throws Exception 626 { 627 /* 628 * invoke handleRequest 629 */ 630 631 Template t = handleRequest( ctx ); 632 633 /* 634 * if it returns null, this is the 'old' deprecated 635 * way, and we want to mimic the behavior for a little 636 * while anyway 637 */ 638 639 if (t == null) 640 { 641 throw new Exception ("handleRequest(Context) returned null - no template selected!" ); 642 } 643 644 return t; 645 } 646 647 /** 648 * Implement this method to add your application data to the context, 649 * calling the <code>getTemplate()</code> method to produce your return 650 * value. 651 * <br><br> 652 * In the event of a problem, you may simple return <code>null</code> 653 * or throw a more meaningful exception. 654 * 655 * @deprecated Use 656 * {@link #handleRequest( HttpServletRequest request, 657 * HttpServletResponse response, Context ctx )} 658 * 659 * @param ctx The context to add your data to. 660 * @return The template to merge with your context. 661 * @throws Exception 662 */ 663 protected Template handleRequest( Context ctx ) 664 throws Exception 665 { 666 throw new Exception ("You must override VelocityServlet.handleRequest( Context) " 667 + " or VelocityServlet.handleRequest( HttpServletRequest, " 668 + " HttpServletResponse, Context)" ); 669 } 670 671 /** 672 * Invoked when there is an error thrown in any part of doRequest() processing. 673 * <br><br> 674 * Default will send a simple HTML response indicating there was a problem. 675 * 676 * @param request original HttpServletRequest from servlet container. 677 * @param response HttpServletResponse object from servlet container. 678 * @param cause Exception that was thrown by some other part of process. 679 * @throws ServletException 680 * @throws IOException 681 */ 682 protected void error( HttpServletRequest request, HttpServletResponse response, Exception cause ) 683 throws ServletException, IOException 684 { 685 StringBuffer html = new StringBuffer(); 686 html.append("<html>"); 687 html.append("<title>Error</title>"); 688 html.append("<body bgcolor=\"#ffffff\">"); 689 html.append("<h2>VelocityServlet: Error processing the template</h2>"); 690 html.append("<pre>"); 691 String why = cause.getMessage(); 692 if (why != null && why.trim().length() > 0) 693 { 694 html.append(why); 695 html.append("<br>"); 696 } 697 698 StringWriter sw = new StringWriter(); 699 cause.printStackTrace( new PrintWriter( sw ) ); 700 701 html.append( sw.toString() ); 702 html.append("</pre>"); 703 html.append("</body>"); 704 html.append("</html>"); 705 response.getOutputStream().print( html.toString() ); 706 } 707 }