a 457949 FM.qxd 6/13/03 1:45 PM Page i Mastering Apache Velocity Joseph D. Gradecki Jim Cole Wiley Publishing, Inc. a 457949 FM.qxd 6/13/03 1:45 PM Page xii a 457949 FM.qxd 6/13/03 1:45 PM Page i Mastering Apache Velocity Joseph D. Gradecki Jim Cole Wiley Publishing, Inc. a 457949 FM.qxd 6/13/03 1:45 PM Page ii Publisher: Joe Wikert Copyeditor: Elizabeth Welch Executive Editor: Robert Elliott Compositors: Gina Rexrode and Amy Hassos Editorial Manager: Kathryn Malm Managing Editor: Vincent Kunkemueller Book Producer: Ryan Publishing Group, Inc. Copyright © 2003 by Joseph D. Gradecki and Jim Cole. All rights reserved. Published by Wiley Publishing, Inc., Indianapolis, Indiana Published simultaneously in Canada No part of this publication may be reproduced, stored in a retrieval system, or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning, or otherwise, except as permitted under Section 107 or 108 of the 1976 United States Copyright Act, without either the prior written permission of the Publisher, or authorization through payment of the appropriate per-copy fee to the Copyright Clearance Center, Inc., 222 Rosewood Drive, Danvers, MA 01923, (978) 750-8400, fax (978) 646-8700. Requests to the Publisher for permission should be addressed to the Legal Department, Wiley Publishing, Inc., 10475 Crosspoint Blvd., Indianapolis, IN 46256, (317) 572-3447, fax (317) 572-4447, E-mail: [email protected]. Limit of Liability/Disclaimer of Warranty: While the publisher and author have used their best efforts in preparing this book, they make no representations or warranties with respect to the accuracy or com- pleteness of the contents of this book and specifically disclaim any implied warranties of mer- chantability or fitness for a particular purpose. No warranty may be created or extended by sales representatives or written sales materials. The advice and strategies contained herein may not be suit- able for your situation. You should consult with a professional where appropriate. Neither the pub- lisher nor author shall be liable for any loss of profit or any other commercial damages, including but not limited to special, incidental, consequential, or other damages. For general information on our other products and services please contact our Customer Care Department within the United States at (800) 762-2974, outside the United States at (317) 572-3993 or fax (317) 572-4002. Trademarks: Wiley, the Wiley Publishing logo and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates, in the United States and other countries, and may not be used without written permission. Java is a trademark of Sun Microsystems, Inc. All other trademarks are the property of their respective owners. Wiley Publishing, Inc., is not associated with any product or vendor mentioned in this book. Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books. ISBN: 0-471-45794-9 Printed in the United States of America 10 9 8 7 6 5 4 3 2 1 a 457949 FM.qxd 6/13/03 1:45 PM Page iii CONTENTS About the Authors xi Introduction xiii What’s in This Book xiv Who Should Read This Book xiv Book Organization xv Part I Introduction to Velocity and MVC Chapter 1 Web Development Basics 1 Static Web Pages 1 Introducing CGI 2 Scripting: JSP/ASP/PHP 3 Future Development 4 What's Next 5 Chapter 2 MVC Fundamentals 7 Mixing Presentation and Logic 7 Smalltalk-80 MVC Triad 10 The Model 11 The View 12 The Controller 12 The MVC Architecture 12 Sun Models 1 and 2 13 Extending MVC to Web Applications 13 A Practical MVC 14 What's Next 16 Chapter 3 Introduction to Velocity 17 What Is Velocity? 17 How It Works 18 Designing the Page 18 Requesting the Right Information 19 Coding the Information 19 Displaying the Information 20 Velocity Features 21 What's Next 22 iii a 457949 FM.qxd 6/13/03 1:45 PM Page iv iv Contents Part II Velocity Basics Chapter 4 Installing Velocity 23 Prerequisites 23 Obtaining Velocity 24 Velocity Versions 27 Compiling Velocity 27 Testing the Velocity Installation 30 Running the Examples 31 examples/appexample1 31 examples/appexample2 31 examples/servletexample1 31 examples/servletexample2 32 examples/context_example 33 examples/logger_example 34 examples/xmlapp_example 34 examples/event_example 35 What's Next 35 Chapter 5 Building a Hello World Example 37 Hello World! 37 A Velocity Template without Context 38 The Velocity Template with Context 41 Velocity and the Web 42 What's Next 44 Chapter 6 Understanding Templates and Context 45 Using Templates 45 The Context 49 Putting the Pieces Together 50 What's Next 55 Chapter 7 Exploring References 57 Reference Types 57 Variables 58 Methods 63 Properties 66 Formal Reference Notation 70 Quiet Notation 71 Escaping References 72 What's Next 76 Chapter 8 Using Directives 77 #stop 77 #include 80 #parse 83 a 457949 FM.qxd 6/13/03 1:45 PM Page v Contents v #set 85 #end 93 #if 94 #else 96 #elseif 97 #foreach 100 #macro 105 Escaping Directives 105 What's Next 107 Chapter 9 Introducing Velocimacros 109 Argument Passing 109 Inline vs. Library Macros 114 Velocimacro Properties 115 velocimacro.library 115 velocimacro.permissions.allow.inline 115 velocimacro.permissions.allow.inline.to.replace.global 116 velocimacro.permissions.allow.inline.local.scope 116 velocimacro.context.localscope 116 velocimacro.library.autoreload 116 velocimacro.messages.on 117 Nesting and Recursion 117 What's Next 118 Chapter 10 Taking Control of Velocity 119 Initializing the Runtime Configuration 119 More Velocity Properties 123 Directive Properties 123 Encoding 124 Logging 125 Resource Management 126 Miscellaneous 128 Resource Loaders 129 Events 130 Context Chaining 133 Managing Whitespace 134 Singleton vs. Non-Singleton 137 What's Next 137 Part III Developing with Velocity Chapter 11 Velocity, XML, and Anakia 139 Accessing XML in Velocity Templates 139 Velocity and Anakia 142 The Ant Build Task 142 Source Documents 144 a 457949 FM.qxd 6/13/03 1:45 PM Page vi vi Contents Anakia Velocity Stylesheets 145 Context References 149 Outputting XML Using Velocity 150 The Artist Query XML 150 The Full CD Report XML 152 What's Next 154 Chapter 12 Using Velocity with Servlets 155 Using Servlets 155 A Common Format for Servlets 156 Extending Servlets with VelocityServlet 157 Basic Velocity Servlet Code 157 Creating an MVC Application 160 The Database Structure 161 Database Access 162 The Model Code 163 The View Code 166 The Controller Code 170 Advanced Servlet Functionality 175 Adding Reports 178 What's Next 183 Chapter 13 Velocity and Internationalization 185 Java Internationalization Components 185 The Java Locale Class 186 Resource Bundles 186 An International CD Web Application 187 What's Next 193 Chapter 14 Using Velocity and Turbine 195 What Is Turbine? 195 The Turbine Architecture 196 The Action Module 197 The Navigation Module 198 The Screen Module 198 The Layout Module 198 The Page Module 198 Module Object Encapsulation 199 How Does It Work? 200 Obtaining and Installing TDK 201 Testing the TDK Installation 202 Your First Turbine Application 203 Dissecting the Application 206 Adding a User with testApplication 215 Rebuilding and Deployment 220 Advanced Velocity in Turbine 220 What's Next 222 a 457949 FM.qxd 6/13/03 1:45 PM Page vii Contents vii Chapter 15 Using Velocity and Maverick 223 How Maverick Works 224 The Load Process 225 The Execution Process 225 Downloading and Installing Maverick 226 Requirements 227 Installing Maverick 227 Testing the Installation with the FriendBook Application 228 Installing the Optional Velocity Module 228 The Maverick Hello World 229 Writing the web.xml File 229 Writing the maverick.xml File 231 Building Controller Classes 232 Building View Files 233 Velocity and Maverick 234 Commands 235 Controllers 237 Velocity Templates 240 What's Next 246 Chapter 16 Velocity IDEs 247 IntelliJ's IDEA 247 UltraEdit 250 JEdit 251 TextPad 252 Emacs 252 What's Next 253 Chapter 17 Using Velocity and Struts 255 Introducing Struts 255 Installing Struts 256 A Sample Application 257 Building the ActionForm 257 Creating an Action 258 Configuring Struts 259 The web.xml File 260 The Success Page 262 The Register Page 263 Setup 265 What's Next 266 Chapter 18 The Hotel Reservation Velocity Application 269 The Hotel Specifications 269 The Hotel Architecture 270 The Hotel Database Schema 271 Configuring the Maverick XML 272 a 457949 FM.qxd 6/13/03 1:45 PM Page viii viii Contents The Look and Feel Frame 274 Building the Welcome Pages 277 Searching for a Room 280 Booking a Room 290 Looking Up a Room 293 What's Next 298 Chapter 19 Using JSP and Velocity 299 The Velocity Taglib 299 Installing the Velocity Taglib 300 Adding the Velocity Taglib to JSP 301 Beans and Tags 303 What's Next 303 Chapter 20 DVSL and Velocity 305 Obtaining and Installing DVSL 305 Creating a Simple Transformation 306 Compiling the DVSL/XML 307 Using Nodes 309 The DVSL Toolbox 310 Using the Command Line 313 Part IV References Appendix A The Velocity Specification 315 org.apache.velocity.Template 315 Class Summary 315 org.apache.velocity.VelocityContext 316 Class Summary 316 org.apache.velocity.anakia.AnakiaElement 316 Class Summary 316 org.apache.velocity.anakia.AnakiaJDOMFactory 317 Class Summary 317 org.apache.velocity.anakia.AnakiaTask 317 Class Summary 317 org.apache.velocity.anakia.Escape 318 Class Summary 318 org.apache.velocity.anakia.NodeList 318 Class Summary 318 org.apache.velocity.anakia.OutputWrapper