Mastering Apache Velocity

Wiley Publishing, Inc.

Mastering Apache Velocity

Joseph D. Gradecki

Jim Cole

Wiley Publishing, Inc.

Mastering Apache Velocity

Joseph D. Gradecki

Jim Cole

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

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

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

iv Contents

#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

Contents v

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

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

Contents vii

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 320

Class Summary 320

org.apache.velocity.anakia.TreeWalker 320

Class Summary 320

org.apache.velocity.app.FieldMethodizer 320

Class Summary 320

org.apache.velocity.app.Velocity 321

Class Summary 321

org.apache.velocity.app.VelocityEngine 322

viii Contents

Class Summary 322

org.apache.velocity.app.event.EventCartridge 323

Class Summary 324

org.apache.velocity.app.event.EventHandler 324

org.apache.velocity.app.event.MethodExceptionEventHandler 324

Class Summary 324

org.apache.velocity.app.event.NullSetEventHandler 324

Class Summary 325

org.apache.velocity.app.event.ReferenceInsertionEventHandler 325

Class Summary 325

org.apache.velocity.app.tools.VelocityFormatter 325

Class Summary 325

org.apache.velocity.app.tools.VelocityFormatter.VelocityAlternator 326

Class Summary 326

org.apache.velocity.app.tools.VelocityFormatter.VelocityAutoAlternator 326

Class Summary 327

org.apache.velocity.context.AbstractContext 327

Class Summary 327

org.apache.velocity.context.Context 327

Class Summary 328

org.apache.velocity.context.InternalContextAdapterImpl 328

Class Summary 328

org.apache.velocity.context.InternalEventContext 329

Class Summary 329

org.apache.velocity.context.VMContext 329

Class Summary 329

org.apache.velocity.convert.WebMacro 330

Class Summary 330

org.apache.velocity.exception.MethodInvocationException 331

Class Summary 331

org.apache.velocity.exception.ParseErrorException 331

Class Summary 331

org.apache.velocity.exception.VelocityException 331

Class Summary 332

org.apache.velocity.io.VelocityWriter 332

Class Summary 332

org.apache.velocity.servlet.VelocityServlet 333

Class Summary 333

org.apache.velocity.texen.ant.Texen 334

Class Summary 334

org.apache.velocity.runtime.RuntimeInstance 335

Class Summary 335

org.apache.velocity.runtime.RuntimeServices 336

Class Summary 337

org.apache.velocity.runtime.RuntimeSingleton 338

Class Summary 338

Contents ix

org.apache.velocity.runtime.VelocimacroFactory 340

Class Summary 340

org.apache.velocity.runtime.VelocimacroManager 340

Class Summary 340

org.apache.velocity.runtime.VelocimacroManager.MacroEntry 341

Class Summary 341

Appendix B Velocity Sites 343

Jakarta Velocity Sites 343

The Jakarta Velocity Site 343

Velocity Tools 343

WebMacro 343

DVSL 344

Velocity Generator 344

Velocity UI for Eclipse 344

Tutorials 344

Template-Based Wizards in JBuilder 344

Start Up the Velocity Template Engine 344

Getting Up to Speed with Velocity 344

Take the Fast Track to Text Generation 344

What Is Velocity? 344

Template for Going Fast 344

Applications 345

Roller Web Logger 345

Maverick 345

vDoclet 345

Turbine 345

WebWork 345

JPublish 345

JeeWiz! 345

Luxor 346

Melati 346

Velocity Support in OpenCms 346

JetSpeed and Portlets 346

JNLP to HTML Converter 346

Velocity and Web Album 346

Index 347

x Contents

xi

Joseph D. Gradecki is a software engineer at Comprehensive Software Solu￾tions, where he works on their SABIL product, a enterprise-level securities pro￾cessing system used by traders. He has built numerous dynamic, enterprise

applications using Java, Velocity, AspectJ, servlets, JSPs, MySQL, XML, and

more. He has also built P2P distributed computing systems in a variety of lan￾guages including Java/JXTA, C/C++, and Linda.

Joe is also an associate professor of computer science at Colorado Technical

University, where he teaches Java, C++, and Software Engineering. He is also

an accomplished writer with John Wiley & Sons, Inc. where he has published

several programming books on Java and MySQL, AspectJ, and JXTA.

Jim Cole is a senior software engineer specializing in Internet and knowledge

management systems. He is an active J2EE developer who regularly uses open

source tools such as Struts and Velocity, and also has experience with Perl and

PHP. Jim serves as a system administrator for several Web-based projects,

where his duties include custom software development, database management,

and security maintenance.

ABOUT THE AUTHORS