This content was uploaded by our users and we assume good faith they have the permission to share this book. If you own the copyright to this book and it is wrongfully on our website, we offer a simple DMCA procedure to remove your content from our site. Start by pressing the button below!
All rights reserved. No part of this book shall be reproduced, stored in a retrieval system, or transmitted by any means, electronic, mechanical, photocopying, recording, or otherwise, without written permission from the publisher. No patent liability is assumed with respect to the use of the information contained herein. Although every precaution has been taken in the preparation of this book, the publisher and author assume no responsibility for errors or omissions. Nor is any liability assumed for damages resulting from the use of the information contained herein.
ACQUISITIONS EDITOR
International Standard Book Number: 0-672-32107-6
Christina Smith
Library of Congress Catalog Card Number: 00-111799
COPY EDITOR
Printed in the United States of America
Cynthia Fields
First Printing: June 2001
INDEXER
04
03
02
01
4
3
2
1
Trademarks All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Sams Publishing cannot attest to the accuracy of this information. Use of a term in this book should not be regarded as affecting the validity of any trademark or service mark.
Paul Boger
EXECUTIVE EDITOR
Carol Ackerman
DEVELOPMENT EDITOR Tiffany Taylor
MANAGING EDITOR Matt Purcell
PROJECT EDITOR
Erika Millen
PROOFREADER Benjamin Berg
TECHNICAL EDITOR Rob Tiffany
TEAM COORDINATOR
Warning and Disclaimer
Lynne Williams
Every effort has been made to make this book as complete and as accurate as possible, but no warranty or fitness is implied. The information provided is on an “as is” basis. The author and the publisher shall have neither liability nor responsibility to any person or entity with respect to any loss or damages arising from the information contained in this book.
INTERIOR DESIGNER Anne Jones
COVER DESIGNER Aren Howell
PAGE LAYOUT Ayanna Lacey Heather Hiatt Miller Stacey Richwine-DeRome
Overview Contents at a Glance Introduction 1 1 PART I
Web Applications and the Model View Controller (MVC) Design Pattern 7 Servlet Fundamentals
2
Servlet Overview and Architecture 15
3
Servlet Basics 25
4
Servlets and HTML 33
5
Servlet Sessions 41
6
HTTP Tunneling 59
7
Servlets, JDBC, and Inter-Servlet Communications 85
8
Servlets and JavaMail 131
9
Servlet Security 143
10
Servlets and XML 151
11
Servlets and LDAP 163
12
Servlets and Enterprise JavaBeans 189
13
A Servlet Controller 225
PART II
JSP Fundamentals
14
JSP Overview and Architecture 235
15
JSP Implicit Objects 247
16
JSP Standard Actions 261
17
Using JavaBeans and JSP Scopes 281
18
Handling JSP Errors 293
19
Custom JSP Tag Libraries 301
PART III
Servlet and JSP Web Applications
20
Catalog Case Study 321
21
An LDAP Web Client 347
22
A Stock Trader 363
23
Wireless Application Development Using WAP 385
24
WML/WMLScript Development 397
PART IV
Appendixes
A
Web Applications and Configuring the Servlet Engine 419
B
The javax.servlet Package 429
C
The javax.servlet.http Package 461
D
The javax.servlet.jsp Package 489
E
The javax.servlet.jsp.tagext Package 513
F
WML (The Wireless Markup Language) 543
G
WMLScript 547 Index 559
Contents Introduction 1 1
PART I
Web Applications and the Model View Controller (MVC) Design Pattern 7 The Model View Controller (MVC) Design Pattern ..............................8 A Server-Side Implementation of the MVC............................................8 Servlets as MVC Controllers..............................................................9 JSPs as MVC Views ........................................................................10 Summary ................................................................................................10
Servlet Fundamentals
2
Servlet Overview and Architecture 15 Movement to Server-Side Java ..............................................................16 Definition of a Java Servlet ..................................................................16 Practical Applications for Java Servlets ................................................16 Java Servlet Alternatives........................................................................17 Common Gateway Interface ............................................................17 Proprietary APIs ..............................................................................18 Server-Side JavaScript......................................................................18 Microsoft’s Active Server Pages ......................................................18 Reasons to Use Java Servlets ................................................................19 Efficiency..........................................................................................19 Persistency ........................................................................................19 Portability ........................................................................................19 Robustness ........................................................................................19 Extensibility......................................................................................20 Security ............................................................................................20 The Java Servlet Architecture ................................................................20 GenericServlet and HttpServlet........................................................20 Summary ................................................................................................23
3
Servlet Basics 25 The Life Cycle of a Servlet ..................................................................26 The init() Method ............................................................................26 The service() Method ......................................................................26 The destroy() Method ......................................................................27 A Basic Servlet ......................................................................................27 The BasicServlet Source ..................................................................27 Dissecting the BasicServlet ..................................................................29 Where Does the BasicServlet Fit into the Servlet Framework? ......29 The Methods Overridden by the BasicServlet ................................30 Summary ................................................................................................31
vi
DEVELOPING JAVA SERVLETS, SECOND EDITION 4
Servlets and HTML 33 Retrieving Form Data in a Servlet ........................................................34 Servicing the GET and POST Requests ..........................................34 How the FormServlet Works ............................................................38 Summary ................................................................................................39
5
Servlet Sessions 41 What Is Session Tracking? ....................................................................42 Using Hidden Form Fields ....................................................................42 Working with Cookies ..........................................................................46 URL Rewriting ......................................................................................50 Session Tracking with the Servlet API ..................................................51 Summary ................................................................................................58
6
HTTP Tunneling 59 What Is HTTP Tunneling? ....................................................................60 Object Serialization................................................................................60 Creating an HTTP Tunneling Client......................................................66 Creating an HTTP Tunneling Servlet ....................................................71 A Practical HTTP Tunneling Example..................................................73 The OrderStatusApplet ....................................................................74 The OrderStatusServlet ....................................................................80 Pros and Cons of Applet-to-Servlet Communication ............................83 Summary ................................................................................................84
7
Servlets, JDBC, and Inter-Servlet Communications 85 What is the JDBC? ................................................................................86 Two- and Three-Tier Database Access Models ....................................86 JDBC Driver Types................................................................................87 Type 1: JDBC-ODBC Bridge, Plus ODBC Driver ..........................88 Type 2: Native-API, Partly Java Driver............................................88 Type 3: JDBC-Net, Pure Java Driver ..............................................89 Type 4: Native-Protocol, Pure Java Driver ......................................90 JDBC Basics ........................................................................................92 Installing and Setting Up a Type 1 Driver ......................................92 Establishing a Database Connection ................................................93 Performing the Basic SQL Commands ............................................94 A Basic JDBC Servlet ........................................................................107 A JDBC Connection Pool....................................................................112 Inter-Servlet Communications ............................................................123 Summary ..............................................................................................130
CONTENTS 8
Servlets and JavaMail 131 JavaMail and Internet E-mail ..............................................................132 JavaMail Services ..........................................................................132 Preparing to Use JavaMail ..................................................................133 A JavaMail Example............................................................................133 Using JavaMail in a Servlet ................................................................137 Summary ..............................................................................................141
9
Servlet Security 143 Introduction to Security ......................................................................144 Roll Your Own ....................................................................................144 Basic Authentication ............................................................................148 Digest Authentication ..........................................................................148 Secure Sockets Layer (SSL) ................................................................149 Summary ..............................................................................................150
10
Servlets and XML 151 XML and Java......................................................................................153 Using the SAX API ........................................................................153 Using XML in a Servlet ......................................................................159 Summary ..............................................................................................162
11
Servlets and LDAP 163 A Brief Discussion of Directories ......................................................164 Attributes ........................................................................................165 Distinguished Names......................................................................165 LDAP ..................................................................................................165 JNDI ....................................................................................................166 Using JNDI to Access LDAP ..............................................................166 Installing Netscape Directory Server ............................................167 Connecting......................................................................................168 Searching the LDAP Server ..........................................................170 Adding an Object to an LDAP Server............................................174 Removing an Object ......................................................................176 Modifying Information Stored in LDAP........................................177 Accessing LDAP from a Servlet..........................................................184 Summary ..............................................................................................188
12
Servlets and Enterprise JavaBeans 189 What Are Enterprise JavaBeans? ........................................................190 EJB Terminology ................................................................................191 Installing JRun ....................................................................................191 The Enterprise JavaBean......................................................................192 Interfaces and Classes ....................................................................192 Naming Conventions ......................................................................193
vii
viii
DEVELOPING JAVA SERVLETS, SECOND EDITION Session Beans ......................................................................................194 Stateless Versus Stateful ................................................................194 Session Bean Interfaces and Classes..............................................195 Deployment Descriptor ..................................................................200 Client View of a Session Bean ......................................................204 Session Bean Lifecycle ..................................................................205 Entity Beans ........................................................................................206 Who Handles the Persistence? ......................................................206 Entity Bean Interfaces and Classes ................................................207 Deployment Descriptor ..................................................................215 Client View of an Entity Bean........................................................217 Entity Bean Life Cycle ..................................................................217 Deploying Your EJB to Your Application Server ................................218 Packaging the jar File ....................................................................218 Deploying the jar File ....................................................................220 Viewing Deployed Beans ..............................................................220 Servlets as EJB Clients ........................................................................220 Summary ..............................................................................................224 13
PART II
A Servlet Controller 225 What Is a Controller? ..........................................................................226 A Servlet Controller ............................................................................226 The Service Interface ..........................................................................229 A Sample Service ................................................................................230 Summary ..............................................................................................232
JSP Fundamentals
14
JSP Overview and Architecture 235 What are JavaServer Pages? ................................................................236 The Components of a JavaServer Page ..............................................237 Directives........................................................................................238 Standard Actions ............................................................................240 Implicit Objects ..............................................................................241 JSP Scripting ..................................................................................242 Summary ..............................................................................................246
15
JSP Implicit Objects 247 What are Implicit Objects? ..................................................................248 The request Object ..............................................................................249 The response Object ............................................................................250 The pageContext Object ......................................................................251 The session Object ..............................................................................252
CONTENTS The application Object ........................................................................254 Testing the JSPs..............................................................................256 The out Object ....................................................................................257 The config Object ................................................................................258 The page Object ..................................................................................260 The exception Object ..........................................................................260 Summary ..............................................................................................260 16
JSP Standard Actions 261 What Are Standard Actions?................................................................262 JavaBean Standard Actions..................................................................262 The <jsp:useBean> Standard Action ..............................................262 The <jsp:setProperty> Standard Action ........................................263 The <jsp:getProperty> Standard Action ........................................264 A JSP Example Using JavaBeans ..................................................264 Other Standard Actions........................................................................268 The <jsp:param> Standard Action ................................................268 The <jsp:include> Standard Action................................................269 The <jsp:forward> Standard Action ..............................................274 The <jsp:plugin> Standard Action ................................................278 Summary ..............................................................................................279
17
Using JavaBeans and JSP Scopes 281 The Counter JavaBean ........................................................................282 page Scope ..........................................................................................283 request Scope ......................................................................................284 session Scope ......................................................................................286 application Scope ................................................................................289 Summary ..............................................................................................291
18
Handling JSP Errors 293 JSP Translation-Time Errors................................................................294 JSP Request-Time Errors ....................................................................294 Creating a JSP Error Page ..............................................................294 Using a JSP Error Page ..................................................................297 Summary ..............................................................................................300
19
Custom JSP Tag Libraries 301 JSP Customs Tags ................................................................................302 Deploying Tag Libraries ......................................................................302 Creating a Taglib Descriptor ..........................................................302 Deploying the Tag Handlers to Your Web Application ..................304 Adding a taglib Entry to Your Web Application ............................304 Adding the taglib Directive to Your JSP ........................................305
ix
x
DEVELOPING JAVA SERVLETS, SECOND EDITION Developing Custom JSP Tags Handlers ..............................................306 Tags Without Bodies ......................................................................306 Tags with Bodies ............................................................................311 Tags with Attributes........................................................................314 Summary ..............................................................................................317
PART III
Servlet and JSP Web Applications
20
Catalog Case Study 321 Catalog Requirements..........................................................................322 Models..................................................................................................322 Shopping Cart ................................................................................325 Views....................................................................................................328 Catalog Layout ..............................................................................328 Index View......................................................................................332 Movie List View ............................................................................334 Shopping Cart View........................................................................335 Check Out View..............................................................................336 Controllers............................................................................................338 The ListMovies Service..................................................................338 The AddToCart Service ..................................................................341 The EmptyCart Service ..................................................................343 The CheckOut Service....................................................................343 Using the Online Catalog ....................................................................344 Summary ..............................................................................................345
21
An LDAP Web Client 347 Directory Requirements ......................................................................348 Models..................................................................................................348 Views....................................................................................................349 The Directory Layout ....................................................................349 Index View......................................................................................351 Directory View................................................................................352 Add View ........................................................................................354 Controllers............................................................................................356 The LDAPDirectory Service ..........................................................356 The LDAPInsert Service ................................................................358 The LDAPDelete Service ..............................................................359 Using the LDAP Application ..............................................................360 Summary ..............................................................................................361
22
A Stock Trader 363 Trader Requirements............................................................................364 Models..................................................................................................364
CONTENTS Views....................................................................................................367 Trader Layout ................................................................................367 Index View......................................................................................370 Get Quote View ..............................................................................371 Buy/Sell View ................................................................................372 Controllers............................................................................................375 The GetQuote Service ....................................................................375 The Buy Service ............................................................................377 The Sell Service..............................................................................380 Using the Trader Application ..............................................................382 Summary ..............................................................................................383 23
Wireless Application Development Using WAP 385 WAP History: Past, Present, and Future..............................................386 The Past: Handheld Device Markup Language (HDML) ..............386 Present: WAP Hits the Street..........................................................387 The Future: WAP 1.2 and Beyond ................................................387 Why WAP? ..........................................................................................389 Screen Size Considerations ............................................................389 Network Considerations ................................................................390 Bandwidth Considerations..............................................................390 WAP Architecture ................................................................................391 Emulators, Browsers, and Developer Tools ........................................392 Online Emulators............................................................................392 WinWAP Browser ..........................................................................392 Emulators and Developer Tools ....................................................394 PDA WAP Browsers ......................................................................394 Application Servers ........................................................................395 Suggested Resources............................................................................395 Summary ..............................................................................................396
24
WML/WMLScript Development 397 The Wireless Markup Language (WML) ............................................398 WML Language Basics ..................................................................398 A WML Example ................................................................................401 WMLScript ..........................................................................................405 Calling WMLScript from WML ....................................................406 Language Basics ............................................................................406 Operators ........................................................................................407 Statements ......................................................................................407 The Standard Libraries ..................................................................408 WMLScript Example......................................................................409
xi
xii
DEVELOPING JAVA SERVLETS, SECOND EDITION Wireless Application Developing Using Servlets................................412 Configuring Server MIME Types ..................................................412 A Quick “Hello World!” WML Servlet ........................................413 Multiple Device Support ................................................................414 Maintaining a Site in XML ............................................................414 Summary ..............................................................................................415
PART IV
Appendixes
A
Web Applications and Configuring the Servlet Engine 419 Web Applications ................................................................................420 The ServletContext in Relation to the Web Application................420 The Directory Structure..................................................................420 Web Application Deployment Descriptors ....................................421 Web Archive (WAR) Files ..................................................................422 Servlet Requirements ..........................................................................422 Apache Tomcat ....................................................................................422 Installing the Tomcat Server ..........................................................422 Adding the DJS Web Application ..................................................424 Building and Installing the BasicServlet........................................426 Summary ..............................................................................................427
B
The javax.servlet Package 429 The javax.servlet Interfaces ................................................................430 The RequestDispatcher Interface ..................................................431 The Servlet Interface ......................................................................432 The ServletConfig Interface ..........................................................433 The ServletContext Interface..........................................................434 The ServletRequest Interface ........................................................440 The ServletResponse Interface ......................................................445 The SingleThreadModel Interface..................................................448 Classes..................................................................................................448 The GenericServlet Class ..............................................................449 The ServletInputStream Class ........................................................452 The ServletOutputStream Class ....................................................452 Exceptions............................................................................................456 The ServletException ....................................................................456 The UnavailableException ............................................................458
C
The javax.servlet.http Package 461 Interfaces..............................................................................................462 The HttpServletRequest Interface ..................................................462 The HttpServletResponse Interface................................................468 The HttpSession Interface ..............................................................476 The HttpSessionBindingListener Interface ....................................479
CONTENTS Classes..................................................................................................479 The Cookie Class............................................................................479 The HttpServlet Class ....................................................................483 The HttpSessionBindingEvent Class..............................................486 The HttpUtils Class ........................................................................487 D
The javax.servlet.jsp Package 489 Interfaces..............................................................................................490 The HttpJspPage Interface..............................................................490 The JspPage Interface ....................................................................491 Classes..................................................................................................492 The JspEngineInfo Class ................................................................492 The JspFactory Class......................................................................492 The JspWriter Class........................................................................494 The PageContext Class ..................................................................502 Exceptions............................................................................................511 The JspError Exception ..................................................................511 The JspException Exception ..........................................................512
E
The javax.servlet.jsp.tagext Package 513 Interfaces..............................................................................................514 The Tag Interface............................................................................514 The BodyTag Interface ..................................................................520 Classes..................................................................................................522 The BodyContent Class..................................................................522 The BodyTagSupport Class............................................................523 The TagSupport Class ....................................................................525 The TagAttributeInfo Class ............................................................528 The TagData Class..........................................................................530 The TagExtraInfo Class ..................................................................532 The TagInfo Class ..........................................................................533 The TagLibraryInfo Class ..............................................................537 The VariableInfo Class ..................................................................539
F
WML (The Wireless Markup Language) 543 WML Elements....................................................................................544
G
WMLScript 547 Lang Library ........................................................................................548 abort()—The abort Function ..........................................................548 abs()—The abs Function ................................................................548 characterSet()—The characterSet Function ..................................548 exit()—The exit Function ..............................................................548 float()—The float Function ............................................................548
xiii
xiv
DEVELOPING JAVA SERVLETS, SECOND EDITION isFloat()—The isFloat Function ....................................................549 isInt()—The isInt Function ............................................................549 max()—The max Function ............................................................549 maxInt()—The maxInt Function ....................................................549 min()—The min Function ..............................................................549 minInt()—The minInt Function......................................................549 parseFloat()—The parseFloat Function..........................................549 parseInt()—The parseInt Function ................................................549 random()—The random Function ..................................................550 seed()—The seed Function ............................................................550 Float Library ........................................................................................550 ceil()—The ceil Function ..............................................................550 floor()—The floor Function ..........................................................550 int()—The int Function ..................................................................550 maxFloat()—The maxFloat Function ............................................550 minFloat()—The minFloat Function ..............................................551 pow()—The pow Function ............................................................551 round()—The round function ........................................................551 sqrt()—The sqrt Function ..............................................................551 String Library ......................................................................................551 charAt()—The charAt Function ....................................................551 compare()—The compare Function ..............................................551 elementAt()—The elementAt Function..........................................551 elements()—The elements Function ..............................................552 find()—The find Function ..............................................................552 format()—The format Function......................................................552 insertAt()—The insertAt Function ................................................552 isEmpty()—The isEmpty Function ................................................552 length()—The length Function ......................................................552 removeAt()—The removeAt Function ..........................................552 replace()—The replace Function....................................................553 replaceAt()—The replaceAt Function............................................553 squeeze()—The squeeze Function..................................................553 subString()—The subString Function ............................................553 toString()—The toString Function ................................................553 trim()—The trim Function..............................................................553 URL Library ........................................................................................553 escapeString()—The escapeString Function ..................................554 getBase()—The getBase Function..................................................554 getFragment()—The getFragment Function ..................................554 getHost()—The getHost Function ..................................................554 getParameters()—The getParameters Function..............................554
CONTENTS getPath()—The getPath Function ..................................................554 getPort()—The getPort Function....................................................555 getQuery()—The getQuery Function ............................................555 getReferer()—The getReferer Function ........................................555 getScheme()—The getScheme Function........................................555 isValid()—The isValid Function ....................................................555 loadString()—The loadString Function..........................................555 resolve()—The resolve Function....................................................555 unescapeString()—The unescapeString Function ..........................555 WMLBrowser Library ........................................................................556 getCurrentCard()—The getCurrentCard Function ........................556 getVar()—The getVar Function ......................................................556 go()—The go Function ..................................................................556 newContext()—The newContext Function ....................................556 prev()—The prev Function ............................................................556 refresh()—The refresh Function ....................................................556 setVar()—The setVar Function ......................................................556 Dialogs Library ....................................................................................557 alert()—The alert Function ............................................................557 confirm()—The confirm Function..................................................557 prompt()—The prompt Function....................................................557 Index 559
xv
About the Authors Lead Author James Goodwill is the co-founder and chief architect at Virtuas Solutions, LLC., located in Denver, Colorado. He has extensive experience in designing and architecting e-business applications. James is also the author of Pure JavaServer Pages, which provides a thorough examination of the JavaServer Pages technology. James is currently leading Virtuas’s efforts in developing cutting edge tools designed for J2EE e-business acceleration. You can find the source code and support for this text at the Virtuas Solutions Web site, http://www.virtuas.com. Select the Publications link.
Contributing Author Bryan Morgan is an experienced writer and software developer and founder of the Wireless Developer Network (http://www.wirelessdevnet.com) in 1999. He is a respected voice in the wireless industry, is a regular contributor to industry publications, and has been a featured speaker at numerous events. He holds a B.S. in electrical engineering from Clemson University and lives in Pensacola, FL with his wife Becky and beautiful daughter Emma.
Dedication To my girls Christy, Abby, and Emma.
Acknowledgments Before I start thanking those close to home, I need to thank the people who made this book what it is. They are the people who took my words and molded and shaped them into something that I hope will help you become an effective Web application developer. I would like to thank Carol Ackerman, my acquisitions editor, who answered all my questions and resolved any issues that came up. I would especially like to thank Tiffany Taylor for her excellent editing. I would like to thank Rob Tiffany for his great technical comments and recommendations. I would also like to thank Cynthia Fields for her excellent copy-editing. And finally, I would like to thank Christina Smith for managing the entire project. Each and every person made this book what it is. On a closer note, I would first like to thank everyone at my company, Virtuas Solutions, Inc. for their support while I was completing this text. The entire staff contributed by picking up my assignments when my plate was too full. In particular I would like to thank those “UNREAL” people that I worked with on a daily basis including Matthew “Deckard” Filios, Karen “Blue Bullet” Jackson, Eric “Crazy Mary” Johnson, Jason “Cutt” Nordyke, David “Busta” Goedecke, Mike “Ivan” Day, Gary “Monica” Goodrum, and especially Aaron “Ronin” Bandell, for his contribution of Chapters 11 and 12. Finally, the most important contributors to this book are my wife Christy, and our daughters Abby and Emma. They supported me throughout the entire book, with complete understanding. They listened to me complain and took care of things when I disappeared into the office. With their support, I can do anything.
Tell Us What You Think! As the reader of this book, you are our most important critic and commentator. We value your opinion and want to know what we’re doing right, what we could do better, what areas you’d like to see us publish in, and any other words of wisdom you’re willing to pass our way. As an executive editor for Sams Publishing, I welcome your comments. You can fax, e-mail, or write me directly to let me know what you did or didn’t like about this book—as well as what we can do to make our books stronger. Please note that I cannot help you with technical problems related to the topic of this book, and that due to the high volume of mail I receive, I might not be able to reply to every message. When you write, please be sure to include this book’s title and author’s name as well as your name and phone or fax number. I will carefully review your comments and share them with the author and editors who worked on the book. Fax: 317-581-4770 E-mail: [email protected] Mail:
Michael Stephens Executive Editor Sams Publishing 201 West 103rd Street Indianapolis, IN 46290 USA
Introduction Structure of This Book Before you begin reading this book, you might want to take a look at its basic structure. This will help you outline your reading plan, if you choose not to read it from cover to cover. This introduction gives you an overview of what each chapter covers.
Chapter 1, “Web Applications and the Model View Controller (MVC) Design Pattern” Chapter 1 lays the foundation for the entire text. It introduces your to the Model View Controller design pattern. It also introduces you to a server-side implementation of the MVC and how both servlets and JSPs fit into this pattern
Chapter 2, “Servlet Overview and Architecture” Chapter 2 introduces you to the Java servlet architecture. It talks about the movement to server-side Java. It also details reasons why you should use Java servlets.
Chapter 3, “Servlet Basics” Chapter 3 is where you begin to actually examine servlets. This chapter details the life cycle of a servlet and shows you source code for a basic servlet.
Chapter 4, “Servlets and HTML” Chapter 4 shows you how to link HTML forms to Java servlets and how you should retrieve form data in a servlet.
Chapter 5, “Servlet Sessions” Chapter 5 discusses several ways that you can maintain state while using servlets. The methods that it discusses include hidden form fields, cookies, URL rewriting, and session tracking with the Servlet API.
Chapter 6, “HTTP Tunneling” Chapter 6 covers HTTP tunneling. It provides a definition of HTTP tunneling, describes object serialization (which is required in tunneling), it describes the creation of a tunneling client and server, and it gives a practical tunneling example. It also covers some of the pros and cons of applet to servlet communications.
2
DEVELOPING JAVA SERVLETS
Chapter 7, “Servlets, JDBC, and Inter-Servlet Communications” Chapter 7 discusses how servlets can use the JDBC to interact with relational databases. It gives a basic introduction to the JDBC and then combines the technology with servlets. It also discusses a technique used to communicate between servlets.
Chapter 8, “Servlets and JavaMail” Chapter 8 discusses JavaMail and how you to use it with servlets and other applications.
Chapter 9, “Servlet Security” Chapter 9 describes security issues that you face when deploying an application to the Internet. It covers the most popular security techniques. It also describes some of each technique’s pros and cons.
Chapter 10, “Servlets and XML” Chapter 10 covers the basics of Extensible Markup Language, or XML. It discusses how to use Sun’s SAX parser. It also shows an example of how you would incorporate XML and servlets.
Chapter 11, “Servlets and LDAP” Chapter 11 covers the Lightweight Directory Access Protocol (LDAP). It covers using JNDI to access LDAP servers and it closes with an LDAP example integrated into a servlet.
Chapter 12, “Servlets and Enterprise JavaBeans” Chapter 12 provides an introduction to Enterprise JavaBeans (EJB). It covers using EJBs from an application as well as integrated into a servlet.
Chapter 13, “A Servlet Controller” Chapter 13 shows you how to create a servlet class that acts as the Controller in the Model View Controller design pattern.
Chapter 14, “JSP Overview and Architecture” Chapter 14 takes a look at the basics of JSP and the components of JSPs. It shows you how to create a JSP document and understand what is happening behind the scenes at request time. It also discusses the process a JSP file goes through when it is first requested.
INTRODUCTION
Chapter 15, “JSP Implicit Objects” Chapter 15 discusses the JSP implicit objects and how they are commonly used. It also talks about how they are created in the JSP’s generated servlet.
Chapter 16, “Using JSP Standard Actions” Chapter 16 covers the JSP standard actions, including how they are implemented and how you can use them.
Chapter 17, “Using JavaBeans and JSP Scopes” Chapter 17 covers how JSP beans are scoped. It discusses the different types of JSP scope. It also covers how the life of a JSP bean is determined by its scope.
Chapter 18, “Handling JSP Errors” Chapter 18 covers the types of errors that can occur in a JSP. It shows you how to handle and respond to these errors using a JSP error page.
Chapter 19, “Custom JSP Tag Libraries” Chapter 19 covers custom JSP tag libraries including tags with and without bodies. It also discusses how tags are packaged and deployed.
Chapter 20, “Catalog Case Study” Chapter 20 provides an MVC case study using an online movie catalog as an example including requirements, MVC components, and how to use the finished catalog.
Chapter 21, “An LDAP Web Client” Chapter 21 provides an MVC case study using a LDAP client as an example including requirements, MVC components, and how to use the finished client.
Chapter 22, “A Stock Trader” Chapter 22 provides an MVC case study using a stock trading application as an example including requirements, MVC components, and how to use the finished application.
3
4
DEVELOPING JAVA SERVLETS
Chapter 23, “Wireless Application Development Using WAP” Chapter 23 introduces you to wireless application development using Java servlets and the Wireless Application Protocol (WAP), including the wide variety of client and server tools available to the WAP developer. It includes an example in which you create a dynamic wireless application using servlets and WAP.
Chapter 24, “WML/WMLScript Development” Chapter 24 illustrates how to develop dynamic wireless Web applications using Java servlets, WML, and WMLScript.
Appendix A, “Web Applications and Configuring the Servlet Engine” Appendix A covers the steps involved in retrieving and configuring the Tomcat server necessary to run the examples in this text.
Appendix B, “The javax.servlet Package” Appendix B covers the classes, interfaces, and exceptions of the javax.servlet package.
Appendix C, “The javax.servlet.http Package” Appendix C covers the classes, interfaces, and exceptions of the javax.servlet.http package.
Appendix D, “The javax.servlet.jsp Package” Appendix D covers the classes, interfaces, and exceptions of the javax.servlet.jsp package.
Appendix E, “The javax.servlet.jsp.tagext Package” Appendix E covers the classes, interfaces, and exceptions of the javax.servlet.jsp.tagext package.
Appendix F, “WML (The Wireless Markup Language)” Appendix F provides a tag references for WML.
INTRODUCTION
Appendix G, “WMLScript” Appendix G describes the libraries and functions used in WMLScript.
5
CHAPTER
Web Applications and the Model View Controller (MVC) Design Pattern
1
IN THIS CHAPTER • The Model View Controller (MVC) Design Pattern 8 • A Server-Side Implementation of the MVC
8
8
DEVELOPING JAVA SERVLETS
This chapter is the foundation for this entire text. We will look at a design pattern that leverages the strengths of both servlets and Java Server Pages (JSPs) to create maintainable and reusable Web applications: the Model View Controller (MVC). In this study we will also look at exactly where and why both servlets and JSPs fit in this pattern. Because you have not yet covered servlet and JSP technologies, you will have to accept some of the statements made in this chapter. My goal for the remainder of this text is to show how and why this pattern and these technologies work so well when developing server-side Java Web applications.
The Model View Controller (MVC) Design Pattern The MVC originated from Smalltalk and was used to design user interfaces. In such an interface, the application was made up of three classes: a Model, a View, and a Controller. Each of these classes is defined in Table 1.1. TABLE 1.1
The Classes of the MVC
Class
Definition
Model
The Model represents the data or application object. It is what is being manipulated and presented to the user. The View is the screen representation of the Model. It is the object that presents the current state of the Model. The Controller defines the way the user interface reacts to the user’s input. The Controller is the object that manipulates the Model.
View Controller
The major advantage of using the MVC design pattern is that it separates the Views and Models. As a result, you can separate presentation from business logic, and, in turn, create or change Views without having to change the Models or the Controller logic that manipulates the Models. The MVC also allows Models to be represented by multiple Views.
A Server-Side Implementation of the MVC To implement the MVC server-side pattern in Java we must combine JSPs and servlets. In this section, we define a high-level server-side implementation of the MVC, where the Model is a JavaBean that represents the data being transmitted or received. The Controller is a servlet that manipulates or transmits data, and the View is a JSP that presents the results of the performed transaction. Figure 1.1 models the steps involved in a sever-side implementation of the MVC.
Web Applications and the Model View Controller (MVC) Design Pattern CHAPTER 1
1
Application Server
1. Web Client 6.
Servlet (Controller)
Web Server
5.
EJB/ BEAN EJB/ BEAN
4.
DBMS EJB/ BEAN
JSP (View) EJB/ BEAN
FIGURE 1.1 The steps in a server-side implementation of the MVC.
These steps are as follows: 1. The Web Client makes a request to the Web Server. 2. The Web Server passes the request to the Controller Servlet. 3. The servlet performs necessary manipulations to the JavaBean/EJB Model. 4. The Controller Servlet forwards the results to the JSP View. 5. The JSP View formats the Model for display and sends the HTML results back to the Web Server. 6. The Web Server then conveys the information back to the Web Client. Some benefits of using a server-side implementation of the MVC include • A clear separation of the presentation and transaction layers, which gives you the ability to change the look and feel of an application without recompiling. • The ability to have multiple views for multiple clients. • The ability to have a less experienced programmer develop and maintain the user interface. • A quicker time-to-market by allowing the Controller programmers to focus only on transactions, whereas the View programmers can focus primarily on presentation.
Servlets as MVC Controllers We have chosen to use servlets as MVC Controllers after examining some of their strengths and weaknesses.
WEB APPLICATIONS AND THE MVC DESIGN PATTERN
3. 2.
9
10
DEVELOPING JAVA SERVLETS
Strengths of servlets as Controllers are as follows: • Servlets have very robust server-side processing capabilities because they have access to almost the entire Java SDK. • The servlet architecture lends itself well to a transactional style of programming, which is analogous to MVC Controllers. Weaknesses of servlets as Controllers are as follows: • Servlets require an advanced level of Java understanding that HTML programmers usually do not have. • Servlets generally require recompilation in order to change the client presentation layer. If we consider the previous lists, we can determine that servlets make prime candidates for MVC Controllers, where there will be fewer changes because the presentation logic has been abstracted.
JSPs as MVC Views JavaServer Pages were chosen as MVC Views after a similar examination of their strengths and weaknesses. Strengths of JSPs as Views are as follows: • JSPs do not require programmer recompilation after source changes. • JSPs allow you to access Java objects that are stored in the HTTP session. • JSPs allow you to embed Java code directly into HTML pages with scriptlets. Weaknesses of JSPs as Views are as follows: • As your JSP code becomes more complicated, so does your scriptlet code. This results in confusing and difficult-to-maintain JSPs. • If you plan to allow your HTML programmers to maintain your JSPs, which is very common, they will require a good understanding of Java. After examining the previous lists, we can determine that JSPs make great candidates for MVC Views. This is because we can leverage a JSP’s access to Java objects, while conquering one of their major weaknesses by limiting scriptlet code to presentation only.
Summary In this chapter, we laid the foundation for the rest of this text. We looked at the MVC design pattern and saw how we could combine servlets and JSPs to implement a server-side solution for Web applications.
Web Applications and the Model View Controller (MVC) Design Pattern CHAPTER 1
1 WEB APPLICATIONS AND THE MVC DESIGN PATTERN
In the rest of this text we will study servlets and JSPs in the context of this model. We will examine how servlets and JSPs work separately and then we will complete the text by combining what we have learned into Web application case studies that implement the MVC.
11
Servlet Fundamentals
IN THIS PART 2 Servlet Overview and Architecture 3 Servlet Basics 4 Servlets and HTML 5 Servlet Sessions 6 HTTP Tunneling 7 Servlets, JDBC, and Inter-Servlet Communications 8 Servlets and JavaMail 9 Servlet Security 10 Servlets and XML 11 Servlets and LDAP 12 Servlets and Enterprise JavaBeans 13 A Servlet Controller
PART
I
CHAPTER
Servlet Overview and Architecture
2
IN THIS CHAPTER • Movement to Server-Side Java • Definition of a Java Servlet
16
16
• Practical Applications for Java Servlets • Java Servlet Alternatives
17
• Reasons to Use Java Servlets
19
• The Java Servlet Architecture
20
16
16
Servlet Fundamentals PART I
Movement to Server-Side Java When the Java language was first introduced by Sun Microsystems Inc., its purpose was to embed greater interactivity into Web pages. Java has accomplished this through the use of applets. Applets add functionality to Web pages, but because of compatibility and bandwidth issues, businesses have started moving to server-side Java. Java applets are programs that are embedded directly into Web pages. When a browser loads a Web page, which contains a reference to an applet, the applet byte-code is downloaded to the client computer and executed by the browser. This is fine for very thin clients, but as applets grow in size the download times become unacceptable. Applets also have compatibility problems. To run an applet you must have a compatible browser. If your customer does not have a compatible browser, applets will not be presented with the proper content. These issues have forced businesses to take a look at server-side Java. Server-side Java solves the problems that applets face. When the code is being executed on the server side, no issues arise with browser compatibility or long download times. The Java application on the server only sends the client small packets of information, including HTML, WML, XML, and so on, that it can understand. Java servlets are one of the options for serverside Java development.
Definition of a Java Servlet Servlets are generic extensions to Java-enabled servers. Their most common use is to extend Web servers, providing a very secure, portable, and easy-to-use replacement for CGI. A servlet is a dynamically loaded module that services requests from a Web server. It runs entirely inside the Java Virtual Machine. Because the servlet is running on the server side, it does not depend on browser compatibility. Figure 2.1 graphically depicts the execution of a Java servlet.
Request Servlet Response Web Browser
Web Server
FIGURE 2.1 Execution of a Java Servlet.
Practical Applications for Java Servlets Servlets can be used for any number of Web-related applications. After you start using servlets, you will find more practical applications for them. The following are three examples that I believe are some of the most important:
Servlet Overview and Architecture CHAPTER 2
17
• Developing e-commerce “store fronts” will become one of the most common uses for Java servlets. A servlet can build an online catalog based on the contents of a database. It can then present this catalog to the customer using dynamic HTML. The customer will choose the items to be ordered, enter the shipping and billing information, and then submit the data to a servlet. When the servlet receives the posted data, it will process the orders and place them in the database for fulfillment. Every one of these processes can easily be implemented using Java servlets.
• Servlets also make very good HTTP-enabled clients to Enterprise Java Bean (EJB) applications. Using servlets as clients to EJB applications creates very secure Web applications that are able to handle very high volumes. These are just a few examples of the power and practicality of using Java servlets. Servlets are very viable options for most Web applications.
Java Servlet Alternatives Some alternatives to using Java servlets are CGI, proprietary server APIs, server-side JavaScript, or even Microsoft’s Active Server Pages. All these are viable solutions, but they each have their own set of problems. The following sections examine some of these issues.
Common Gateway Interface The Common Gateway Interface (CGI) is one of the most common server-side solutions used to develop Web applications. A CGI application is an independent module that receives requests from a Web server. The application processes the data it receives and sends it back to the server, typically as HTML. The server then sends the data to the browser. CGI has become a standard that is used by most of today’s Web servers. Figure 2.2 shows the interaction between the browser, Web server, and CGI application when you implement this type of solution. Although CGI is a widely used solution to dynamic Web development, it is also a very problematic solution. The following are some of the most common problems with CGI: • A Web server creates a new process every time it receives a CGI request. This results in a slower response time, because the server must create and initialize a new address space for every process. You can also face the problem of running out of processes. Most
2 SERVLET OVERVIEW AND ARCHITECTURE
• Servlets can be used to deploy Web sites that open up large legacy systems on the Internet. Many companies have massive amounts of data stored on large mainframe systems. These businesses do not want to re-architect their systems, so they choose to provide inexpensive Web interfaces into them. Because you have the entire JDK at your disposal and security provided by the Web server, you can use servlets to interface into these systems using anything from TCP/IP to CORBA.
18
Servlet Fundamentals PART I
servers are configured to run a limited number of processes. If the server runs out, it will not be able to handle the client’s requests. • Although CGI code can be implemented in almost any language, the most common platform-independent language is Perl. Perl is very powerful at processing text, but it requires the server to start a new interpreter for every request. This takes longer than starting compiled code and still eats up available processes and resources. • CGI runs in a completely separate process from the Web server. If a client submits a request to a CGI program that terminates before responding to the Web server, the browser has no way of knowing what happened. It just sits there waiting for a response until it times out. Request CGI1 Client
New CGI1 Process Request CGI1
Client
New CGI1 Process Request CGI1
Client
New CGI1 Process Web Server
FIGURE 2.2 The interaction of a CGI solution.
Proprietary APIs Many Web servers include APIs that extend their functionality. The most common examples include Netscape’s NSAPI, Microsoft’s ISAPI, and O’Reilly’s Web site API called WSAPI. The problem with these solutions is that they are proprietary. You cannot decide to change servers without porting your code. These APIs are also developed using languages such as C or C++ that can contain memory leaks or core dumps that can crash the Web server.
Server-Side JavaScript Server-side JavaScript is another solution for implementing dynamic Web sites. With this solution you embed JavaScript into precompiled HTML pages. By precompiling the Web pages you improve performance, but the only servers that implement server-side JavaScript are Netscape’s Enterprise, FastTrack Servers, and Microsoft’s IIS. This again ties you to a particular vendor.
Microsoft’s Active Server Pages Microsoft has developed its own solution to the problem of dynamic Web content: Active Server Pages (ASP). Like Server-side JavaScript, ASP is embedded into HTML pages, but it is
Servlet Overview and Architecture CHAPTER 2
19
also similar to server-side JavaScript in that it is tied to a particular Web server: Microsoft’s Internet Information Server. Some third-party products implement ASP, but you must purchase them separately at additional costs.
Reasons to Use Java Servlets
Efficiency A servlet’s initialization code is executed only the first time the Web server loads it. Once the servlet is loaded, it is only a matter of calling a service method to handle new requests. This is a much more efficient technique than loading a completely new executable with every request.
Persistency Servlets can maintain state between requests. Once a servlet is loaded, it stays resident in memory while serving incoming requests. A simple example of this is a Vector that holds a list of categories used in an online catalog. When the servlet is initialized, it queries the database for a list of categories and stores these categories in a Vector. As it services requests, the servlet accesses the Vector that holds the categories instead of querying the database again. Taking advantage of the persistent characteristics of servlets can improve your application’s performance drastically.
Portability Servlets are developed using Java; therefore, they are portable. This portability enables servlets to be moved to a new operating system without changing the source. You can take code that was compiled on a Windows NT platform and move it to a Solaris box without making any changes.
Robustness Because servlets are developed with access to the entire JDK, they are very powerful and robust solutions. Java provides a well-defined exception hierarchy for error handling. It has a garbage collector to prevent problems with memory leaks. In addition, it includes a very large class library that includes network support, file support, database access, distributed object components, security, and many other classes.
2 SERVLET OVERVIEW AND ARCHITECTURE
Java servlets are one of the most exciting new technologies I have had the opportunity to work with. Servlets are efficient, persistent, portable, robust, extensible, secure, and they are receiving widespread acceptance. If you use them only to replace CGI, you will have saved yourself a lot of time and headache. Servlets solve many common problems you run into when using CGI, and they prove to have a clear advantage over many of the other alternatives. The following sections discuss some of the advantages offered by servlets.
20
Servlet Fundamentals PART I
Extensibility Another advantage servlets gain by being developed in an object-oriented language such as Java is that they can be extended and polymorphed into new objects that better suit your needs. A good example of this is an online catalog. You might want to display the same catalog search tool at the top of every dynamic page throughout your Web site. You definitely don’t want to add this code to every one of your servlets. So, you implement a base servlet that builds and initializes the search tool and then extend it to display transaction-specific responses.
Security Servlets run on the server side, inheriting the security provided by the Web server. Servlets can also take advantage of the Java Security Manager.
The Java Servlet Architecture Two packages make up the servlet architecture: javax.servlet and javax.servlet.http. The javax.servlet package contains the generic interfaces and classes that are implemented and extended by all servlets. The java.servlet.http package contains the classes that are extended when creating HTTP-specific servlets. An example of this is a simple servlet that responds using HTML. At the heart of this architecture is the interface javax.servlet.Servlet. It provides the framework for all servlets. The Servlet interface defines five methods. The three most important are the init() method, which initializes a servlet; the service() method, which receives and responds to client requests; and the destroy() method, which performs cleanup. All servlets must implement this interface, either directly or through inheritance. It is a very clean objectoriented approach that makes the interface easy to extend. Figure 2.3 shows an object model that gives a high-level view of the servlet framework.
GenericServlet and HttpServlet The two main classes are the GenericServlet and HttpServlet classes. The HttpServlet class is extended from GenericServlet. When you are developing your own servlets, you will most likely be extending one of these two classes. Java servlets do not have a main() method, which is why all servlets must implement the javax.servlet.Servlet interface. Every time a server receives a request that points to a servlet it calls that servlet’s service() method. If you decide to extend the GenericServlet class, you must implement the service() method. The GenericServlet.service() method has been defined as an abstract method to force you to follow this framework. The service() method prototype is defined as follows: public abstract void service(ServletRequest req, ServletResponse res) throws ServletException, IOException;s
FIGURE 2.3 A high-level object model of the servlet framework.
The two objects that the service() method receives are ServletRequest and ServletResponse. The ServletRequest object holds the information that is being sent to the servlet, whereas the ServletResponse object is where you place the data you want to send back to the client. Figure 2.4 diagrams the flow of a GenericServlet request.
Unlike the GenericServlet, when you extend HttpServlet, you don’t usually implement the service() method. The HttpServlet class has already implemented it for you. The following is the prototype: protected void service(HttpServletRequest req, HttpServletResponse resp) throws ServletException, IOException;
When the HttpServlet.service() method is invoked, it reads the method type stored in the request and determines which method to invoke based on this value. These are the methods that you will want to override. If the method type is GET, the service() method will call doGet(). If the method type is POST, it will call doPost(). Five other method types exist; they are discussed in Chapter 3, “Servlet Basics.” All these methods have the same parameter list as the service() method. You might have noticed the different request/response types in the parameter list of the HttpServlet and the GenericServlet classes. The HttpServletRequest and HttpServletResponse classes are just extensions of ServletRequest and ServletResponse with HTTP-specific information stored in them. Figure 2.5 diagrams the flow of a HttpServlet request. HttpServlet doDelete() doGet()
Request Client Response Web Server
FIGURE 2.5 A HttpServlet Request.
service()
doOptions() doPost() doPut() doTrace()
Servlet Overview and Architecture CHAPTER 2
23
Summary In this chapter, you learned about Java servlet basics, practical applications for servlets, servlet alternatives, reasons to use servlets over the alternatives, and the basic architecture of servlets. At this point, you should have a high-level understanding of the flow of a servlet request and what objects are involved. In the next chapter we will look at the life cycle of a servlet. We will also create and dissect a basic servlet.
2 SERVLET OVERVIEW AND ARCHITECTURE
CHAPTER
Servlet Basics
3
IN THIS CHAPTER • The Life Cycle of a Servlet • A Basic Servlet
26
27
• Dissecting the BasicServlet
29
26
Servlet Fundamentals PART I
The Life Cycle of a Servlet The life cycle of a Java servlet is a very simple object-oriented design. A servlet is constructed and initialized. It then services zero or more requests until the service that it extends shuts down. At this point the servlet is destroyed and garbage is collected. This design explains why servlets are such a good replacement for CGI: The servlet is loaded only once and it stays resident in memory while servicing requests. The javax.servlet.Servlet interface declares this framework. The Servlet interface defines the life cycle methods. These methods are the init(), the service(), and the destroy() methods.
The init() Method The init() method is where the servlet’s life begins. It is called by the server immediately after the servlet is instantiated. It is called only once. In the init() method the servlet creates and initializes the resources that it will be using while handling requests. The init() method’s signature is defined as follows: public void init(ServletConfig config) throws ServletException;
The init() method takes a ServletConfig object as a parameter. You should save this object so that it can be referenced later. The most common way of doing this is to have the init() method call super.init() passing it the ServletConfig object. You will also notice that the init() method can throw a ServletException. If, for some reason, the servlet cannot initialize the resources necessary to handle requests, the init() method should throw a ServletException.
The service() Method The service() method handles all requests sent by a client. It cannot start servicing requests until the init() method has been executed. You will not usually implement this method directly, unless you extend the GenericServlet abstract class. The most common implementation of the service() method is in the HttpServlet class. The HttpServlet class implements the Servlet interface by extending GenericServlet. Its service() method supports standard HTTP/1.1 requests by determining the request type and calling the appropriate method. The signature of the service() method is shown below. public void service(ServletRequest req, ServletResponse res) throws ServletException, IOException;
Servlet Basics CHAPTER 3
27
The service() method implements a request and response paradigm. The ServletRequest object contains information about the service request, encapsulating information provided by the client. The ServletResponse object contains the information returned to the client.
The destroy() Method This method signifies the end of a servlet’s life. When a service is being shut down it calls the servlet’s destroy() method. This is where any resources that were created in the init() method should be cleaned up. If you have an open database connection, you should close it here. This is also a good place to save any persistent information that will be used the next time the servlet is loaded. The signature of destroy() is very simple, but I have displayed it here just to complete the picture: public void destroy();
A Basic Servlet
The BasicServlet Source Listing 3.1 contains the source code for this example. You can find the following source listing on this book’s Web site. If you have the time, it is probably best to type the first few examples yourself. This will help you become familiar with the basic parts of servlets. As you type or browse over this listing, feel free to look up the referenced classes in Appendices A and B. LISTING 3.1 import import import import
BasicServlet.java Displays the REQUEST_METHOD used by the Client
public class BasicServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException {
3 SERVLET BASICS
In this section, we are going to look at building a very basic servlet. Its purpose will be to service a request and respond with the request method used by the client. We will take a quick look at the servlet’s source code, the steps involved in compiling and installing the servlet, and the HTML necessary to invoke the servlet. After you have the servlet compiled, you will need to refer to Appendix A, “Web Applications and Configuring the Servlet Engine,” for instructions on how to configure the servlet engine, which actually runs your servlets.
28
Servlet Fundamentals PART I
LISTING 3.1
Continued
// Always pass the ServletConfig object to the super class super.init(config); } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“BasicServlet”); out.println(“”); // Prints the REQUEST_METHOD sent by the client out.println(“Your request method was “ + request.getMethod() + “\n”); out.println(“”); out.close(); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“BasicServlet”); out.println(“”); // Prints the REQUEST_METHOD sent by the client out.println(“Your request method was “ + request.getMethod() + “\n”); out.println(“”); out.close(); }
Servlet Basics CHAPTER 3
LISTING 3.1
29
Continued
//Get Servlet information public String getServletInfo() { return “BasicServlet Information”; } }
Dissecting the BasicServlet Now that you have had a chance to look over the source of the BasicServlet, let’s take a closer look at each of its integral parts. We will examine where the servlet fits into the JSDK framework, the methods that the servlet implements, and the objects being used by the servlet.
Where Does the BasicServlet Fit into the Servlet Framework?
javax.servlet.Servlet
javax.servlet.ServletConfig
javax.servlet.GenericServlet
javax.servlet.http.HttpServlet
BasicServlet
FIGURE 3.1 The BasicServlet depicted in the Servlet Framework.
java.io.Serializable
3 SERVLET BASICS
The first thing we are going to look at is where the BasicServlet fits into the servlet framework. This servlet extends the HttpServlet class. The HttpServlet class is an abstract class that simplifies writing HTTP servlets. It extends the GenericServlet class and provides the functionality for handling the HTTP protocol-specific requests. The BasicServlet overrides four of its inherited methods. Figure 3.1 shows where the BasicServlet fits into this hierarchy.
30
Servlet Fundamentals PART I
The Methods Overridden by the BasicServlet The following four methods are overridden by the BasicServlet: •
init()
•
doGet()
•
doPost()
•
getServletInfo()
Let’s take a look at each of these methods in more detail.
The init() Method The BasicServlet defines a very simple implementation of the init() method. It takes the ServletConfig object that is passed to it and passes it to its parent’s init() method, which stores the object for later use. The parent that actually holds on to the ServletConfig object is the GenericServlet. The GenericServlet provides your servlet, through inheritance, with methods to access the ServletConfig object. The code that performs this action follows: super.init(config);
This is a very important step. If you do not do this, you must hold the ServletConfig object yourself. We will discuss the significance of the ServletConfig object in later chapters. You will also notice this implementation of the init() method does not create any resources. This is why the BasicServlet does not implement a destroy() method.
The doGet() and doPost() Methods The BasicServlet’s doGet() and doPost() methods are identical. The only difference is the requests they service. The doGet() method handles GET requests and the doPost() method handles POST requests. Both of these methods receive HttpServletRequest and HttpServletResponse objects. These objects encapsulate the request/response paradigm. The HttpServletRequest contains information sent from the client, and the HttpServletResponse contains information that will be sent back to the client. The first executed line of these methods follows: response.setContentType(“text/html”);
This method sets the content type for the response. You can set this response property only once. You must set this property before you can begin writing to a Writer or an OutputStream. In our example, we are using a PrintWriter and setting the response type to text/html. The next thing to do is get the PrintWriter. This is accomplished by calling the ServletResponses’s getWriter() method. This is done in the following line of code: PrintWriter out = response.getWriter();
Servlet Basics CHAPTER 3
31
Now you have a reference to an object that will allow you to write HTML text that will be sent back to the client in the HttpServletResponse object. The next few lines of code show how this is done: out.println(“”); out.println(“BasicServlet”); out.println(“”); // Prints the REMOTE_ADDR sent by the client in the request out.println(“Your request method was “ + request.getMethod() + “\n”); out.println(“”); out.close();
This is a very straightforward method of sending HTML text back to the client. You simply pass to the PrintWriter’s println() method the HTML text you want included in the response and close the stream. The only thing that you might have a question about is the following few lines:
This code takes advantage of the information sent from the client. It calls the HttpServletRequest’s getMethod() method, which returns the HTTP method with which the request was made. The HttpServletRequest object holds HTTP-protocol specific header information.
The getServletInfo() Method The getServletInfo() method is like the applet’s getAppletInfo() method. It can be used to provide version, copyright, author, and any other information about itself.
Summary In this chapter, we were finally able to start examining some servlet code. We looked at the life cycle of a servlet. We also dissected a basic servlet, which gave us a view of each integral part of a servlet. You should now be able to create your own servlets. You should also have a basic understanding of the servlet life cycle and where your servlets will fit into the Java servlet framework. In the next chapter we will take a look at Web applications and how to leverage them to deploy servlet applications.
3 SERVLET BASICS
// Prints the REMOTE_ADDR sent by the client in the request out.println(“Your request method was “ + request.getMethod() + “\n”);
CHAPTER
Servlets and HTML
4
IN THIS CHAPTER • Retrieving Form Data in a Servlet
34
34
Servlet Fundamentals PART I
Retrieving Form Data in a Servlet We will now look at how servlets retrieve information from the client. Servlets most commonly receive data from both POST and GET requests. The methods used to retrieve this data are the same in either case. The three methods used to retrieve request parameters are the ServletRequest’s getParameterNames(), getParameter(), and getParameterValues(). Their signatures are as follows: public Enumeration ServletRequest.getParameterNames(); public String ServletRequest.getParameter(String name); public String[] ServletRequest.getParameterValues(String name);
returns the parameter names for the request as an enumeration of strings, or an empty enumeration if there are no parameters. It is used as a supporting method to getParameter(). When you have the enumerated list of parameter names, you can iterate over them calling getParameter() with each name in the list. getParameterNames()
The getParameter() method returns a string containing the single value of the specified parameter, or null if the parameter is not contained in the request. This method should be used only if you are sure the request contains only one value for the parameter. If the parameter has multiple values you should use getParameterValues(). returns the values of the specified parameter as an array of strings, or null if the named parameter does not exist in the request. getParameterValues()
Servicing the GET and POST Requests Let’s take a look at a servlet that services a POST request. The servlet in Listing 4.1 retrieves the parameters sent to it and returns the parameters and their values back to the client. LISTING 4.1 import import import import
FormServlet.java Displays All Parameter/Value Pairs in Request
public class FormServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { // Always pass the ServletConfig object to the super class
Servlets and HTML CHAPTER 4
LISTING 4.1
35
Continued
super.init(config); } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“FormServlet”); out.println(“”); // Get all the parameter names Enumeration parameters = request.getParameterNames(); String param = null; // Iterate over the names, getting the parameters while ( parameters.hasMoreElements() ) { param = (String)parameters.nextElement(); out.println(“” + param + “ : “ + request.getParameter(param) + “ ”); } out.println(“”); out.close(); }
response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“FormServlet”); out.println(“”); // Get all the parameter names Enumeration parameters = request.getParameterNames();
SERVLETS AND HTML
//Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
4
36
Servlet Fundamentals PART I
LISTING 4.1
Continued
String param = null; // Iterate over the names, getting the parameters while ( parameters.hasMoreElements() ) { param = (String)parameters.nextElement(); out.println(“” + param + “ : “ + request.getParameter(param) + “ ”); } out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “FormServlet Information”; } }
As you look over this servlet, you will notice that it services both GET and POST requests. You can invoke the FormServlet by encoding a URL string or by using a form. The HTML source, used to invoke the servlet using the POST method, is shown in Listing 4.2. LISTING 4.2
Form.html Displays HTML Required to Invoke the Servlet Using the POST
Method <TITLE> Chapter 4 Form
Last Name:
Servlets and HTML CHAPTER 4
LISTING 4.2
37
Continued
After you have examined both of these listings, build and install the servlet. The next thing you will need to do is load the HTML document in your browser. The loaded page should look similar to Figure 4.1.
4 SERVLETS AND HTML
First Name:
Age:
SSN:
DOB:
Username:
Password:
38
Servlet Fundamentals PART I
FIGURE 4.1 Form HTML Page.
You should now complete the form and click the Submit button. The response you receive, which will of course depend on your entries, should look something like that shown in Figure 4.2.
How the FormServlet Works Now that you have seen what the FormServlet does, let’s take a look at how it does it. The area we want to focus on is listed here: // Get all the parameter names Enumeration parameters = request.getParameterNames(); String param = null; // Iterate over the names, getting the parameters while ( parameters.hasMoreElements() ) { param = (String)parameters.nextElement(); out.println(“” + param + “ : “ + request.getParameter(param) + “ ”); }
Servlets and HTML CHAPTER 4
39
FIGURE 4.2 FormServlet Response Page.
The code is the same for both the doPost() and doGet() methods. The first executed line calls the getParameterNames() method for the current request. This method returns an enumerated list of parameter names. We then iterate over the Enumerator calling getParameter() and passing it each one of the parameter names; it returns the value of each request parameter. These tag/value pairs are then passed to the response writer with some HTML formatting tags. The completed response is then passed back to the client and displayed in the browser.
Summary In this chapter we covered a lot of information. We looked at how servlets parse request parameters. We also created an HTML package that encapsulates basic HTML. At this point you should feel comfortable with how servlets receive information from the client.
4 SERVLETS AND HTML
This example shows just how easy it is to retrieve request parameters in a servlet. Although the FormServlet works fine for most requests, it does have a flaw. When we chose to use getParameter() to retrieve our parameter values, we knew there would only be one value per request parameter. If you need to handle multiple values, you should use the getParameterValues() method discussed previously.
40
Servlet Fundamentals PART I
In the next chapter we will look at the servlet architecture’s provisions for maintaining state, namely the HttpSession.
CHAPTER
Servlet Sessions
5
IN THIS CHAPTER • What Is Session Tracking?
42
• Using Hidden Form Fields
42
• Working with Cookies • URL Rewriting
46
50
• Session Tracking with the Servlet API
51
42
Servlet Fundamentals PART I
What Is Session Tracking? Session tracking is the capability of a server to maintain the current state of a single client’s sequential requests. The HTTP protocol used by Web servers is stateless. This means that every transaction is autonomous. This type of stateless transaction is not a problem unless you need to know the sequence of actions a client has performed while at your site. For example, an online video store must be able to determine each visitor’s sequence of actions. Suppose a customer goes to your site to order a movie. The first thing he does is look at the available titles. When he has found the title he is interested in, he makes his selection. The problem now is determining who made the selection. Because each one of the client’s requests is independent of the previous requests, you have no idea who actually made the final selection.
NOTE You could use HTTP authentication as a method of session tracking, but each of your customers would need an account on your site. This is fine for some businesses, but would be a hassle for a high-volume site. You probably could not get every user who simply wants to browse through the available videos to open an account.
In this chapter, you will look at several different ways to determine the actions that a particular client has taken. You will examine hidden form fields, cookies, URL rewriting, and the built-in session tracking functionality found in the servlet API.
Using Hidden Form Fields Using hidden form fields is one of the simplest session tracking techniques. Hidden form fields are HTML input types that are not displayed when read by a browser. The following sample HTML listing includes hidden form fields:
Servlet Sessions CHAPTER 5
43
When you open this HTML document in a browser, the input types marked as hidden will not be visible. They will, however, be transmitted in the request. Let’s create a simple example that shows how this technique works. You’ll create a servlet that can service both POST and GET methods. In the doGet() method, you’ll build a form that contains hidden fields and an action that points to the servlet’s doPost() method. The doPost() method will then parse the hidden values sent in the request and echo them back to the client. The example is found in Listing 5.1. LISTING 5.1 import import import import
public class HiddenFieldServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“HiddenFieldServlet” + “”); out.println(“”);
SERVLET SESSIONS
// Create the Form with Hidden Fields out.println(“”);
5
44
Servlet Fundamentals PART I
LISTING 5.1
Continued
// These values would be uniquely generated out.println(“”); out.println(“”); // These are the currently selected movies out.println(“”); out.println(“”); out.println(“”); out.println(“”); out.println(“”); out.println(“”); out.close(); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“HiddenFieldServlet” + “”); out.println(“”); // Get the hidden inputs and echo them String user = request.getParameter(“user”); String session = request.getParameter(“session”); out.println(“” + user + “, the contents of your Shopping Basket are: ”);
Servlet Sessions CHAPTER 5
LISTING 5.1
45
Continued
String[] movies = request.getParameterValues(“movie”); if ( movies != null ) { for ( int x = 0; x < movies.length; x++ ) { out.println(movies[x] + “ ”); } } out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “HiddenFieldServlet Information”; } }
When you have this servlet installed, open your browser to the servlet’s URL. The URL on my local box is listed as follows: http://localhost/djs/servlet/HiddenFieldServlet
When the servlet is loaded, you should only see a Submit button. If you view the current HTML source, you will see a listing similar to this snippet:
Notice the hidden fields. Now click the Submit button. The form invokes the doPost() method of the HiddenFieldServlet. This method parses the hidden fields out of the request and displays them in a “shopping cart” listing. Figure 5.1 shows the results of the HiddenFieldServlet’s doPost() method.
5 SERVLET SESSIONS
HiddenFieldServlet
46
Servlet Fundamentals PART I
FIGURE 5.1 Output of HiddenFieldServlet.
You can see that hidden form fields have their advantages. They are easy to implement and are supported by most browsers. This technique also has its disadvantages. The hidden fields must be created in a particular sequence. You are not able to click the Back button on your browser without losing the additional fields added to the current page. You are also restricted to dynamically generated documents.
Working with Cookies One of the more elegant solutions to session tracking is the use of persistent cookies. Netscape first introduced cookies in one of the company’s first versions of Netscape Navigator. A cookie is a keyed piece of data that is created by the server and stored by the client browser. Browsers maintain their own list of unique cookies. This makes cookies a very viable solution for session tracking. The Servlet API provides built-in support for cookies. It does this through the use of the Cookie class and the HttpServletResponse.addCookie() and HttpServletRequest.getCookies() methods.
Servlet Sessions CHAPTER 5
47
The Cookie class encapsulates persistent cookies as defined by RFC 2109. The prototype for the Cookie’s constructor takes a String representing the unique name of the cookie and a String representing the value of the cookie, and it is listed as follows: public Cookie(String name, String value)
The Cookie class also provides accessors used to get and set the values of the cookie. Listing 5.2 contains an example of using cookies to perform session handling. LISTING 5.2 import import import import
public class CookieServlet extends HttpServlet { //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); } private String getCurrentUser(String value) { String userName = new String(“”); // This would normally be a Select from a database or // other storage area. if ( value.equals(“564XX892”) ) { userName = new String(“Bob”); } return userName; }
// Get the list of Cookies stored in the request Cookie[] cookieList = request.getCookies(); String user = null;
5 SERVLET SESSIONS
//Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
48
Servlet Fundamentals PART I
LISTING 5.2
Continued
String responseString = null; if ( cookieList != null ) { // Cookies found, let’s get the session id for ( int x = 0; x < cookieList.length; x++ ) { String name = cookieList[x].getName(); if ( name.equals(“session_id”) ) { // Get the user based on the session id user = getCurrentUser(cookieList[x].getValue()); break; } } } if ( user == null ) { // Let’s create a cookie that represents a unique // session id. response.addCookie(new Cookie(“session_id”, “564XX892”)); responseString = new String(“Welcome to our site, “ + “we have created a session for you.”); } else { responseString = new String(“Hello : “ + user); } response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“CookieServlet”); out.println(“”); out.println(responseString); out.println(“”); out.close(); }
Servlet Sessions CHAPTER 5
LISTING 5.2
49
Continued
//Get Servlet information public String getServletInfo() { return “CookieServlet Information”; } }
Every time the CookieServlet services a request, it checks for cookies in the HttpServletRequest. It does this by calling the HttpServletRequest.getCookies() method. If the request does contain cookies, the servlet will iterate over the list of cookies looking for a cookie with the name session_id. If the request contains no cookies or the list of cookies does not contain a cookie named session_id, you create one and add it to the response. The code snippet that does this is listed as follows: response.addCookie(new Cookie(“session_id”, “564XX892”));
NOTE Cookies are stored in the response as HTTP headers. Therefore, you must add cookies to the response before adding any other content.
The best way to test this functionality is to open your browser to the CookieServlet. The first time it runs, you should get a response that says “Welcome to our site, we have created a session for you.” After you get this message, click the Refresh button. You should see a new response that says “Hello : Bob.” The servlet can now identify the user “Bob” by the session ID stored as a cookie.
NOTE If you have trouble running this example, make sure the use of cookies is enabled in your browser.
5 SERVLET SESSIONS
50
Servlet Fundamentals PART I
URL Rewriting If your browser does not support cookies, URL rewriting provides you with another session tracking alternative. URL rewriting is a method in which the requested URL is modified to include a session ID. There are several ways to perform URL rewriting. You are going to look at one method that is provided by the Servlet API. Listing 5.3 shows an example of URL rewriting. LISTING 5.3 import import import import
public class URLRewritingServlet extends HttpServlet { //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“URL Rewriting”); out.println(“”); // Encode a URL string with the session id appended // to it. String url = response.encodeRedirectURL( “http://localhost:8000/servlet/checkout?sid=5748”); // Redirect the client to the new URL response.sendRedirect(url); out.println(“”); out.close();
Servlet Sessions CHAPTER 5
LISTING 5.3
51
Continued
} //Get Servlet information public String getServletInfo() { return “URLRewritingServlet Information”; } }
This servlet services a GET request and redirects the client to a new URL. This new URL has the string sid=5748 appended to it. This string represents a session ID. When the servlet that services the redirection receives the request, it will be able to determine the current user based on the appended value. At that point, the servlet can perform a database lookup on the user and her actions based on this ID. Two methods are involved in this redirection. The first is HttpServletResponse.encodeRedirectURL(), which takes a String that represents a redirection URL and encodes it for use in the second method. The second method used is the HttpServletRequest.sendRedirect() method. It takes the String returned from the encodeRedirectString() and sends it back to the client for redirection. The advantage of URL rewriting over hidden form fields is the capability to include session tracking information without the use of forms. Even with this advantage, it is still a very arduous coding process.
Session Tracking with the Servlet API The Servlet API has its own built-in support for session tracking. The HttpSession object provides this functionality. In this section, I focus on four of the HttpSession’s session tracking methods. The first method is the setAttribute() method. The setAttribute() method binds a name/value pair to store in the current session. If the name already exists in the session, it is replaced. The method signature for setAttribute() is listed as follows: public void setAttribute(String name, Object value)
public Object getAttribute(String name)
5 SERVLET SESSIONS
The next method is the getAttribute() method, which is used to get an object that is stored in the session. The getAttribute() method takes a string representing the name that the desired object is bound to. Its signature is listed as follows:
52
Servlet Fundamentals PART I
The third session method returns an array of the current bound names stored in the session. This method is convenient if you want to remove all the current bindings in a session. Its signature is listed as follows: public String[] getAttributeNames()
The last session method is the removeAttribute() method. As its name suggests, it removes a binding from the current session. It takes a string parameter representing the name associated with the binding. Its method signature is listed as follows: public void removeAttribute(String name)
Now that I have discussed the HttpSession object, let’s take a look at an example of how to use it. In this example, you will service a request that contains a list of movies to add to a user’s account. You will then parse the submitted list, add it to the customer’s session, and redisplay it for approval. When the customer approves the list, they will click the Proceed to Checkout button to commit the transaction. Listing 5.4 contains the source for this example. LISTING 5.4 import import import import
public class HttpSessionServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } //Process the HTTP Get request, this method // will handle the checkout public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { String[] movies = null; // Get a handle to the HttpSession Object // if there is no session create one HttpSession session = request.getSession(true); // Get the movies list object bound to the
Servlet Sessions CHAPTER 5
LISTING 5.4
53
Continued
// name “Movies” if ( session != null ) { movies = (String[])session.getAttribute(“Movies”); } response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“Session Servlet”); out.println(“”); // Iterate over the movies array, displaying the // current list of movies stored in the session out.println(“Thank you for purchasing:”); for ( int x = 0; x < movies.length; x++ ) { out.println(movies[x] + “ ”); } out.println(“”); out.close(); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Parse the movies selected String movies[] = request.getParameterValues(“Movies”); // Get a handle to the HttpSession Object // if there is no session create one HttpSession session = request.getSession(true); // add the list of movies to the session // binding it to the String “Movies” if ( session != null ) { session.setAttribute(“Movies”, movies);
response.setContentType(“text/html”); PrintWriter out = response.getWriter();
SERVLET SESSIONS
}
5
54
Servlet Fundamentals PART I
LISTING 5.4
Continued
out.println(“”); out.println(“Session Servlet”); out.println(“”); out.println(“Contents of Shopping Cart”); // Display the submitted movie array for ( int x = 0; x < movies.length; x++ ) { out.println(movies[x] + “ ”); } // Create a form to submit an order out.println(“”); out.println(“”); out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “HttpSessionServlet Information”; } }
To invoke this servlet, you need to create an HTML file that will make a POST request containing a list of selected movies. The HTML file that contains this form is in Listing 5.5. LISTING 5.5
HtmlSessionServlet.html
<TITLE> Movie List Select From Available Movies
Servlet Sessions CHAPTER 5
LISTING 5.5
55
Continued
<SELECT NAME=”Movies” SIZE=”5” MULTIPLE> Air Force One Happy Gilmore So I Married an Axe Murderer Austin Powers Pure Luck
To see how this example works, load this HTML page in a browser. You should see a screen similar to Figure 5.2.
FIGURE 5.2 The Movie Selection List screen.
SERVLET SESSIONS
When this page is loaded, select a couple of the movies in the list and click the Add Movies button. You should now see a screen containing the list of movies you selected. Figure 5.3 displays an example of this output.
5
56
Servlet Fundamentals PART I
FIGURE 5.3 The Contents of Shopping Cart screen.
To understand how this first part works, you need to examine the doPost() method. This is the method that services the POST request sent by your HTML document. The first thing the doPost() method does is get the list of submitted movies from the request. It then tries to get a reference to the HttpSession object stored in the HttpServletRequest. This is done by calling the HttpServletRequest.getSession() method. The code snippet that performs this is listed in the following: // Get a handle to the HttpSession Object // if there is no session create one HttpSession session = request.getSession(true);
The getSession() method takes one parameter. This parameter is a Boolean value that, if true, tells the method to create an HttpSession if one doesn’t exist. When you have a reference to the HttpSession object, you can add your movie list to it. You do this by calling the HttpSession.setAttribute() method, passing it the name “Movies” and the object to be bound to it: movies. The movie list is now stored in the client’s session. The last thing you do in the doPost() method is redisplay the list of selected movies and ask the user to click Proceed to Checkout.
Servlet Sessions CHAPTER 5
57
NOTE Sessions do expire. Therefore, you will need to consult your server’s documentation to determine the length of time a session is valid.
Now you are going to look at the really cool part. Click the Proceed to Checkout button. You should see a screen similar to Figure 5.4, which tells you “Thank you for purchasing:” and displays the movies you selected.
FIGURE 5.4 The Thank You screen.
The request performed by this form simply calls the same servlet using the GET method. If you look at the URL your browser now points to, you will notice there is no movie data encoded in the URL string.
5 SERVLET SESSIONS
Look at the doGet() method to see exactly how this is done. The first thing you do is get a reference to the HttpSession object, which is done exactly as before with the getSession() method. When you have a reference to the session, you can get the list of movies stored in the session. You do this by calling the HttpSession.getAttribute() method, passing it the name bound to the movies object. The following code snippet shows how this is done:
58
Servlet Fundamentals PART I // Get the movies list object bound to the // name “Movies” if ( session != null ) { movies = (String[])session.getAttribute(“Movies”); }
NOTE Make sure that you downcast your stored object back to its original type. While in the HttpSession, it is stored as an object.
When you have the list of movies, thank the customer for the purchase and redisplay the list of ordered movies. That is all there is to it. As you have seen, the Servlet API provides you with a very elegant and simple-to-use method of maintaining persistent sessions.
Summary In this chapter, we covered several methods that you can integrate into your servlets to handle persistent sessions. We talked about the hidden form fields, persistent cookies, URL rewriting, and the Servlet API’s built-in session handling support. At this point, you should be able to examine your session handling requirements and determine which method satisfies your needs. You should also be able to implement a session handling solution based on your decision. In the next chapter, we will look at communication between Java applets and servlets using a method call HTTP tunneling.
CHAPTER
HTTP Tunneling
6
IN THIS CHAPTER • What is HTTP Tunneling? • Object Serialization
60
60
• Creating an HTTP Tunneling Client
66
• Creating an HTTP Tunneling Servlet
71
• A Practical HTTP Tunneling Example
73
• Pros and Cons of Applet-to-Servlet Communication 83
60
Servlet Fundamentals PART I
What Is HTTP Tunneling? HTTP tunneling is a method of reading and writing serialized objects using an HTTP connection. You are creating a sub-protocol inside the HTTP protocol—that is, “tunneling” inside another protocol. This relieves you from the hassles of dealing with the actual transport layer.
Object Serialization Before you can get started with HTTP tunneling, you need to understand object serialization. Object serialization is a feature introduced in the Java Development Kit version 1.1. It enables you to create objects that are persistent across several media. An exceptionally convenient characteristic of serialization is that it not only serializes your object, it also unwinds and serializes all the objects that are referenced by your object. To make an object serializable, it must implement the Serializable interface. This interface is found in the java.io package. The entire Serializable interface is listed as follows: public interface Serializable { static final long serialVersionUID = 1196656838076753133L; }
As you can see, there is not much to this interface. Its only purpose is to signify that an object can be serialized. The steps involved in serializing an object are as follows: 1. Create an OutputStream object. This can be a stream to a file, a TCP/IP connection, or most any other target. 2. Create an ObjectOutputStream and pass to its constructor the OutputStream created in Step 1. 3. Call the ObjectOutputStream’s writeObject() method and pass to it the object that implements the Serializable interface. The equivalent steps involved in reading a serialized object are as follows: 1. Create an InputStream object that points to the location of the serialized object. 2. Create an ObjectInputStream and pass to its constructor the InputStream created in Step 1. 3. Call the ObjectInputStream’s readObject() method. 4. The readObject() method returns an upcasted Object that must be downcasted back to your original object’s type.
HTTP Tunneling CHAPTER 6
LISTING 6.1
StudentList.java
import java.io.*; import java.util.*; public class StudentList implements Serializable { // Vector holding our students Vector list = new Vector(6); // Default Constructor public StudentList() { } public void addStudent(String value) { // Add a String representing a student name if ( value != null ) { list.addElement(value); } } public void listStudents() { // Iterate over list vector, printint all Strings for ( int x = 0; x < list.size(); x++ ) { System.out.println(“Student “ + x + “ : “ + (String)list.elementAt(x)); } } }
Notice that the StudentList object implements the java.io.Serializable interface. It also contains a vector of strings representing student names, which are also defined as Serializable. The StudentListApplication will be used to create, store, and retrieve the StudentList from persistent storage. In this example, the persistent storage is the file file.dat. The StudentListApplication is found in Listing 6.2.
6 HTTP TUNNELING
Now, you’ll create a simple example that writes an object to a file and reads the same object back in. The created object will contain a vector of other objects. Listing 6.1 contains the object you will be serializing.
61
62
Servlet Fundamentals PART I
LISTING 6.2
StudentListApplication.java
import java.io.*; public class StudentListApplication { // Default Constructor public StudentListApplication() { } // Adds Student Names to List public void buildStudentList(StudentList value) { value.addStudent(“Bob Robinson”); value.addStudent(“Steve Bobinson”); value.addStudent(“Rob Stevinson”); value.addStudent(“Todd Thompson”); value.addStudent(“Tom Toddson”); value.addStudent(“Rob Bobinson”); } // Stores the Serializable StudentList to the file “file.dat” public void putStudentList(StudentList value) { try { // Create the ObjectOutputStream passing it the // FileOutputStream object that points to our // persistent storage. ObjectOutputStream os = new ObjectOutputStream( new FileOutputStream(“file.dat”)); // Write the StudentList to the ObjectOutputStream os.writeObject(value); os.flush(); os.close(); } catch (IOException e) { System.err.println(e.getMessage()); } } public StudentList getStudentList() { StudentList list = null;
HTTP Tunneling CHAPTER 6
LISTING 6.2
Continued
// Create the ObjectInputStream passing it the // FileInputStream object that points to our // persistent storage. ObjectInputStream is = new ObjectInputStream( new FileInputStream(“file.dat”)); // Read the stored object and downcast it back to // a StudentList list = (StudentList)is.readObject(); is.close(); } catch (IOException e) { System.err.println(e.getMessage()); } catch (ClassNotFoundException ce) { System.err.println(ce.getMessage()); } return list; } public void invoke() { StudentList list = new StudentList(); buildStudentList(list); System.out.println(“Before being serialized.”); list.listStudents(); putStudentList(list); System.out.println(“After being read back in.”); // Get the StudentList and print it out StudentList inList = getStudentList(); if ( inList != null ) { inList.listStudents(); } else { System.err.println(“readObject failed.”); }
6 HTTP TUNNELING
try {
63
64
Servlet Fundamentals PART I
LISTING 6.2
Continued
try { System.out.println(“\n Press enter to quit.”); System.in.read(); } catch (Exception e) { System.err.println(e.getMessage()); } } public static void main(String[] args) { StudentListApplication studentListApplication = new StudentListApplication(); studentListApplication.invoke(); } }
You need to look at two sections of the StudentListApplication. The first is the putStudentList() method in which the StudentList object is written to the file file.dat. This method is listed as follows: // Stores the Serializable StudentList to the file “file.dat” public void putStudentList(StudentList value) { try { // Create the ObjectOutputStream passing it the // FileOutputStream object that points to our // persistent storage. ObjectOutputStream os = new ObjectOutputStream( new FileOutputStream(“file.dat”)); // Write the StudentList to the ObjectOutputStream os.writeObject(value); os.flush(); os.close(); } catch (IOException e) { System.err.println(e.getMessage()); } }
HTTP Tunneling CHAPTER 6
The second section to study is the getStudentList() method. It does the exact opposite of the putStudentList() method. One important step in this method that is not part of its counterpart is the downcast from an object to a StudentList. You must do this because when the StudentList object was stored, it was upcast to an Object. The getStudentList() method is listed as follows: public StudentList getStudentList() { StudentList list = null; try { // Create the ObjectInputStream passing it the // FileInputStream object that points to our // persistent storage. ObjectInputStream is = new ObjectInputStream( new FileInputStream(“file.dat”)); // Read the stored object and downcast it back to // a StudentList list = (StudentList)is.readObject(); is.close(); } catch (IOException e) { System.err.println(e.getMessage()); } catch (ClassNotFoundException ce) { System.err.println(ce.getMessage()); } return list; }
Build and run the application. The output should look like the following: Before being serialized. Student 0 : Bob Robinson Student 1 : Steve Bobinson Student 2 : Rob Stevinson Student 3 : Todd Thompson Student 4 : Tom Toddson Student 5 : Rob Bobinson After being read back in.
6 HTTP TUNNELING
This method follows the exact three-step process discussed earlier. It creates the appropriate streams for writing and writes the object to persistent storage.
65
66
Servlet Fundamentals PART I Student Student Student Student Student Student
0 1 2 3 4 5
: : : : : :
Bob Robinson Steve Bobinson Rob Stevinson Todd Thompson Tom Toddson Rob Bobinson
Press enter to quit.
Notice that the objects are exactly the same before and after being serialized.
Creating an HTTP Tunneling Client Now that you understand Java serialization, let’s put together an example using HTTP tunneling. The first part of this example is the client. This will be a simple application that opens an HTTP connection to your servlet. It will then write the same StudentList object used in the previous example to the open connection and wait for a response. The response will be the original StudentList object echoed back to the client. The client can be found in Listing 6.3. LISTING 6.3
StudentListTunnelApp.java
import java.io.*; import java.net.*; public class StudentListTunnelApp { public StudentListTunnelApp() { } // Adds Student Names to List public void buildStudentList(StudentList value) { value.addStudent(“Bob Robinson”); value.addStudent(“Steve Bobinson”); value.addStudent(“Rob Stevinson”); value.addStudent(“Todd Thompson”); value.addStudent(“Tom Toddson”); value.addStudent(“Rob Bobinson”); } // Write the StudentList to the Connection public void writeStudentList(URLConnection connection, StudentList value) {
HTTP Tunneling CHAPTER 6
LISTING 6.3
Continued
// Set this to false in order to ignore caching connection.setUseCaches(false); // Set the content-type of the request // application/octet-stream is used when writing // application specific byte size data connection.setRequestProperty(“CONTENT_TYPE”, “application/octet-stream”); // Set these vales to true to use the same connection // for both input and output connection.setDoInput(true); connection.setDoOutput(true); // Create the ObjectOutputStream passing it the // OutputStream object. ObjectOutputStream os = new ObjectOutputStream(connection.getOutputStream()); // Write the StudentList to the ObjectOutputStream System.err.println(“Writing StudentList Object.”); os.writeObject(value); os.flush(); os.close(); } catch (IOException e) { System.err.println(e.getMessage()); } } public StudentList readStudentList(URLConnection connection) { StudentList list = null; try { // Create the ObjectInputStream passing it the // InputStream object from the URLConnection ObjectInputStream is = new ObjectInputStream( connection.getInputStream());
6 HTTP TUNNELING
try {
67
68
Servlet Fundamentals PART I
LISTING 6.3
Continued
System.err.println(“Waiting for response.”); // Read the stored object and downcast it back to // a StudentList list = (StudentList)is.readObject(); is.close(); } catch (IOException e) { System.err.println(e.getMessage()); } catch (ClassNotFoundException ce) { System.err.println(ce.getMessage()); } return list; } public void invoke() { try { StudentList list = new StudentList(); buildStudentList(list); // create our URL URL url = new URL(“http://localhost/djs” + “/servlet/StudentListTunnelServlet”); // Open our URLConnection System.err.println(“Opening Connection.”); URLConnection con = url.openConnection(); // Write the StudentList writeStudentList(con, list); // Get the StudentList from the response // and print it out. StudentList inList = readStudentList(con); if ( inList != null ) { System.out.println(“After being read back in.”); inList.listStudents();
HTTP Tunneling CHAPTER 6
LISTING 6.3
Continued
System.err.println(“readObject failed.”); } System.out.println(“\n Press enter to quit.”); System.in.read(); } catch (MalformedURLException mue) { System.err.println(mue.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } } public static void main(String[] args) { StudentListTunnelApp studentListTunnelApp = new StudentListTunnelApp(); studentListTunnelApp.invoke(); } }
Take a look at exactly how the client works. You need to focus on several areas of this example. The first is creating the URL and opening the URLConnection. This section is listed as follows: // create our URL URL url = new URL(“http://localhost/djs” + “/servlet/StudentListTunnelServlet”); // Open our URLConnection System.err.println(“Opening Connection.”); URLConnection con = url.openConnection();
This is a very simple procedure. It first instantiates a URL object with a string pointing to the servlet URL. It then calls the URL.openConnection() method, which returns a URLConnection object. This is the object you will be using as your communications medium. It will be passed to the writeStudentList() and readStudentList() methods. These methods are your next areas of focus.
6 HTTP TUNNELING
} else {
69
70
Servlet Fundamentals PART I
The writeStudentList() method takes a URLConnection object and a StudentList object as parameters. This method first sets the appropriate URLConnection properties. This code is listed as follows: // Set this to false in order to ignore caching connection.setUseCaches(false); // Set the content-type of the request // application/octet-stream is used when writing // application specific byte size data connection.setRequestProperty(“CONTENT_TYPE”, “application/octet-stream”); // Set these vales to true to use the same connection // for both input and output connection.setDoInput(true); connection.setDoOutput(true);
These property settings are very important. The first executable line turns off caching for this request. The second is one of the more important property settings. It specifies that you will be using application-specific, byte-size data as your content type because you will be sending a binary data stream. The last two lines in this section set the doInput and doOutput connection properties to True. This makes it possible to both send and receive using the same connection. The last section of the writeStudentList() method you will look at follows the same three steps discussed in the section “Object Serialization.” It gets an OutputStream object from the URLConnection.getOutputStream() method. This OutputStream object is then passed to the constructor of the ObjectOutputStream, which is used to write the object to the HTTP connection. This code is listed as follows: // Create the ObjectOutputStream passing it the // OutputStream object. ObjectOutputStream os = new ObjectOutputStream(connection.getOutputStream()); // Write the StudentList to the ObjectOutputStream System.err.println(“Writing StudentList Object.”); os.writeObject(value); os.flush(); os.close();
The readStudentList() method is even more simple than its counterpart. It simply follows the object serialization steps for reading an object. It gets an InputStream object from the URLConnection and passes it to the constructor of the ObjectInputStream, which is then used to read the StudentList object. For your convenience, it is listed in its entirety:
HTTP Tunneling CHAPTER 6
StudentList list = null; try { // Create the ObjectInputStream passing it the // InputStream object from the URLConnection ObjectInputStream is = new ObjectInputStream( connection.getInputStream()); System.err.println(“Waiting for response.”); // Read the stored object and downcast it back to // a StudentList list = (StudentList)is.readObject(); is.close(); } catch (IOException e) { System.err.println(e.getMessage()); } catch (ClassNotFoundException ce) { System.err.println(ce.getMessage()); } return list; }
When you see how easy it is to serialize objects across an HTTP connection, or any other connection, you really have to give credit to the people who wrote these classes. They have saved all of us a lot of hassle. You will see again how easy it is in the next section, when you look at the servlet side of an HTTP tunnel.
Creating an HTTP Tunneling Servlet Now that you have seen the client side, let’s take a look at the server side. The servlet example will service requests from the StudentListTunnelApp. When it receives a request, it will read the StudentList object from the InputStream and send it, unchanged, back to the client. The source for the servlet is in Listing 6.4.
6 HTTP TUNNELING
public StudentList readStudentList(URLConnection connection) {
import StudentList; public class StudentListTunnelServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } //Service the request public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { try { // Create the ObjectInputStream with // the Request InputStream. ObjectInputStream ois = new ObjectInputStream(request.getInputStream()); // Read the Object. Make sure the StudentList Object // is in your CLASSPATH or you will receive a // ClassNotFoundException. StudentList list = (StudentList)ois.readObject(); // The Response Begins Here response.setContentType(“application/octet-stream”); ObjectOutputStream oos = new ObjectOutputStream(response.getOutputStream()); // Echo the object to the response oos.writeObject(list); oos.flush(); oos.close(); } catch (ClassNotFoundException cnfe) {
HTTP Tunneling CHAPTER 6
LISTING 6.4
Continued
} //Get Servlet information public String getServletInfo() { return “StudentListTunnelServlet Information”; } }
As you can see, this is a very simple servlet. The service() method is where all the functionality is located. The StudentList objects are written and read just as they were on the client side. The same three-step process is used on both sides.
A Practical HTTP Tunneling Example You will now put HTTP tunneling to work in a practical example. Your example will be a realtime order status tool. You will use an applet as your client side, which will be called OrderStatusApplet. It will send a serializable order object to the OrderStatusServlet. This servlet will then read the object off the wire, update the status attribute, and send the object back to the applet. Listing 6.5 contains the source code for the Order object. LISTING 6.5
Order.java
import java.io.*; // Notice this object implements the Serializable interface public class Order implements Serializable { // This private // This private
attribute holds the Order# String order = new String(“”); attribute holds the Status of the Order String status = new String(“”);
// Default Constructor public Order() { } // Accessor used to set the Order #
6 HTTP TUNNELING
System.err.println(cnfe.getMessage()); }
73
74
Servlet Fundamentals PART I
LISTING 6.5
Continued
public void setOrder(String value) { if ( value != null ) { order = value; } } // Accessor used to get the Order # public String getOrder() { return order; } // Accessor used to set the Order Status public void setStatus(String value) { if ( value != null ) { status = value; } } // Accessor used to get the Order Status public String getStatus() { return status; } }
The Order object encapsulates the order and its status, and it will be passed between the applet and servlet.
The OrderStatusApplet The OrderStatusApplet will leverage some of the Java Swing classes that are bundled with the JDK 1.1.6. You do not need to concern yourself with all the swing classes. The only two you need to understand are the JTextField and JTextArea classes. The JTextField will hold your order number, and the JTextArea will display the returned status. Listing 6.6 contains the source for the client applet.
//import com.sun.java.swing.UIManager; public class OrderStatusApplet extends JApplet { boolean isStandalone = false; JPanel jStatusPanel = new JPanel(); JPanel jActionPanel = new JPanel(); GridLayout gridLayout1 = new GridLayout(1, 2); JButton jGetStatusButton = new JButton(); JTextField jOrderTextField = new JTextField(); JLabel jLabel1 = new JLabel(); JTextArea jStatusResultTextArea = new JTextArea(); //Get a parameter value public String getParameter(String key, String def) { return isStandalone ? System.getProperty(key, def) : (getParameter(key) != null ? getParameter(key) : def); } // Default Construct public OrderStatusApplet() { } //Initialize the applet public void init() { try { jbInit(); } catch (Exception e) { e.printStackTrace(); } }
6 HTTP TUNNELING
import import import import import import
OrderStatusApplet.java
75
76
Servlet Fundamentals PART I
LISTING 6.6
Continued
//Component initialization private void jbInit() throws Exception { this.setSize(400,150); this.getContentPane().setLayout(gridLayout1); jGetStatusButton.setText(“Get Status”); jGetStatusButton.addActionListener( new java.awt.event.ActionListener() { public void actionPerformed(ActionEvent e) { jGetStatusButton_actionPerformed(e); } }); jLabel1.setText(“Order #”); jOrderTextField.setPreferredSize(new Dimension(50, 19)); jStatusResultTextArea.setPreferredSize( new Dimension(175, 135)); this.getContentPane().add(jActionPanel, null); jActionPanel.add(jLabel1, null); jActionPanel.add(jOrderTextField, null); jActionPanel.add(jGetStatusButton, null); this.getContentPane().add(jStatusPanel, null); jStatusPanel.add(jStatusResultTextArea, null); } //Get Applet information public String getAppletInfo() { return “Applet Information”; } //Get parameter info public String[][] getParameterInfo() { return null; } // Write the StudentList to the Connection public void writeOrder(URLConnection connection, Order value) { try {
HTTP Tunneling CHAPTER 6
LISTING 6.6
Continued
// Set the content-type of the request // application/octet-stream is used when writing // application specific byte size data connection.setRequestProperty(“CONTENT_TYPE”, “application/octet-stream”); // Set these vales to true to use the same connection // for both input and output connection.setDoInput(true); connection.setDoOutput(true); // Create the ObjectOutputStream passing it the // ByteArrayOutputStream object. ObjectOutputStream os = new ObjectOutputStream(connection.getOutputStream()); // Write the StudentList to the ObjectOutputStream System.err.println(“Writing Order Object.”); os.writeObject(value); os.flush(); os.close(); } catch (IOException e) { System.err.println(e.getMessage()); } } public Order readOrder(URLConnection connection) { Order order = null; try { // Create the ObjectInputStream passing it the // InputStream object from the URLConnection ObjectInputStream is = new ObjectInputStream( connection.getInputStream()); System.err.println(“Waiting for response.”);
6 HTTP TUNNELING
// Set this to false in order to ignore caching connection.setUseCaches(false);
77
78
Servlet Fundamentals PART I
LISTING 6.6
Continued
// Read the stored object and downcast it back to // a Order order = (Order)is.readObject(); is.close(); } catch (IOException e) { System.err.println(e.getMessage()); } catch (ClassNotFoundException ce) { System.err.println(ce.getMessage()); } return order; } void jGetStatusButton_actionPerformed(ActionEvent event) { try { // This is where the OrderStatus Transaction begins Order order = new Order(); order.setOrder(jOrderTextField.getText()); // create our URL URL url = new URL(“http://localhost/djs” + “/servlet/OrderStatusServlet”); // Open our URLConnection System.err.println(“Opening Connection.”); URLConnection con = url.openConnection(); // Write the Order writeOrder(con, order); // Get the Order from the response, // after the status has been checked, and print it out. Order response_order = readOrder(con); if ( response_order != null ) { // Put the status String returned from the // OrderStatusServlet into the jTextArea Object jStatusResultTextArea.setText(
The three areas of the applet you must focus on are the jGetStatusButton_actionPerformed(), writeOrder(), and readOrder() methods. These methods make up the functional areas of the applet. The jGetStatusButton_actionPerformed() method is where the transaction is invoked. It creates an Order object, setting the order attribute to the value typed into the jOrderTextField swing component. It then opens a URL connection pointing to your OrderStatusServlet, http://localhost/djs/servlet/OrderStatusServlet. The connection and the order are then passed to the writeOrder() method. The writeOrder() method first sets the appropriate properties of the Connection object. It then creates an ObjectOutputStream using the OutputStream of the connection. When the ObjectOutputStream is successfully created, the Order object is written to it. When the writeOrder() method returns, the readOrder() method is called. It takes the URLConnection object passed to it and creates an ObjectInputStream. It then calls the ObjectInputStream’s readObject() method, which block reads until a response object is received. This new Order object is then returned to the calling method. The jGetStatusButton_actionPerformed() method then takes the Order object that was returned to it and calls the getStatus() method, passing the returned status to the jStatusResultTextArea’s setText() method. Compile these classes, making sure that the swingall.jar file, which contains all the swing components, is in your CLASSPATH. The HTML used to load this applet is shown in Listing 6.7.
6 HTTP TUNNELING
response_order.getStatus());
79
80
Servlet Fundamentals PART I
LISTING 6.7 <TITLE> Order Status <APPLET ARCHIVE = CODE = NAME = WIDTH = HEIGHT = HSPACE = VSPACE = ALIGN = >
OrderStatusApplet.html
Page
“swingall.jar” “OrderStatusApplet.class” “Order Status Applet” 400 150 0 0 middle
NOTE For this example, you must copy the HTML file and the compiled class files into your Web server’s document area. You will also need to have the swingall.jar file in this same area. If you are using the Tomcat server, you can copy all of the client-side files to the SERVER_ROOT/djs/ directory. You should also note that this example has only been tested using Microsoft’s Internet Explorer v5.5.
After you have compiled and installed the HTML and class files, you can load the OrderStatusApplet.html file. Figure 6.1 shows the OrderStatusApplet after it is loaded.
The OrderStatusServlet The OrderStatusServlet services order-status requests sent by the OrderStatusApplet. It reads the Order object from the ObjectInputStream and passes it to the getOrderStatus() method. In a “real-world” application, this method would be a client to some other real-time server. It could be a CORBA client, an RMI client, or even a JDBC query to a database. For the example, it simply calls the Order.setStatus() method, passing it the string “Your order
public class OrderStatusServlet extends HttpServlet { //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); } private void getOrderStatus(Order order) { // This could do just about anything;
6 HTTP TUNNELING
The service() method then writes the Order object to the to be read by the OrderStatusApplet. Listing 6.8 contains the source for the OrderStatusServlet. ObjectOutputStream
81
82
Servlet Fundamentals PART I
LISTING 6.8
Continued
// It could be CORBA/RMI client // It could be a database query, etc. order.setStatus(“Your order is in transit.”); } //Service the request public void service(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { try { // Create the ObjectInputStream with // the Request InputStream. ObjectInputStream ois = new ObjectInputStream(request.getInputStream()); // Read the Object. Make sure the StudentList Object // is in your CLASSPATH or you will receive a // ClassNotFoundException. Order order = (Order)ois.readObject(); getOrderStatus(order); // The Response Begins Here response.setContentType(“application/octet-stream”); ObjectOutputStream oos = new ObjectOutputStream(response.getOutputStream()); // Echo the object to the response oos.writeObject(order); oos.flush(); oos.close(); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage()); } } //Get Servlet information public String getServletInfo() { return “OrderStatusServlet Information”; } }
HTTP Tunneling CHAPTER 6
NOTE
After you have a chance to look over the source for the OrderStatusServlet, build and install it to the Tomcat server. You then need to load the OrderStatusApplet into your browser, enter an order number, and click the Get Status button. Your results should look similar to Figure 6.2.
FIGURE 6.2 Results from OrderStatusServlet.
Pros and Cons of Applet-to-Servlet Communication As you have seen in the previous sections, HTTP tunneling is a very simple method for appletto-servlet communication, but it does have its own set of pros and cons. Some of the pros of using HTTP tunneling are as follows: • It is simple to use because of the Serializable interface. • It is very fast for lightweight objects.
6 HTTP TUNNELING
The Order.class file must be in the <SERVER_ROOT>djs/WEB-INF/classes/ directory, or the OrderStatusServlet will not be able to find it.
83
84
Servlet Fundamentals PART I
• It shields you from the transport layer. • It provides you with a method of tunneling through firewalls. On the other hand, some cons of this technique are the following: • You must make sure that all your objects and nested objects implement the Serializable interface. • Because you are opening a connection with an applet, security issues limit you to connecting only to the applet’s originating server. • When you start using larger objects or collections of objects, your throughput declines considerably. • Because you are using an applet as a client, you must make sure that your users have a compatible browser.
Summary This chapter covered the basics of Java serialization. You created two servlets that serviced HTTP tunneling requests. You also took a look at applets and applications as HTTP tunneling clients. At this point, you should be able to create your own servlet that can service HTTP tunneling requests. You should understand how to create Serializable objects. You should also be able to determine when to use (or not use) an applet-to-servlet solution. In the next chapter, you will look at Java’s JDBC. You will first go over a basic introduction to the JDBC and then examine how you can leverage the JDBC in servlets.
What is the JDBC? The JDBC (short for Java Database Connectivity) interface is a pure Java API used to execute SQL statements. The JDBC provides a set of classes and interfaces that can be used by developers to write database applications. Basic JDBC interaction, in its simplest form, can be broken down into four steps: 1. Open a connection to the database. 2. Execute a SQL statement. 3. Process the results. 4. Close the connection to the database. The following code fragment shows these steps in action: // Step 1. Open a connection to the ODBC datasource titles. con = DriverManager.getConnection(“jdbc:odbc:titles”, “username”, “password”); // Step 2. Execute the SQL statement. Statement statement = con.createStatement(); ResultSet rs = statement.executeQuery(“SELECT * “ + “FROM Types”); // Step 3. Process the Results while ( rs.next() ) { // get the type_id, which is an int System.err.println(“Type ID = “ + rs.getInt(“type_id”)); // get the type_name, which is a String System.err.println(“Type Name = “ + rs.getString(“type_name”)); } // Step 4. Close the Connection. rs.close(); con.close();
This chapter will introduce the JDBC and explore how to use it in a servlet.
Two- and Three-Tier Database Access Models The JDBC provides support for two- and three-tier database access models. We will examine both in this section.
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
87
When you use the two-tier database access model, your Java application talks directly to the database. This is accomplished through the use of a JDBC driver, which sends commands directly to the database. The results of these commands are then sent back from the database directly to the application. Figure 7.1 shows the two-tier model. Application Space Java Application
7
SQL Command
Result Set
Database
FIGURE 7.1 The two-tier JDBC model.
The three-tier model, as you might have guessed, is a little more complicated. When you use the three-tier model, your JDBC driver sends commands to a middle tier, which in turn sends commands to the database. The results of these commands are then sent back to the middle tier, which communicates them back to the application. Figure 7.2 shows the three-tier model.
JDBC Driver Types Sun has defined four JDBC driver types: • JDBC-ODBC Bridge, plus ODBC driver • Native-API, partly Java driver • JDBC-net, pure Java driver • Native-protocol, pure Java driver Each of these types meets a different application need, as we’ll discuss in the following sections.
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
JDBC Driver
88
Servlet Fundamentals PART I
Application Space Java Application
JDBC Driver
SQL Command
Result Set
Application Server (middle-tier)
Proprietary Protocol
Database
FIGURE 7.2 The three-tier JDBC model.
Type 1: JDBC-ODBC Bridge, Plus ODBC Driver The first type of JDBC driver is the JDBC-ODBC Bridge. This driver type is provided by Sun with the JDK 1.1 and later. It provides JDBC access to databases through Open Database Connectivity (ODBC) drivers. The ODBC driver must be configured on the client for the bridge to work. This driver type is commonly used for prototyping or when there is no JDBC driver available for a particular Database Management System (DBMS). Figure 7.3 shows the driver interaction of the JDBC-ODBC Bridge.
Type 2: Native-API, Partly Java Driver The native-API driver converts JDBC commands into DBMS-specific native calls. This is much like the restriction of Type 1 drivers, in that the client must have some binary code loaded on its machine. These drivers do have an advantage over Type 1 drivers, because they interface directly with the database. Figure 7.4 shows the interactions of a Type 2 driver.
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
89
Application Space Java Application
JDBC-PDBC Bridge
Result Set
ODBC Driver
Proprietary Protocol
Database
FIGURE 7.3 The Type 1 JDBC-ODBC Bridge.
Type 3: JDBC-Net, Pure Java Driver The JDBC-Net drivers are a three-tier solution. This type of driver translates JDBC calls into a database-independent network protocol that is sent to a middleware server. This server then translates this DBMS-independent protocol into a DBMS-specific protocol, which is sent to a particular database. The results are routed back through the middleware server and sent back to the client. This type of solution makes it possible to implement a pure Java client. It also makes it possible to swap databases without affecting the client. This is by far the most flexible JDBC solution. Figure 7.5 shows this three-tier solution.
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
SQL Command
90
Servlet Fundamentals PART I
Application Space Java Application
Type 2 JDBC Driver
SQL Command
Result Set
Native Database Library
Proprietary Protocol
Database
FIGURE 7.4 The Type 2 Native-API JDBC driver.
Type 4: Native-Protocol, Pure Java Driver The Type 4 drivers are pure Java drivers that communicate directly with the vendor’s database. They do this by converting JDBC commands directly into the database engine’s native protocol. The Type 4 driver has a very distinct advantage over all the other driver types: It has no additional translation or middleware layer, which improves performance tremendously. Figure 7.6 diagrams the communications of a Type 4 driver.
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
91
Application Space Java Application
Type 3 JDBC Driver
Result Set
Middleware Space JDBC Driver
Proprietary Protocol
Database
FIGURE 7.5 The Type 3 JDBC-Net driver.
Application Space Java Application
Type 4 JDBC Driver
SQL Command Using Proprietary Protocol
Result Set Using Proprietary Protocol
Database
FIGURE 7.6 The Type 4 native-protocol JDBC driver.
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
SQL Command
92
Servlet Fundamentals PART I
JDBC Basics Now that we have discussed what the JDBC is and some of its characteristics, let’s start learning how to use it. In this section, we will discuss how to install and set up a Type 1 driver, make a connection to the database, and perform the basic SQL commands.
Installing and Setting Up a Type 1 Driver In the JDBC examples throughout this book, you will be connecting to a Microsoft Access database using a Type 1 driver. To install the JDBC-ODBC Bridge, download the JDK and follow the installation directions. The JDBC-ODBC Bridge is included in version 1.1 and later. The JDBC-ODBC Bridge requires no specific setup steps, but the ODBC driver does. For our examples, assume that you are using a PC and running Windows NT or 2000. If not, you will need to create your own database using the drivers supplied by your database vendor. To configure the ODBC data source for the examples, you will follow these steps: 1. Copy to your local drive the database file moviecatalog.mdb, which can be found on the book’s Web site. 2. Start the application ODBC. You will see a window similar to the one in Figure 7.7.
FIGURE 7.7 The ODBC Administrator.
3. Select the System DSN tab and click the Add button to add a new data source. Figure 7.8 shows the Create New Data Source screen.
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
93
7 The Create New Data Source screen.
4. Select the Microsoft Access Driver and click the Finish button. You will now see the ODBC Microsoft Access Setup screen. Figure 7.9 shows this screen.
FIGURE 7.9 The ODBC Microsoft Access Setup screen.
5. Enter the string “Movie Catalog” as the data source name and click the database Select button. Enter the path to the location of your moviecatalog.mdb file and click OK. You will now see the ODBC Microsoft Access Setup screen with your changes displayed. Click OK to commit to your changes. 6. You will now see the ODBC Data Source Administrator screen with the Movie Catalog data source in the list. Click the OK button to close this window.
Establishing a Database Connection The first thing you need to do when using the JDBC is establish a connection to the database. This is a two-step process. You must load the JDBC driver and then make a connection.
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
FIGURE 7.8
94
Servlet Fundamentals PART I
Loading a JDBC driver is very simple. It takes only one line of code. In our examples, we will be using the JDBC-ODBC Bridge. The class name for this driver is sun.jdbc.odbc.JdbcOdbcDriver. The following code snippet shows you how to load this driver: Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”);
When you call the Class.forName() method, it creates an instance of the driver and registers it with the DriverManager. This is all there is to loading a JDBC driver. After you have the driver loaded, it is easy to make a connection. You make a call to the static method DriverManager.getConnection(), which returns a connection to the database. Its method signature is listed as follows: public static synchronized Connection getConnection(String url, String user, String password) throws SQLException
The first parameter is the URL that points to your data source. In the case of the JDBC-ODBC Bridge, it always begins with jdbc:odbc:DataSourceName, where the DataSourceName is the name of the ODBC data source you set up. The next two parameters are self-explanatory. They are the username and password associated with the database login. For this example, you will use empty strings for each. Here is the code used to open a connection to your Movie Catalog database: con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”);
The Connection object returned from the DriverManager is an open connection to the database. You will be using it to create JDBC statements that pass SQL statements to the database.
Performing the Basic SQL Commands In this section we will look at how to create a JDBC Statement object and five JDBC examples that use the Statement object. In all the examples, you will be using the Movie Catalog database that you configured earlier.
Creating a JDBC Statement Object To execute any SQL command using a JDBC connection, you must first create a Statement object. To create a statement, you need to call the Connection.createStatement() method. It returns a JDBC statement that you will use to send your SQL statements to the database. The following code snippet shows how to create a statement: Statement statement = con.createStatement();
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
95
Creating a Table The first thing you will do is create a database table that represents a list of movie titles. Currently two tables are in the database: the Categories table and the Types table. Table 7.1 shows the composition of your new Titles table. TABLE 7.1
Titles Table Elements
Data Type
title_id
INTEGER
title_name
VARCHAR(50)
rating
VARCHAR(5)
price
FLOAT
quantity
INTEGER
type_id
INTEGER
category_id
INTEGER
The application that creates this table can be found in Listing 7.1. Notice that it follows the step-by-step process that I described earlier: 1. Open a connection to the database. 2. Execute a SQL statement. 3. Process the results. 4. Close the connection to the database. LISTING 7.1
CreateTablesApp.java
import java.sql.*; public class CreateTablesApp { public void createTables() { Connection con = null; try { // Load the Driver class file Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”); // Make a connection to the ODBC datasource Movie Catalog
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
Field Name
96
Servlet Fundamentals PART I
LISTING 7.1
Continued
con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”); // Create the statement Statement statement = con.createStatement(); // Use the created statement to CREATE the database table // Create Titles Table statement.executeUpdate(“CREATE TABLE Titles “ + “(title_id INTEGER, title_name VARCHAR(50), “ + “rating VARCHAR(5), price FLOAT, quantity INTEGER, “ + “type_id INTEGER, category_id INTEGER)”); } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } finally { try { if ( con != null ) { // Close the connection no matter what con.close(); } } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } } } public static void main(String[] args) {
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.1
97
Continued
CreateTablesApp createTablesApp = new CreateTablesApp(); createTablesApp.createTables(); } }
The section we want to focus on is listed here: // Create the statement Statement statement = con.createStatement();
The first statement executed creates a Statement object with the given Connection. To perform the actual creation of the table, call the Statement.executeUpdate() method, passing it the SQL statement to create the table. Its signature is listed as follows: public int executeUpdate(String sql) throws SQLException
This method is used for all update-type transactions. It takes a string representation of an SQL statement and returns an integer. The return value is either a row count for INSERT, UPDATE, and DELETE statements, or 0 for SQL statements that return nothing, such as a CREATE. After you have created the Titles table, the table relationships of your Movie Catalog database will look something like Figure 7.10.
Inserting Data into a Table Now that you have all your tables in place, you can put some data into them. Listing 7.2 shows the application used to populate your Movie Catalog database.
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Use the created statement to CREATE the database table // Create Titles Table statement.executeUpdate(“CREATE TABLE Titles “ + “(title_id INTEGER, title_name VARCHAR(50), “ + “rating VARCHAR(5), price FLOAT, quantity INTEGER, “ + “type_id INTEGER, category_id INTEGER)”);
7
98
Servlet Fundamentals PART I
FIGURE 7.10 The Movie Catalog database.
LISTING 7.2
InsertDataApp.java
import java.sql.*; public class InsertDataApp { public InsertDataApp() { } public void insertData() { Connection con = null; try { // Load the Driver class file Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”); // Make a connection to the ODBC datasource Movie Catalog con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”);
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.2
99
Continued
// Create the statement Statement statement = con.createStatement(); // Use the created statement to INSERT DATA into // the database tables. // Insert Data into the Types Table statement.executeUpdate(“INSERT INTO Types “ + “VALUES (0, ‘VHS’)”);
statement.executeUpdate(“INSERT INTO Types “ + “VALUES (2, ‘Laserdisc’)”); // Insert Data into the Categories Table statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (0, ‘Action Adventure’)”); statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (1, ‘Comedy’)”); statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (2, ‘Drama’)”); statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (3, ‘Western’)”); statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (4, ‘Sci-Fi’)”); statement.executeUpdate(“INSERT INTO Categories “ + “VALUES (5, ‘Classics’)”); // Insert Data into the Titles Table statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (0, ‘The Adventures of Buckaroo Banzai’, “ + “‘PG’, 19.95, 10, 0, 4)”); statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (1, ‘Saving Private Ryan’, “ + “‘R’, 19.95, 12, 1, 0)”);
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
statement.executeUpdate(“INSERT INTO Types “ + “VALUES (1, ‘DVD’)”);
100
Servlet Fundamentals PART I
LISTING 7.2
Continued
statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (2, ‘So I Married An Axe Murderer’, “ + “‘PG’, 19.95, 15, 1, 1)”); statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (3, ‘Happy Gilmore’, “ + “‘PG’, 19.95, 9, 1, 1)”); statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (4, ‘High Plains Drifter’, “ + “‘PG’, 29.95, 10, 2, 3)”); statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (5, ‘Cape Fear’, “ + “‘NR’, 6.99, 21, 0, 5)”); statement.executeUpdate(“INSERT INTO Titles “ + “VALUES (6, ‘The Last Emperor’, “ + “‘PG’, 19.95, 12, 1, 2)”); } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } finally { try { if ( con != null ) { // Close the connection no matter what con.close(); } } catch (SQLException sqle) {
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.2
101
Continued
System.err.println(sqle.getMessage()); } } } public static void main(String[] args) { InsertDataApp insertDataApp = new InsertDataApp(); insertDataApp.insertData(); }
The InsertDataApp application uses the same executeUpdate() method you used to create your tables. You only change the SQL string that you pass to it, using a basic SQL INSERT statement instead. You insert data into your Types, Categories, and Titles tables, respectively. Also notice that you can perform all your inserts using the same Statement object. There is nothing preventing you from reusing this object, instead of creating a new one for each execution.
Selecting Data from a Table The most common SQL statement is the SELECT statement. It gives you the ability to look at the data stored in your tables. In the previous examples, you created and populated the Movie Catalog database. In this example, we are going to look at the data you put in these tables, and we will do it with a SELECT statement. Listing 7.3 contains the source for this example. LISTING 7.3
SelectDataApp.java
import java.sql.*; import java.io.*; public class SelectDataApp { public SelectDataApp() { } public void selectData() { Connection con = null; try {
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
}
102
Servlet Fundamentals PART I
LISTING 7.3
Continued
// Load the Driver class file Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”); // Make a connection to the ODBC datasource Movie Catalog con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”); // Create the statement Statement statement = con.createStatement(); // Use the created statement to SELECT the DATA // FROM the Titles Table. ResultSet rs = statement.executeQuery(“SELECT * “ + “FROM Titles”); // Iterate over the ResultSet while ( rs.next() ) { // get the title_name, which is a String System.err.println(“Title Name = “ + rs.getString(“title_name”)); // get the rating System.err.println(“Title Rating = “ + rs.getString(“rating”)); // get the price System.err.println(“Title Price = “ + rs.getString(“price”)); // get the quantity System.err.println(“Title Quantity = “ + rs.getString(“quantity”) + “\n”); } // Close the ResultSet rs.close(); System.in.read(); } catch (IOException ioe) { System.err.println(ioe.getMessage()); } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage());
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.3
103
Continued
} catch (Exception e) { System.err.println(e.getMessage()); } finally { try { if ( con != null ) {
To execute a query, use the same Statement object as in previous examples. You just call a different method. The method to perform a query is executeQuery(). Its signature is listed here: public ResultSet executeQuery(String sql) throws SQLException
It takes a SQL string like the executeUpdate() method. The difference from executeUpdate() is that executeQuery() returns a ResultSet object containing the results of the query. In the example, you pass it the string “SELECT * FROM Titles”, which returns a collection of rows resulting from the query. After you have your ResultSet object returned from executeQuery(), you can iterate over it. The following code snippet shows how the example processes the query results:
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Close the connection no matter what con.close();
7
104
Servlet Fundamentals PART I // Iterate over the ResultSet while ( rs.next() ) { // get the title_name, which is a String System.err.println(“Title Name = “ + rs.getString(“title_name”)); // get the rating System.err.println(“Title Rating = “ + rs.getString(“rating”)); // get the price System.err.println(“Title Price = “ + rs.getString(“price”)); // get the quantity System.err.println(“Title Quantity = “ + rs.getString(“quantity”) + “\n”); } // Close the ResultSet rs.close();
The first thing you do is call the ResultSet.next() method. This method returns a Boolean value, indicating whether the next row in the set is valid. If it is, you can access that row using the Get accessors provided by the ResultSet object. In our example, you use only the getString() method; but the Get accessors all function the same except for their return type. They take a string value representing the name of the column in the table and return the type that is part of their method name. For example, getString() returns a java.lang.String and getInt() returns an int. You can continue iterating over the ResultSet until next() returns false; at that point you need to close the ResultSet object. When you execute this application, the results will be similar to the following output: Title Title Title Title
Name = The Adventures of Buckaroo Banzai Rating = PG Price = 19.95 Quantity = 10
Title Title Title Title
Name = Saving Private Ryan Rating = R Price = 19.95 Quantity = 12
Title Title Title Title
Name = So I Married An Axe Murderer Rating = PG Price = 19.95 Quantity = 15
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7 Name = High Plains Drifter Rating = PG Price = 29.95 Quantity = 10
Title Title Title Title
Name = Cape Fear Rating = NR Price = 6.99 Quantity = 21
Title Title Title Title
Name = The Last Emperor Rating = PG Price = 19.95 Quantity = 12
Updating Tables Another SQL command we need to examine is the UPDATE statement. It looks for a matching condition and makes the specified changes if the WHERE clause is true. An example of this would be if you sold seven copies of The Last Emperor. You would need to update its quantity to 5. The example in Listing 7.4 does just that. LISTING 7.4
UpdateDataApp.java
import java.sql.*; public class UpdateDataApp { public UpdateDataApp() { } public void updateData() { Connection con = null; try { // Load the Driver class file Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”); // Make a connection to the ODBC datasource Movie Catalog con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”); // Create the statement
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
Title Title Title Title
105
106
Servlet Fundamentals PART I
LISTING 7.4
Continued
Statement statement = con.createStatement(); // Use the created statement to UPDATE DATA in // the database tables. // Update the Quantity of “The Last Emperor” statement.executeUpdate(“UPDATE Titles “ + “SET quantity = 5 “ + “WHERE title_name = ‘The Last Emperor’”); } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } finally { try { if ( con != null ) { // Close the connection no matter what con.close(); } } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } } } public static void main(String[] args) { UpdateDataApp updateDataApp = new UpdateDataApp(); updateDataApp.updateData(); } }
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
107
If you examine the executeUpdate() method in Listing 7.4, you will see the appropriate SQL string used to perform the previously mentioned update. Run this application and then run the example from Listing 7.3. You will see the change to the quantity value of The Last Emperor.
Deleting Data from a Table The last topic for this section is deleting data from the database. It is not much different from the previous database updating functions, but it does deserve its own section.
// Use the created statement to DELETE DATA // FROM the Titles table. statement.executeUpdate(“DELETE FROM Titles “ + “WHERE title_name = ‘Cape Fear’”);
After you have run this application, run SelectDataApp again and you will see that the title Cape Fear is no longer in the database.
A Basic JDBC Servlet In this section, you will connect the JDBC and servlets. You will create a servlet that gets the movie rating parameter from the request and searches for all titles with this matching rating. The servlet that does this will be called the TitleListServlet and is shown in Listing 7.5. LISTING 7.5 import import import import import
public class TitleListServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); }
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
To delete a row from a table, you again use the executeUpdate() method. The only change will be the SQL statement you pass to it. In this example, assume you have decided to take Cape Fear off the market. It just doesn’t sell as well as it did in previous years. So, you put a SQL string together and substitute it into the executeUpdate() method. The changed call will look something like the following snippet:
108
Servlet Fundamentals PART I
LISTING 7.5
Continued
//Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request, response); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Set the response content-type response.setContentType(“text/html”); // get the Writer object PrintWriter out = response.getWriter(); out.println(“\n\n
”); // Get the search_string parameter, passed from the // SearchServlet. String search_string = request.getParameter(“search_string”); Connection con = null; try { // Load the Driver class file Class.forName(“sun.jdbc.odbc.JdbcOdbcDriver”); System.err.println(“Getting Connection!”); // Make a connection to the ODBC datasource Movie Catalog // In this example we are opening a connection to the // database with every request. con = DriverManager.getConnection(“jdbc:odbc:Movie Catalog”, “”, “”); if ( con != null ) { System.err.println(“Got Connection!”);
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.5
109
Continued // Create the statement Statement statement = con.createStatement();
// Iterate over the ResultSet while ( rs.next() ) { out.println(“
”); // get the id, which is an int out.println(“
” + rs.getInt(“title_id”) + “
”); // get the name, which is a String out.println(“
” + rs.getString(“title_name”) + “
”); // get the rating, which is a String out.println(“
” + rs.getString(“rating”) + “
”); // get the price, which is a Float out.println(“
” + rs.getFloat(“price”) + “
”); // get the Quantity, which is a Integer out.println(“
” + rs.getInt(“quantity”) + “
”); // get the Type, which is a Integer out.println(“
” + rs.getInt(“type_id”) + “
”); // get the Category, which is a Integer out.println(“
” + rs.getInt(“category_id”) + “
”); out.println(“
”); } // Close the ResultSet rs.close(); out.println(“
”);
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Use the created statement to SELECT the DATA // FROM the Titles Table. // In this instance we are searching for an exact match. // If you were to deploy this to a production site, you // might want to use a “LIKE” clause instead of WHERE. ResultSet rs = statement.executeQuery(“SELECT * “ + “FROM Titles WHERE rating = ‘“ + search_string + “‘“);
110
Servlet Fundamentals PART I
LISTING 7.5
Continued
} } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) { System.err.println(cnfe.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } finally { try { if ( con != null ) { // Close the connection no matter what con.close(); } } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } } out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “TitleListServlet Information”; } }
All the action in the TitleListServlet is taking place in the doPost() method. It first gets the search_string passed in the request on the URL. The next steps involved are opening a connection to the database, performing a query using the search_string, displaying the results,
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
111
and then closing the connection. This type of algorithm, although simple, is very time consuming. Opening and closing a database connection with every request is hardly an optimal solution. Now, take a look at this servlet in action. Open your browser to the following link: http://yourserver/djs/servlet/TitleListServlet?search_string=PG
Your results should look similar to Figure 7.11. Try this several times so you can get used to the speed.
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
FIGURE 7.11 TitleListServlet output.
To speed up the servicing of requests, you could open the connection to the database in the init() method and then close it in the destroy() method, but you would be limited to a single connection. If you chose to do this, you would need to have your servlet implement the SingleThreadModel interface. This interface defines a single-thread model for servlet execution, guaranteeing that no two threads will execute concurrently the service() method of the implementing servlet. This would save execution time, but would limit you to servicing requests one at a time.
112
Servlet Fundamentals PART I
A JDBC Connection Pool To remedy the slow servicing of requests encountered in the previous section, you will create a pool of connections to the database. This will give you access to a collection of already opened database connections, which will reduce the time it takes to service a request, and you can service n number of requests at once. The following are the requirements for the ConnectionPool object: • It must hold n number of open connections. • It must be able to determine when a connection is in use. • If n+1 connections are requested, it must create a new connection and add it to the pool. • When you close the pool, all connections must be released. Now that we know what we want, let’s look at the result. The source for the ConnectionPool is in Listing 7.6. LISTING 7.6
ConnectionPool.java
package ConnectionPool; import java.sql.*; import java.util.*; public class ConnectionPool { // JDBC Driver Name private String driver = null; // URL of database private String url = null; // Initial number of connections. private int size = 0; // Username private String username = null; // Password private String password = null; // Vector of JDBC Connections private Vector pool = null; public ConnectionPool() { } // Set the value of the JDBC Driver
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.6
113
Continued
public void setDriver(String value) { if ( value != null ) { driver = value; } } // Get the value of the JDBC Driver public String getDriver() {
// Set the URL Pointing to the Datasource public void setURL(String value ) { if ( value != null ) { url = value; } } // Get the URL Pointing to the Datasource public String getURL() { return url; } // Set the initial number of connections public void setSize(int value) { if ( value > 1 ) { size = value; } } // Get the initial number of connections public int getSize() { return size; }
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
return driver; }
7
114
Servlet Fundamentals PART I
LISTING 7.6
Continued
// Set the username public void setUsername(String value) { if ( value != null ) { username = value; } } // Get the username public String getUserName() { return username; } // Set the password public void setPassword(String value) { if ( value != null ) { password = value; } } // Get the password public String getPassword() { return password; } // Creates and returns a connection private Connection createConnection() throws Exception { Connection con = null; // Create a Connection con = DriverManager.getConnection(url, username, password); return con; } // Initialize the pool public synchronized void initializePool() throws Exception {
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.6
115
Continued
// Check our initial values if ( driver == null ) { throw new Exception(“No Driver Name Specified!”); } if ( url == null ) {
throw new Exception(“Pool size is less than 1!”); } // Create the Connections try { // Load the Driver class file Class.forName(driver); // Create Connections based on the size member for ( int x = 0; x < size; x++ ) { System.err.println(“Opening JDBC Connection “ + x); Connection con = createConnection(); if ( con != null ) { // Create a PooledConnection to encapsulate the // real JDBC Connection PooledConnection pcon = new PooledConnection(con); // Add the Connection to the pool addConnection(pcon); } } } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (ClassNotFoundException cnfe) {
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
throw new Exception(“No URL Specified!”); } if ( size < 1 ) {
116
Servlet Fundamentals PART I
LISTING 7.6
Continued
System.err.println(cnfe.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } } // Adds the PooledConnection to the pool private void addConnection(PooledConnection value) { // If the pool is null, create a new vector // with the initial size of “size” if ( pool == null ) { pool = new Vector(size); } // Add the PooledConnection Object to the vector pool.addElement(value); } public synchronized void releaseConnection(Connection con) { // find the PooledConnection Object for ( int x = 0; x < pool.size(); x++ ) { PooledConnection pcon = (PooledConnection)pool.elementAt(x); // Check for correct Connection if ( pcon.getConnection() == con ) { System.err.println(“Releasing Connection “ + x); // Set its inuse attribute to false, which // releases it for use pcon.setInUse(false); break; } } } // Find an available connection public synchronized Connection getConnection() throws Exception {
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.6
117
Continued
PooledConnection pcon = null; // find a connection not in use for ( int x = 0; x < pool.size(); x++ ) { pcon = (PooledConnection)pool.elementAt(x); // Check to see if the Connection is in use if ( pcon.inUse() == false ) {
} } // Could not find a free connection, // create and add a new one try { // Create a new JDBC Connection Connection con = createConnection(); // Create a new PooledConnection, passing it the JDBC // Connection pcon = new PooledConnection(con); // Mark the connection as in use pcon.setInUse(true); // Add the new PooledConnection object to the pool pool.addElement(pcon); } catch (Exception e) { System.err.println(e.getMessage()); } // return the new Connection return pcon.getConnection(); } // When shutting down the pool, you need to first empty it. public synchronized void emptyPool() { // Iterate over the entire pool closing the
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Mark it as in use pcon.setInUse(true); // return the JDBC Connection stored in the // PooledConnection object return pcon.getConnection();
118
Servlet Fundamentals PART I
LISTING 7.6
Continued
// JDBC Connections. for ( int x = 0; x < pool.size(); x++ ) { System.err.println(“Closing JDBC Connection “ + x); PooledConnection pcon = (PooledConnection)pool.elementAt(x); // If the PooledConnection is not in use, close it if ( pcon.inUse() == false ) { pcon.close(); } else { // If it’s still in use, sleep for 30 seconds and // force close. try { java.lang.Thread.sleep(30000); pcon.close(); } catch (InterruptedException ie) { System.err.println(ie.getMessage()); } } } } }
The first steps in using the ConnectionPool are to create an instance of the object and set the appropriate accessors. This is accomplished in an init() method of a servlet that would be responsible for initializing the ConnectionPool. This makes the ConnectionPool available to all future requests. An sample init() method follows: //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); // Instantiate the ConnectionPool
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
119
ConnectionPool pool = new ConnectionPool();
// Initialize the pool pool.initializePool();
The init() method first creates an instance of the ConnectionPool. It then sets the accessors appropriately. It sets the driver to the JDBC-ODBC Bridge, the data source URL to the Movie Catalog, and the initial number of connections to 4. The next two accessors (username and password) are set to empty strings. This is because the Microsoft Access database that we have created has no login or password. The last executable line of the init() method initializes the ConnectionPool. This is where the ConnectionPool connections begin their life. An excerpt of the ConnectionPool’s initializePool() method is listed as follows: // Load the Driver class file Class.forName(driver); // Create Connections based on the size member for ( int x = 0; x < size; x++ ) { System.err.println(“Opening JDBC Connection “ + x); Connection con = createConnection(); if ( con != null ) { // Create a PooledConnection to encapsulate the // real JDBC Connection PooledConnection pcon = new PooledConnection(con); // Add the Connection the pool. addConnection(pcon); } }
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Set the JDBC Driver pool.setDriver(“sun.jdbc.odbc.JdbcOdbcDriver”); // Set the URL to the Datasource pool.setURL(“jdbc:odbc:Movie Catalog”); // Set the initial size of the Connection Pool pool.setSize(4); // Set the Username pool.setUsername(“”); // Set the Password pool.setPassword(“”);
120
Servlet Fundamentals PART I
The initializePool() method first loads the JDBC driver. It then creates size number of Connection objects. For each Connection object created, it creates a PooledConnection object, passing it the Connection in the constructor. Finally, it adds the newly create PooledConnection object to the pool. The PooledConnection object simply wraps a JDBC Connection object in a class that holds the connection and a flag that determines whether the connection is in use or not. It is listed in Listing 7.9. LISTING 7.9
PooledConnection.java
package ConnectionPool; import java.sql.*; public class PooledConnection { // Real JDBC Connection private Connection connection = null; // boolean flag used to determine if connection is in use private boolean inuse = false; // Constructor that takes the passed in JDBC Connection // and stores it in the connection attribute. public PooledConnection(Connection value) { if ( value != null ) { connection = value; } } // Returns a reference to the JDBC Connection public Connection getConnection() { // get the JDBC Connection return connection; } // Set the status of the PooledConnection. public void setInUse(boolean value) { inuse = value; }
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.9
121
Continued
// Returns the current status of the PooledConnection. public boolean inUse() { return inuse; } // Close the real JDBC Connection public void close() { try {
System.err.println(sqle.getMessage()); } } }
Next we need to look at the doPost()/doGet() method of the servlet that initialized the ConnectionPool. Whereas in the TitleListServlet you had to load the driver and call the DriverManager.getConnection() method directly, here all you have to do is call the ConnectionPool.getConnection(), which will iterate through its vector of connections until it finds an available connection. If it cannot find an available connection, it will create one and add it to the pool. It will then mark the connection as in use and return it. A sample doPost() method follows: //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); Connection con = null; try { // Get a connection from the ConnectionPool con = pool.getConnection(); if ( con != null ) {
SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
connection.close(); } catch (SQLException sqle) {
7
122
Servlet Fundamentals PART I // Create the statement Statement statement = con.createStatement(); // Use the created statement to SELECT the DATA // FROM the Titles Table. ResultSet rs = statement.executeQuery(“SELECT * “ + “FROM Titles”); // iterate over the results here, if you choose!!! // Close the ResultSet rs.close(); } } catch (SQLException sqle) { System.err.println(sqle.getMessage()); } catch (Exception e) { System.err.println(e.getMessage()); } finally { // Release the connection pool.releaseConnection(con); } out.close(); }
When the doPost() method is finished with the connection, it must return it to the pool. To do this, it calls the ConnectionPools’s releaseConnection() method, passing it the Connection object: // Release the connection pool.releaseConnection(con);
The releaseConnection() method searches the pool for the Connection object and marks it as available for use. The last interaction a servlet has with the ConnectionPool is when it shuts down. In its method, the servlet calls the ConnectionPool.emptyPool() method. This method iterates over the entire pool, closing connections until all the Connection objects are closed. destroy()
Now you have access to pre-opened connections to the database and can service just about any number of simultaneous requests.
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
123
NOTE The database you use will, of course, determine the number of connections you can really have opened at once. Consult your database documentation or license agreement for this number.
public class ConnectionPoolServlet extends HttpServlet { //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); // Instantiate the ConnectionPool ConnectionPool pool = new ConnectionPool(); try { // Set the JDBC Driver pool.setDriver(“sun.jdbc.odbc.JdbcOdbcDriver”); // Set the URL to the Datasource pool.setURL(“jdbc:odbc:Movie Catalog”); // Set the initial size of the Connection Pool
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
In the previous section, you saw how a connection pool saves you a lot of time when servicing requests. Wouldn’t it be nice if, instead of creating a ConnectionPool local only to one specific servlet, you could have a ConnectionPool that was global to all your servlets? To do this, you will need to create a servlet that can manage a ConnectionPool object and provide a way for other servlets to communicate with it. Listing 7.10 contains the source for a servlet that will do just this.
124
Servlet Fundamentals PART I
LISTING 7.10
Continued
pool.setSize(4); // Set the Username pool.setUsername(“”); // Set the Password pool.setPassword(“”); // Initialize the pool pool.initializePool(); // Once the pool is Initialized, add it to the // Global ServletContext. This makes it available // To other servlets using the same ServletContext. ServletContext context = getServletContext(); context.setAttribute(“CONNECTION_POOL”, pool); } catch (Exception e) { System.err.println(e.getMessage()); } } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Set the response content-type response.setContentType(“text/html”); // get the Writer object PrintWriter out = response.getWriter(); out.println(“This Servlet does not service requests!”); out.close(); } public void destroy() { // Access the ServletContext using the getAttribute() // method, which returns a reference to the ConnectionPool. ServletContext context = getServletContext(); ConnectionPool pool = (ConnectionPool) context.getAttribute(“CONNECTION_POOL”); if ( pool != null ) {
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.10
125
Continued
// empty the pool pool.emptyPool(); // Remove the Attribute from the ServletContext context.removeAttribute(“CONNECTION_POOL”); } else { System.err.println(“Could not get a reference to Pool!”); } //Get Servlet information public String getServletInfo() { return “ConnectionPoolServlet Information”; } }
The two areas of the ConnectionPoolServlet that you need to examine are the init() and destroy() methods. The doGet() method is just a placeholder; it has no functionality. The ConnectionPoolServlet.init() method creates the ConnectionPool and makes it available to the other servlets. It does this by first creating an instance of the ConnectionPool just like any other application would. It then takes the newly created ConnectionPool object and adds it to the shared ServletContext. It does this in the following code snippet: // Once the pool is Initialized, add it to the // Global ServletContext. This makes it available // To other servlets using the same ServletContext. ServletContext context = getServletContext(); context.setAttribute(“CONNECTION_POOL”, pool);
The preceding code gets a reference to the ServletContext, which is shared by all servlets that exist in the same ServletContext. It then calls the setAttribute() method, passing it a string that represents a key and a reference to the ConnectionPool object. This makes the ConnectionPool available to other servlets. The destroy() method does just the opposite. It first gets a reference to the ConnectionPool by calling the ServletContext.getAttribute() method. The signature for this method is as follows: public java.lang.Object getAttribute(java.langString name)
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
}
126
Servlet Fundamentals PART I
It takes a string that represents the key that was used to add the object in the setAttribute() method, and returns a reference to an object. You must downcast the object back to a ConnectionPool because when it was stored in the ServletContext, it was stored as an object. The destroy() method then empties the ConnectionPool and removes the attribute from the ServletContext using the removeAttribute() method. The destroy() method is listed in the following: public void destroy() { // Access the ServletContext using the getAttribute() // method, which returns a reference to the ConnectionPool. ServletContext context = getServletContext(); ConnectionPool pool = (ConnectionPool) context.getAttribute(“CONNECTION_POOL”); if ( pool != null ) { // empty the pool pool.emptyPool(); // Remove the Attribute from the ServletContext context.removeAttribute(“CONNECTION_POOL”); } else { System.err.println(“Could not get a reference to Pool!”); } }
NOTE You might want to set up the ConnectionPoolServlet as a preloaded servlet. This will make sure that the connections are already available before the first request is made. You can do this by including the following lines in your web.xml file: <servlet> <servlet-name>ConnectionPool.ConnectionPoolServlet <servlet-class>ConnectionPool.ConnectionPoolServlet 1
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
127
Now that you have created and understand the ConnectionPoolServlet, you can put it to use with another example. This example is based on your TitleListServlet, except that you will do a generic query with no request parameters. There are two important changes to this servlet. The first is how it gets a connection and the second is how it releases that connection. The TitleListGlobalPooledServlet gets a Connection object by calling the method, passing it the key “CONNECTION_POOL”, which returns a reference to the ConnectionPool object. It can then call the ConnectionPool.getConnection() method to get a JDBC connection: ServletContext.getAttribute()
// Get a connection from the ConnectionPool con = pool.getConnection();
When the servlet finishes with the connection, it must release it. This is done by calling the ConnectionPool’s releaseConnection() method: // Release the connection pool.releaseConnection(con);
That is all there is to it. After you are finished with the ConnectionPool, it still resides in the ServletContext waiting on future requests. You’ll find the entire source for the TitleListGlobalPooledServlet in Listing 7.11. LISTING 7.11 import import import import import
import ConnectionPool.*; public class TitleListGlobalPooledServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); }
7 SERVLETS, JDBC, & INTER-SERVLET COMMUNICATIONS
// Get a reference to the ConnectionPool from the Global // ServletContext pool =(ConnectionPool) getServletContext().getAttribute(“CONNECTION_POOL”);
128
Servlet Fundamentals PART I
LISTING 7.11
Continued
//Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // If we get a GET request, pass the request/response to // the doPost() method doPost(request, response); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“\n\n
”); Connection con = null; ConnectionPool pool = null; try {
// Get a reference to the ConnectionPool from the Global // ServletContext pool =(ConnectionPool) getServletContext().getAttribute(“CONNECTION_POOL”); // Get a connection from the ConnectionPool con = pool.getConnection(); if ( con != null ) { // Create the statement Statement statement = con.createStatement(); // Use the created statement to SELECT the DATA // FROM the Titles Table. ResultSet rs = statement.executeQuery(“SELECT * “ + “FROM Titles”);
Servlets, JDBC, and Inter-Servlet Communications CHAPTER 7
LISTING 7.11
129
Continued
// Iterate over the ResultSet while ( rs.next() ) { out.println(“
”); // get the id, which is an int out.println(“
” + rs.getInt(“title_id”) + “
”); // get the name, which is a String out.println(“
” + rs.getString(“title_name”) + “
”);
// get the price, which is a Float out.println(“
” + rs.getFloat(“price”) + “
”); // get the Quantity, which is a Integer out.println(“
” + rs.getInt(“quantity”) + “
”); // get the Type, which is a Integer out.println(“
” + rs.getInt(“type_id”) + “
”); // get the Category, which is a Integer out.println(“
” + rs.getInt(“category_id”) + “
”); out.println(“
”); } // Close the ResultSet rs.close(); out.println(“
// get the rating, which is a String out.println(“
” + rs.getString(“rating”) + “
”);
7
130
Servlet Fundamentals PART I
LISTING 7.11
Continued
pool.releaseConnection(con); } out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “TitleListGlobalPooledServlet Information”; } }
To see how your new servlet works, load the following URL into your browser: http://yourserver/djs/servlet/TitleListGlobalPooledServlet
Summary This chapter covered the basics of the JDBC. I discussed setting up the JDBC-ODBC Bridge and how to load JDBC drivers. You took a look at the most common SQL statements and how to execute them using the JDBC. You then merged the JDBC with the servlets and performed some basic queries. Finally, you looked at some ways to optimize the use of JDBC in servlets. You did this by using a connection pool and inter-servlet communications. At this point, you should be able to create your own servlet that can access a database using either a straight JDBC connection or a connection pool. You should understand how to create and execute basic SQL statements. You should also understand and be able to use the ServletContext for inter-servlet communications. In the next chapter we will take a look at JavaMail and how we can incorporate JavaMail into servlets.
CHAPTER
Servlets and JavaMail
8
IN THIS CHAPTER • JavaMail and Internet E-mail • Preparing to Use JavaMail • A JavaMail Example
132
133
133
• Using JavaMail in a Servlet
137
132
Servlet Fundamentals PART I
JavaMail and Internet E-mail Traditionally when you needed to interact with a mail server from within code, you encountered a messy collection of socket code containing a lot of string parsing. The code would have to send a request to the server, wait for the response, and then break down the response to parse the necessary information. The JavaMail API has provided a clean and easy-to-use Java interface to design and implement messaging and Internet e-mail solutions. Internet e-mail is comprised of several standards detailing the format and makeup of a message that is to be sent across the Internet. Standards, as well as some proposed standards, dictate how Internet e-mail services handle the messages.
JavaMail Services The two types of services that JavaMail offers are the transport and store services. The transport service has several jobs, but we will simply think of it as the service that takes our message and sends it to the recipient. The message can make several stops along the way, but the intricacies of these stops are not within the scope of this book. The second type of service that a JavaMail system deals with is the store service. The store manipulates the persistent storage of messages. The storage of messages is done in what most of us know as mailboxes: for example, your inbox. JavaMail refers to these mailboxes as folders because it is possible for one folder to contain other folders, messages, or both. The physical structure of the folders on a mail server depends on the mail server used to create and manage them. So, to put it simply, a store service allows you to read and manipulate your folders and messages. Store and transport are generic terms used by the JavaMail API to refer to the protocols that actually implement these services. In the case of Internet e-mail, the most widely used transport protocol is the Simple Mail Transfer Protocol (SMTP). The most widely used protocols that implement the store service are the Post Office Protocol (POP3) and Internet Message Access Protocol (IMAP4). JavaMail provides you with an interface to a messaging system. For it to be useful, you also require service providers that implement the JavaMail API. Packaged with the JavaMail API, Sun Microsystems supplies you with both an SMTP and an IMAP service provider. A POP provider can be downloaded through Sun. These providers are the companies’ implementations of the JavaMail API, designed to interact with each of the different protocols.
Servlets and JavaMail CHAPTER 8
133
NOTE Anyone can write his own implementation of the JavaMail API, to interact with these or other protocols. The document titled “The JavaMail Guide for Service Providers” is packaged with the JavaMail archive and specifies how to develop and package a service provider.
Preparing to Use JavaMail Before you get started using JavaMail, you probably want to know what you will need to use the JavaMail API, and where to locate it. The JavaMail API can be downloaded from http://www.javasoft.com/products/javamail/index.html
The archive you will get contains the JavaMail API jar file, all of the javadoc files, the JavaMail Specification in PDF format, the guide for service providers in PDF format, and a decent collection of demo code with documentation.
http://www.javasoft.com/beans/glasgow/jaf.html
This archive contains a collection of files similar to the JavaMail archive. The two important files you will need are mail.jar and activation.jar. Both of these archives must be added to your classpath before you can begin working with JavaMail.
A JavaMail Example Let’s walk through a simple example of sending a message using JavaMail.
NOTE The JavaMail API provides an interface to perform many more complex tasks, including sending MIME-encoded attachments with your mail. And, as we discussed earlier, you can retrieve and manipulate messages from your mailboxes. The demo code that accompanies JavaMail gives good examples of some of the other features that you can use. With a little creativity, you are not limited in what you can accomplish.
8 SERVLETS AND JAVAMAIL
JavaMail makes extensive use of the JavaBeans Activation Framework (JAF), so you will also need to download this Java extension. It can be found at
134
Servlet Fundamentals PART I
Listing 8.1 contains the JavaMail example. LISTING 8.1
SimpleSendMessage.java
import java.util.*; import javax.mail.*; import javax.mail.internet.*; import javax.activation.*; public class SimpleSendMessage { public static void main(String[] args) { // Collect the necessary information to send a simple message // Make sure to replace the values for host, to, and from with // valid information. // host - must be a valid smtp server that you currently have // access to. // to - whoever is going to get your email // from - whoever you want to be. Just remember that many smtp // servers will validate the domain of the from address // before allowing the mail to be sent. String host = “server.myhost.com”; String to = “[email protected]”; String from = “[email protected]”; String subject = “JavaMail Rules!”; String messageText = “I am sending a message using the” + “ JavaMail API.\n” + “I can include any text that I want.”; boolean sessionDebug = false; // Create some properties and get the default Session. Properties props = System.getProperties(); props.put(“mail.host”, host); props.put(“mail.transport.protocol”, “smtp”); Session session = Session.getDefaultInstance(props, null); // Set debug on the Session so we can see what is going on // Passing false will not echo debug info, and passing true // will. session.setDebug(sessionDebug); try {
Servlets and JavaMail CHAPTER 8
LISTING 8.1
135
Continued
// Instantiate a new MimeMessage and fill it with the // required information. Message msg = new MimeMessage(session); msg.setFrom(new InternetAddress(from)); InternetAddress[] address = {new InternetAddress(to)}; msg.setRecipients(Message.RecipientType.TO, address); msg.setSubject(subject); msg.setSentDate(new Date()); msg.setText(messageText); // Hand the message to the default transport service // for delivery. Transport.send(msg); } catch (MessagingException mex) { mex.printStackTrace(); } }
In analyzing Listing 8.1, the first topic we must discuss is the Session class. The Session represents a mail session and is typically the first thing that you will set up in code using the JavaMail API. It collects properties and defaults that will be used by different pieces throughout the API. In the following code snippet, you retrieve the system properties, add the JavaMail-specific information to them, and retrieve a default session using them. The properties you use here are just some of the JavaMail-specific attributes that can be used; however, they are the only ones necessary to accomplish sending a simple message: String host = “server.myhost.com”; String to = “[email protected]”; String from = “[email protected]”; String subject = “JavaMail Rules!”; String messageText = “I am sending a message using the” + “ JavaMail API.\nI can include any text that I want.”; boolean sessionDebug = false; // Create some properties and get the default Session. Properties props = System.getProperties();
8 SERVLETS AND JAVAMAIL
}
136
Servlet Fundamentals PART I props.put(“mail.host”, host); props.put(“mail.transport.protocol”, “smtp”); Session session = Session.getDefaultInstance(props, null);
The mail.host environment property specifies the default mail server. In many cases the servers for transport and store are the same machine. However, they can be specified separately if this is not the case. For our purposes it does not matter, because you will only need access to the transport service.
NOTE You will need to change the mail host in the application to use your ISP’s mail host.
Using the mail.transport.protocol property tells the Session what protocol to use as the default transport provider. You specified smtp as the default transport, so the Session now knows that whenever you use a transport, this is the service provider you want. This becomes important later when you actually send the message, because you use a static method in the Transport class to send, and you never specify what type of transport you want to use. In the next code snippet, you create a message and prepare it to be shipped. There is quite a bit more that can take place before a message is sent, but in this case we are only interested in the bare necessities: String to = “[email protected]”; String from = “[email protected]”; String subject = “JavaMail Rules!”; String messageText = “I am sending a message using the JavaMail API.\n” + “I can include any text that I want.”; Message msg = new MimeMessage(session); msg.setFrom(new InternetAddress(from)); InternetAddress[] address = {new InternetAddress(to)}; msg.setRecipients(Message.RecipientType.TO, address); msg.setSubject(subject); msg.setSentDate(new Date()); msg.setText(messageText);
The first thing you might notice is the use of the MimeMessage class. It implements the Message abstract class, and uses certain criteria to make sure the message adheres to the Internet e-mail standards. It formats the message and message headers in the proper MIME
Servlets and JavaMail CHAPTER 8
137
style to be sent over the Internet. (A discussion of the MIME Standard is beyond the scope of this book.) The next several method calls fill the message with the needed information. Addresses used by a MimeMessage are implemented by the InternetAddress class. You will notice that this class is used for both the sender and recipients. Neither the subject nor the content of the message is required to successfully transport the message, but let’s face it, how exciting would it be without them? Now that the Message is ready to be sent, all you have to do is ask your default transport provider to send it for you. The code snippet to accomplish this is simple and looks like this: Transport.send(msg);
That is all there is to sending a simple e-mail using the JavaMail API.
Using JavaMail in a Servlet Next, let’s look at what is necessary to send an e-mail using JavaMail and servlets. For the servlet example, you’ll use an HTML form to submit the mail message and a servlet to parse and send the submitted message. The HTML form can be found in Listing 8.2. MailForm.html
JavaMail Form
To:
From:
SERVLETS AND JAVAMAIL
LISTING 8.2
8
138
Servlet Fundamentals PART I
LISTING 8.2
Continued
Subject
You can see that there is nothing special about this form. You should only notice that the action attribute of the form points to your servlet, found in Listing 8.3. LISTING 8.3
public class MailServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } public void doGet(HttpServletRequest request, HttpServletResponse response)
Servlets and JavaMail CHAPTER 8
LISTING 8.3
139
Continued
throws ServletException, IOException { doPost(request, response); } public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Create some properties and get the default Session. String host = “YOURMAILHOST”; String to = request.getParameter(“to”); String from = request.getParameter(“from”); String subject = request.getParameter(“subject”); String messageText = request.getParameter(“body”); boolean sessionDebug = false; response.setContentType(“text/html”); PrintWriter out = response.getWriter();
Properties props = System.getProperties(); props.put(“mail.host”, host); props.put(“mail.transport.protocol”, “smtp”); Session mailSession = Session.getDefaultInstance(props, null); // Set debug on the Session so we can see what is going on // Passing false will not echo debug info, and passing true // will. mailSession.setDebug(sessionDebug); // Instantiate a new MimeMessage and fill it with the // required information. Message msg = new MimeMessage(mailSession); try { msg.setFrom(new InternetAddress(from)); InternetAddress[] address = {new InternetAddress(to)}; msg.setRecipients(Message.RecipientType.TO, address); msg.setSubject(subject);
8 SERVLETS AND JAVAMAIL
out.println(“”); out.println(“MailServlet”);
140
Servlet Fundamentals PART I
LISTING 8.3
Continued msg.setSentDate(new Date()); msg.setText(messageText); // Hand the message to the default transport service // for delivery. Transport.send(msg); out.println(“”); out.println(“Mail was sent to “ + to); out.println(“ from “ + from); out.println(“ using host “ + host + “.”);
As you look over the MailServlet, you will notice only a few differences from the JavaMail application in Listing 8.1. The first change is the addition of the code to get the necessary request parameters, which is included in the following snippet: String String String String
to = request.getParameter(“to”); from = request.getParameter(“from”); subject = request.getParameter(“subject”); messageText = request.getParameter(“body”);
The only other notable change is that, instead of referring to the Session with the variable name session, we have changed the variable name to mailSession. To see this example in action, copy the HTML file and the MailServlet into your <SERVER_ROOT>/djs/ Web application and load the following URL into your browser: http://localhost/djs/MailForm.html
You should see a page similar to Figure 8.1.
Servlets and JavaMail CHAPTER 8
FIGURE 8.1
NOTE You will need to change the mail host in the servlet to use your ISP’s mail host.
Now fill in the appropriate form data and click the Submit button. You should see a response that tells you who received the mail, who sent the mail, and the mail host. To test the example, it is probably best to send mail to yourself, so you can check the message.
Summary In this chapter, we covered what JavaMail is and how you can use it. We also looked at how you can use JavaMail with servlets. In the next chapter we are going to take a look at servlet security.
8 SERVLETS AND JAVAMAIL
Output of the MailForm.html.
141
CHAPTER
Servlet Security
9
IN THIS CHAPTER • Introduction to Security • Roll Your Own
144
144
• Basic Authentication • Digest Authentication
148 148
• Secure Sockets Layer (SSL)
149
144
Servlet Fundamentals PART I
Introduction to Security The need for security has increased as the Internet’s traffic has increased. Every day more people are transferring their credit card numbers or other confidential information over the Internet. If these transfers are not secured, they are exposed to just about any evildoer with a network connection. In this chapter, we will cover some of the more common security methods from rolling your own to Secure Sockets Layer (SSL). One of the key benefits of servlets is that they inherit the security of the server, without any additional effort on your part. They are protected because they are resources of the server.
Roll Your Own The first security method we will discuss is probably the worst method, but at the same time probably safe enough if you are protecting non-vital information. In your homegrown version of security, you are going to use a basic form to query the user for an ID and password. When you have the request, parse off the ID/password combination and do a lookup to make sure that the user is approved for access. When you have approval, add the ID to the user’s HttpSession object as proof of approval for future transactions. Listing 9.1 contains the servlet code for this example. LISTING 9.1 import import import import
public class RollYourOwnSecurityServlet extends HttpServlet { public void init(ServletConfig config) throws ServletException { super.init(config); } private boolean validateUser(String id, String password) { // This is a dummy method. If you really implement // a method like this, you will need to store id/password // combinations somewhere else and they should also be // encrypted. return true;
Servlet Security CHAPTER 9
LISTING 9.1
145
Continued
} //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get the current session HttpSession session = request.getSession(true); // Get the id stored in the session after approval String id = (String)session.getAttribute(“id”); response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“Roll Your Own”); out.println(“”); out.println(“Hello “ + id + “ how can we help you today?”); out.println(“”); out.close(); } //Process the HTTP Post request public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
HttpSession session = null; // Check to see if this is a valid id/password combination. boolean valid = validateUser(id, password); // If it is valid, get the session // and add the id for future transactions if ( valid == true ) { session = request.getSession(true); session.setAttribute(“id”, id);
9 SERVLET SECURITY
// Get the id/password combination from the request String id = request.getParameter(“id”); String password = request.getParameter(“password”);
146
Servlet Fundamentals PART I
LISTING 9.1
Continued
} response.setContentType(“text/html”); PrintWriter out = response.getWriter(); out.println(“”); out.println(“Roll Your Own”); out.println(“”);
if ( valid == true ) { // Successful validation, redirect to the GET method // of this servlet response.sendRedirect(“/djs/servlet/” + “RollYourOwnSecurityServlet”); } else { out.println(“We don’t know who you are please leave!”); } out.println(“”); out.close(); } //Get Servlet information public String getServletInfo() { return “RollYourOwnSecurityServlet Information”; } }
This is a simple example of implementing your own security model. The first step is to display the login form when the user accesses the Web site. The HTML source for the login screen is in Listing 9.2. LISTING 9.2 <TITLE> Login Screen
LoginScreen.html
Servlet Security CHAPTER 9
LISTING 9.2
147
Continued
Please Login User Id: Password:
Load the HTML file into your browser. You should see a screen similar to Figure 9.1.
9 SERVLET SECURITY
FIGURE 9.1 The login screen.
148
Servlet Fundamentals PART I
When the user submits her ID/password, it is parsed by the doPost() method of the servlet and checked against a database of valid users (in the example, everybody is approved). When the user is validated, her ID is added to her HttpSession object and she is redirected to the servlet’s doGet() method. Now future requests only need to check for the user’s ID in the session to verify that she has been properly validated.
Basic Authentication Basic authentication is a challenge/response security model. It is based on the fact that the client must authenticate itself with a user ID/password combination for each resource it wants to access. A protected resource could be a directory, a servlet, or even a specific page. The steps involved in authenticating a client are as follows: 1. The client makes an unauthorized request for a protected resource. 2. The server responds with a challenge to authenticate. 3. The client sends a username/password combination (separated by a colon) within a base64-encoded string. 4. The server decodes the string containing the user ID/password combination and looks in its database for a match. 5. If the server finds a match, it grants access to the requested resource. When you deploy your applications to a commercial level server you will need to consult the server documentation to configure protected resources and users.
Digest Authentication Digest authentication, like basic authentication, is based on the challenge/response model. In fact, digest authentication was created as a direct result of basic authentication’s shortcomings. The main difference between basic and digest authentication is that the digest scheme never sends the user’s password across the network. It instead sends a digest representation of the password.
NOTE Currently there is no support for digest authentication.
Servlet Security CHAPTER 9
149
Two steps are involved in creating a digest value. The first is to apply a mathematical formula to the ID/password combination. The second is to permute the mathematical calculation with a nonce. This makes each request more secure because the digest is unique to each request.
NOTE A nonce is a server-specific data string that is uniquely generated each time a protected resource is requested.
Secure Sockets Layer (SSL) The Secure Sockets Layer (SSL) is an authentication protocol used to send encrypted information over the Internet. It was originally developed by Netscape to transfer secure information between its Web browser and Web server products. Since then, it has been widely adopted and is now one of the most popular methods for sending encrypted information over the Internet. SSL is implemented as a layer between the TCP/IP protocol and the application layer. The following steps are involved in sending secure messages using the SSL protocol: 1. A client makes a request for a resource located on a secure site. 2. The server signs its public key with its private key and sends the public key back to the client. 3. The client takes the returned public key and makes sure the appropriate owner signed it. 4. The client verifies that the key was signed by an approved certificate authority.
6. The server optionally compresses the information requested by the client. 7. The server encrypts the message using the key created in step 5. 8. The server transmits the message to the client. 9. The client receives the message. 10. The message is decrypted using the same key created in step 5. 11. The message is decompressed if necessary and delivered to the client. 12. All further requests restart at step 6, using the same public key. The first 5 steps make the SSL protocol a very secure way to send information across the Internet. The only real drawback of the SSL protocol is the performance degradation taken during the public key encryption and decryption required during these first five steps.
9 SERVLET SECURITY
5. The client creates a key that is encrypted with the public key of the server and sends the newly constructed key back to the server.
150
Servlet Fundamentals PART I
The SSL protocol is very involved and is beyond the scope of this book. If you have further interest, I suggest getting the latest specification from the Netscape Web site at http://www.netscape.com/eng/ssl3/3-SPEC.HTM#7-1.
Summary In this chapter, we briefly discussed some of the more common security protocols. You saw how you can roll your own security, a technique that really isn’t secure. We covered basic and digest authentication and their problems. Finally, we discussed the Secure Sockets Layer protocol, which is a very secure and widely used protocol. In the next chapter, you will learn about the basics of XML and servlets.
CHAPTER
Servlets and XML
10
IN THIS CHAPTER • XML and Java
153
• Using XML in a Servlet
159
152
Servlet Fundamentals PART I
The Extensible Markup Language, or XML, is a metalanguage for creating markup languages used to describe structured data. XML is a self-describing language, composed of tags and values. It is often used to describe objects that are passed in messages between applications. An example of a simple XML document is included in Listing 10.1. LISTING 10.1
item.xml
33445 Austin Powers: International Man of Mystery 19.95 56
The first line of this snippet describes a processing instruction that states that this XML document is based on version 1 of the XML specification. Processing instructions begin with a lessthan sign and a question mark (). The rest of this document describes an ITEM object with four attributes: ID, DESCRIPTION, PRICE, and QUANTITY. Each of these attributes is contained in an open and closed pair. You should notice how the hierarchy of the object is described in a container-like fashion, wherein the attributes of the ITEM are between the ITEM’s open and closing tags. This shows the parent/child relationship of the ITEM object. All XML documents can be viewed as navigable tree structures. Figure 10.1 shows the standard structure of an XML document. Document Root
ITEM
ID
DESCRIPTION
PRICE
QUANTITY
FIGURE 10.1 The XML document tree structure.
Servlets and XML CHAPTER 10
153
Although this is hardly a complete definition of XML, which is well beyond the scope of this book, it is complete enough for us to see in this chapter how XML and servlets can be used together.
XML and Java Now that you understand XML basics, let’s take a look at how we can use XML and Java together. Many Java parsers have been developed to interact with XML documents. The three most common have been developed by Sun Microsystems, IBM, and Microsoft. For our example, you will use Sun’s Java API for XML Processing (JAXP), which can be downloaded from the following URL: http://java.sun.com/xml/download.html
Follow the installation instructions for your platform, including adding the jaxp.jar and the parser.jar files to your classpath. Sun’s API is composed of two core components, the Document Object Model (DOM) and the Simple API for XML (SAX API). The DOM is a tree-based API, and the SAX is an eventbased API. For our examples, you will use the SAX API.
Using the SAX API As we stated earlier, the SAX API is an event-based API. This means that, as the parser parses the XML document, it triggers certain events based upon encountered elements of the document. To see exactly how this works, let’s take a look at Listing 10.2. LISTING 10.2
// Check for the appropriate usage if ( argv.length != 1 ) {
SERVLETS AND XML
public static void main (String argv []) throws IOException {
10
154
Servlet Fundamentals PART I
LISTING 10.2
Continued
System.err.println (“USAGE: java XMLTest filename”); System.exit(1); } try { // Get the path to the file String xmlResource = “file:” + new File(argv[0]).getAbsolutePath(); Parser parser; // Get an instance of the SAXParserFactory SAXParserFactory spf = SAXParserFactory.newInstance(); // Get a SAXParser instance from the factory SAXParser sp = spf.newSAXParser(); // Create an instance of our HandlerBase SAXHandler handler = new SAXHandler(); // Set the Document handler to call our SAXHandler when // SAX event occurs while parsing our XMLResource sp.parse(xmlResource, handler); // After the resource has been parsed get the resulting table Hashtable cfgTable = handler.getTable(); // Print the config settings that we are interested in. System.out.println(“ID == “ + (String)cfgTable.get(new String(“ID”))); System.out.println(“DESCRIPTION == “ + (String)cfgTable.get(new String(“DESCRIPTION”))); System.out.println(“PRICE == “ + (String)cfgTable.get(new String(“PRICE”))); System.out.println(“QUANTITY == “ + (String)cfgTable.get(new String(“QUANTITY”))); } catch (Exception e) { e.printStackTrace(); } System.exit(0); } }
Servlets and XML CHAPTER 10
155
As you look over this document, you can see that its main function is to take an XML file from the command line, parse it, and print out the elements that you are looking for. The first thing you should notice is the following section: Parser parser; // Get an instance of the SAXParserFactory SAXParserFactory spf = SAXParserFactory.newInstance(); // Get a SAXParser instance from the factory SAXParser sp = spf.newSAXParser();
In this section, you are creating a reference to a parser that will be used to actually parse the XML document. To do this you use the static factory method SAXParserFactory.newInstance(), which obtains a new instance of a SAXParserFactory. After you have an instance of a SAXParserFactory, you create a new SAXParser, by calling the SAXParserFactory.newSAXParser() method. The SAXParser defines the API that wraps an org.xml.sax.Parser implementation class. By using this class, an application can parse content using the SAX API. The next section we need to examine is // Create an instance of our HandlerBase SAXHandler handler = new SAXHandler();
This section of code creates an instance of your event handler SAXHandler. To capture events invoked by the parser, you need to either create a class that implements the org.xml.sax.DocumentHandler interface or extend the class org.xml.sax.HandlerBase, which implements default handlers defined by the DocumentHandler interface. For our example, you have extended HandlerBase so you only have to implement the methods you are interested in handling. This is much like the event handlers of the AWT. After you have an instance of your event handler, you can start the parser. The snippet for this is // Set the Document handler to call our SAXHandler when // SAX event occurs while parsing our XMLResource sp.parse(xmlResource, handler);
The SAXParser.parse() method takes an InputSource that contains an XML stream and a reference to your handler. As the parser parses your XML document, it will trigger events that will be handled by your SAXHandler, which can be found in Listing 10.3. SAXHandler.java
import java.io.*; import java.util.Hashtable;
SERVLETS AND XML
LISTING 10.3
10
156
Servlet Fundamentals PART I
LISTING 10.3
Continued
import org.xml.sax.*; public class SAXHandler extends HandlerBase { private Hashtable table = new Hashtable(); private String currentElement = null; private String currentValue = null; // Simple Accessor for the Hashtable of parsed values public void setTable(Hashtable table) { this.table = table; } // Simple Accessor for the Hashtable of parsed values public Hashtable getTable() { return table; } // Called when a new element is encountered public void startElement(String tag, AttributeList attrs) throws SAXException { // hold onto the new element tag, that will be placed in // our Hashtable when matching character data is encountered. currentElement = tag; } // Called when character data is found inside an element public void characters(char[] ch, int start, int length) throws SAXException { // create a String containing the characters // found in the element currentValue = new String(ch, start, length); } // Called when the end of element is encountered public void endElement(String name) throws SAXException { // Make sure we have a matching closing element if ( currentElement.equals(name) ) {
Servlets and XML CHAPTER 10
LISTING 10.3
157
Continued
// Put the element/value pair into the Hashtable table.put(currentElement, currentValue); } } }
As you look over this handler, you will notice that there are only five methods, two of which are only accessors to a Hashtable. The other three methods represent the events you are interested in responding to. Each of these methods will be discussed in the following sections. The first method overridden is startElement(), which is shown here: // Called when a new element is encountered public void startElement(String tag, AttributeList attrs) throws SAXException { // hold onto the new element tag, that will be placed in // our Hashtable when matching character data is encountered. currentElement = tag; }
This method is called whenever the parser encounters a new element in the XML document. A new element would be a starting tag similar to . When your overridden method is called, you simply hold onto the passed-in tag representing the element name. The next method you override is the characters() method. The overridden method is shown here: // Called when character data is found inside an element public void characters(char[] ch, int start, int length) throws SAXException { // create a String containing the characters // found in the element currentValue = new String(ch, start, length); }
This method is invoked when the parser encounters character data inside an element. An example of this would be the value 33445 found in the element 33445. When your overridden method is called, you create a string from the character array and hold onto the string for later use.
SERVLETS AND XML
The last method you override from the HandlerBase class is the endElement() method, which is included in the following code snippet:
10
158
Servlet Fundamentals PART I // Called when the end of element is encountered public void endElement(String name) throws SAXException { // Make sure we have a matching closing element if ( currentElement.equals(name) ) { // Put the element/value pair into the Hashtable table.put(currentElement, currentValue); } }
The endElement() method is the final event handler that we are concerned with. It is called whenever the end of an element is encountered. If we use the same example from the startElement() method, then endElement() would be invoked when the tag was encountered. The overridden endElement() method takes the passed-in name and compares it with the current element being processed. If they match, the endElement() method puts the element and its character data into the Hashtable. Now that you understand what happens as each event is triggered, we will return to our XMLTest application. The remainder of our application is listed in the following code snippet: // After the resource has been parsed get the resulting table Hashtable cfgTable = handler.getTable(); // Print the config settings that we are interested in. System.out.println(“ID == “ + (String)cfgTable.get(new String(“ID”))); System.out.println(“DESCRIPTION == “ + (String)cfgTable.get(new String(“DESCRIPTION”))); System.out.println(“PRICE == “ + (String)cfgTable.get(new String(“PRICE”))); System.out.println(“QUANTITY == “ + (String)cfgTable.get(new String(“QUANTITY”)));
As you can see, after the parser is finished parsing, the application calls your handler’s getTable() method. This method returns a Hashtable containing the elements and their text data that was parsed from the XML file. The final steps you perform are printing the elements you are interested in from the parsed file. To see this in action, compile and build the handler and application and then execute the application with the XML file we described earlier. Your command line should be similar to the following: java XMLTest item.xml
Servlets and XML CHAPTER 10
159
The output should look similar to the following: ID == 33445 DESCRIPTION == Austin Powers: International Man of Mystery PRICE == 19.95 QUANTITY == 56
Using XML in a Servlet Now let’s take the previous example and incorporate it into a servlet. The only difference is that the XML file that you are parsing has been hard coded into the servlet; therefore, you will need to replace the <SERVER_ROOT> with the location of your installed Tomcat server. The better route would be to use an init parameter, but I want to keep the example as simple as possible. Listing 10.4 contains our servlet example. LISTING 10.4
public class XMLServlet extends HttpServlet { private static final String CONTENT_TYPE = “text/html”; private String moviefile = “<SERVER_ROOT>\\djs\\item.xml”; public void init(ServletConfig config) throws ServletException { super.init(config); }
doPost(request, response);
10 SERVLETS AND XML
public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException {
160
Servlet Fundamentals PART I
LISTING 10.4
Continued
} public void doPost(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { response.setContentType(CONTENT_TYPE); PrintWriter out = response.getWriter(); // Load the movie file File file = new File(moviefile); FileReader reader = new FileReader(file); Parser parser; out.println(“”); out.println(“XMLServlet”); out.println(“”); try { // Get an instance of the SAXParserFactory SAXParserFactory spf = SAXParserFactory.newInstance(); // Get a SAXParser instance from the factory SAXParser sp = spf.newSAXParser(); // Create an instance of our HandlerBase SAXHandler handler = new SAXHandler(); // Set the Document handler to call our SAXHandler when // SAX event occurs while parsing our XMLResource sp.parse(new InputSource(reader), handler); // After the resource has been parsed get the resulting table Hashtable cfgTable = handler.getTable(); out.println(“
”); out.println(“XML Item”); // Print the config settings that we are interested in. out.println(“
ID
” + “
” + (String)cfgTable.get(new String(“ID”)) + “
”); out.println(“
DESCRIPTION
” + “
” +
Servlets and XML CHAPTER 10
LISTING 10.4
161
Continued (String)cfgTable.get(new String(“DESCRIPTION”)) + “
As you can see, there is really very little difference in the application code and the servlet code. The only noticeable differences are the way you load the XMLResource and the way you output the results.
http://yourserver/djs/servlet/XMLServlet
You should see a page similar to Figure 10.2.
10 SERVLETS AND XML
To see this servlet run, you will need to copy the SAXHandler class file to the <SERVER_ROOT>/djs/WEB-INF/classes/ directory, copy the item.xml file to the <SERVER_ROOT>/djs/ directory, and build XMLServlet. Then load the following URL into your browser:
162
Servlet Fundamentals PART I
FIGURE 10.2 Output from XMLServlet.
Summary This chapter covered the basics of XML. We covered how to use Sun’s SAX parser, and we also looked at an example of how you would incorporate XML and servlets. In the next chapter we will talk about servlets and the Lightweight Directory Access Protocol (LDAP).
CHAPTER
Servlets and LDAP
11
IN THIS CHAPTER • A Brief Discussion of Directories • LDAP • JNDI
164
165 166
• Using JNDI to Access LDAP
166
• Accessing LDAP from a Servlet
184
164
Servlet Fundamentals PART I
A Brief Discussion of Directories A directory provides a method of persistence where information can be organized and searched quickly. This might sound similar to the relational databases that you are used to; however, there are some fundamental differences. The most noticeable difference is the way the stored information is organized. In a relational database, information is stored in tables that are interconnected using foreign keys that reference a related table. The structure of the information stored in a directory is quite different. The information is stored in more of a hierarchy that provides a logical relationship between the objects. The informational structure will look something like Figure 11.1. o = Airius.com
ou = Groups
ou = People
cn = Tad Hans sn = Hans givenName = Tad uid = thans mail = [email protected] telephoneNumber = (123) 432-6581 pager = (123) 239-0911
cn = Bob Smith sn = Smith givenName = Bob uid = bsmith mail = [email protected] telephoneNumber = (800) 123-4567
FIGURE 11.1 Organization of the data stored in a directory.
The following notes summarize the other differences between a directory and a relational database: • Directories are more suitable for environments where the data is being read quite a bit and is not being modified often. • Directories generally come with a preexisting schema. • Directories do not support complex joining during searches like a relational database. • Directories have better support for substring searches and for searching on similarities. • Directories are usually quicker and easier to configure and manage than relational databases. They are generally less expensive also.
Servlets and LDAP CHAPTER 11
Attributes
Each attribute provided for an object in the schema is used for a specific purpose. For example, in Figure 11.1, the attribute cn refers to the common name of the object. You will see this attribute in many of the objects from all directory providers.
Distinguished Names Another important topic to discuss is how to refer to a specific point in the directory structure. Every object or point in the directory structure can be located using its Distinguished Name (DN). The DN is very much like the primary key from a relational database. The DN for an object is made up of the path through the tree, listing the objects beginning at the root. For example, the DN for the Tad Hans object in Figure 11.1 would look like this: uid=thans, ou=People, o=airius.com
This DN is actually used in the previous example to place Tad in the Managers group. It is also possible to have a relative DN, or RDN. Based on the DN above, uid=thans
is an RDN from ou=People, o=Airius.com
By prepending the RDN onto the base, you have the full DN for the object. This will become more apparent when we begin to do searches and begin each search from a specific base. One of the first uses for directories was to store phone book information. This scenario is what the examples throughout this chapter will display.
LDAP With an understanding of a directory, it is now time to learn how to access the information stored within the directory. Each vendor of a directory server will usually provide a proprietary API that can be used to access a directory. They can also provide the capability to access the directory server using one or more of several other available protocols.
11 SERVLETS AND LDAP
You will notice in Figure 11.1 that all of the information is stored in an object based on attribute names. The possible attribute names are based on the object schema. This is similar to column names for a table in a relational database. When using a directory server, there is generally a preexisting schema that will handle your data with little or no change. In many cases, this directory structure and schema is standardized across different directory vendors. This is different from using a database because you are not required to design and define the necessary schema.
165
166
Servlet Fundamentals PART I
Lightweight Directory Access Protocol (LDAP) is a standard protocol that can be used to access a directory structure. Currently, it is the most popular protocol available. For this reason, many directory vendors provide access to their server through LDAP. Any of the LDAP-compliant servers can be accessed using LDAP, and to the client can seem to be working the same way. This does not mean that they store and handle the information the same way internally, only that they will return it to the LDAP client in a specific manner.
JNDI The Java Naming and Directory Interface (JNDI) provides a standard API for interacting with naming and directory services. JNDI allows a Java client to interact with several different directory protocols using this standard API. JNDI places another layer of abstraction on top of the directory protocol. This is accomplished by using the JNDI API with the appropriate service provider plugged in to talk to your directory API. By doing this, the client Java code only needs to be aware of the JNDI API. By plugging in different service providers, your client can switch from LDAP to Novell’s NDS, for example, without changing the client code. This is a very powerful design pattern that is widely used throughout Java. Another example is Java Database Connectivity (JDBC), which provides a standard API to communicate with many databases. It is because of this flexibility, and the fact that JNDI is a standard API, that JNDI is the proper choice for communicating with LDAP servers from within Java code.
Using JNDI to Access LDAP With a basic understanding of LDAP and JNDI, we can take a look at how to use the two together to access information stored in a directory. In this section we will take a look at searching, adding, modifying, and deleting objects stored in an LDAP server. You will develop two utility classes that can be used with any LDAP server. The first class will contain all of the code to perform the LDAP operations. This class will be named LDAPManager. Sections of this class will be revealed in pieces and explained; the full listing for LDAPManager.java is found later in the chapter in Listing 11.2. The examples in this chapter were developed using Netscape Directory Server (NDS). To work through the examples, you’ll need to download, install, and configure NDS as described in the following section.
Servlets and LDAP CHAPTER 11
Installing Netscape Directory Server http://www.iplanet.com
Begin here and work your way to the downloads page. Download the NDS version 4.12 that is correct for your platform. The download will give you an executable file that will install the Netscape server. When you run the installation, first you will accept the licensing agreement. Then select the installation of Netscape Servers from the Setup screen. Accept all of the default options during the installation. There are several screens where you must enter information about your computer and about how the application should be configured. The first screen where you will need to enter information will appear just as in Figure 11.2.
FIGURE 11.2 Input of computer information.
Three input areas are on this dialog. The first is Server Identifier. Type your computer’s name here. The second is the port number. Allow this to default to the standard LDAP port of 389. The last is for the Suffix for your server. For all of our examples we have used our company’s name; so type o=virtuas.com.
11 SERVLETS AND LDAP
To download Netscape, direct your browser to the following:
167
168
Servlet Fundamentals PART I
The next screen will ask you to enter a password to access the admin account of for the Admin Server. Use something you will remember here. The setup program will then ask you to enter the Administration Domain for your server. Once again, type virtuas.com. At this point you will be asked for a password for the server’s Directory Manager. The screen accepting this information will look just like Figure 11.3.
FIGURE 11.3 Input of Directory Manager password.
To enable all of the examples developed in this chapter, you must use directory as the password for the Directory Manager. Type this into both text boxes, and click Next. From here through the completion of installation, accept all of the default values. On the final screen, click Finish and you are ready to go.
Connecting Only a little information is required to make an initial connection to the LDAP server. This connection comes in the form of the Context class that is part of the JNDI package. All of the necessary information could be retrieved from a properties file, however for simplicity you will just provide the information directly in the manager class. In the following code snippet, you collect the necessary information:
Servlets and LDAP CHAPTER 11 String factory = “com.sun.jndi.ldap.LdapCtxFactory”; String serverName = “yourServerName”; int port = 389; String securityAuthentication = “simple”; String dirManager = “cn=Directory Manager”; String dirManagerPw = “directory”;
All of these attributes have matching accessor methods so their values can be changed however you initialize them with some default values. The factory specifies the LDAP Context factory class that you would like to use to bind your Contexts. The serverName is the host machine of the LDAP server. The standard port used by an LDAP server is port 389. The other three attributes deal with authenticating with the LDAP server upon binding. You have the username and password to bind with, and the authentication method. The standard setup of a LDAP server allows anonymous connections. This means that if there is no password specified the server tries to bind the client anonymously. Most servers will only allow searching anonymously. To change the data in some way requires a valid username and password. You are hard-coding a username and password into the class as an example, however this would not provide any security for an actual application. The following code contains a method to collect all of the information needed for binding: protected Hashtable getEnvironment() { Hashtable env = new Hashtable(); // generate LDAP host URL StringBuffer url = new StringBuffer(“ldap://”); url.append(serverName).append(“:”).append(port); // set Context Factory class env.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY, factory); // set host URL env.put(javax.naming.Context.PROVIDER_URL, url.toString()); // Only set authentication information if there is a username // present if ((dirManager != null) && (dirManager.trim().length() > 0)) { env.put(javax.naming.Context.SECURITY_AUTHENTICATION, securityAuthentication); env.put(javax.naming.Context.SECURITY_PRINCIPAL, dirManager); env.put(javax.naming.Context.SECURITY_CREDENTIALS, dirManagerPw); } return env; }
To actually bind to the LDAP server you need to create a Context based on these criteria. Because you are dealing with some sort of directory server, more specifically an LDAP server, you use a more specific Context called a DirContext. The DirContext includes some methods and functionality specifically suited to binding to and manipulating a directory server. Here is how you create a new Context to bind to your LDAP server: DirContext ctx = new InitialDirContext(env);
The Hashtable that was generated in the getEnvironment() method is what is passed into the constructor for the InitialDirContext. You now have a Context that is properly bound to the LDAP server. It is ready to perform many different functions on the data stored in the server.
Searching the LDAP Server Searching for information in an LDAP server is probably the most important function because this is what LDAP servers are made for—storing a lot of information that is searched often. To search an LDAP server you need to know where in the directory tree you would like to begin the search. You need to know how far down the tree you are going to search from there. Finally you need to know the criteria you are searching on. The search base can be any valid point in the directory tree, and you specify this location using its DN. You can begin your search at the base of the tree by specifying o=virtuas.com as your search base. You can also begin the search in the People branch by specifying ou=People,o=virtuas.com instead. From this beginning point, there are three different depths for the search: • •
OBJECT_SCOPE—The
shallowest search; searches just the named object.
ONELEVEL_SCOPE—Searches
only objects that exist one level directly below the named
point in the tree. •
SUBTREE_SCOPE—Searches
all objects below the starting point. This is the default that you specify in your LDAPManager.
After you have decided how the search will be accomplished, you must specify the criteria you want to use to select the objects. Naming the criteria is done by using a string to filter the objects. For example, you could search for all objects where uid=jgoodwill. The necessary attributes and method used to search your LDAP server look like this: protected String searchBase = null; protected int searchScope = SearchControls.SUBTREE_SCOPE;
Servlets and LDAP CHAPTER 11 public Vector search(String[] returnAttributes, String searchFilter) throws NamingException {
// bind to the LDAP server. DirContext ctx = getInitialContext(getEnvironment()); // perform the search on the LDAP server. results = ctx.search(searchBase, searchFilter, ctls); while ((results != null) && (results.hasMore())) { // get the next set of results from the search. SearchResult sr = (SearchResult)results.next(); // get all of the attributes for this object. Attributes attributes = sr.getAttributes(); NamingEnumeration attEnum = attributes.getAll(); // create an LDAPObject to hold the results. LDAPObject tmpObj = new LDAPObject(); // set the Distinguished Name for // the relative dn and the searcb tmpObj.setDn(sr.getName() + “,” + // iterate through the attributes while (attEnum.hasMore()) {
the object. Append base together. searchBase); setting them in the LDAPObject
// get the next attribute Attribute att = (Attribute)attEnum.next(); // set the attribute in the LDAPObject tmpObj.setAttribute(att.getID(), att.get()); } // add the object to the list of return objects ldapObjects.add(tmpObj); } return ldapObjects; }
You have included the search base as an attribute to the class instead of as a parameter for the search method. This is because it is common to set the search base and perform several searches from there. This eliminates the need to set the search base each time you search.
11 SERVLETS AND LDAP
Vector ldapObjects = new Vector(); SearchControls ctls = new SearchControls(); ctls.setReturningAttributes(returnAttributes); ctls.setSearchScope(searchScope); NamingEnumeration results = null;
171
172
Servlet Fundamentals PART I
The next important piece of information is the search scope. This also is an attribute to the class, and is defaulted to perform subtree searches. The search method requires two pieces of information. The first is an array of strings that specify which attributes should be returned from the search. Here you must provide exactly which attributes should be returned for each object that meets your search criteria. The second parameter to the search method is the search filter for this particular search. After you have results from your search, you transfer them into a container object called LDAPObject. This is not a standard object, just a simple container that makes it easier to return the information to the client. The full listing of this class is in Listing 11.1. LISTING 11.1
LDAPObject.java
import java.util.Hashtable; public class LDAPObject { protected String dn = null; protected Hashtable attributes = new Hashtable(); public LDAPObject() { } public String getDn() { return dn; } public void setDn(String dn) { this.dn = dn; } public Object getAttribute(String attName) { return (String)attributes.get(attName); } public void setAttribute(String attName, Object attValue) { attributes.put(attName, attValue); } }
Servlets and LDAP CHAPTER 11
NOTE
All of the code written for this chapter allows for only one value for each attribute. This is done for simplicity reasons; however, multiple values are possible.
Now let’s take a look at the client code that uses this method to search the LDAP server: LDAPManager lm = new LDAPManager(); lm.setSearchBase(“o=virtuas.com”); String[] returnAtts = {“cn”, “sn”, “mail”, “telephoneNumber”}; String searchFilter = “uid=proy”; Vector results = null; try { results = lm.search(returnAtts, searchFilter); } catch (NamingException e) { e.printStackTrace(); } Iterator iter = results.iterator(); while (iter.hasNext()) { LDAPObject lobj = (LDAPObject)iter.next(); System.out.println(lobj.getDn()); System.out.println(lobj.getAttribute(“cn”)); System.out.println(lobj.getAttribute(“sn”)); System.out.println(lobj.getAttribute(“mail”)); System.out.println(lobj.getAttribute(“telephoneNumber”)); }
This client first creates a new LDAPManager and then sets the appropriate search base. It then defines the required return attributes and the search filter. After all of this information is in order, it uses the LDAPManager to perform the search. It can then easily iterate through the results, using a simple container object, and print out the information.
11 SERVLETS AND LDAP
Many attributes in an LDAP server can hold multiple values. For example, a person could have two telephone numbers, both of which are stored in the attribute telephoneNumber. If this is the case, both values are returned as values for the single Attribute object holding the telephone number.
173
174
Servlet Fundamentals PART I
These are the basics of searching an LDAP server. Now we can move on and learn how to use JNDI to manipulate the information that is stored there.
Adding an Object to an LDAP Server Adding an object to an LDAP server is not difficult, as long as you have a little knowledge of the structure of the information in the server. The first piece of knowledge necessary is the object type. There is a special attribute for every object in the LDAP server called objectClass. As we discussed earlier, the directory server comes with a predefined schema. The schema includes definitions for many objects, including the possible attributes available for each object. The existing object definitions can be reused by other objects, similar to inheritance in Java. The objectClass attribute holds multiple values, specifying which object definitions are used to define the object’s schema. This attribute is required when adding an object so that the LDAP server knows what type of object is being added. You also need to know where to place the object into the directory tree. Essentially you are going to bind a group of attributes to a new DN in the structure. The simple method used to bind a new object in an LDAP server looks like this: public void add(String dn, HashMap attributes, String[] objectClass) throws NamingException { // parse the attributes that were passed in Attributes atts = parseAttributes(attributes); // add objectClass attribute to the list of attributes Attribute oc = new BasicAttribute(“objectClass”); for (int i = 0; i < objectClass.length; i++) { oc.add(objectClass[i]); } atts.put(oc); // perform the addition to the LDAP server DirContext ctx = getInitialContext(getEnvironment()); ctx.bind(dn, null, atts); }
This method is very simple. As you can see, you accept the object type information as an array of strings, and build an Attribute object out of them. All the attribute names and values to place in the new object are passed to the method using a standard Java collection so that the client does not need to learn to handle the Attribute and Attributes objects. This collection is parsed into the required form in another method in the LDAPManager. That method is used in several places and appears like this:
Servlets and LDAP CHAPTER 11 public Attributes parseAttributes(HashMap attributes) {
return null; } Attributes newAtts = new BasicAttributes(); // get an iterator for all of the keys in the HashMap Iterator attIter = attributes.keySet().iterator(); while (attIter.hasNext()) { // get the value for the key. String attName = (String)attIter.next(); Object value = attributes.get(attName); // create a new Attribute Attribute attribute = new BasicAttribute(attName, value); // add the attribute to the list of attributes newAtts.put(attribute); } return newAtts; }
Client code can use this method to add objects to any place in the directory tree. Because you are dealing with a phone book, you will be adding the proper information in the People branch. The client code to do this would look like this: LDAPManager lm = new LDAPManager(); String[] objectClass = {“top”, “person”, “organizationalPerson”, “inetOrgPerson”}; String dn = “uid=bjones,ou=People,o=virtuas.com”; HashMap atts = new HashMap(); atts.put(“cn”, “Bob Jones”); atts.put(“sn”, “Jones”); atts.put(“givenName”, “Bob”); atts.put(“uid”, “bjones”); atts.put(“mail”, “[email protected]”); atts.put(“telephoneNumber”, “(800) 456-4908”);
11 SERVLETS AND LDAP
if (attributes == null) {
175
176
Servlet Fundamentals PART I try { lm.add(dn, atts, objectClass); } catch (NamingException e) { e.printStackTrace(); }
After all of the information has been collected, all you need to do is ask your LDAPManager to add the object to the server. Here you define the person object by combining the inherited objects that include the attributes that you want. These include top, person, organizationalPerson, and inetOrgPerson. To find this information, you have to know a little about the schema that came with the LDAP server you are using. These object definitions make up the standard user object in the Netscape Directory Server.
Removing an Object Removing an object from an LDAP server is very easy. There is little information that is necessary. All that is required is the object’s DN. Hand the DN to the Context and ask it to remove the object for you. It is that simple. The method to perform the deletion from an LDAP server appears in the manager class as follows: public void remove(String dn) throws NamingException { // perform the deletion from the LDAP server based on the objects DN DirContext ctx = getInitialContext(getEnvironment()); ctx.destroySubcontext(dn); }
All the client code must do is provide the manager with the object’s DN. The method would be invoked like this: LDAPManager lm = new LDAPManager(); try { lm.remove(“uid=bjones,ou=People,o=virtuas.com”); } catch (NamingException e) { e.printStackTrace(); }
That is all there is to removing entire objects from a directory service.
Servlets and LDAP CHAPTER 11
Modifying Information Stored in LDAP
The three possible modification operations are: ADD, REPLACE, and REMOVE. When the ADD_ATTRIBUTE operator is used, any values that are specified for an attribute are added to the existing values already stored in the LDAP object. The REPLACE_ATTRIBUTE operator specifies that any values already present for the attribute should be replaced with the new values. No matter how many values are already assigned to the attribute in the LDAP server, they will all be removed and replaced with the values that are given to the modify method. Finally, you can remove values and entire attributes from an existing LDAP object by using the REMOVE_ATTRIBUTE operator. When using the REMOVE operator, if a value is specified for the attribute that is passed into the modify method, only those given values will be removed from the LDAP object. On the other hand if no value is given for the attribute in conjunction with a REMOVE operator, all values will be removed from the attribute. Now let’s take a look at the method in the LDAPManager that modifies an existing LDAP object. Here is what it looks like: public void modify(String dn, HashMap attributes, int modOp) throws NamingException { // perform the modification on all of the given attributes // based on the modOp that was passed in DirContext ctx = getInitialContext(getEnvironment()); ctx.modifyAttributes(dn, modOp, parseAttributes(attributes)); }
There is not a lot to this method. The DN for the object that you are modifying must be present so the LDAP server knows where to make the changes. The modify operation that we discussed earlier is specified so the LDAP server knows how to make the changes. The attributes to be modified must be given so that the LDAP server knows what changes to make. Notice that you use the parseAttributes() method, defined earlier, to build the list of attributes from a Java HashMap. Here is an example of how you might use this method to change the value for someone’s email address LDAPManager lm = new LDAPManager(); try {
11 SERVLETS AND LDAP
Modifying the attributes of an existing object in an LDAP server requires slightly more thought than the rest of the operations. When changing the values for the attributes for an object, there are three ways in which the modification can be performed.
177
178
Servlet Fundamentals PART I HashMap modifications = new HashMap(); modifications.put(“mail”, “[email protected]”); lm.modify(“uid=proy,ou=People,o=virtuas.com”, modifications, DirContext.REPLACE_ATTRIBUTE); } catch (NamingException e) { e.printStackTrace(); }
In this example we are replacing the existing value for the e-mail address with the new value of “[email protected]”. This change is made to the object specified by the DN “uid=proy, ou=People, o=virtuas.com”. It is important to note that more than one attribute can be modified at the same time, however the attributes will all be bound by the same modification operator. The full listing for the manager class we have been developing appears in Listing 11.2. LISTING 11.2 import import import import import import import import import
Hashtable env = new Hashtable(); // generate LDAP host URL StringBuffer url = new StringBuffer(“ldap://”); url.append(serverName).append(“:”).append(port); // set Context Factory class env.put(javax.naming.Context.INITIAL_CONTEXT_FACTORY, factory); // set host URL env.put(javax.naming.Context.PROVIDER_URL, url.toString()); // Only set authentication information if there is a username // present if ((dirManager != null) && (dirManager.trim().length() > 0)) { env.put(javax.naming.Context.SECURITY_AUTHENTICATION, securityAuthentication); env.put(javax.naming.Context.SECURITY_PRINCIPAL, dirManager); env.put(javax.naming.Context.SECURITY_CREDENTIALS, dirManagerPw); } return env; } /** * Creates a new Directory Context based on the local settings. */ protected DirContext getInitialContext(Hashtable env) throws ➥NamingException { return new InitialDirContext(env); } /** * Searches the ldap server using the search filter that is passed to the * method. */
11 SERVLETS AND LDAP
/** * Returns all of the necessary environment information required to * create a Context and bind to an LDAP server. */ protected Hashtable getEnvironment() {
179
180
Servlet Fundamentals PART I
LISTING 11.2
Continued
public Vector search(String[] returnAttributes, String searchFilter) throws NamingException { Vector ldapObjects = new Vector(); SearchControls ctls = new SearchControls(); ctls.setReturningAttributes(returnAttributes); ctls.setSearchScope(searchScope); NamingEnumeration results = null; // bind to the LDAP server. DirContext ctx = getInitialContext(getEnvironment()); // perform the search on the LDAP server. results = ctx.search(searchBase, searchFilter, ctls); while ((results != null) && (results.hasMore())) { // get the next set of results from the search. SearchResult sr = (SearchResult)results.next(); // get all of the attributes for this object. Attributes attributes = sr.getAttributes(); NamingEnumeration attEnum = attributes.getAll(); // create an LDAPObject to hold the results. LDAPObject tmpObj = new LDAPObject(); // set the Distinguished Name for // the relative dn and the searcb tmpObj.setDn(sr.getName() + “,” + // iterate through the attributes while (attEnum.hasMore()) {
the object. Append base together. searchBase); setting them in the LDAPObject
// get the next attribute Attribute att = (Attribute)attEnum.next(); // set the attribute in the LDAPObject tmpObj.setAttribute(att.getID(), att.get()); } // add the object to the list of return objects ldapObjects.add(tmpObj); } return ldapObjects; } /** * Updates the given object in the LDAP server. */
Servlets and LDAP CHAPTER 11
LISTING 11.2
Continued
// perform the modification on all of the given attributes // based on the modOp that was passed in DirContext ctx = getInitialContext(getEnvironment()); ctx.modifyAttributes(dn, modOp, parseAttributes(attributes)); } /** * Adds a new object to the LDAP server with the give attributes. */ public void add(String dn, HashMap attributes, String[] objectClass) throws NamingException { // parse the attributes that were passed in Attributes atts = parseAttributes(attributes); // add objectClass attribute to the list of attributes Attribute oc = new BasicAttribute(“objectClass”); for (int i = 0; i < objectClass.length; i++) { oc.add(objectClass[i]); } atts.put(oc); // perform the addition to the LDAP server DirContext ctx = getInitialContext(getEnvironment()); ctx.bind(dn, null, atts); } /** * Remove the specified object from the LDAP server. */ public void remove(String dn) throws NamingException { // perform the deletion from the LDAP server based on the objects DN DirContext ctx = getInitialContext(getEnvironment()); ctx.destroySubcontext(dn); } public Attributes parseAttributes(HashMap attributes) { if (attributes == null) {
11 SERVLETS AND LDAP
public void modify(String dn, HashMap attributes, int modOp) throws NamingException {
181
182
Servlet Fundamentals PART I
LISTING 11.2
Continued return null;
} Attributes newAtts = new BasicAttributes(); // get an iterator for all of the keys in the HashMap Iterator attIter = attributes.keySet().iterator(); while (attIter.hasNext()) { // get the value for the key. String attName = (String)attIter.next(); Object value = attributes.get(attName); // create a new Attribute Attribute attribute = new BasicAttribute(attName, value); // add the attribute to the list of attributes newAtts.put(attribute); } return newAtts; } public void setFactory(String factory) { this.factory = factory; } public String getServerName() { return serverName; } public void setServerName(String serverName) { this.serverName = serverName; } public int getPort() { return port; }
Servlets and LDAP CHAPTER 11
LISTING 11.2
Continued
this.port = port; } public String getSearchBase() { return searchBase; } public void setSearchBase(String sb) { searchBase = sb; } public String getSecurityAuthentication() { return securityAuthentication; } public void setSecurityAuthentication(String sa) { this.securityAuthentication = sa; } public String getDirManager() { return dirManager; } public void setDirManager(String dirManager) { this.dirManager = dirManager; } public String getDirManagerPw() { return dirManagerPw; } public void setDirManagerPw(String dirManagerPw) { this.dirManagerPw = dirManagerPw; }
11 SERVLETS AND LDAP
public void setPort(int port) {
183
184
Servlet Fundamentals PART I
LISTING 11.2
Continued
public int getSearchScope() { return searchScope; } public void setSearchScope(int sc) { searchScope = sc; } }
Accessing LDAP from a Servlet By using the LDAP manager class that we have developed, accessing the LDAP server from any servlet is very simple. You acquire all the information you need to perform the specific operation and then make the appropriate call to LDAPManager. If you download the source code for this book, an extra class is provided to help load several people into a LDAP server. This class is named LDAPInsertData. All you need to do is compile it and run it to insert 14 people into the server. This will work as long as you have installed the root of your LDAP tree as “o=virtuas.com”. The source code for LDAPInsertData appears in Listing 11.3. LISTING 11.3
LDAPInsertData.java
import java.util.HashMap; import javax.naming.NamingException; public class LDAPInsertData { public LDAPInsertData() { } public static void main(String[] args) { LDAPManager lm = new LDAPManager(); String[] objectClass = {“top”, “person”, “organizationalPerson”, “inetOrgPerson”};
We have already written the foundation for many simple LDAP applications. Here is an example of a servlet that selects information from an LDAP server by searching on the user’s last name and then outputs the results. The full listing for LDAPTestServlet is in Listing 11.4.
public class LDAPTestServlet extends HttpServlet { private static final String CONTENT_TYPE = “text/html”; /**Initialize global variables*/ public void init(ServletConfig config) throws ServletException { super.init(config); } /**Process the HTTP Get request*/ public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // define what results we want from the search String[] returnAtts = {“cn”, “sn”, “givenName”, “mail”, “telephoneNumber”}; // get the search criteria from the request String lName = request.getParameter(“lName”); // create a search filter, searching on the last name passed in String filter = “sn=” + lName.trim(); // create and initialize an LDAPManager LDAPManager lm = new LDAPManager(); lm.setSearchBase(“o=virtuas.com”); // perform the search Vector results = null; try { results = lm.search(returnAtts, filter); } catch (NamingException ex) {
11 SERVLETS AND LDAP
import import import import import
LDAPTestServlet.java
187
188
Servlet Fundamentals PART I
LISTING 11.4
Continued throw new ServletException(ex);
}
// output the results response.setContentType(CONTENT_TYPE); PrintWriter out = response.getWriter(); out.println(“”); out.println(“LDAPTestServlet”); out.println(“”); out.println(“
”); } out.println(“”); } /**Clean up resources*/ public void destroy() { } }
Summary LDAP provides an alternative method of persistent storage. It is well suited for systems that require a high volume of read operations combined with a limited number of modifications. The data is represented in a tree-like hierarchy and consists of objects containing name-value pairs. Java provides an API to access LDAP servers called Java Naming and Directory Interface (JNDI). JNDI makes accessing LDAP servers simple, and it is a good choice for many systems. In the next chapter we are going to discuss Enterprise JavaBeans and how they can be leveraged to encapsulate Web application business logic.
CHAPTER
Servlets and Enterprise JavaBeans
12
IN THIS CHAPTER • What Are Enterprise JavaBeans? • EJB Terminology • Installing JRun
191 191
• The Enterprise JavaBean • Session Beans • Entity Beans
190
192
194 206
• Deploying Your EJB to Your Application Server 218 • Servlets as EJB Clients
220
190
Servlet Fundamentals PART I
What Are Enterprise JavaBeans? Sun’s Enterprise JavaBean specification defines the EJB architecture as follows: “The Enterprise JavaBeans architecture is a component-based architecture for the development and deployment of component-based distributed business applications. Applications written using the Enterprise JavaBeans architecture are scalable, transactional, and multi-user secure. These applications may be written once, and then deployed on any server platform that supports the Enterprise JavaBeans specification.” The definition mentions component-based–distributed business applications. The EJB architecture enables different components of a system to exist on distributed machines and to operate together as if they all existed in the same application space. Alone this might not sound much different from Java’s Remote Method Invocation (RMI), and actually EJB makes use of RMI as part of its underlying structure. However, it is not this one aspect of EJB that makes the architecture so powerful but it is this in combination with the other traits that are mentioned. EJB systems are easily scalable. You will see how simple it is to add and remove functionality to a system that has been written using the EJB architecture. Not only are the applications scalable in terms of functionality, but they can easily scale to handle changing numbers of clients accessing the application. Because an application server manages EJBs, their number can be increased or reduced depending on the need. This is a topic that will be discussed later. Previously the application developer was responsible for writing and maintaining transactional management code. The EJB designer has the ability to decide whether to let the EJBs manage all transactions and how each individual EJB will participate in the transactions. It is important to have all related tasks included within one transaction to make sure that all necessary tasks are completed or that none of them are. This is the concept of ACID (Atomicity, Consistency, Isolation, and Durability) transactions that are so talked about by database designers. Another topic that we will discuss is the ability to reuse EJBs across many systems with very little work. The two types of EJBs are the session bean and the entity bean. One holds the key issues related to business logic, and the other acts as an object-oriented interface to your persistence layer. Both can be easily moved from system to system, database to database, and from platform to platform without the slightest code change. This is a great characteristic of any software component, but when combined with the rest of the EJB concepts, it becomes a great building block for all software systems. The rest of this chapter will help you understand the power associated with designing a system using EJBs. This is a brief chapter on a very complex topic. The specification itself is over 500 pages, and although it lays out exactly what all of the pieces of an EJB system are responsible for, it does not discuss all of the intricacies of properly developing an EJB system. This chapter attempts to give you an awareness of the topic, the ability to write and deploy simple Enterprise JavaBeans, and the foundation to continue your education on the topic.
Servlets and Enterprise JavaBeans CHAPTER 12
191
EJB Terminology For the purposes of this chapter we must define several concepts as they relate to Enterprise JavaBeans. Each of these pieces has a specific role that is defined by the EJB specification, which lays out very precisely the responsibilities of each and how they interact with each other. These components are as follows: • EJBs—The server-side objects containing your business logic. This is where you will do all of your work to define the functionality of the system.
• EJB Client—The client to an EJB is the software that is accessing and making method invocations to the EJB, either through its home or remote interfaces, both of which will be discussed later. The EJB client can be an applet, a servlet, or any code, including any other EJB. All of these pieces must work flawlessly together for an EJB system to accomplish its goals. As mentioned before, all of the interactions between these pieces are defined in the specification, and this contractual agreement is what enables an EJB application to be easily deployed on different systems.
Installing JRun Before we get started developing our example, you need to download and install an EJB container. For our examples we are going to be using Allaire’s JRun. Installing and configuring JRun is very simple. The first thing to do is to download the product from Allaire. This can be done at http://www.allaire.com
You will download an executable that will install the program. The first thing that you will do during installation is to accept the licensing agreement. The setup program will then ask you for a serial number; you should leave this blank. By leaving the serial number blank you will gain access to a developer’s license for the product. This license is a full working version of the application server, but it only allows three simultaneous connections. After this, accept all of the default entries for the installation of JRun. After the product installs you will be guided through the configuration of the Admin server for JRun. Choose a password for the admin account that you will remember. You should also write down the port that is chosen for the Admin server. You will need both pieces of information to access the Admin server to deploy your EJBs. Now you are ready to deploy and test your Enterprise JavaBeans.
12 SERVLETS AND ENTERPRISE JAVABEANS
• Application Server—Provides the deployment tools necessary to deploy the EJBs, as well as runtime support for the deployed EJBs. The interaction between application server and EJB is important, and we will discuss how the application server manages the lifecycle of each EJB instance.
192
Servlet Fundamentals PART I
The Enterprise JavaBean Enterprise JavaBeans come in two fundamentally different flavors: the entity bean and the session bean. Entity beans model a real-world object, a noun if you will. The entity bean is associated with persistent state held in a database. Simple examples are an employee, an organization, a company, and any other object that might be represented in a database. Not only does the entity bean represent the persistent data associated with the object, it also provides the functionality to make changes directly to the object. Session beans on the other hand are not associated with a persistent state. They encompass a process or task. This is where the business logic of your application exists. Session beans add meaning to the changes that might be made on an entity bean. For example, reducing the number of a specific item in inventory and billing a customer are two tasks that by themselves do not make much sense. However, they have a solid meaning when combined into the specific context of selling the item to the customer. The total transaction of billing a customer for a specific item, having it shipped, and maintaining proper records on inventory makes use of many different objects. A customer bean and an item bean are some entity beans that would be required to accomplish this task. A session bean is required to perform all of the necessary steps and make all of the changes to the entity beans to complete the process of selling this item to the customer. There is resulting persistent data in the form of entity beans: for example, updated inventory, a bill for the customer, and possibly a record of the credit card transaction, however the session bean is inherently transient. The process begins, the steps are carried out, and then it is finished.
Interfaces and Classes Now that you have some understanding of the difference between entity beans and session beans, let’s take a look at the objects and interfaces that make up an EJB.
Home Interface The home interface for an EJB defines the lifecycle methods for the bean. It has methods for creating, removing, and in the case of entity beans, searching beans. This is the first interaction with an EJB that most clients have. The home interface extends the javax.ejb.EJBHome interface.
Remote Interface The remote interface defines the business methods that can be performed on the bean. This is the API that the bean presents the outside world for use. The remote interface extends the javax.ejb.EJBObject interface.
Servlets and Enterprise JavaBeans CHAPTER 12
193
Bean Object The bean object is made up of the methods that implement the business logic for the bean. Clients never directly access the methods in this object. They always make use of the home and remote interfaces. An interesting note is that the bean object does not implement either the home or remote interfaces. However, it must have methods that match the signatures for all of the methods in the remote interface and methods that correspond with many of the methods in the home interface. These are some of the interaction regulations that are laid out in the specification. We will take a deeper look at these rules later. Depending on whether the bean is a session bean or entity bean, the bean object must extend either javax.ejb.SessionBean or javax.ejb.EntityBean.
The primary key class is specific to entity beans. It is a very simple class that specifies the attributes that make up the unique primary key for the entity bean. The only requirement is that it implements java.io.Serializable.
Naming Conventions The naming conventions for the interfaces and classes associated with an EJB do not actually have any specific rules, however there is a recommended convention. This convention holds true for both session and entity beans, and will be used throughout this chapter. We will use a fictitious entity bean—Employee—to illustrate the naming conventions associated with an EJB. The overall component made up of all of the interfaces and classes necessary for a bean is referred to as the bean itself, for example Employee Bean. The home interface class is generally named after the bean with Home appended. In the case of the Employee Bean, the home interface is named EmployeeHome. The remote interface is the client’s real view of the bean; therefore it takes the bean’s name alone. The name of the remote interface for the Employee Bean is simply Employee. The bean object containing the data for the bean takes the bean’s name and adds the word Bean, for example EmployeeBean. The primary key class associated with entity beans is somewhat more ambiguous. If a specific user-defined class will be the primary key, a good convention is the bean’s name followed by PK. Our Employee Bean’s primary key class would be named EmployeePK. The ambiguity arises because it is possible to use any Serializable class in Java. A very commonly used primary key class found in Java is Integer. It is up to the bean designer to define the primary key. With the knowledge of the different classes and interfaces that are required for an EJB, we can and look at the ways EJBs are used by clients and managed by application servers.
SERVLETS AND ENTERPRISE JAVABEANS
Primary Key
12
194
Servlet Fundamentals PART I
Session Beans Session beans define a process or task. Software systems are made up of collections of processes, and in many instances each process is composed of smaller tasks. This architecture is exactly what session beans are designed to build. This is how you should design the business logic of your software using session beans. If you develop processes that are generic and reusable on many systems, you can use these session beans independently, or develop more detailed session beans that string together several of these processes. Think of a session bean that processes a credit card transaction or a session bean with methods to provide several different billing mechanisms. This is certainly a useful utility from which many systems can benefit.
Stateless Versus Stateful Within the family of session beans there are two types, stateless and stateful. Session beans do not have persistence, but that does not prevent them from having attributes and holding state. The distinction between stateless and stateful is that a stateful session bean can have attributes that hold a conversational state between method invocations. This state is necessary and must not be lost between method calls. An example is an e-commerce shopping cart. When the cart is created it will be empty, but eventually a call will be made to add an item, and then to change the quantity of that item in the cart. More items can be added, but at some point the user will want to check out. If all of the information about the items previously placed in the basket is lost at some point during this process, the customer will be angry. This is a great concept, but allowing a session bean to maintain state does not come without a price. A stateful session bean is less efficient than a stateless bean for more than one reason. One of the big costs comes from the fact that more stateful session beans need to exist simultaneously because they cannot be shared as readily as stateless session beans. How would you like it if somebody else placed things in your shopping cart? The topic of bean pooling and reuse will be discussed later. Stateless session beans on the other hand hold no state that is required to be kept between method invocations. After the method has finished processing, it returns and no longer maintains any information specific to the client that it just serviced. A session bean used to process a credit card payment illustrates this. The method to handle this business process would take all the necessary information as parameters, and would return success or failure. None of the information needs to be retained by the session bean. This fictitious bean can also contain the business logic to process a payment by check. Each session bean in a system should be evaluated as to whether it needs to maintain conversational state. In most cases it will be obvious after the processes are clearly specified.
Servlets and Enterprise JavaBeans CHAPTER 12
195
Session Bean Interfaces and Classes The differences that occur in the interfaces and classes required to build a session bean depend on whether the bean is stateful or stateless. You will develop a sample session bean throughout the next section. The sample session bean is a stateless session bean, CalculateLoan, with a method that can be used to calculate the monthly payment for a loan, given the necessary information.
Remote Interface
This interface will drive the development for the bean class. Here you must design the client’s interaction with the bean. After this API is well defined it usually remains static. After it has been integrated into client code, changing the existing prototypes will have detrimental effects on the client. Because this is only an interface and contains no code, after it is finished it is possible for clients to begin integrating it. Defining the remote interface is governed by a few regulations. The interface must extend the Every method must follow the rules for RMI/Internet Inter-ORB Protocol (IIOP). This means that each parameter and return type must be of valid types for RMI/IIOP. Also, each method must include at least java.rmi.RemoteException in the throws clause. Other than these two simple regulations all you must do is define what the public interface for your session bean will contain. javax.ejb.EJBObject.
The remote interface for the CalculateLoan bean is very simple. The source code for the remote interface is in Listing 12.1. LISTING 12.1
CalculateLoan.java
import javax.ejb.EJBObject; import java.rmi.RemoteException; public interface CalculateLoan extends EJBObject { public Float calcMonthlyPayment(Integer months, Float principal) throws RemoteException; public Float getCurrentInterestRate() throws RemoteException }
Let’s look at the exceptions in this class. You will see that all of the methods throw RemoteException as required by the EJB specification. As long as this exception is included in the throws clause, any other exception can also be included in the throws clause. Once again these exceptions are system specific and defined by the bean designer.
12 SERVLETS AND ENTERPRISE JAVABEANS
The remote interface for any session bean defines the client’s access to the business logic contained within the bean. These are the methods that define the usefulness of the bean.
196
Servlet Fundamentals PART I
Notice also that the calcMonthlyPayment() method does not take an interest rate as a parameter. This is because the interest rate will be used to illustrate how values can be deployed in a specific bean’s environment and made available to the bean at any time. This will also give you some understanding of how an EJB system can be configured upon deployment without any code changes.
Home Interface The home interface for an EJB defines lifecycle methods. In the case of a session bean the important lifecycle events are creation and removal. The only thing that you need to worry about as a bean designer is the creation of session beans. The remove method and functionality are contained within the base interface. The home interface for a session bean has slightly more stipulations associated with it than the remote interface. It must extend javax.ejb.EJBHome. All of the RMI/IIOP regulations that were in place for the remote interface are also present for the home interface; it is an interface to a remote object. The other rules apply specifically to the name and prototypes of the methods contained within the home interface. The first stipulation on the methods is that there must be one or more creation methods. Each of these methods must be named create(). They must also include javax.ejb.CreateException, as well as the RemoteException specified by the RMI/IIOP rules. Once again there is no rule that limits any other exceptions from being present in the throws clause. Each create() method must return the specific remote interface type for that bean. This allows the client access to the business logic after it has retrieved the home interface and created an instance of the bean. For example the create() methods for the CalculateLoanHome interface will return the CalculateLoan interface. These create() methods provide the first difference you will see between stateless and stateful session beans. In almost all cases, a stateless session bean will contain only one create() method that takes no parameters. The reason for this is that any parameters passed to the create() method would be client-specific information that would need to be stored in the bean after the creation until the next method invocation. This is a conversational state that the stateless session bean cannot maintain. The CalculateLoan bean in Listing 12.2 shows only one create() method because it is being defined as a stateless session bean. LISTING 12.2
public interface CalculateLoanHome extends EJBHome { public CalculateLoan create() throws RemoteException, CreateException; }
This is a simple interface that has only a few rules to follow. Now we will look at the bean class and some of the more difficult to understand rules that the specification imparts to EJB code.
The bean class holds the implementation for the EJB. It has certain requirements in relation to both the home and remote interfaces. The rules related to each interface are different, so we will go through them independently. First we will cover the general requirements for the session bean’s bean class. It must implement the javax.ejb.SessionBean interface. In implementing SessionBean, four methods must be implemented: ejbActivate(), ejbPassivate(), ejbRemove(), and setSessionContext(). All of these methods will be discussed briefly later in the chapter. The class must contain a public constructor that takes no arguments. This is the only constructor that is useful in any EJB because all client construction of these beans is done through the create() methods. The first requirement is related to the home interface. For each create() method in the home interface, the bean class must have an ejbCreate() method with an argument list that exactly matches the signature of the corresponding create() method. The ejbCreate() method also defines the same throws clause as the matching create() method. Each ejbCreate() method must be public and return void. The following code snippet gives an example of a create() method from a home interface and the matching ejbCreate() method that would exist in the bean class: public BeanRemote create(Integer number) throws RemoteException, CreateException, AppDefinedException; public void ejbCreate(Integer number) throws RemoteException, CreateException, AppDefinedException { this.number = number; }
SERVLETS AND ENTERPRISE JAVABEANS
Bean Class
12
198
Servlet Fundamentals PART I
Notice the matching argument lists and throws clauses. As mentioned before, because this create() method accepts an argument list, it would probably be associated with a stateful session bean. This also explains why the body of the ejbCreate() method initializes the bean’s state. The create()/ejbCreate() combination of methods acts as a pseudoconstructor that the client uses for the bean. Next are the responsibilities of the bean class in relation to the remote interface. The bean class must implement each of the business methods defined in the remote interface. This includes following all the rules laid out for these methods, for example RMI/IIOP compliance. One important rule is that the name of these methods cannot begin with ejb, to avoid naming conflicts with the callback methods that begin this way. The sample bean class still remains a fairly simple class. You can find the source for the bean class in Listing 12.3. LISTING 12.3 import import import import import
public class CalculateLoanBean implements SessionBean { protected SessionContext ctx = null; public CalculateLoanBean() { } public Float calcMonthlyPayment(Integer months, Float principal) throws RemoteException { Float yearlyIntTmp = getCurrentInterestRate(); // Perform all of the calculations to figure out // the monthly payment. float yearlyInt = yearlyIntTmp.floatValue() / 100; float monthlyInt = yearlyInt / 12; double payment = (principal.floatValue() * monthlyInt) / (1 - (Math.pow(1 / (1 + monthlyInt), months.intValue()))); return new Float((float)payment); }
Servlets and Enterprise JavaBeans CHAPTER 12
LISTING 12.3
199
Continued
public Float getCurrentInterestRate() throws RemoteException { Float yearlyInt = null; try { // Obtain the enterprise bean’s environment // naming context. Context initCtx = new InitialContext(); Context myEnv = (Context)initCtx.lookup(“java:comp/env”);
} catch (javax.naming.NamingException nex) { // If there was a problem with JNDI, // getting the yearly interest // rate, we will just default it to 8% yearlyInt = new Float(8.0f); } return yearlyInt; } public void ejbCreate() throws javax.ejb.CreateException, java.rmi.RemoteException { } public void ejbActivate() throws javax.ejb.EJBException, java.rmi.RemoteException { } public void ejbPassivate() throws javax.ejb.EJBException, java.rmi.RemoteException { } public void ejbRemove() throws javax.ejb.EJBException, java.rmi.RemoteException { }
SERVLETS AND ENTERPRISE JAVABEANS
// Obtain the yearly interest rate from the // bean’s environment yearlyInt = (Float)myEnv.lookup(“interestRate”);
Remember that there is an ebjCreate() method to match each of the create() methods in the home interface. The bean class fully implements each of the business methods specified in the remote interface. Note the exact same signatures between the two methods. All of the abstract methods defined in the base class SessionBean have been implemented, even though most of them are empty. Every session bean is required to maintain the SessionContext, which will be assigned to it by the container. The attribute is set through the setSessionContext() method. This and the other callback methods, ejbActivate(), ejbPassivate(), and ejbRemove(), will all be discussed when we look at the container’s interaction with the session bean and the bean’s lifecycle. The business method, calcMonthlyPayment(), includes code to perform the necessary calculations. This method is not written differently from any other Java method. The one piece of code that is specific to an EJB is in the getCurrentInterestRate() method where you obtain the yearly interest rate from the EJB’s environment.
Deployment Descriptor Deploying a group of EJBs gives the application server a description of each bean as well as a set of instructions that tell it how to manage the beans. One or more EJBs are grouped into a jar file along with an ejb-jar.xml file (the deployment descriptor), and they are deployed to the application server to handle. The ejb-jar.xml file can contain two types of information. The EJB’s structural information provides all of the dependency information for an EJB. This information is required, and is usually not changed after it is solidified, because change will affect not only the structure of the bean, but the clients that use it. The second type of information that can be present in the ejb-jar.xml file is application assembly information. This information defines how each EJB interacts to compose a larger application unit. The application assembly information is optional, and by changing it you are only affecting how the bean works in the larger group. The ejb-jar.xml file contains XML tags to describe all the necessary information. The structure of the ejb-jar.xml file is regulated by a document type definition (DTD) that can be found at http://java.sun.com/j2ee/dtds/ejb-jar_1_1.dtd. We will use only a small subset of the XML tags that are possible in an EJB deployment descriptor.
Servlets and Enterprise JavaBeans CHAPTER 12
201
The ejb-jar.xml file must include a directive pointing to the DTD. The following code snippet is an example of this directive:
This line must appear at the top of every ejb-jar.xml file. The outermost tag in the ejb-jar.xml file is <ejb-jar>. Everything will be contained within this tag. You will have two main sections within this tag, one to define the EJB structural information, contained inside the <enterprise-beans> tag, and a second section to define the application assembly information, contained inside the tag.
<session> <description> Makes calculations related to a loan <ejb-name>CalculateLoan CalculateLoanHome CalculateLoan <ejb-class>CalculateLoanBean <session-type>Stateless Container
This is a basic descriptor for our session bean. Each session bean in the jar file will have an entry similar to this in the ejb-jar.xml file. The <ejb-name> tag identifies the name under which the home interface will be kept by Java Naming and Directory Interface (JNDI). JNDI provides a standard method for accessing named objects. This is the name needed to look it up. It is arbitrary, however it must be unique within the application. Many times a prefix will be used to avoid naming collisions with other EJB packages, for example, bookExamples.CalculateLoan. The , , and <ejb-class> tags all contain the fully qualified classpath to their respective interface or class. The <session-type> tag can contain only two values, Stateless or Stateful. This identifies whether you have decided to include conversational state in the session bean. The last tag you see is . It can hold two possible values—Container or have seen that it is possible to allow the container to manage all of the transactions, and that each individual bean participates in the transactions. This tag specifies whether to let the container take these responsibilities or have the bean handle them itself. For our example, the container will handle all of the dirty work. Bean. You
SERVLETS AND ENTERPRISE JAVABEANS
You describe the dependencies of a session bean with an entry inside the <enterprise-beans> tag. The following code snippet gives an example of this description:
12
202
Servlet Fundamentals PART I
You must add one more section to your bean descriptor, allowing you to use the environment variable. The bean’s environment is made available to the bean by the container. The values that are available to the bean are specific to each bean type. The variable values are set up at deployment time, and are not changeable at runtime. The environment is provided under the context java:comp/env. Each environment variable is declared in the deployment descriptor for the bean. The possible values for these basic variables are: String, Integer, Boolean, Double, Byte, Short, Long, and Float. The deployment of the interest rate is added to the session description you already have, and looks like the following code snippet: <session> ... <env-entry> <description> The yearly interest rate. <env-entry-name>interestRate <env-entry-type>java.lang.Float <env-entry-value>8.2
This is just a brief introduction to the uses of the EJB’s environment. It is also possible to place SQL DataSources, other EJB’s home interfaces, and other useful items into the environment. This is a more advanced topic. This is all we need to provide in the EJB structure part of the deployment descriptor. We will also provide a small entry in the application assembly section to tell the container how to handle transactions. The entire application assembly description appears as follows: <method> <ejb-name>CalculateLoan <method-name>* Required
Here you tell the container that for every method in CalculateLoan, the transaction setting is Required; this setting means that if the client is not already involved in a transaction, a new transaction should be started when entering the bean. How the transactions are handled can be defined at the method level. Each method in the home and remote interface of your bean could
Servlets and Enterprise JavaBeans CHAPTER 12
203
be specified here. Definitions for the six different transactional attributes are in the EJB specification. You can see the contents of the entire ejb-jar.xml file in Listing 12.4 LISTING 12.4
ejb-jar.xml
SERVLETS AND ENTERPRISE JAVABEANS
<ejb-jar> <enterprise-beans> <session> <description> Makes calculations related to a loan <ejb-name>CalculateLoan CalculateLoanHome CalculateLoan <ejb-class>CalculateLoanBean <session-type>Stateless Container <env-entry> <description> The yearly interest rate. <env-entry-name>interestRate <env-entry-type>java.lang.Float <env-entry-value>8.2 <method> <ejb-name>CalculateLoan <method-name>* Required
12
204
Servlet Fundamentals PART I
Now that you have all of the interfaces and the deployment descriptor finished, it is time to create a jar file containing all of the class files, and the ejb-jar.xml file in the META-INF directory. After this jar file is complete, you must follow the deployment directions specific to your application server. This topic is discussed in a later section, “Deploying Your EJB to Your Application Server.”
Client View of a Session Bean We have talked quite a bit about what goes into the writing of an EJB and session beans. Now we will finish the picture by discussing how a client accesses an EJB. The first thing that any client must do is locate the home interface for the session bean it requires. If you remember, the home interface is stored in a JNDI service, so we must use a JNDI context to look it up. The code looks like this: Context initialContext = getInitialContext(); CartHome cartHome = (CartHome)javax.rmi.PortableRemoteObject.narrow( initialContext.lookup(“CalculateLoan”), CalculateLoanHome.class);
Creating the InitialContext for the JNDI lookup can be specific to the application server you are using. In general client code, it requires that a Context factory class be passed to it. However, when another EJB is acting as the client, other bean home interfaces can be deployed into the bean’s environment. Deploying a home interface into another bean’s environment is similar to the variable you deployed earlier. When this is done, the lookup becomes easier because the client already has some knowledge of the home interface. The method of casting the object returned from the JNDI lookup is unique. You will notice that the static narrow() method of the PortableRemoteObject class is used prior to casting the home interface with a simple casting operator. According to the Enterprise JavaBeans Specification, this method of narrowing the remote object is required if your code is to be used among different EJB-compliant containers. It also states that programs that use the casting operator to narrow the remote and home interfaces are likely to fail if the current container is using RMI/IIOP as the underlying communication. Because many of the most popular application servers implement their EJB container using RMI/IIOP, it is strongly recommended that you narrow the interfaces using this method. After the client has obtained the home interface it requires, it must obtain the remote interface before it can perform any business logic calls to the bean. Because you have developed a stateless session bean, you really only have one choice, and that is the no-argument create() method. The create() method will return the remote interface which gives you access to the business logic of the session bean.
Servlets and Enterprise JavaBeans CHAPTER 12
205
Session Bean Lifecycle The application server is responsible for many resources. The way in which it hands out and manages the lifecycle of each Enterprise JavaBean is most important here. For system design purposes this is important, but I only describe how this works at a very high level because it is out of the scope of this text.
A session bean can be in several states while the application is running. Different actions performed by both the client and the application server can move the bean instance between the states. I briefly describe the states and movement for each type of session bean in the following text. Full descriptions, including state diagrams, are in the EJB Specification.
Stateless Session Beans A stateless session bean can exist in only two states—does not exist and method-ready pool. The does not exist state is the state that the bean is in prior to the application server creating the bean and moving it into the pool. The method-ready pool state is the state that the bean is in when the bean is on the server waiting for a client to request it. As you have seen, a stateless session bean holds no state between method invocations. This means that when the bean is finished processing a request for a client, it is immediately moved back into a waiting state until another request is made for its services. Even if the client maintains a copy of the remote interface for the bean, it is only attached to an actual instance of the bean for the duration of one method call.
Stateful Session Beans Stateful session beans have a slightly modified lifecycle. We will review the basics at a high level. A stateful session bean also begins in the does not exist state. From here it will be moved into the method ready state when a client invokes any creation method. When it is in the method ready state, it is considered to have client-specific conversational state, and that instance of the bean belongs to the client. It will continue to service that client’s requests. It can be removed from this state back into the does not exist state when the client calls the remove method. Another possibility from the method ready state is to have the bean passivated. Passivation occurs when a client has a remote interface to a stateful session bean, but is in between method calls; the application server can choose to allow the bean instance to service another client.
12 SERVLETS AND ENTERPRISE JAVABEANS
An important concept to know is instance pooling. For efficiency purposes the application server will pool instances of each EJB. By maintaining several instances of an individual bean and sharing them among clients, the application server can reduce the amount of time necessary to create and remove a bean every time a client requests one. The client holds a remote interface to a bean, but in reality this remote interface interacts with a container class around the bean instance.
206
Servlet Fundamentals PART I
The application server will store the conversational state somewhere and initialize the bean for another client. When this client needs to make another method call the application server will activate an instance of the bean for it to use. When a bean is passivated, the conversational state is stored so that it is not lost. When an instance of the bean is activated again for use by this client, the conversational state is restored to the same condition it was in at passivation. Subsequent method calls are not necessarily handled by the same instance of the bean, however it does not matter because whenever a new instance is given to the client the conversational state is restored. Activation and passivation are where the callback methods in the bean class come into play. The ejbActivate() and ejbPassivate() methods are called during this process in case some special processing is required to release or restore the state of the bean object.
Entity Beans Persistence is the primary difference between a session bean and an entity bean. The entity bean represents some persistence, and this determines many of the processes involved in writing, deploying, and even using an entity bean. When a client is accessing an entity bean, any changes that are made are automatically reflected in the database. There is no need to tell the entity bean to store itself, or to hand it to a database manager to be updated. This is all part of the contract between the container and all entity beans. It is a great concept and we will take a brief look at how it is taken care of. Entity beans are not totally different from session beans. They are all still Enterprise JavaBeans and follow many of the same principles. There is still the concept of a home interface, which controls lifecycle events; a remote interface, which provides access to business logic; and a bean class, which handles all of the requests. For this reason, we will not repeat all of the concepts discussed earlier on session beans. We will point out how they differ and address the concepts specific to entity beans.
Who Handles the Persistence? The Enterprise JavaBeans Specification enables the developer to write all of the code to handle persistence, or enables the container to take care of everything. These two concepts are called bean-managed persistence and container-managed persistence, respectively. It is possible to write an entity bean and never write any database-related code. This is usually the case when implementing beans using container-managed persistence. This sounds great, but there are also disadvantages to this scheme also. You have less control over how the data is stored, and possibly over the efficiency of the database transaction.
Servlets and Enterprise JavaBeans CHAPTER 12
207
On the other hand, with bean-managed persistence you must write the SQL statements and logic to store the information to the database. However, you also have the ability to perform complex joins, as well as use several statements if necessary to access your data. Both methods of persistence have advantages and disadvantages and once again the one you use is a decision you must make. For the purposes of this chapter you will develop a simple bean implemented using container-managed persistence.
Entity Bean Interfaces and Classes
Remote Interface The remote interface provides access to the entity bean’s business logic, just like the session bean’s. With an entity bean, the most common remote interface contains accessor methods for all of the bean’s attributes. This way the client has the capability to set and get the value for each attribute. This is common in many Java objects; the unique concept here is that changes that are made are also made in the database. The Quote remote interface is only going to provide the accessor methods. Listing 12.5 contains the source for your Quote remote interface. LISTING 12.5
Quote.java
import javax.ejb.EJBObject; import java.rmi.RemoteException; public interface Quote extends EJBObject { public void setCustomerName(String name) throws RemoteException; public String getCustomerName() throws RemoteException; public void setPhoneNumber(String phone) throws RemoteException; public String getPhoneNumber() throws RemoteException; public void setLoanAmount(Float amt) throws RemoteException; public Float getLoanAmount() throws RemoteException; public void setMonthlyPayment(Float pmt) throws RemoteException; public Float getMonthlyPayment() throws RemoteException; public void setInterestRate(Float rate) throws RemoteException; public Float getInterestRate() throws RemoteException; }
12 SERVLETS AND ENTERPRISE JAVABEANS
Let’s jump right in and look at the necessary parts to develop an entity bean. The sample entity bean you will develop is a Quote Bean. This container-managed bean will represent a customer’s loan quote that was acquired from your CalculateLoan Bean.
208
Servlet Fundamentals PART I
There is nothing special about this interface. Note once again that every method throws RemoteException. There is really no difference between the session bean and entity bean remote interface. Moving on to the home interface, you will begin to see some of the major differences.
Home Interface The home interface still provides access to methods that control the EJB’s lifecycle. There are also some added implications because the entity bean is associated with persistence. Two types of methods can exist in an entity bean’s home interface—creation methods and finder methods. You have seen create() methods in the session bean’s home interface, where you were required to have at least one such method. The process of creation returns to the client a remote interface associated with a bean that has been initialized depending on the parameters passed to the create() method. Also, during this process, a new entry is added to the database. When the client receives the remote interface, the bean has already been inserted into the database. Creation methods are not required for an entity bean, allowing for information in your database that is read only. The second type of method in the entity bean’s home interface is the finder method. These methods allow the client to look for information in the database. These methods also return remote interfaces for the specific bean type, however the beans are initialized from information from the database. There were no finder methods present in the session bean. This makes sense considering that there is nothing to look up when dealing with session beans. Finder methods all have unique names that are structured find<method>. For example This will be one of the finder methods for your Quote Bean so that it is possible to look up all of the quotes with the same customer name. The parameters passed to the finder method are usually used to build the search criteria.
findByName().
Every finder method must either return the remote interface for the bean, or a collection of these remote interfaces. This is determined while the bean is being designed, and depends on whether the associated search always returns a unique result, or can return multiple entries. Every entity bean is required to include a findByPrimaryKey() method in their home interface. This is a single-object finder that takes the bean’s primary key class as a search parameter. We will talk a little more about the primary key class in the next section. Listing 12.6 contains the source for the QuoteHome interface. LISTING 12.6
import javax.ejb.FinderException; import java.rmi.RemoteException; public interface QuoteHome extends EJBHome { public Quote create(Integer id) throws RemoteException, CreateException; public Quote create(Integer id, String name) throws RemoteException, CreateException;
}
Primary Key Class The primary key class is specific to entity beans. Every entity bean must have a primary key class specified in the deployment descriptor. This is the simplest class involved when writing an entity bean. Many times it is as simple as using the java.lang.Integer class as the primary key. The primary key class contains attributes to uniquely identify one bean from another of the same type. It is the primary key for the entry in the database. There are few specifications for the primary key class. It must be serializable and have a public default constructor. It is also recommended that the class properly implement the hashCode() and equals(Object)() methods. This is to simplify the management of primary keys by both the client and the container. It is possible to use preexisting classes like java.lang.Integer, however you will develop a simple primary key class for the Quote Bean. Its source code is in Listing 12.7. LISTING 12.7
QuotePk.java
import java.io.Serializable; public class QuotePk implements Serializable { public Integer id = null; public QuotePk() { }
12 SERVLETS AND ENTERPRISE JAVABEANS
public Quote findByPrimaryKey(Integer pk) throws RemoteException, FinderException; public Collection findByName(String name) throws RemoteException, FinderException;
210
Servlet Fundamentals PART I
LISTING 12.7
Continued
public QuotePk(int pk) { id = new Integer(pk); } public boolean equals(Object obj) { if (obj instanceof QuotePk) { return id.equals(((QuotePk)obj).id); } else { return false; } } public int hashCode() { return id.hashCode(); } public void setId(Integer id) { this.id = id; } public Integer getId() { return id; } }
It is important to note that the attributes contained in the primary key class must be a subset of the container-managed fields when using container-managed persistence. This enables the container to match up the proper attributes from the bean class to those in the primary key class.
Bean Class This EJB’s bean class contains the business logic of the entity bean. It has similar rules to the bean class for a session bean, just many more of them. It implements all of the business methods from the remote interface. It has methods that match each of the methods in the home interface. There is also a group of callback methods that are used by the container to manage the bean.
Servlets and Enterprise JavaBeans CHAPTER 12
211
The business methods work just like those of the session bean. There must be a method that exactly matches the signature for each method in the remote interface. Your accessor methods should be a breeze. The methods that correspond to those in the home interface have rules slightly different when dealing with a bean written with bean-managed persistence versus container-managed persistence. Because the Quote Bean you are writing is a container-managed bean I will focus on those concepts.
NOTE For the Quote example in this chapter, you will manually supply a primary key during creation. This is not necessarily a good technique to use. Many algorithms and design patterns can be used to obtain a primary key for entity bean creation.
Another method is required in the creation process for entity beans. There must be an ejbPostCreate() method with the same parameter list as each of the ejbCreate() methods. This method is used in case any processing is required after the database insert is complete and before the client has access to the bean. You have now created the entity bean and have a new entry in the database. What happens when a client wants to find this entry later? There is a finder method in the home interface that the client will call, and because you are implementing a container-managed bean, you do not have to write any more code. You will define the select criteria during deployment to the application server. Writers of bean-managed beans must provide ejbFind<method> methods in the Bean class to perform the database query. The source code for the QuoteBean is included in Listing 12.8. LISTING 12.8 import import import import
Creation, as you have seen, inserts an entry into the database. There is still a matching ejbCreate() method for each create() method in the home interface. In this method all of the bean attributes must be initialized based on the parameters passed in. With containermanaged persistence, the database insert will be processed after the ejbCreate() method, so if the container-managed fields are not initialized properly the insert will reflect the corrupt data. At a minimum, the fields representing the primary key must be initialized. A bean written with bean-managed persistence must complete the database insert inside the ejbCreate().
212
Servlet Fundamentals PART I
LISTING 12.8
Continued
public class QuoteBean implements EntityBean { protected EntityContext ctx = null; public public public public public public
A unique note on the ejbCreate() methods in a container-managed entity bean: Notice that it returns null. This return value is actually ignored by the container, but it must return a value so that the method signature matches that of a bean-managed bean. This way it is easier to switch between the two methods of persistence, so that all of the bean classes appear to be the same. You also see several callback methods that were not present in the session bean class, ejbLoad() and ejbStore(). You might be able to guess what these methods do by their names. Each of these methods is more important when dealing with a bean-managed bean, however we will discuss them further in the section dealing with the lifecycle of entity beans, “Entity Bean Life Cycle.” The Quote Bean class is a very simple container-managed bean. We have looked at some of the basic concepts involved in writing an entity bean; however, to develop an enterprise-level system using EJB there is much more information required.
Deployment Descriptor Writing the deployment descriptor for an entity bean is similar to doing so for a session bean. The concept is the same, however the information required for an entity bean is different. The information will go inside of the same ejb-jar.xml file. As a matter of fact all of the deployment information for every EJB that is packaged into one jar file is included in the same ejb-jar.xml file. This includes both session and entity beans.
SERVLETS AND ENTERPRISE JAVABEANS
The class includes all of the information you want to store as a quote entry in the database. Each of the attributes in this class is a container-managed field. When you deploy the bean, you will have to map each of these attributes to a field in the database. Also, it is important to know that every container-managed field must be specified as a public attribute. This is so that the container can handle them directly. This breaks some important encapsulation rules that are generally followed in object-oriented (OO) design, however, because clients always access this class through a remote interface, and it is not accessible to any code directly, it is all right to declare the attributes as public.
12
216
Servlet Fundamentals PART I
An <entity> entry in the structural section defines the makeup of the entity bean. The structural information for our Quote Bean is listed in the following code snippet: <entity> <description> Describes a persistent quote. <ejb-name>Quote QuoteHome Quote <ejb-class>QuoteBean <prim-key-class>QuotePk Container False id customerName phoneNumber loanAmount monthlyPayment nterestRate
There are a couple of additions here. The first is the declaration of the primary key class. Just like the other class declarations, this is the fully qualified Java classname for the primary key class. The entry for persistence type must be present and specified whether the given entity bean’s persistence is container-managed or bean-managed. We discussed the difference between these two in the earlier section, “Who Handles the Persistence?” The two possible values of for this entry are Container and Bean. Because you have decided to let the container manage the persistence for the Quote bean, you must tell the container which fields in the entity bean it is required to manage. Each of these attributes is declared inside the container-managed persistence entry, . If you remember, each of these attributes was declared as public in the bean class so that the container has access to it. A concept that we have not discussed yet is reentrance. The Quote Bean is defined as nonreentrant by specifying the false value for the tag. Reentrance defines whether the entity bean can be looped back into during the same execution context. An example of reentrance would be: A client makes a call to entity bean A, bean A then invokes a method in bean B, and bean B tries to invoke a method in bean A and reenter it. When developing beans deployed to enable reentrance, take this multithreading into consideration. If reentrance is denied in the deployment descriptor, an exception will be thrown if the system tries to reenter an object.
Servlets and Enterprise JavaBeans CHAPTER 12
217
As with session beans, you can also define quite a bit about how the container should manage the entity bean in the application. This information is placed in the section that defines application-assembly information. Here you can define transactional attributes, set up client roles, and assign permissions to bean methods, among other things.
Client View of an Entity Bean The client of an entity bean is similar to the client to a session bean. The same statement can be used to look up the home interface for the entity bean that you would like to use.
Creation is an acceptable option for any entity bean that is not defined as read-only. Searching by use of finder methods is always an option. Every entity bean defines a findByPrimaryKey() method that enables the client to find a specific bean instance by its unique identifier. Other finder methods can also be defined that search based on other criteria. With the creation methods, the remote interface for the new bean instance is returned from the method. Remember that finder methods can be defined to return either a single remote interface or a collection of remote interfaces. The following code snippet gives an example of finding an entity bean: Context initialContext = getInitialContext(); QuoteHome quoteHome = (QuoteHome)javax.rmi.PortableRemoteObject.narrow( initialContext.lookup(“Quote”), QuoteHome.class); Quote = quoteHome.findByPrimaryKey(new QuotePk(1));
After the client has hold of a remote interface for an entity bean, it is business as usual. At this point the client can invoke methods that access the entity bean’s business logic. In many cases, these method calls represent database updates.
Entity Bean Life Cycle The life cycle for an entity bean instance is unique. Like session beans, it is driven by both client activity and actions performed by the application server. An entity bean instance can exist in three states. The first state is the does not exist state. This is the state before the application server has started. When the application server starts it will create a pool of entity beans. The number of pooled beans is configurable during deployment. The bean instance will sit in the pooled state until it is needed.
12 SERVLETS AND ENTERPRISE JAVABEANS
After you have the home interface, major differences appear to the client. There are more ways to obtain remote interfaces for an entity bean. Not only are there creation methods that enable you to create a new entity bean, there are finder methods that allow you to look up existing information from the persistent storage.
218
Servlet Fundamentals PART I
A bean instance will be moved into the ready state when a client makes a call to one of the create() methods in the home interface. In the ready state, the bean instance is available to the client for use. As with session beans, there is instance sharing of entity bean instances. They can be moved in and out of the pooled state when the application server feels it is acceptable to share the bean instance with another client. The application server uses the same processes of passivation and activation that it does when dealing with session beans. Next we need to talk about persistence. As we have discussed, an entity bean is tied to an entry in a database. When an instance of an entity bean is used during a transaction, it must be stored to the database. There are also times when the instance needs to be filled with the information it represents in the database. The timing of these stores and loads is up to the application server. For loading and storing the persistent information you must implement the ejbLoad() and ejbStore() methods. As their names indicate, ejbLoad() loads information from the database into the bean instance and ejbStore() stores the information back to the database. For bean-managed beans the ejbStore() and ejbLoad() methods are very important. It is here that the developer must provide the update and select SQL statements. For any container-managed bean these methods provide the capability to do any processing of the data before it is stored or after it is loaded. The application server will call ejbStore() immediately before it stores the container-managed fields to the database. Consequently, it will also call ejbLoad() immediately after loading the information into the bean instance again. We have left these two methods empty because there is no processing required for the Quote Bean.
Deploying Your EJB to Your Application Server The process of deploying your Enterprise JavaBeans is not regulated by any specification, so it is usually different for each application server. There are, however, some concepts that are the same.
Packaging the jar File First is packaging all of your classes and the deployment descriptor in a jar file. As we have discussed before, all of the beans that are described in the ejb-jar.xml deployment descriptor will be included within one jar file. Archive all of the class files as well as the ejb-jar.xml file into a jar file. The ejb-jar.xml file belongs in the meta-inf directory in the archive. Many existing application servers provide a graphical deployment tool. Each one will appear differently. One of the major steps that is taken when deploying your jar file to any application server is to run the EJB compiler over it. In many cases, the application server does this during the process of using its deployment tool. However, many developers choose to handle this during the build process of their beans. The EJB compiler will create all of the necessary clientand server-side classes required to process the remote-method invocations.
Servlets and Enterprise JavaBeans CHAPTER 12
219
The instructions provided here are for deploying to Allaire JRun 3.0. Instructions for installing JRun are found at the beginning of this chapter, in the section “Installing JRun.” JRun configures all of its bean information by using a property file. This can be done with a separate file for each bean. These property files can include all of the necessary information, to the point where the standard ejb-jar.xml file is not necessary. An alternate route is to include each of the properties as an environment property in the ejb-jar.xml deployment descriptor.
The database mappings for the container-managed Quote Bean is the most important information you have. This information is always defined differently when deploying to application servers. JRun requires you to write a SQL statement and bind the bean’s attributes to the SQL statement. A different SQL statement is required for each type of database transaction: creation, loading, storing, and finding. The following code snippet contains an example for your load method. This is the database transaction that will be called when ejbLoad() is invoked by the container and the bean is to be loaded from the information in the database. ejipt.loadSQL= SELECT name, phone, amount, pmt, rate FROM quote WHERE id = ? ejipt.loadSQL.source= bookDataSource ejipt.loadSQL.params= id ejipt.loadSQL.paramTypes= INTEGER ejipt.loadSQL.fields= customerName, phoneNumber, loanAmount, monthlyPayment, interestRate
This block of properties includes all of the information necessary to load a Quote Bean from the database. It also defines which fields to load with the information returned from the query. The list of properties that JRun accepts is quite extensive. After this property file is completed for each bean, include it in the jar file.
NOTE You might wonder about the benefits of container-managed persistence if you still have to write SQL. There are many pros and cons of both ways of persistence management, but here all you must do is change a properties file to change the database mapping or data source.
12 SERVLETS AND ENTERPRISE JAVABEANS
We will split the difference and use a combination of these two methods. Your deployment descriptor will include all of the standard information, enabling you to deploy the beans to any compliant application server. You will also include a property file for the other information to configure JRun. This information goes in a file named .properties; for the Quote Bean the file name is Quote.properties.
220
Servlet Fundamentals PART I
Deploying the jar File Now you are ready to deploy your jar file. Start JRun’s administration server, and bring up the administration application. Log in to the application using the username and password that you set up during installation. On the left side of the window, expand the entry in the tree for JRun Default Server. Select the link at the bottom of the tree for Enterprise JavaBeans. The main window now displays the main page for the EJB tool. On this page you can select the option for deployment, which then brings up the page for deploying EJB jar files. Click the Browse button and choose the jar file that contains your EJBs. Also make sure that the selection under JRun Server Name is JRun Default Server. You will use a large text box for placing deployment properties to deploy a data source to the container. This is the data source that the entity beans will use to interact with the database. The data source must be set up on your system and be associated with a valid database. On Microsoft Windows systems, you can add a data source by using the Data Sources (ODBC) tool under the Control Panel|Administrative Tools. Add the following code snippet to JRun’s Deploy Properties text box: bookDataSource.ejipt.sourceURL=jdbc:odbc:bookDataSource bookDataSource.ejipt.sourceUser= bookDataSource.ejipt.sourcePassword= ejipt.jdbcSources=bookDataSource
The name of the data source, bookDataSource, is also the name specified for all of the SQL statements in the individual bean’s properties files. Now everything is ready for deployment. Click the Deploy button and wait. It takes a moment for the EJB compiler to be run and for everything to be packaged. After it is finished you will receive a message in red text on the left side of the page. Hopefully it tells you that deployment was successful. After you have successfully deployed the beans, you must restart the JRun server.
Viewing Deployed Beans Now that your Enterprise JavaBeans are deployed, you can view all of the deployment information associated with each bean by expanding the navigation tree in the left panel of the administration application. Expand the entry titled Enterprise JavaBeans, and it will list all of your deployed beans. Select the bean you want to view and all of the information will appear in the main window.
Servlets as EJB Clients Listing 12.9 contains the source for a simple servlet that accepts the necessary parameters, calculates the monthly loan payment, and then stores the quote to the database.
/**Process the HTTP Get request*/ public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Get all of the information from the request. Integer months = new Integer(request.getParameter(“months”)); Float principal = new Float(request.getParameter(“principal”)); String custName = request.getParameter(“name”); String phoneNumber = request.getParameter(“phone”); Float payment = null; Float interestRate = null; CalculateLoanHome clHome = null; CalculateLoan cl = null; QuoteHome quoteHome = null; Quote quote = null; try { // Lookup the home interface for the CaluclateLoan Bean Object obj = ctx.lookup(“CalculateLoan”); clHome = (CalculateLoanHome) PortableRemoteObject.narrow(obj, Class.forName(“CalculateLoanHome”)); // Create a new remote interface cl = clHome.create(); // Calculate the monthly payment and get the // current interest rate. payment = cl.calcMonthlyPayment(months, principal); interestRate = cl.getCurrentInterestRate(); // Lookup the home interface for the Quote Bean obj = ctx.lookup(“Quote”); quoteHome = (QuoteHome) PortableRemoteObject.narrow(obj, Class.forName(“QuoteHome”)); // Insert a new Quote into the database with the id of ‘1’ quote = quoteHome.create(new Integer(1)); // Update the database entry with all // of the necessary information.
Servlets and Enterprise JavaBeans CHAPTER 12
LISTING 12.9
223
Continued quote.setCustomerName(custName); quote.setPhoneNumber(phoneNumber); quote.setLoanAmount(principal); quote.setMonthlyPayment(payment); quote.setInterestRate(interestRate);
} catch (ClassNotFoundException ex) {
throw new ServletException(ex); } catch (CreateException ex) { throw new ServletException(ex); } catch (RemoteException ex) { throw new ServletException(ex); } // Create a simple screen as output from the servlet. response.setContentType(CONTENT_TYPE); PrintWriter out = response.getWriter(); out.println(“”); out.println(“EJBTestServlet”); out.println(“”); out.println(“
”); out.println(“The current interest rate is: “ + interestRate + “ ”); out.println(“For the loan amount of: “ + principal + “ ”); out.println(“Your monthly payment will be: “ + payment + “ ”); out.println(“
”); out.println(“”); }
/**Clean up resources*/ public void destroy() {
12 SERVLETS AND ENTERPRISE JAVABEANS
throw new ServletException(ex); } catch (NamingException ex) {
To see this servlet in action, compile and copy the EJBTestServlet to the <SERVER_ROOT>/servers/default/default-app/WEB-INF/classes directory and open your browser to the following URL: http://localhost/servlet/EJBTestServlet?months=360& principle=250000&name=Bob&phone=(303)555-1212
Summary Enterprise JavaBeans are a very robust and scalable option for building the business logic and persistence layers for your Web application. They provide the ability to easily distribute the application without making any code changes. If it is architected correctly, the application’s infrastructure is easily changed with a simple redeployment. This chapter is a beginning look at Enterprise JavaBeans. EJBs are quite powerful and hopefully you now have enough knowledge to further your understanding and develop enterprise level applications using Enterprise JavaBeans. In the next chapter you will create a Controller servlet that will be at the core of our case studies.
CHAPTER
A Servlet Controller
13
IN THIS CHAPTER • What Is a Controller? • A Servlet Controller
226 226
• The Service Interface • A Sample Service
230
229
226
Servlet Fundamentals PART I
What Is a Controller? As we described in Chapter 1, “Web Applications and the Model View Controller (MVC) Design Pattern,” a Controller defines the way the user interface reacts to the user’s input. For our purposes the Controller is the heart of our Web applications. The Controller is what determines how your incoming requests are handled.
A Servlet Controller You will be implementing your Controller as a servlet. It will act as a factory to instantiate a class that is determined by the request. We call these instantiated classes Services. They will be further defined in the next section. To create your servlet Controller, you need to create a servlet that takes the incoming request, parses the named Service, executes the created Service, and then forwards the results to a target that is also included on the request. An example of a request containing these elements is listed below: http://localhost/djs/servlet/Controller?service=Search&target=/ ➥searchresults.jsp
This requests that the Service Search be executed and the results be forwarded to the searchresults.jsp page. Now let’s define a servlet that will represent this Controller. Listing 13.1 contains the source for your Controller servlet. LISTING 13.1 import import import import
public class Controller extends HttpServlet { /** * */ public void init(ServletConfig config) throws ServletException { super.init(config); } /** The forward method forwards the results of the Service to the passed in target. @throws VSException if an IOException or ServletException is thrown by the RequestDispatcher.
/** Services all requests for the controllers. It expects a request parameter, service, specifying the name of the transaction that is to be executed. * @param request the ServletEngine created HttpServletRequest. @param response the ServletEngine created HttpServletResponse. @throws ServletException if an Exception is not handled by the ➥web application. @throws IOException if there is an IO error during the request. */ public void doPost(HttpServletRequest request, HttpServletResponse response)
13 A SERVLET CONTROLLER
/** Calls the doPost() with the request and response. * @param request the ServletEngine created HttpServletRequest. @param response the ServletEngine created HttpServletResponse. @throws ServletException if an Exception is not handled by the ➥web application. @throws IOException if there is an IO error during the request. */ public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { doPost(request, response); }
228
Servlet Fundamentals PART I
LISTING 13.1
Continued
throws ServletException, IOException { // Get the name of the Transaction to perform String serviceName = request.getParameter(“service”); if (serviceName == null) { throw new ServletException(“No service named!”); } // Get the target of the request String target = request.getParameter(“target”); if (target == null) { throw new ServletException(“No target named!”); } ServletContext context = getServletContext(); // Create and execute an instance of the named service try { // Create an instance of the fully qualified Service Class Class cls = Class.forName(serviceName); Service service = (Service)cls.newInstance(); // Execute the Transaction service.execute(request, response, context); } catch (ClassNotFoundException ce) { throw new ServletException(ce.getMessage()); } catch (IllegalAccessException iae) { throw new ServletException(iae.getMessage()); } catch (Exception e) { throw new ServletException(e.getMessage()); } // Forward the results forward(request, response, target); } }
We need to discuss two sections of the Controller class. The first is the heart of the class, which is contained in the following code snippet: // Create and execute an instance of the named service try { // Create an instance of the fully qualified Service Class Class cls = Class.forName(serviceName);
A Servlet Controller CHAPTER 13
LISTING 13.1
229
Continued
Service service = (Service)cls.newInstance(); // Execute the Transaction service.execute(request, response, context); }
This section of code acts as a Service factory. It parses the service parameter of the request and creates the class dynamically by creating a new instance of the Service class using its physical name. It then calls the execute() method which, as you will see in the next section, is a method defined in the Service interface. This is where the business logic will exist. The second section of the Controller that we need to examine is the forward() method. It is used to pass the results of the executed Service to a JSP for viewing. The key logic in the forward method can be found in the following code snippet:
In this section the Controller creates a RequestDispatcher object and calls its forward() method, passing it the request and response objects and the targeted JSP for viewing.
The Service Interface Now that we have defined the Controller, let’s define the Service interface that will act as the prototype of all services. For this interface you will have a single method, execute(), that accepts the necessary parameters to receive and pass HTTP objects to and from the browser. The listing for the Service can be found in Listing 13.2. LISTING 13.2
Service.java
import javax.servlet.http.HttpServletRequest; import javax.servlet.http.HttpServletResponse; import javax.servlet.ServletContext; /** An interface that provides the base functionality for all Services.
To implement a Service, the execute() method is the only method that must be implemented. * */ public interface Service { /** Single method to become a service. * @throws Exception if any exceptions need to be thrown back to the calling Controller. */ public void execute(HttpServletRequest request, HttpServletResponse response, ServletContext context) throws Exception; }
As you can see, the Service interface contains a single method that takes an HttpServletRequest, HttpServletResponse, and a ServletContext. Now you can add a new Service by simply implementing the Service’s execute() method.
A Sample Service To see how easy this model is to extend, let’s add a sample Service. The source for this sample Service can be found in Listing 13.3. LISTING 13.3 import import import import
/** SearchService - This class provides an example of how to add a Service. It must implement the Servlet interface. */ public class ExampleService implements Service { /** Empty constructor. */ public ExampleService() {
A Servlet Controller CHAPTER 13
LISTING 13.3
231
Continued
} /** This method is the implementation of the parents interface’s execute() method. It contains the core functionality of a Service. */ public void execute(HttpServletRequest request, HttpServletResponse response, ServletContext context) throws Exception { // Do Something Here request.setAttribute(“example”, “Example Value”); } }
The only thing you need to notice about this class is that it does implement the Service’s execute() method. In this implementation it simply adds an attribute to the request with a key of example and a value of Example Value.
LISTING 13.4
ExampleView.jsp
<TITLE> Example View Example JSP View The value added to the request was
A SERVLET CONTROLLER
To see this Controller in action, you will need to compile the Controller.java, and ExampleService.java files and move the resulting class files into the <SERVER_ROOT>/djs/WEB-INF/classes directory. After you have the Controller and its necessary support files you need to create a simple JSP that acts as the view. We have not yet covered JSPs, but Listing 13.4 contains a simple JSP that outputs the request attribute example and its value. Service.java,
13
232
Servlet Fundamentals PART I
Now copy this JSP to the <SERVER_ROOT>/djs directory and open your browser to the following URL, broken here onto two lines: http://localhost/djs/servlet/Controller?service=ExampleService&target= ➥/ExampleView.jsp
You should see a screen similar to Figure 13.1.
FIGURE 13.1 Output from our ExampleService.
Summary This chapter covered the Controller part of our server-side implementation of the MVC. This class will be at the core of all of our case studies at the end of this text. In the next chapter, we will begin our study of JavaServer Pages (JSPs), starting with an overview of the JSP architecture.
JSP Fundamentals
IN THIS PART 14 JSP Overview and Architecture 15 JSP Implicit Objects 16 JSP Standard Actions 17 Using JavaBeans and JSP Scopes 18 Handling JSP Errors 19 Custom JSP Tag Libraries
PART
II
JSP Overview and Architecture
IN THIS CHAPTER • What are JavaServer Pages?
236
• The Components of a JavaServer Page
237
CHAPTER
14
236
JSP Fundamentals PART II
What are JavaServer Pages? JavaServer Pages, also known as JSPs, are a simple but powerful technology used to generate dynamic HTML on the server side. They are a direct extension of Java servlets and provide a way to separate content generation from content presentation. The JSP engine is just another servlet that is mapped to the extension *.jsp. The following code contains a simple example of a JSP file:
Its output would look similar to Figure 14.1.
FIGURE 14.1 Output of the JSP example.
You can see that this document looks like any other HTML document with some added tags containing Java code. The source code is stored in a file called HelloJSPWorld.jsp and copied to the document directory of the Web server. When a request is made for this document, the server recognizes the *.jsp extension and realizes that special handling is required. The first
JSP Overview and Architecture CHAPTER 14
237
time the file is requested, it is compiled into a servlet object and stored in memory and the output is sent back to the requesting client. After the first request, the server checks to see whether the *.jsp file has changed. If it has not changed, then the server invokes the previously compiled servlet object. In this chapter and the next five chapters, we will be discussing how JSPs work and how to use them. We will focus strictly on using JSPs as Views, as we discussed in Chapter 1, “Web Applications and the Model View Controller (MVC) Design Pattern.” Figure 14.2 shows the steps of a JSP request graphically. 1. The client requests a JSP page.
Web Server
2. The JSP engine compiles the JSP into a servlet.
JSP Page
1. Request
Web Browser
2.
Generated Servlet 3. 4. Response Compiled Servlet
3. The generated servlet is compiled and loaded. 4. The compiled servlet services the request and sends a response back to the client.
FIGURE 14.2 The steps of a JSP request.
In this section we cover the components that make up a JavaServer page. Each is discussed in detail in the following sections.
AND
The Components of a JavaServer Page
JSP OVERVIEW
A key thing to remember about JSPs is that they are just servlets that are created from a combination of HTML text and Java source code. This means that they contain all the functionality of a normal servlet.
ARCHITECTURE
NOTE
14
238
JSP Fundamentals PART II
Directives Directives are JSP elements that provide global information about an entire JSP page. An example would be a directive that indicated the language to be used in compiling a JSP page. The syntax of a directive is as follows:
This states that, for this page directive, assign these values for these attributes. A directive can contain n number of optional attribute/value pairs. If we use our previous example for indicating the JSP language, the following line of code would indicate that the JSP language to use would be Java:
Three possible directives are currently defined by the JSP specification: page, include, and taglib. Each one of these directives and their attributes, if applicable, are defined in the following sections.
The page Directive The page directive defines information that will be globally available for that JavaServer page. These page level settings will directly affect the compilation of the JSP. Table 14.1 defines the attributes for the page directive.
NOTE Because the mandatory attributes are defaulted, you are not required to specify any page directives.
TABLE 14.1
The Attributes for the page Directive
Attribute
Definition
language=”scriptingLanguage”
This attribute tells the server what language will be used to compile the JSP file. Currently Java is the only available language. This attribute defines the parent class that the JSP generated servlet will extend from. This attribute defines the list of packages that will be available to this JSP. It will be a comma-separated list of package names.
extends=”className” import=”importList”
JSP Overview and Architecture CHAPTER 14
TABLE 14.1
239
Continued
Attribute
Definition
session=”true|false”
This attribute determines whether the session data will be available to this page. The default is true. This attribute determines whether the output stream is buffered. The default value is 8KB. This attribute determines whether the output buffer will be flushed automatically, or whether an exception will be raised when the buffer is full. The default is true, which states that the buffer should be flushed automatically.
This attribute tells the JSP engine that this page can service more than one request at a time. By default this value is true; if false, the SingleThreadModel is used. This attribute represents information about the JSP page that can be accessed by the page’s Servlet.getServletInfo() method. This attribute represents the relative URL to the JSP page that will handle exceptions. This attribute states whether or not the JSP page is an errorPage. The default is false. This attribute represents the MIME type and character set of the response.
The include Directive
NOTE Currently the JSP 1.1 specification does not have a defined method for notifying the JSP engine that the included JSP file has changed.
AND
The file that the file attribute points to can reference a normal text HTML file or it can reference a JSP file, which will be evaluated at translation time.
JSP OVERVIEW
ARCHITECTURE
The include directive is used to insert text and/or code at JSP translation time. The syntax of the include directive is as follows:
14
240
JSP Fundamentals PART II
The taglib Directive The most recent version of the JSP specification defines a mechanism for extending the current set of JSP tags. It does this by creating a custom set of tags called a tag library. That is what the taglib points to. The taglib directive declares that the page uses custom tags, uniquely names the tag library defining them, and associates a tag prefix that will distinguish usage of those tags. The syntax of the taglib directive is as follows:
The taglib attributes are described in Table 14.2. TABLE 14.2
The Attributes for the taglib Directive
Attribute uri prefix
Definition This attribute references a URI that uniquely names the set of custom tags. This attribute defines the prefix string used to distinguish a custom tag instance.
Standard Actions JSP standard actions provide an abstraction that can be used to easily encapsulate common tasks. They typically create or act on objects, normally JavaBeans. The JSP technology provides some standard actions. These actions are briefly defined in the following list; we’ll explore them in more detail in Chapter 16, “JSP Standard Actions”: •
<jsp:useBean>
•
<jsp:setProperty>
The <jsp:useBean> action associates an instance of a JavaBean defined with a given scope and ID, using a newly declared scripting variable of the same ID. The <jsp:setProperty> action sets the value of a bean’s
property. The <jsp:getProperty> action takes the value of the referenced bean instance’s property, converts it to a java.lang.String, and places it into the implicit out object.
•
<jsp:getProperty>
•
<jsp:include>
•
<jsp:forward>
The <jsp:include> action provides a mechanism for including additional static and dynamic resources in the current JSP page. The <jsp:forward> action enables the JSP engine to dispatch, at runtime, the current request to a static resource, servlet, or another JSP.
JSP Overview and Architecture CHAPTER 14
•
<jsp:param> The <jsp:param> action is used to provide tag/value pairs of information, by including them as sub-attributes of the <jsp:include>, <jsp:forward>, and <jsp:plugin> actions.
•
<jsp:plugin>
241
The <jsp:plugin> action gives a JSP author the ability to generate HTML that contains the appropriate client browser–dependent constructs.
Implicit Objects When you write JSPs, you can use several implicit objects in JSP documents without declaring them first. Table 14.3 lists the implicit objects provided by the JSP architecture. Each of these implicit objects has a class or interface type defined in a core Java Development Kit (JDK) or Java Servlet Development Kit (JSDK). We’ll discuss JSP’s implicit objects in greater detail in Chapter 15, “JSP Implicit Objects.” TABLE 14.3
The JSP Implicit Objects
Implicit Variable application
Type
Description
Scope
javax.servlet.Servlet Context
Represents the servlet Application context returned from a call to getServletConfig(). getContext()
config
javax.servlet.Servlet Config
exception
java.lang.Throwable
java.lang.Object
pageContext
javax.servlet.jsp. PageContext
request
Protocol-dependent subtype of either javax.servlet.Servlet Request or javax. servlet.HttpServlet Request
14 Page Page
Page Request
AND
page
Page
JSP OVERVIEW
javax.servlet.jsp. JspWriter
Page
ARCHITECTURE
out
Represents the Servlet Config for this JSP Represents the uncaught Throwable that resulted from a call to the error page Represents the JspWriter object to the output stream Represents the this object for this instance of the JSP Represents the page context for the JSP Represents the request object that triggered the request
242
JSP Fundamentals PART II
TABLE 14.3
Continued
Implicit Variable response
Type
Description
Scope
Protocol-dependent subtype of either
Represents the response object that triggered the request
Page
Represents the session object, if any, created for the client during an HTTP request
Session
javax.servlet. ServletResponse or javax.servlet. HttpServletResponse session
javax.servlet. http.HttpSession
JSP Scripting JSP scripting is a mechanism for embedding code fragments directly into an HTML page. Three scripting language elements are involved in JSP scripting. Each of these JSP scripting elements has its appropriate location in the generated servlet. In this section we will look at these elements and how together they will result in a complete servlet.
Declarations JSP declarations are used to declare variables and methods in the scripting language used in a JSP page. A JSP declaration should be a complete declarative statement. JSP declarations are initialized when the JSP page is initialized. After the declarations have been initialized, they are available to other declarations, expressions, and scriptlets. The syntax for a JSP declaration is as follows:
A sample variable declaration using this syntax is declared here:
A sample method declaration using the same syntax is declared as follows:
JSP Overview and Architecture CHAPTER 14
243
To get a better understanding of declarations, let’s take the previous string declaration and actually use it to create a JSP document. The sample document would look similar to the following code snippet:
When this document is initially requested, the JSP code is converted to servlet code and the previous declaration is placed in the declaration section of the generated servlet. The Declarations section of the generated servlet would look similar to the following code snippet: // begin [file=”D:\\Declarations.jsp”;from=(3,3);to=(3,37)] String name = new String(“BOB”); // end
Expressions JSP expressions are elements in a scripting language that are evaluated with the result being converted to a java.lang.String. After the string is converted, it is written to the current out JspWriter object. JSP expressions are evaluated at HTTP request time, with the resulting string being inserted at the expression’s referenced position in the .jsp file. If the resulting expression cannot be converted to a string then a translation time error will occur. If the conversion to a string cannot be detected during translation, a ClassCastException will be thrown at request time. The syntax of a JSP expression is as follows:
To get a better understanding of expressions, let’s take this snippet and insert it into a simple JSP document. The sample document would look similar to the following code snippet:
AND
Hello
JSP OVERVIEW
A code snippet containing a JSP expression is shown here:
14 ARCHITECTURE
244
JSP Fundamentals PART II Hello
When this document is initially requested, the JSP code is converted to servlet code and the previous expression is resolved and placed in its referenced location of the generated servlet’s _jspService() method. The generated servlet would look similar to the following code snippet: // begin out.write(“\r\n\r\n\r\n”); // end // begin out.write(“\r\n”); // end // begin out.write(“\r\n\r\nHello ”); // end // begin [file=”D:\\Expressions.jsp”;from=(6,12);to=(6,23)] out.print( getName() ); // end // begin out.write(“\r\n\r\n\r\n\r\n”); // end
Scriptlets Scriptlets are what bring all the scripting elements together. They can contain any coding statements that are valid for the language referenced in the language directive. They are executed at request time and they can make use of declarations, expressions, and JavaBeans. The syntax for a scriptlet is as follows:
During the initial request, the JSP scripting code is converted to servlet code and then compiled and loaded into resident memory. The actual source code, which is found between scriptlet tags , is placed into the newly created servlet’s _jspService() method. See the following sample JSP source:
JSP Overview and Architecture CHAPTER 14
245
It has a very simple scriptlet section that will print HELLO JSP WORLD to the JspWriter implicit object out. The actual servlet code, resulting from the initial request, would look similar to the following code snippet: public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { JspFactory _jspxFactory = null; PageContext pageContext = null; HttpSession session = null; ServletContext application = null; ServletConfig config = null; JspWriter out = null; Object page = this; String _value = null; try { if (_jspx_inited == false) { jspx_init(); jspx_inited = true; } jspxFactory = JspFactory.getDefaultFactory(); response.setContentType(“text/html”); pageContext = _jspxFactory.getPageContext(this, request, response, “”, true, 8192, true);
AND
JSP OVERVIEW
// begin out.write(“\r\n\r\n\r\n”); // end // begin [file=”D:\\HelloJsp.jsp”;from=(3,2);to=(3,35)] out.println(“HELLO JSP WORLD”); // end // begin out.write(“\r\n\r\n\r\n\r\n”); // end
JSP Fundamentals PART II } catch (Exception ex) { if (out.getBufferSize() != 0) out.clear(); pageContext.handlePageException(ex); } finally { out.flush(); jspxFactory.releasePageContext(pageContext); } }
You don’t need to dig too deeply into this code, because it is generated for you. You just need to understand that it is being generated by the JSP engine and is the JSP equivalent to a servlet’s service() method. It is also important to know that the JSP engine creates a servlet equivalent to the init() and destroy() methods.
Summary In this chapter we covered quite a bit of information. We also covered the basics of JSP and the components of JSPs. You now should be able to create a JSP document and understand what is happening behind the scenes during request time. You should also understand the process a JSP file goes through when it is first requested. In the next chapter we will discuss the implicit objects available in the JSP architecture.
CHAPTER
JSP Implicit Objects
15
IN THIS CHAPTER • What are Implicit Objects? • The request Object
249
• The response Object
250
• The pageContext Object • The session Object
251
252
• The application Object • The out Object
254
257
• The config Object • The page Object
248
258 260
• The exception Object
260
248
JSP Fundamentals PART II
What are Implicit Objects? As a JSP author, you have access to certain objects that are available for use in JSP documents without being declared first. These objects are parsed by the JSP engine and inserted into the generated servlet as if you defined them yourself. In reality the JSP engine recognizes the implicit object names and knows that they will be declared by, or passed into, the generated servlet. The following code is an example of a code snippet containing a _jspService() method. As we continue with the rest of this chapter, we will examine exactly where in this code each of the implicit objects is declared. We will also look at examples, where applicable, of how you can use each one of these objects. public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { JspFactory _jspxFactory = null; PageContext pageContext = null; HttpSession session = null; ServletContext application = null; ServletConfig config = null; JspWriter out = null; Object page = this; String _value = null; try { if (_jspx_inited == false) { _jspx_init(); _jspx_inited = true; } _jspxFactory = JspFactory.getDefaultFactory(); response.setContentType(“text/html”); pageContext = _jspxFactory.getPageContext(this, request, response, “errorpage.jsp”, true, 8192, true); application = pageContext.getServletContext(); config = pageContext.getServletConfig(); session = pageContext.getSession(); out = pageContext.getOut(); // begin out.write(“\r\n\r\n\r\n \r\n “JSP\r\n \r\n \r\n
Hello “ + “);
JSP Implicit Objects CHAPTER 15
249
// end // begin [file=”D:\\hello.jsp”;from=(7,6);to=(10,4)] // Print a simple message in the client area. out.println(“Hello!”); // end // begin out.write(“\r\n // end
NOTE To run these examples, you will need to copy the JSP files from each of the following listings to the <SERVER_ROOT>/djs/ directory.
The request Object The implicit object request represents the javax.servlet.http.HttpServletRequest object that is passed into the generated _jspService() method. The HttpServletRequest interface defines an object that provides access to HTTP-protocol–specific header information sent by the client. You can see how it is passed in the following code snippet:
JSP IMPLICIT OBJECTS
public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
15
250
JSP Fundamentals PART II
One of the more common uses for the request object is to access request parameters. You can do this by calling the request object’s getParameter() method, which is inherited from its parent javax.servlet.ServletRequest, with the parameter name you are looking for. It will return a string with the value matching the named parameter. An example of this can be found in Listing 15.1. LISTING 15.1
UseRequest.jsp
UseRequest
You can see that this JSP calls the request.getParameter() method passing in the parameter user. This method looks for the key user in the parameter list and returns the value, if it is found. Enter the following URL into your browser to see the results from this page: http://localhost/djs/UseRequest.jsp?user=Bob
After loading this URL, you should see a screen similar to Figure 15.1.
The response Object The JSP implicit object response represents the javax.servlet.http.HttpServletResponse object, which defines an object that provides the JSP with the capability to manipulate HTTPprotocol–specific header information and return data to the client. The response object is passed into the generated _jspService() method. You can see how it is passed in the following code snippet: public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException {
The most common use for the response object is writing HTML output back to the client browser. You would normally call the response.getWriter() method, but the JSP API abstracts you from this by providing the implicit out object, which will be discussed in a later section of this chapter.
JSP Implicit Objects CHAPTER 15
251
FIGURE 15.1 Output from UseRequest.jsp.
The pageContext Object The pageContext object provides access to the namespaces associated with a JSP page. It also provides accessors to several other JSP implicit objects. An instance of an implementation-dependent pageContext is created by a JSP implementation class at the beginning of the generated servlet’s _jspService() method. It is created through an implementation-dependent JspFactory. An example of the pageContext object’s creation and its use in the creation of other implicit objects is shown in the following code snippet: pageContext = _jspxFactory.getPageContext(this, request, response, “errorpage.jsp”, true, 8192, true); application = pageContext.getServletContext(); config = pageContext.getServletConfig(); session = pageContext.getSession(); out = pageContext.getOut();
JSP IMPLICIT OBJECTS
You can see by examining the previous code snippet that the pageContext is used often in the generated servlet. However it is not often used directly in a JavaServer page. The exception to this is in the creation of custom tags, which we will examine in Chapter 19, “Custom JSP Tag Libraries.”
15
252
JSP Fundamentals PART II
The session Object The implicit session object holds a reference to a javax.servlet.http.HttpSession object. The HttpSession object is used to store objects between client requests. It provides an almost state-full HTTP interactivity. The session object is initialized by a call to the pageContext.getSession() method in the generated servlet. The code snippet that initializes the session is as follows: session = pageContext.getSession();
An example of using the implicit session object can be found in Listing 15.2. LISTING 15.2
UseSession.jsp
UseSession
JSP Implicit Objects CHAPTER 15
253
You should now move this JSP to the <SERVER_ROOT>/djs/ directory and open your browser to the following URL: http://localhost/djs/UseSession.jsp
You should see a page similar to Figure 15.2.
FIGURE 15.2 Output from UseSession.jsp.
Now go ahead and click your reload button a few times. The count should increment with every reload.
NOTE You should also note that the session object has session scope; therefore it will not hold the objects added to it after its expiration.
15 JSP IMPLICIT OBJECTS
254
JSP Fundamentals PART II
The application Object The application object holds a reference to the javax.servlet.ServletContext retrieved from the servlet configuration. The following code snippet, from the JSP’s generated servlet, shows how the application object is initialized: pageContext = _jspxFactory.getPageContext(this, request, response, “errorpage.jsp”, true, 8192, true); application = pageContext.getServletContext();
You can see that the generated servlet simply gets a reference to the current ServletContext and stores it in the application object. The application object has application scope, which means that it is available to all JSPs until the JSP engine is shut down. The application object is most often used to access environment information. Some of the more common pieces of information accessed by the application object are objects that are stored in the ServletContext. These objects are stored there so that they will be available the whole time the servlet engine is running. The ServletContext is a great place to share objects between JSPs and servlets. In the following example, you use the application object to store and access our application’s specific information. You will do this by creating a JSP that creates a Properties object with the following properties: PROP1:VAL1 PROP2:VAL2 PROP3:VAL3
You can see that your property object contains three name:value pairs. Next, you will create a JSP that checks the application for a reference to the Properties object, by calling the application.getAttribute() method with a key that represents the object in the ServletContext. If you do not find the referenced object, you will create it and store the object in the ServletContext using the application.setAttribute() method. Now the Properties object is available to other JSPs and servlets. Listing 15.3 contains this JSP. LISTING 15.3
StoreInApplication.jsp
UseApplication
JSP Implicit Objects CHAPTER 15
LISTING 15.3
255
Continued
Now you need to create a servlet that will use the shared Properties object that is stored in the ServletContext. Listing 15.4 contains this JSP. LISTING 15.4
GetFromApplication.jsp
Get From Application
As you can see, the GetFromApplication.jsp first checks the application object for a reference to the Properties. If it cannot find the object, it writes a message to the implicit out object stating this. If it does find the Properties object, GetFromApplication.jsp iterates over the object, printing out the name:value pairs.
Testing the JSPs To test your JSPs, perform the following steps: 1. Copy all the files into the <SERVER_ROOT>/djs/ directory. 2. Open your browser to the following URL: http://localhost/djs/StoreInApplication.jsp
NOTE When you open your browser during step 2, no output will be displayed in the browser.
3. Then, open your browser to the following URL: http://localhost/djs/GetFromApplication.jsp
When you open your browser in step 3, you should see a page similar to Figure 15.3.
JSP Implicit Objects CHAPTER 15
257
FIGURE 15.3 Output from GetFromApplication.jsp.
The out Object The implicit out object is a very simple object that represents a reference to a JspWriter, which is derived from a java.io.Writer. You can see how the out object is initialized in the following code snippet that was pulled from a JSP’s generated servlet: JspWriter out = null; Object page = this; String _value = null; try { if (_jspx_inited == false) { _jspx_init(); _jspx_inited = true;
JSP Fundamentals PART II application = pageContext.getServletContext(); config = pageContext.getServletConfig(); session = pageContext.getSession(); out = pageContext.getOut();
You have seen many examples of how the out object is used. It is used to write into the output stream that is delivered back to the client. The most common use is to use the out.println() method, passing it HTML text that will be displayed in the client’s browser. Most of your output will be presented to the client in the out.println() method. Listing 15.5 contains an example of how you use the implicit out object. LISTING 15.5
UseOut.jsp
Use Out
Copy this file to the <SERVER_ROOT>/djs/ directory and then open your browser to the following URL: http://localhost/djs/UseOut.jsp
You should now see a page similar to Figure 15.4.
The config Object The implicit config object represents the ServletConfig, which defines a servlet-engine– generated object that contains configuration information. The configuration information that this servlet will have access to is the ServletContext object, which describes the context within which the generated servlet will be running. You can see how the config object is initialized in the following code snippet: ServletConfig config = null; JspWriter out = null; Object page = this;
Most often, you will not need to use the config object, because you will already have access to the ServletContext through the implicit application object.
15 Output from UseOut.jsp.
JSP IMPLICIT OBJECTS
FIGURE 15.4
260
JSP Fundamentals PART II
The page Object The page object is just as it sounds, a reference to the current instance of the JSP. It is initialized to the actual this reference by the generated servlet. The actual code snippet that does this follows: Object page = this;
You use the page object just as you would a this object, to reference the current instance of your generated servlet.
The exception Object The implicit exception object only exists in a defined errorPage. It holds a reference to the uncaught exception that caused the error page to be invoked. You can find a complete description of the errorPage mechanism, including use of the implicit exception object in Chapter 18, “Handling JSP Errors.”
Summary In this chapter we covered the JSP implicit objects and how they are commonly used. We also talked about how these objects are created in the JSP’s generated servlet. You should now have a clear understanding of the implicit objects that are available to you and what they represent. In the next chapter, we will cover using the JSP’s standard actions.
CHAPTER
JSP Standard Actions
16
IN THIS CHAPTER • What Are Standard Actions? • JavaBean Standard Actions • Other Standard Actions
268
262 262
262
JSP Fundamentals PART II
What Are Standard Actions? JSP standard actions are predefined tags that can be used to easily encapsulate common actions. There are two types of JSP standard actions: those related to JavaBean functionality and all other standard actions. Each group will be defined and used, where appropriate, in the following sections.
JavaBean Standard Actions Three standard actions are defined to help integrate JavaBeans into JSPs: <jsp:useBean>, <jsp:setProperty>, and <jsp:getProperty>.
The <jsp:useBean> Standard Action The first standard action is <jsp:useBean>. It associates an instance of a JavaBean defined with a given scope and id using a newly declared scripting variable of the same id. The <jsp:useBean> action is very flexible. Its exact semantics depend on the values of the given attributes. The basic action tries to find an existing object using the same id and scope. If it does not find an existing instance, it will attempt to create the object. It is also possible to use this action only to give a local name to an object defined elsewhere, as in another JSP page or in a servlet. This can be done by using the type attribute, and by not providing the class or the beanName attribute. The syntax of the <jsp:useBean> action is as follows: <jsp:useBean id=”name” scope=”page|request|session|application” typeSpec> body typeSpec ::=class=”className” | class=”className” type=”typeName” | type=”typeName” class=”className” | beanName=”beanName” type=”typeName” | type=”typeName” beanName=”beanName” | type=”typeName”
Table 16.1 contains the attributes of the <jsp:useBean> action. TABLE 16.1
The Attributes for the <jsp:useBean> Action
Attribute
Definition
id
This attribute represents the identity of the instance of the object in the specified scope. The name is case sensitive and must satisfy the current scripting language’s variable naming conventions.
JSP Standard Actions CHAPTER 16
TABLE 16.1
Continued
Definition
scope
The scope attribute represents the life of the object. The scope options are page, request, session, and application. The fully qualified classname that defines the implementation of the object. The classname is case sensitive. This attribute references the name of the bean, as expected to be instantiated by the instantiate() method of the java.beans.Beans class. The type attribute specifies the type of scripting variable defined. If this attribute is unspecified, then the value is the same as the value of the class attribute.
class beanName type
The <jsp:setProperty> Standard Action The second standard action to help integrate JavaBeans into JSPs is <jsp:setProperty>. It sets the value of a bean’s property. Its name attribute denotes an object that must already be defined and in scope. The syntax for the <jsp:setProperty> action is as follows: <jsp:setProperty name=”beanName” prop_expr />
In the preceding syntax, the name attribute represents the name of the bean whose property you are setting and prop_expr can be represented in the following syntax: property=”*” | property=”propertyName” | property=”propertyName” param=”parameterName” | property=”propertyName” value=”propertyValue”
Table 16.2 contains the attributes and their descriptions for the <jsp:setProperty> action. TABLE 16.2
The Attributes for the <jsp:setProperty> Action
Attribute
Definition
name
This attribute represents the name of the bean instance defined by a <jsp:useBean> action or some other action. This attribute represents the bean property for which you want to set a value. If you set propertyName to an asterisk (*), then the action will iterate over the current ServletRequest parameters, matching parameter names and value types to property names and setter method types, and setting each matched property to the value of the matching parameter. If a parameter has an empty string for a value, the corresponding property is left unmodified.
property
16 JSP STANDARD ACTIONS
Attribute
263
264
JSP Fundamentals PART II
TABLE 16.2
Continued
Attribute
Definition
param
The param attribute represents the name of the request parameter whose value you want to set the named property to. A <jsp:setProperty> action cannot have both param and value attributes referenced in the same action. The value attribute represents the value assigned to the named bean’s property.
value
The <jsp:getProperty> Standard Action The last standard action that references JavaBeans in JSPs is <jsp:getProperty>. It takes the value of the referenced bean instance’s property, converts it to a java.lang.String, and places it into the implicit out object. The referenced bean instance must be defined and in scope before this action references it. The syntax for the <jsp:getProperty> action is as follows: <jsp:getProperty name=”name” property=”propertyName” />
Table 16.3 contains the attributes and their descriptions for the <jsp:getProperty> action. TABLE 16.3
The Attributes for the <jsp:getProperty> Action
Attribute
Definition
name
This attribute represents the name of the bean instance from which the property is obtained, defined by a <jsp:useBean> action or some other action. This attribute represents the bean property for which you want to get a value.
property
A JSP Example Using JavaBeans In this example, you’ll use a simple JavaBean that acts as a counter. It has a single int property, count, which holds the current number of times the bean’s property has been accessed. It also contains the appropriate methods for getting and setting this property. Listing 16.1 contains the source code for the Counter bean. LISTING 16.1
Counter.java
public class Counter { // Initialize the bean on creation int count = 0;
JSP Standard Actions CHAPTER 16
LISTING 16.1
Continued
} // Property Getter public int getCount() { // Increment the count property, with every request count++; return this.count; } // Property Setter public void setCount(int count) { this.count = count; } }
Now that you have defined your bean, let’s look at how to integrate it into a JSP. Listing 16.2 contains the JSP that will use the Counter bean. LISTING 16.2
In this snippet, you use the <jsp:setProperty> standard action to set the value of the count property. You do this by setting the name attribute to the name of the bean you want to reference, the property attribute to the name of the property to be set, and the param attribute to the name of the request parameter you want to set the property to.
JSP Standard Actions CHAPTER 16
The second example uses the <jsp:getProperty> standard action, which requires the name of the bean and the property to be accessed. The action takes the attribute, calls the appropriate accessor, and embeds the results directly into the resulting HTML document, as shown in the following: Count from jsp:getProperty : <jsp:getProperty name=”counter” property=”count” />
Notice that the second reference to the count property results in a value that is one greater that the first reference. This is because both methods of accessing the count property result in a call to the getCount() method, which increments the value of count. To see this in action compile the Counter class, move it to the <SERVER_ROOT>/djs/WEB-INF/classes directory, and copy the BeanCounter.jsp file to the <SERVER_ROOT>/djs/ directory. Now you should open your browser to the following URL: http://localhost/djs/BeanCounter.jsp
Another thing you might want to try is changing the value of the <jsp:useBean> action’s scope attribute. This will affect the life of the bean and the value of the count property in the previous example. We will examine bean scope further in the Chapter 17, “Using JavaBeans and JSP Scopes.” The available options for the scope attribute are described in Table 16.4. TABLE 16.4
The scope Values for the <jsp:useBean> Action
Value
Definition
page
Objects with page scope are accessible only within the page where they were created. References to an object with page scope will be released when the response is sent back to the client or the request is forwarded to another resource. Objects with page scope are stored in the pagecontext.
16 JSP STANDARD ACTIONS
The final two actions you perform show how you can get the current value of a bean’s property. The first of these two examples uses a scriptlet. It simply accesses the bean by its referenced name counter and calls the getCount() method, just as any other Java code would. The scriptlet snippet is listed here:
267
268
JSP Fundamentals PART II
TABLE 16.4
Continued
Value
Definition
request
Objects with request scope are accessible only within pages processing the same request in which the object was created. References to the object will be released after the request is processed completely. If the request is forwarded to a resource in the same runtime, the object is still in scope. References to objects with request scope are stored in the request object. Objects with session scope are accessible only within pages processing requests that are in the same session as the one in which the bean was created. It is illegal to define an object with session scope within a page if that page’s page directive has the session attribute set equal to false. References to the session objects will be released after their associated sessions end. Objects with session scope are stored in the session object associated with the page activation. Objects with application scope are accessible within pages processing requests that are in the same application space as the page in which they were created. References to the object will be released when the runtime environment reclaims the ServletContext. Objects with application scope can be defined and reached within pages that are not session-aware. References to objects with application scope are stored in the application object associated with the page.
session
application
Other Standard Actions The remaining predefined standard actions include <jsp:param>, <jsp:include>, <jsp:forward>, and <jsp:plugin>. Each of these tags is described in detail in the following sections.
The <jsp:param> Standard Action The <jsp:param> action is used to provide tag/value pairs of information, by including them as sub-attributes of the <jsp:include>, <jsp:forward>, and the <jsp:plugin> actions. The syntax of the <jsp:param> action is as follows: <jsp:param name=”paramName” value=”paramValue”/>
Table 16.5 contains the attributes and their descriptions for the <jsp:param> action.
JSP Standard Actions CHAPTER 16
TABLE 16.5
Attributes for the <jsp:param> Action
Definition
name
This attribute represents the name of the parameter being referenced. This attribute represents the value of the named parameter.
value
The <jsp:include> Standard Action The <jsp:include> action provides a mechanism for including additional static and dynamic resources in the current JSP page. The syntax for this action is as follows: <jsp:include page=”urlSpec” flush=”true” />
and <jsp:include page=”urlSpec” flush=”true”> <jsp:param ... />
The first syntax description does a request-time inclusion, whereas the second contains a list of param sub-elements that are used to argument the request for the purpose of inclusion. Table 16.6 contains the attributes and their descriptions for the <jsp:include> action. TABLE 16.6
The Attributes for the <jsp:include> Action
Attribute
Definition
page
This attribute represents the relative URL of the resource to be included. This attribute represents a mandatory Boolean value stating whether or not the buffer should be flushed. Currently, true is the only valid value for this attribute.
flush
To further explain how the <jsp:include> works, we will create two JSPs. The first, which will be the included JSP, will act as the header of the second JSP document. This JSP will search the request for an employee’s name and title. Listing 16.3 contains the source for your first JSP. LISTING 16.3
header.jsp
16 JSP STANDARD ACTIONS
Attribute
269
270
JSP Fundamentals PART II
The second JSP will include the header.jsp in the top row of its table and pass it the employee’s name and title, using the <jsp:param> standard action. It will then include some static text indicating the employee’s current statistics. Listing 16.4 contains the source code for your second JSP. LISTING 16.4
To see the <jsp:include> in action, copy both of these JSPs to the <SERVER_ROOT>/djs/ directory and open your browser to the following URL: http://localhost/djs/EmployeeInfo.jsp
The include is actually taking place in the following code snippet from the _jspService() method mentioned earlier: { String _jspx_qStr = “”; out.flush(); _jspx_qStr = _jspx_qStr + “?employee=” + “Bob”; _jspx_qStr = _jspx_qStr + “&title=” + “Engineer”; pageContext.include(“header.jsp” + _jspx_qStr); }
You can see that the string _jspx qStr is created and then the parameter list, which was created using the <jsp:param> standard action, is appended to it. This is what forms the query string that will be passed to your included JSP. When the string is ready, it is passed to the pageContext.include() method with the name of the JSP to include. Now the included JSP can parse the passed-in query string. As you can see, the generated servlet does not directly contain the output from the included JSP. This is because the output is included during request-time. This makes it possible for you to make changes to the included JSP without restarting the JSP engine.
16 JSP STANDARD ACTIONS
} // end // begin out.write(“\r\n
\r\n
\r\n” + “
\r\n
\r\n “ + “ Years of Employment:\r\n
\r\n
\r\n “ + “ 7\r\n
\r\n
\r\n
\r\n “ + “\r\n\r\n”); // end
273
274
JSP Fundamentals PART II
To see this in action, open the included header.jsp and make some changes to it. Now reload the EmployeeInfo.jsp. Your changes should take effect immediately. This is the difference between the include directive and the <jsp:include> standard action. To propagate changes using the include directive, you would have needed to restart the JSP engine. Using the <jsp:include> directive relieves you of this need.
The <jsp:forward> Standard Action The <jsp:forward> action enables the JSP engine to dispatch, at runtime, the current request to a static resource, servlet, or another JSP. The appearance of this action effectively terminates the execution of the current page.
NOTE A <jsp:forward> action can contain <jsp:param> sub-attributes. These sub-attributes provide values for parameters in the request to be used for forwarding.
The syntax of the <jsp:forward> action is as follows: <jsp:forward page=”relativeURLspec” />
and <jsp:forward page=relativeURLspec”> <jsp:param .../>
Table 16.7 contains the attribute and its description for the <jsp:forward> action. TABLE 16.7
The Attribute for the <jsp:forward> Action
Attribute
Definition
page
This attribute represents the relative URL of the target of the forward.
The <jsp:forward> standard action is commonly used as a conditional in a JSP. In our example, you will get the company id from the request and, based on it, you will use the <jsp:forward> to go to the employee’s particular company page. Listing 16.5 contains the JSP that does this.
As you can see, the UseForward.jsp simply checks the request for the company id and forwards the user, along with a set of request parameters, to the appropriate company home page. Listings 16.6 and 16.7 contain the source of the company home pages. LISTING 16.6
SamsHome.jsp
LISTING 16.7
MCPHome.jsp
After you have copied the JSPs and the two image files, sams.gif and mcplogo.gif, into the <SERVER_ROOT>/djs/ directory, open your browser to the following URL: http://localhost/djs/UseForward.jsp?companyId=1
You will see an image similar to Figure 16.2.
JSP Standard Actions CHAPTER 16
277
16 JSP STANDARD ACTIONS
FIGURE 16.2 The output from UseForward.jsp.
You should also go ahead and change the companyId request parameter to equal something other than 1. This will show you how the JSP forwards based on a conditional. To see how the <jsp:forward> action is implemented, let’s take a look at the following code snippet removed from the generated servlet’s _jspService() method: // begin [file=”C:\\UseForward.jsp”;from=(7,6);to=(11,8)] if ( (request.getParameter(“companyId”)).equals(“1”) ) { // end // begin [file=”C:\\UseForward.jsp”;from=(12,10);to=(15,24)] if (true) { out.clear(); String _jspx_qfStr = “”; _jspx_qfStr = _jspx_qfStr + “?employee=” + “Bob”; _jspx_qfStr = _jspx_qfStr + “&title=” + “Senior Engineer”; pageContext.forward(“SamsHome.jsp” + _jspx_qfStr); return; }
278
JSP Fundamentals PART II // end // begin out.write(“\r\n “); // end // begin [file=”C:\\UseForward.jsp”;from=(16,10);to=(19,8)] } else { // end // begin out.write(“\r\n “); // end // begin [file=”C:\\UseForward.jsp”;from=(20,10);to=(23,24)] if (true) { out.clear(); String _jspx_qfStr = “”; _jspx_qfStr = _jspx_qfStr + “?employee=” + “Joe”; _jspx_qfStr = _jspx_qfStr + “&title=” + “Senior Engineer”; pageContext.forward(“MCPHome.jsp” + _jspx_qfStr); return; } // end // begin out.write(“\r\n “); // end // begin [file=”C:\\UseForward.jsp”;from=(24,10);to=(26,4)] }
You can see that there is nothing really complicated about this code snippet. It simply decides which JSP to forward to, creates the query string, and calls the pageContext.forward() method with the name of the JSP and the query string.
The <jsp:plugin> Standard Action The <jsp:plugin> action enables a JSP author to generate HTML that contains the appropriate client-browser independent constructs, for example, OBJECT or EMBED, that will result in the download of the Java plug-in and subsequent execution of the specified applet or JavaBeans component. The <jsp:plugin> tag is replaced by either an or <embed> tag, as appropriate for the requesting user agent, and is written to the output stream of the response object. The attributes of the <jsp:plugin> action provide configuration data for the presentation of the element. The syntax of the <jsp:plugin> action is as follows:
JSP Standard Actions CHAPTER 16
<jsp:params>
Table 16.8 contains the attributes and their descriptions for the <jsp:plugin> action. TABLE 16.8
The Attributes for the <jsp:plugin> Action
Attribute
Definition
type
This attribute represents the type of plug-in to include. An example of this would be an applet. This attribute represents the name of the class that will be executed by the plug-in. This attribute references the base or relative path of where the code attribute can be found.
code codebase
Summary This chapter covered the JSP standard actions. You should feel comfortable with how they are implemented and how you can use them. In the next chapter we will cover the scope differences when using JavaBeans in a JSP.
IN THIS CHAPTER • The Counter JavaBean • page Scope
282
283
• request Scope
284
• session Scope
286
• application Scope
289
CHAPTER
17
282
JSP Fundamentals PART II
The Counter JavaBean As discussed in Chapter 16, “JSP Standard Actions,” the <jsp:useBean> standard action provides four different options for the scope attribute: page, request, session, and application. We will discuss each of these and give an example of how to use them in the following sections. For our examples, we will be using the Counter bean from Chapter 16, which acts as a simple counter. It has a single int property, count, which holds the current number of times the bean’s property has been accessed. It also contains the appropriate methods for getting and setting this property. Listing 17.1 contains the source for this bean. LISTING 17.1
Counter.java
import java.io.Serializable; public class Counter implements Serializable{ // Initialize the bean on creation int count = 0; // Parameterless Constructor public Counter() { } // Property Getter public int getCount() { // Increment the count property, with every request count++; return this.count; } // Property Setter public void setCount(int count) { this.count = count; } }
To use this bean you will need to compile it and move the class file to your <SERVER_ROOT>/djs/WEB-INF/classes/ directory, if you have not already done so.
Using JavaBeans and JSP Scopes CHAPTER 17
283
page Scope Beans with page scope are accessible only within the page where they were created. References to an object with page scope will be released when the response is sent back to the client or the request is forwarded to another resource. Objects with page scope are stored in the pageContext. A bean with page scope is most often used for single instance calculations or transactions. An example of using the Counter bean with page scope can be found in Listing 17.2.
Request Bean Example <jsp:useBean id=”counter” scope=”request” class=”Counter” /> Request Bean Example 2 Request Bean Example 2 The current count for the counter bean is:
As you examine the source of the second JSP, you will see that it gets a reference to the counter bean from the request, and then prints the current value of the bean’s count property.
USING JAVABEANS AND JSP SCOPES
counter.setCount(10);
286
JSP Fundamentals PART II
To see how it works, copy both of these JSPs to the <SERVER_ROOT>/djs/ directory and open your browser to the following URL: http://localhost/djs/RequestBean1.jsp
You will see a page similar to Figure 17.2.
FIGURE 17.2 The output from RequestBean1.jsp.
You can reload the page several times, but the result will always be the same. The second JSP will print the current value of the count property as 11. This is because the instance of the bean only lasts as long as the request.
session Scope Beans with session scope are accessible only within pages processing requests that are in the same session as the one in which the bean was created. It is illegal to define an object with session scope from within a page whose page directive has an attribute session=false. References to the session objects are released after their associated sessions expire. Objects with session scope are stored in the session object associated with the page. Beans that use session scope are most often used when there is a need to share information between requests for a single client. A common application using bean scope is a shopping
Using JavaBeans and JSP Scopes CHAPTER 17
287
cart. For our example, you will use the Counter bean and two almost identical JSPs. Each JSP creates an instance of your bean and prints out the current value of the count property. The two JSPs can be found in Listings 17.5 and 17.6, respectively. LISTING 17.5
SessionBean1.jsp
<jsp:useBean id=”counter” scope=”session” class=”Counter” /> Session Bean Example 2 Session Bean Example 2 The current count for the counter bean is:
You can see that the only difference between these two JSPs is the values of the HTML and tags.
17 USING JAVABEANS AND JSP SCOPES
Session Bean Example 1 Session Bean Example 1 The current count for the counter bean is:
288
JSP Fundamentals PART II
To see how a session bean works, copy both of these JSPs to the <SERVER_ROOT>/djs/ directory and open your browser to the following URL: http://localhost/djs/SessionBean1.jsp
You should see an image similar to Figure 17.3.
FIGURE 17.3 The output from SessionBean1.jsp.
Click your reload button several times. You should see the count increase each time the page is reloaded. Now use the same browser instance to open the following URL: http://localhost/djs/SessionBean2.jsp
You will see the count increment from the last count from the first JSP. This is because the counter bean is stored in the session of the client. Now open a completely new instance of the browser and you will see that the value of the property is reset. This is because each instance of a client creates its own instance of the HttpSession, which is where the counter bean is stored. count
Using JavaBeans and JSP Scopes CHAPTER 17
289
application Scope Beans with application scope are accessible within pages processing requests that are in the same application space as the page in which they were created. References to the object will be released when the runtime environment reclaims the ServletContext. More simply put, this means that until the JSP engine is restarted, the bean created with application scope will be available. Beans with application scope are best used when you need to share information between JSPs and servlets for the life of your application.
LISTING 17.7
ApplicationBean1.jsp
<jsp:useBean id=”counter” scope=”application” class=”Counter” /> Application Bean Example 2
17 USING JAVABEANS AND JSP SCOPES
To give an example of application scope, you will use two JSPs. The first will load the bean using an id of “counter” and a scope of “application”. It will then print out the current value of the counter bean, using the Counter.getCount() method. Listing 17.7 contains the source for your first JSP. Counter
290
JSP Fundamentals PART II
LISTING 17.8
Continued
Application Bean Example 2 The current count for the counter bean is:
Go ahead and copy both of these JSPs to the <SERVER_ROOT>/djs/ directory and open your browser to the following URL: http://localhost/djs/ApplicationBean1.jsp
Click the reload button a few times and watch the count go up. You will see a page similar to Figure 17.4.
FIGURE 17.4 The output from ApplicationBean1.jsp.
Now open another browser window to the second JSP using the following URL: http://localhost/djs/ApplicationBean2.jsp
Using JavaBeans and JSP Scopes CHAPTER 17
291
Click the reload button a few times and watch the count go up. You will see that each page increments the other page’s instance; both of these pages share the same instance of the Counter bean. They will share this instance until the JSP engine is shut down.
Summary In this chapter, we covered how JSP beans are scoped. You should feel comfortable with the different types of JSP scope. You should also understand how the life of a JSP bean is determined by its scope.
17 USING JAVABEANS AND JSP SCOPES
In the next chapter we will take a look at how you handle errors that occur in your JSPs.
CHAPTER
Handling JSP Errors
18
IN THIS CHAPTER • JSP Translation-Time Errors • JSP Request-Time Errors
294
294
294
JSP Fundamentals PART II
Errors can occur in a JSP in two different phases of its life. The first type of error, which occurs during the initial request, is known as a translation-time error. The second type of JSP error occurs during subsequent requests and is know as a request-time error. These errors are discussed in the following sections.
JSP Translation-Time Errors The first type of JSP error occurs when a JavaServer Page is first requested and goes through the initial translation from a JSP source file into a corresponding servlet class file. These translation-time errors are usually the result of compilation failures. They are reported to the requesting client with an error status code 500 or Server Error and usually contain the reported compilation error. The JSP engine handles translation-time errors.
JSP Request-Time Errors The second type of JSP error occurs during request time. These errors are runtime errors that can occur either in the body of the JSP page or in some other object that is called from the body of the JSP page. Request-time errors result in an exception being thrown. These exceptions can be caught and appropriately handled in the body of the calling JSP, which would be the end of the error. Those exceptions that are not caught result in the forwarding of the client request, including the uncaught exception, to the error page specified by the offending JSP. The following sections describe, in detail, how to define and implement JSP error pages.
Creating a JSP Error Page To create a JSP error page, you need to create a basic JavaServer Page and then tell the JSP engine that the page is an error page. You do this by setting its page attribute isErrorPage to true. Listing 18.1 contains a sample error page. LISTING 18.1
errorpage.jsp
Handling JSP Errors CHAPTER 18
LISTING 18.1
295
Continued
Error: has been reported.
There are two lines of code you need to look at to understand just how easy it is to create a JSP error page. The first is the page directive line, which indicates that this JSP is an error page. This code snippet is
The second line of code designates where the thrown exception is being used. This line is Error: has been reported.
You will notice that this line uses the implicit exception object that is part of all JSP error pages. The exception object holds the reference to the unhandled exception that was thrown in the offending JSP.
NOTE The generated code included in the examples will differ depending on the application server used.
To gain a complete understanding of how the error page works, take a look at the servlet code that is generated from the JSP error page. The following code snippet contains the _jspService() method generated from Listing 18.1:
296
JSP Fundamentals PART II String
_value = null;
try { if (_jspx_inited == false) { _jspx_init(); _jspx_inited = true; } _jspxFactory = JspFactory.getDefaultFactory(); response.setContentType(“text/html”); pageContext = _jspxFactory.getPageContext(this, request, response, “”, true, 8192, true); application = pageContext.getServletContext(); config = pageContext.getServletConfig(); session = pageContext.getSession(); out = pageContext.getOut(); // begin out.write(“\r\n\r\n\r\n\r\n”); // end // begin out.write(“\r\n\r\n\r\n\r\nError: “); // end // begin [file=”D:\\errorpage.jsp”;from=(9,10);to=(9,34)] out.print( exception.getMessage() ); // end // begin out.write(“ has been reported. \r\n\r\n\r\n\r\n”); // end } catch (Exception ex) { if (out.getBufferSize() != 0) out.clear(); pageContext.handlePageException(ex); } finally { out.flush(); _jspxFactory.releasePageContext(pageContext); } }
Handling JSP Errors CHAPTER 18
297
You will notice that the _jspService() method looks much like any other generated JSP, except that it has the following lines: Throwable exception = (Throwable)request.getAttribute(“javax.servlet.jsp.jspException”);
These two lines make it possible for the error page to access the implicit exception object. It does this by getting the exception object from the request, using the request.getAttribute() method with a key of javax.servlet.jsp.jspException. Now your JSP can do whatever it wants with the received exception. In the next section, we will examine how the exception object gets placed into the request.
Using a JSP Error Page Now that you know how to create a JSP error page, let’s put one to use. It takes only one additional attribute, in your page directive, to make your JSP aware of an error page. You simply need to add the errorPage attribute and set its value equal to the location of your JSP error page. The JSP in Listing 18.2 uses the error page you created in the previous section. LISTING 18.2
testerror.jsp
You will notice in this listing that the first line of code sets the errorPage equal to errorpage.jsp, which is the name of your error page. The rest of the example is used to throw an exception that will not be caught. That is all there is to it. Copy both of these JSPs to the <SERVER_ROOT>/djs/ directory and open the testerror.jsp page in your browser. You will see a page similar to Figure 18.1.
HANDLING JSP ERRORS
18
298
JSP Fundamentals PART II
FIGURE 18.1 Output of the testerror.jsp example.
To see how this error is handled in the actual compiled code, take a look at the _jspService() method generated from the testerror.jsp example. The following code snippet contains the generated _jspService() method: public void _jspService(HttpServletRequest request, HttpServletResponse response) throws IOException, ServletException { JspFactory _jspxFactory = null; PageContext pageContext = null; HttpSession session = null; ServletContext application = null; ServletConfig config = null; JspWriter out = null; Object page = this; String _value = null; try { if (_jspx_inited == false) { _jspx_init();
Handling JSP Errors CHAPTER 18
299
_jspx_inited = true; } _jspxFactory = JspFactory.getDefaultFactory(); response.setContentType(“text/html”); pageContext = _jspxFactory.getPageContext(this, request, response, “errorpage.jsp”, true, 8192, true); application = pageContext.getServletContext(); config = pageContext.getServletConfig(); session = pageContext.getSession(); out = pageContext.getOut(); // begin out.write(“\r\n\r\n”); // end // begin [file=”D:\\testerror.jsp”;from=(2,2);to=(10,0)] if ( true ) { // Just throw an exception throw new Exception(“A JSP Exception”);
// end // begin out.write(“\r\n”); // end } catch (Exception ex) { if (out.getBufferSize() != 0) out.clear(); pageContext.handlePageException(ex); } finally { out.flush(); _jspxFactory.releasePageContext(pageContext); } }
The first section of code you need to look at is the call to get the PageContext object from the JspFactory, using the getPageContext() method. This method obtains an instance of an
HANDLING JSP ERRORS
}
18
300
JSP Fundamentals PART II
implementation-dependent javax.servlet.jsp.PageContext abstract class for the calling servlet and currently pending request and response. You will also notice that one of its parameters is the name you specified as your error page. The following code snippet shows the call to getPageContext(): pageContext = _jspxFactory.getPageContext(this, request, response, “errorpage.jsp”, true, 8192, true);
Now this instance of the PageContext object knows which page to forward all uncaught errors to. This is done in the following code snippet: catch (Exception ex) { if (out.getBufferSize() != 0) out.clear(); pageContext.handlePageException(ex); }
You can see that this catch block catches all uncaught exceptions and passes them to the pageContext.handlePageException() method, which in turn places the exception into the request and forwards it to the error page referenced during the creation of the PageContext.
Summary In this chapter we covered the types of errors that can occur in a JSP. You have also seen how you can handle and respond to these errors, using a JSP error page. In the next chapter, we will cover one of the more useful JSP topics: custom JSP tags.
CHAPTER
Custom JSP Tag Libraries
19
IN THIS CHAPTER • JSP Custom Tags
302
• Deploying Tag Libraries
302
• Developing Custom JSP Tags Handlers
306
302
JSP Fundamentals PART II
JSP Customs Tags JSP custom tags encapsulate functional and/or business logic that can be reused inside of a JavaServer Page. This gives you the ability to insert complex logic into a JSP without having the JSP code itself be overly complicated. This is a true use of object-oriented encapsulation. Some custom tag examples that we have already discussed are the JSP standard actions. They have the same functionality as a custom tag. A code snippet with a custom tag follows:
This JSP contains two lines that you need to examine. The first is the line:
This is the taglib directive. It describes the tag library and must be included to reference any custom tag library. We will cover the taglib directive in more detail in the next section. The second thing you should notice is the tag itself. Our tag has a prefix of djs, which was defined by the taglib directive, and the tag itself is hello. When the JSP container encounters this line of JSP text, it will execute the code associated with this tag. The code that will be executed is called a tag handler, which will also be covered in further detail in a later section.
Deploying Tag Libraries Before you can start using tag libraries, you must understand how they are deployed. JSP tag libraries are groups of JSP custom tags that have been packaged together for deployment. As sample grouping might be a set of tags that encapsulate database functionality. Four steps are involved in deploying a tag library: 1. Create a tag library descriptor. 2. Deploy the tag handlers to your Web application. 3. Add a taglib entry to your Web application’s web.xml file. 4. Add a taglib directive to your JSP that will be using the custom tag library.
Creating a Taglib Descriptor A tag library descriptor (tld) is just what it sounds like. It is an XML file that describes the tag library that you are trying to deploy.
Custom JSP Tag Libraries CHAPTER 19
303
NOTE This text will not define every attribute associated with the tag library descriptor. This would be beyond the scope of this book. To find more information on tlds you can look at the JSP specification.
The following code snippet contains a simple tld with one tag defined named hello:
hello com.djs.HelloTag empty Just Says Hello
You only need to examine two parts in this simple tld. The first is the entry, which is /djs for your library. This tells the container that this tag library should be referenced when a JSP’s taglib directive contains the same uri.
The next section to examine is the section. It describes the name of the tag and its associated tag handler. It also says that the bodycontent for this tag is empty. The next step is to copy this tld into a directory that can be referenced in the Web application’s deployment descriptor. For this example, create a directory <SERVER_ROOT>/webapps/djs/WEB-INF/tlds/ and copy the tld into it. The final step to deploy your tag library is to add the following section to your application’s web.xml file. /djs /WEB-INF/tlds/taglib.tld
Now you can see your new tag in action. Listing 19.3 contains the source for the JSP that will use your Hello tag. LISTING 19.3
Hello.jsp
Now open your browser to the following URL: http://localhost/djs/Hello.jsp
You should see an image similar to Figure 19.2.
FIGURE 19.2 The Hello Tag Page.
Custom JSP Tag Libraries CHAPTER 19
Now whenever you add the text
311
to your JSP, it will be replaced by the text
Tags with Bodies Now that you have seen a custom tag without a body, let’s create a tag that uses a body. All tag handlers with bodies must implement the BodyTag interface. The BodyTag interface extends the Tag interface by adding functionality to handle body content. It does this by adding three new methods. Each one of these methods is described in Table 19.3. TABLE 19.3
Methods Added by the BodyTag Interface
Method
Definition
setBodyContent()
Used by the container to set the current content of the tag’s body. Executed once per invocation after the setBodyContent() method and before the evaluation of the tag’s body. Called by the container after the body content has been evaluated.
doInitBody() doAfterBody()
Like tags without bodies, tags with bodies also have a helper class. Their helper is BodyTagSupport and it extends TagSupport and implements the BodyTag interface. When the JSP container encounters a tag with a body it performs the following steps: 1. The setPageContext() method is called, setting the current page’s PageContext. 2. The setParent() method is called with a reference to the parent Tag object, if this is a nested tag, or null if not.
4. The setBodyContext() is then called. 5. The doInitBody() is then called. 6. The doAfterBody() is then called repeatedly as long as it returns EVAL_BODY_TAG. 7. The doEndTag() method is called when the closing tag element is encountered. It can return either of two values: EVAL_PAGE, which tells the container to continue evaluating the page, or SKIP_PAGE, which tells the container to stop evaluating the rest of the page. 8. The final step performed by the container is to call the release() method. This method is used to reset class level attributes and to release any allocated resources.
19 CUSTOM JSP TAG LIBRARIES
3. The doStartTag() is then called. It will return either EVAL_BODY_INCLUDE or SKIP_BODY. If EVAL_BODY_INCLUDE is returned, the container should evaluate the body of the tag. If SKIP_BODY is returned, the container will not evaluate the body.
312
JSP Fundamentals PART II
A Sample Tag with a Body Let’s create a tag with a body. You will use a tag much like your Hello tag. The difference is that your BodyTag will print the text Hello and the content of the tag. Your new tag will be named HelloBodyTag. Listing 19.4 contains the source for this tag. LISTING 19.4
HelloBodyTag.java
package com.djs; import javax.servlet.jsp.JspException; import javax.servlet.jsp.JspTagException; import javax.servlet.jsp.tagext.BodyTagSupport; public class HelloBodyTag extends BodyTagSupport { public HelloBodyTag() { } // Method called when the closing hello tag is encountered public int doEndTag() throws JspException { try { // Get the content of this tag’s body String name = bodyContent.getString(); // We use the pageContext to get a Writer // We then print the text string Hello + the content // of the tag’s body. pageContext.getOut().print(“Hello “ + name); } catch (Exception e) { throw new JspTagException(e.getMessage()); } // return SKIP_BODY, because we will not evaluate the body again. return SKIP_BODY; } public void release() { // // // //
Call the parent’s release to release any resources used by the parent tag. This is just good practice for when you start creating hierarchies of tags.
Custom JSP Tag Libraries CHAPTER 19
LISTING 19.4
313
Continued
super.release(); } }
As you look over this tag, you will see that it first extends the BodyTagSupport class. This is the helper class for tags with bodies. It provides default implementations for the methods defined in the BodyTag interface. The only difference from the HelloTag’s doEndTag() method is the following code snippet: // Get the content of this tag’s body String name = bodyContent.getString(); // We use the pageContext to get a Writer // We then print the text string Hello + the content // of the tag’s body. pageContext.getOut().print(“Hello “ + name);
In the HelloBodyTag’s doEndTag() method you first get the String representation of the tag’s body using the bodyContent.getString() method. After you have this String you get a reference to a JspWriter that references the current stream being used for client response, as you did in your HelloTag. You then use the print() method to write the text Hello string plus the text value in the body of your HelloBodyTag to the response stream. To see this tag in action you need to first compile the HelloBodyTag.java file and move the class file into the <SERVER_ROOT>/webapps/djs/WEB-INF/classes/com/djs/ directory. You then need to add the following code snippet to your tld:
The most important thing to notice in the above snippet is the bodycontent for this tag. It is now JSP instead of empty. This tells the container that the tag body can have content and this content can be JSP code. Now you can see your new body tag in action. Listing 19.5 contains the source for the JSP that will use your helloBody tag.
19 CUSTOM JSP TAG LIBRARIES
helloBody com.djs.HelloBodyTag JSP Just Says Hello to the Body
314
JSP Fundamentals PART II
LISTING 19.5
HelloBody.jsp
Bob
Now open your browser to the following URL: http://localhost/djs/HelloBody.jsp
You should see an image similar to Figure 19.3.
FIGURE 19.3 The HelloBody Tag Page.
Tags with Attributes The last tag you will develop is a tag with attributes. With JSP custom tags you have the ability to pass attributes to custom tags. You do this by adding an attribute list to the tag element. An example of this, using a modification of the original hello tag, is in the following code snippet:
The preceding snippet has only one attribute: name. When the JSP container encounters this tag it then checks its matching tag handler for a class-level attribute name. It uses introspection to find this attribute and then calls its setXXX() method. All tags must have a matching set method for each attribute that can be included in the tag element’s attribute list. The matching method for the above snippet would be the setName() method. To further examine how this works, let’s develop a tag with attributes.
Custom JSP Tag Libraries CHAPTER 19
315
For your sample tag you will use your original hello tag and add the appropriate functionality to handle a single name attribute. Listing 19.6 contains the source for your new tag. LISTING 19.6
HelloAttributeTag.java
package com.djs; import javax.servlet.jsp.JspException; import javax.servlet.jsp.JspTagException; import javax.servlet.jsp.tagext.TagSupport; public class HelloAttributeTag extends TagSupport { private String name = new String(); public HelloAttributeTag() { } // Accessor to set the name public void setName(String name) { this.name = name; } // Method called when the closing hello tag is encountered public int doEndTag() throws JspException { try {
} catch (Exception e) { throw new JspTagException(e.getMessage()); } // We want to return SKIP_BODY because this Tag does not support // a Tag Body return SKIP_BODY; } public void release() { // Call the parent’s release to release any resources
19 CUSTOM JSP TAG LIBRARIES
// We use the pageContext to get a Writer // We then print the text string Hello pageContext.getOut().print(“Hello “ + name);
316
JSP Fundamentals PART II
LISTING 19.6
Continued
// used by the parent tag. // This is just good practice for when you start creating // hierarchies of tags. super.release(); // Reset the name to an empty String name = new String(); } }
There are only a couple of new things to notice here. The first is the name attribute and the setName() method. This is the attribute/method matching that is used to set attribute values as we discussed earlier. The class level attribute name is prepended with set and the first letter of the attribute is capitalized to perform this matching. To deploy this new tag you need to add an entry to the tld, compile the HelloAttributeTag, and move the class file to the <SERVER_ROOT>/webapps/djs/WEB-INF/classes/com/djs/ directory. The code snippet that needs to be added to the tld follows: helloAttribute com.djs.HelloAttributeTag JSP Just Says Hello to the Body name <required>true true
The only real change to this tag element is the addition of the attribute element. In this element you state three things. You first name the attribute, which is name for this tag. You then state whether the attribute is required. This can be either true or false. The final addition to the attribute element is the rtexprvalue element. This states whether the value of the attribute can be an evaluated expression. The options are true or false. To see this tag in action, use the JSP found in Listing 19.7. LISTING 19.7
HelloAttribute.jsp
Custom JSP Tag Libraries CHAPTER 19
LISTING 19.7
317
Continued
Copy this file to the <SERVER_ROOT>/webapps/djs/ directory and open your browser to the following directory: http://localhost/djs/HelloAttribute.jsp
You should see a page similar to Figure 19.4.
FIGURE 19.4 The HelloAttribute Tag Page.
Summary
In Chapter 20, “Catalog Case Study,” we will begin our case studies. The next few chapters will show you how to put together all the concepts we have covered so far.
19 CUSTOM JSP TAG LIBRARIES
In this chapter you covered custom JSP tag libraries. We discussed the two types of tag libraries: tags without bodies and tags with bodies. We also looked at how attributes can be passed to custom tags.
Servlet and JSP Web Applications
IN THIS PART 20 Catalog Case Study 21 An LDAP Web Client 22 A Stock Trader 23 Wireless Application Development Using WAP 24 WML/WMLScript Development
PART
III
CHAPTER
Catalog Case Study
20
IN THIS CHAPTER • Catalog Requirements • Models • Views
322
322 328
• Controllers
338
• Using the Online Catalog
344
322
Servlet and JSP Web Applications PART III
Catalog Requirements NOTE You will need to create a Web application named catalog, following the steps in Appendix A, “Web Applications and Configuring the Servlet Engine.” Make sure you have the classes ConnectionPool, Controller, and Service in your Web application’s classpath.
In this chapter you will put your newly found knowledge to practical use by creating a movie catalog system. This system will be based on the server-side implementation of the MVC as defined in Chapter 13 “A Servlet Controller.” The basic requirements are defined as follows: • Movie Presentation—The catalog interface must give the user the ability to browse a list of movies by category. • Movie Selection—When the user has found the movie they are looking for they should be able to select the movie and have it added to the shopping cart. They can repeat these two steps as many times as they would like until their order is complete. • Order Processing Requirements—The order processing section of the catalog application comes into action when the user has selected all of the movies they want to order. At this point they require a method to submit the order for processing. After the order has been submitted, it will then be transferred to the fulfillment department.
NOTE For this example, the submitted order will not actually be submitted to fulfillment. It will only be acknowledged with a thank you message.
Models This section of the requirements defines the database representation of the movie catalog application. Only one object in the application will be modeled in the database—the Titles table. For our purposes you will not build an object representation of the database. We will simply use SQL and iterate over ResultSets. The Title object that will be represented in the database is the Movie object itself. Each of the Movie object’s attributes must be included in the table representation. Table 20.1 lists the required elements needed to store a Movie object.
Catalog Case Study CHAPTER 20
TABLE 20.1
323
Required Attributes to Model a Movie
Attribute
Type
title_id
int
title_name
String
price
double
quantity
int
category
int
To make the Titles table available to your application you must set up an ODBC data source following the same steps used in Chapter 7 “Servlets, JDBC, and Inter-Servlet Communications.” You will need to use catalog as the data source name and select the catalog.mdb file included in this chapter’s source code. To complete your configuration of the database you will need to create a servlet that initializes the ConnectionPool created in Chapter 7 with the appropriate setting for this application. The source for the extension of the ConnectionPoolServlet is in Listing 20.1. LISTING 20.1 import import import import
import ConnectionPool.ConnectionPool; public class CatalogConnectionPool extends HttpServlet { //Initialize global variables public void init(ServletConfig config) throws ServletException { super.init(config); // Instantiate the ConnectionPool ConnectionPool pool = new ConnectionPool(); try { // Set the JDBC Driver pool.setDriver(“sun.jdbc.odbc.JdbcOdbcDriver”); pool.setURL(“jdbc:odbc:catalog”); pool.setSize(2);
CATALOG CASE STUDY
// Set the Username pool.setUsername(“”);
20
324
Servlet and JSP Web Applications PART III
LISTING 20.1
Continued
// Set the Password pool.setPassword(“”); // Initialize the pool pool.initializePool(); // Once the pool is Initialized, add it to the // Global ServletContext. This makes it available // To other servlets using the same ServletContext. ServletContext context = getServletContext(); context.setAttribute(“CATALOG_POOL”, pool); System.err.println(“ADDED CATALOG_POOL”); } catch (Exception e) { System.err.println(e.getMessage()); } } //Process the HTTP Get request public void doGet(HttpServletRequest request, HttpServletResponse response) throws ServletException, IOException { // Set the response content-type response.setContentType(“text/html”); // get the Writer object PrintWriter out = response.getWriter(); out.println(“This Servlet does not service requests!”); out.close(); } public void destroy() { // Access the ServletContext using the getAttribute() // method, which returns a reference to the ConnectionPool. ServletContext context = getServletContext(); ConnectionPool pool = (ConnectionPool) context.getAttribute(“CATALOG_POOL”); if ( pool != null ) { // empty the pool pool.emptyPool(); // Remove the Attribute from the ServletContext context.removeAttribute(“CATALOG_POOL”); } else {
Catalog Case Study CHAPTER 20
LISTING 20.1
325
Continued
System.err.println(“Could not get a reference to Pool!”); } } }
The only changes from the ConnectionPoolServlet found in Chapter 7 are the name of the servlet, changing the URL to point to the catalog data source, and setting the number of connections to two. Make sure you also add the following code snippet to the catalog’s web.xml file: <servlet> <servlet-name>CatalogConnectionPool <servlet-class>CatalogConnectionPool 1
This snippet preloads the CatalogConnectionPool when the Tomcat engine starts up.
Shopping Cart The only real object that you will create for this case study is a simple shopping cart that will hold the items the user has selected. The shopping cart will be represented by the ShoppingCart class. Each user will get an instance of the ShoppingCart stored in their unique session. The source code for the ShoppingCart object is in Listing 20.2. LISTING 20.2 import import import import import
public class ShoppingCart { protected Hashtable items = new Hashtable(); public ShoppingCart() { }
CATALOG CASE STUDY
/** Add a new item to the shopping cart. * attributes itemId - the unique key associated with the item
20
326
Servlet and JSP Web Applications PART III
LISTING 20.2
Continued
desc - a text description of the item price - the unit price for this item quantity - number of this item to insert into the shopping cart */ public void addItem(String itemId, String desc, float price, int quantity) { String[] item = {itemId, desc, Float.toString(price), Integer.toString(quantity)}; if (items.containsKey(itemId)) { String[] tmpItem = (String[])items.get(itemId); int tmpQuant = Integer.parseInt(tmpItem[3]); quantity += tmpQuant; tmpItem[3] = Integer.toString(quantity); } else { items.put(itemId, item); } } /** Remove an item from the shopping cart. * attributes itemId - the unique key associated with the item to be removed */ public void removeItem(String itemId) { if (items.containsKey(itemId)) { items.remove(itemId); } } /** Change the quantity of a specific item in the shopping cart. The item must have previously been added to perform this function. * attributes itemId - unique key for the item to be updated quantity - the new quantity to be stored in the shopping cart */
Catalog Case Study CHAPTER 20
LISTING 20.2
327
Continued
public void updateQuantity(String itemId, int quantity) { if (items.contains(itemId)) { String[] tmpItem = (String[])items.get(itemId); tmpItem[3] = Integer.toString(quantity); } } /** Get an Enumeration to the list of items in the shopping cart. */ public Enumeration getEnumeration() { return items.elements(); } /** Get the total cost of all of the items currently in the shopping cart. */ public float getCost() { Enumeration enum = items.elements(); String[] tmpItem; float totalCost = 0.00f; while (enum.hasMoreElements()) { tmpItem = (String[])enum.nextElement(); totalCost += (Integer.parseInt(tmpItem[3]) * Float.parseFloat(tmpItem[2])); } return totalCost; }
return numOfItems; }
20 CATALOG CASE STUDY
/** Get the total number of items currently in the shopping cart. */ public int getNumOfItems() { Enumeration enum = items.elements(); String[] tmpItem; int numOfItems = 0; while (enum.hasMoreElements()) { tmpItem = (String[])enum.nextElement(); numOfItems += Integer.parseInt(tmpItem[3]); }
328
Servlet and JSP Web Applications PART III
LISTING 20.2
Continued
/** Get the total number of items currently in the shopping cart. */ public void empty() { Enumeration enum = items.elements(); String[] item; while (enum.hasMoreElements()) { item = (String[])enum.nextElement(); removeItem((String)item[0]); } } }
As you can see, the ShoppingCart contains the basic functionality to add, remove, and display its contents. We will look at it further as you use it in the application.
Views Now you need to define the interface that your users will interact with. From our requirements defined in the first section of this chapter you will need to create four views and an error page.
Catalog Layout Each of these pages, excluding the error page, will have the basic layout shown in Figure 20.1.
Title Bar
N a v i g a t i o n
FIGURE 20.1 The catalog view layout.
Client Area
Catalog Case Study CHAPTER 20
329
The catalog view layout has three basic parts. The Title Bar shows a simple graphic of the Sams logo and a hyperlinked image of a shopping cart. This will display a list of the shopping cart’s contents when selected. This Title Bar will be at the top of all of your Views, and it will be represented by the titlebar.jsp page. Figure 20.2 contains an image of the real contents of the Title Bar.
FIGURE 20.2 Contents of the Title Bar.
The source for the Title Bar is in Listing 20.3. LISTING 20.3
titlebar.jsp
20 CATALOG CASE STUDY
The next section of your catalog layout is the Navigation section, the way that users will browse your list of movies by category. It will be contained in the navigation.jsp page. This file contains a list of hard-coded hyperlinks that execute the ListMovies() service method, which will be defined in the following sections, with the category ID and target of the Movie List view. Figure 20.3 shows an image of your Navigation.
330
Servlet and JSP Web Applications PART III
FIGURE 20.3 The Navigation section.
The source for the Navigation part of your views is in Listing 20.4. LISTING 20.4
navigation.jsp
Action/Adventure
Comedy
Catalog Case Study CHAPTER 20
LISTING 20.4
331
Continued
20 CATALOG CASE STUDY
Drama
Children/Family
Suspense/Thriller
Sci-Fi/Horror
Classics
332
Servlet and JSP Web Applications PART III
LISTING 20.4
Continued
Westerns
Home
Check Out
Empty Cart
The final section of your catalog layout is the client area. This will change based on the view that is currently being represented. Each view is described in the following sections. All views will use JSP includes to incorporate the Title Bar and Navigation into their individual layouts.
Index View The Index view will be represented by the file index.jsp. It will act as the home page for your catalog. An image of the Index view is in Figure 20.4.
Catalog Case Study CHAPTER 20
333
FIGURE 20.4 The Index view.
The source for the Index view is in Listing 20.5. LISTING 20.5
index.jsp
Sams Movie Catalog
20 CATALOG CASE STUDY
<jsp:include page=”titlebar.jsp” flush=”true” />
Welcome to the Sams Movie Catalog
334
Servlet and JSP Web Applications PART III
Movie List View The Movie List view will be represented by the file ListMovies.jsp. It will display the movies as they relate to the categories in your catalog. Figure 20.5 shows an image of the Movie List view.
FIGURE 20.5 The Movie List view.
The source for the Movie List view can be found in Listing 20.6. LISTING 20.6
ListMovies.jsp
Movie List
Catalog Case Study CHAPTER 20
LISTING 20.6
335
Continued
Shopping Cart View The Shopping Cart view will be represented by the file ListShoppingCart.jsp. It will display the current contents of the shopping cart. An image of the Shopping Cart view is in Figure 20.6. The source for the Shopping Cart view is in Listing 20.7. LISTING 20.7
ListShoppingCart.jsp
20 CATALOG CASE STUDY
24 WML/ WMLSCRIPT DEVELOPMENT
You entered: $inputBox
You entered: $selectList
You viewed the advertisement! <do type=”accept” label=”Home”>
404
Servlet and JSP Web Applications PART III
The example in Listing 24.2 creates five sample cards to demonstrate the basic elements discussed in this chapter. Running the example in an emulator will produce the results seen in Figures 24.1–24.6.
FIGURE 24.1 The WMLExample.wml Welcome Card.
FIGURE 24.2 The setvar Card.
FIGURE 24.3 The input Card.
WML/WMLScript Development CHAPTER 24
405
FIGURE 24.4 The select Card.
FIGURE 24.5 The previous Card.
24 The timer Card.
WML works well for displaying information to the user, but any programming logic must be accessed through a or link to a server, that is, unless you use WMLScript. The next section introduces client-side programming with WAP’s WMLScript programming language.
WMLScript The Wireless Application Protocol defines a client-scripting environment and programming language based on ECMAScript. If you are familiar with client-side JavaScript programming, you are well on your way to learning WMLScript. WMLScript is a client-only scripting
WML/ WMLSCRIPT DEVELOPMENT
FIGURE 24.6
406
Servlet and JSP Web Applications PART III
platform used in combination with WML to provide client-side procedural logic. Like WML, WMLScript is compiled through a WAP gateway into binary form to provide intelligence to mobile clients. This section will be used to present the WMLScript language and its libraries; it concludes with an example illustrating the use of WMLScript to perform client-side validation.
Calling WMLScript from WML For a WMLScript function to be called from WML, the function must be declared within its source file using the extern keyword. The syntax for calling a function is as follows: sourcefile.wmls#functionname(arguments)
WML calls the WMLScript function through a hyperlink such as the anchor tag or the action tag. For example, a fictional WMLScript function call could be triggered from an anchor tag such as: Click Here!
Language Basics WMLScript uses virtually the same syntax as JavaScript. Some of the basic language rules include • All statements must end with a semicolon (;) • Variables are declared using the var keyword (for example, var • Multiline comments are surrounded by /*
*/;
counter=0;)
single-line comments begin with //
• The language is case sensitive • All WMLScript code must live inside a function • The language is comprised of six standard libraries: Lang, Float, String, URL, WMLBrowser, and Dialogs • No run-time or compile-time type checking is done • The language supports five internal data types: Boolean, Integer, Floating-point, String, and Invalid WMLScript functions feature the following syntax: function new_function(parameters) { code body }
To return a value from a function, use the return keyword.
WML/WMLScript Development CHAPTER 24
407
Operators WMLScript defines a complete set of operators that are very similar to languages such as C and Java. These operators are as follows: • Assignment Operators—=, +=, -=, *=, /=, div=, %=, &=, |=, ^=, =, and >>>=. • Arithmetic Operators—+, -, *, /, div, and %. • Bitwise Operators—, >>>, &, ^, |, and ~. • Logical Operators—&&, ||, and !. • Equality Testing Operators—==, !=, >, >=,
Variable = $txtOutput
You entered: $txtInput
As you can see, the WML file defines three starter scenarios that each call a WML function. The WMLScript functions set variables and return focus back to one of the three output cards for displaying information to the user.
WML/ WMLSCRIPT DEVELOPMENT
Length = $strLength
24
412
Servlet and JSP Web Applications PART III
Wireless Application Developing Using Servlets This section will address the topic of dynamic wireless application development using Java servlets. As mentioned earlier, not much separates WAP/servlet development from the standard HTML/servlet development techniques presented throughout the rest of this book. As you will see in this section, it is as simple as setting a few new MIME types on your Web server and you’re off and running! Several more advanced techniques enable servlet applications to simultaneously support multiple client types, and these techniques will also be discussed.
NOTE For more information on wireless Java servlet development, visit the following URLs: Go Wireless (XML Magazine): http://www.xmlmag.com/upload/free/features/xml/2000/03sum00/mf10300/ ➥mf10300-1.asp
Building Servlets To Output WML Content (AnywhereYouGo.com): http://www.anywhereyougo.com/ayg/ayg/Article.po?id=10743
Configuring Server MIME Types If you’re going to serve up WML and WMLScript files from your Web server, you need to notify your Web server of this by setting the appropriate MIME types. The file and MIME types you should be aware of when supporting WAP are •
.wml—text/vnd.wap.xml
•
.wbmp—image/vnd.wap.wbmp
•
.wmls—text/vnd.wap.wmlscript
•
.wmlc—application/vnd.wap.wmlscriptc
•
.wmlsc—application/vnd.wap.wmlc
If you are using the popular Apache Web server (http://www.apache.org), these MIME types can be added by editing the server’s .htaccess file. For example, to add support for the .wml file type, add the following line to .htaccess: AddType text/vnd.wap.wml .wml
If you are using the popular Microsoft Internet Information Server (http://www.microsoft.com/iis/), modifying the server is done through a graphical user interface. Within the Internet Service Manager application, select the Web server you would like to modify, and then select the Properties menu option. From the Properties dialog box,
WML/WMLScript Development CHAPTER 24
413
select the HTTP Headers tab, and then select the Add button within the Custom HTTP Headers box. Add the appropriate MIME types to IIS using this option. If you are using another HTTP server product, consult your product’s documentation to learn how to add support for additional MIME types.
A Quick “Hello World!” WML Servlet To reiterate, WML/WMLScript content is output from Java servlets in the exact same manner as HTML content (using the java.io.PrintWriter class). Listing 24.5 shows a simple “Hello World!” servlet that outputs WML content to a WAP browser. LISTING 24.5
The HelloWorld! Servlet
import java.io.*; import javax.servlet.*; import javax.servlet.http.*; public class HelloWorldServlet extends HttpServlet { public void doGet(HttpServletRequest request, HttpServletResponse response) { response.setContentType(“text/vnd.wap.wml”); PrintWriter out = response.getWriter();
} }
This simple servlet does two things: 1. It sets the MIME type being output by calling the HttpServletResponse.setContentType() method. 2. It outputs a simple WML card displaying the text “Hello World!”
Using this basic functionality, it is possible to construct dynamic Java servlets that generate WML content based on JDBC database queries or other typical programming tasks. What happens, though, when your boss asks you to develop one common set of code that supports both desktop (for example, HTML) users and mobile (for example, WAP) users? This will be the topic of the following two sections.
Multiple Device Support As you might imagine, supporting a completely different code base for HTML and WML content would become unmanageable quickly on any moderate-to-large-sized project. In order to “force” all users to enter through a central servlet, it is useful to first detect the browser type and then redirect the user to the appropriate content. This way, all users enter your server application through one servlet and WML/HTML output code within that servlet can access the same core set of helper methods and classes. (In fact, only the text output methods will differ!) User agents can be detected using the javax.servlet.http.HttpServletRequest.getHeader() method to retrieve the HTTP_USER_AGENT CGI Environment Variable. The following line of code does just that: String userAgent = request.getHeader(“User-Agent”);
This is a rather tedious approach but enterprise developers should be able to narrow down the list of potential accessors somewhat. For an up-to-date list of WAP user agent values, visit http://allnetdevices.com/faq/useragents.php3.
Maintaining a Site in XML A common approach in use today by wireless application developers is to store the site content and data in XML format. XML documents can be transformed into any number of formats using an XML technology known as eXtensible Stylesheet Language Transformation, or XSLT. WML is particularly suited to this sort of transformation because it is itself based on XML, making the transformation very clean and straightforward. If you are familiar with objectoriented programming concepts, you will recognize the concepts of data hiding and encapsulation—two concepts enthusiastically supported by XML and XSLT. The actual formatting of the body to be displayed to the user (for example, WML or HTML) is stored in an XML file. The data stored within that formatted body is stored within a separate XML file and united with the formatting XML using an XML parser. Some HTML clients (such as Microsoft Internet Explorer 5.0 and later releases) support XML/XSLT in the client; therefore no further work will be required. At the current time, WAP browsers do not embed XML parsers, so processing will need to be completed on the server by a Java servlet and a Java XML parser framework such as that provided by the Apache Cocoon project (http://xml.apache.org/cocoon/).
WML/WMLScript Development CHAPTER 24
415
Summary Chapters 23 and 24 have presented the Wireless Application Protocol and its associated programming languages: WML and WMLScript. Combining WML and WMLScript with an advanced server-side technology such as Java servlets supports the development of industrialstrength dynamic wireless applications for a variety of devices.
24 WML/ WMLSCRIPT DEVELOPMENT
Appendixes
IN THIS PART A Web Applications and Configuring the Servlet Engine B The javax.servlet Package C The javax.servlet.http Package D The javax.servlet.jsp Package E The javax.servlet.jsp.tagext Package F WML (The Wireless Markup Language) G WMLScript
PART
IV
Web Applications and Configuring the Servlet Engine
Web Applications The release of the Java Servlet Specification 2.2 introduced the concept of a Web application. According to this specification a Web application is a collection of servlets, HTML pages, classes, and other resources that can be bundled and run on multiple containers from multiple vendors. In this book you create the Web application directory structure and create a new application entry in the server.xml file. (Because you develop your examples as you progress through the book, you don’t deploy the examples into a Web ARchive (WAR) file; however we do discuss WAR files.) The following is a list of items that can exist in a Web application: • Servlets • JavaServer Pages • Utility classes • Static documents including HTML and images • Client-side classes • Meta information that describes the Web application
The ServletContext in Relation to the Web Application Each Web application belongs to one and only one ServletContext. This mapping is controlled by the servlet container, and guarantees that no two applications will have clashes when storing objects in the ServletContext.
The Directory Structure The container that holds the Web application is the directory structure in which it exists. The first step in creating a Web application is to create this structure. Table A.1 contains sample directories you will need. Each one of these directories should be created from the <SERVER_ROOT> of the servlet container. TABLE A.1
The Web Application Directories Structure
Directory
Description
/applicationname
This is the root directory of the Web application. This is where we will be installing all of our JSPs and HTML files.
Web Applications and Configuring the Servlet Engine APPENDIX A
TABLE A.1
421
Continued
Directory
Description
/applicationname/WEB-INF
This directory contains all resources related to the application that are not in the document root of the application. You must note that the WEB-INF directory is not part of the public document tree of the application. No file contained in this directory can be served directly to a client. This directory is where servlet and utility classes are located.
/applicationname/WEB-INF/classes
The applicationname we use throughout this book is djs; therefore you need to substitute djs for applicationname in the previously described directory structure.
Web Application Deployment Descriptors The Web application deployment descriptor describes configuration and deployment information for the entire Web application. The Web application descriptor is an XML file named web.xml, located in the /<SERVER_ROOT>/applicationname/WEB-INF/ directory. For our application the location of the web.xml file is in the /<SERVER_ROOT>/djs/WEB-INF/ directory. The information that is contained in the deployment descriptor includes the following elements: •
The XML descriptor elements that we focus on are mainly servlet specific. The following code snippet contains an example of a Web application deployment descriptor:
422
Appendixes PART IV <servlet> <servlet-name>BasicServlet <servlet-class>BasicServlet 1 <param-name>name <param-value>value
Web Archive (WAR) Files Web applications can be packaged into a Web ARchive (WAR) file using Java’s standard archiving tool jar. The only difference would be its extension. For this text we could package all our examples into a file called djs.war. However, as stated earlier, we don’t package them as a WAR because we develop the examples as we progress through the book.
Servlet Requirements To begin a development effort using Java servlets, you will need to decide what tools you will use to both write and run your servlets. You will need only a minimal set of tools to actually write Java servlets. The two most important requirements are the Java Development Kit (JDK), and the Java Servlet Development Kit (JSDK), also on version 2.2. Both of these development kits can be downloaded from the JavaSoft home page at http://www.javasoft.com at no cost. You will also need the Tomcat server, which we will discuss in the next section.
Apache Tomcat Tomcat is the flagship product of The Apache Software Foundation’s Jakarta Project. It is intended to be a reference implementation of Sun’s Java Servlet SDK 2.2 and JavaServer Pages 1.1 specifications.
Installing the Tomcat Server The first thing you need to do is get a copy of Tomcat from the Jakarta Project’s Web site. You can find the necessary links at the http://jakarta.apache.org/ site. Figure A.1 shows the Jakarta Project’s home page.
Web Applications and Configuring the Servlet Engine APPENDIX A
423
FIGURE A.1 The Jakarta Project’s home page.
You can choose to download either class files or source code. When you have the file, decompress it to a local drive. For this text I am installing it to drive C:, therefore my <SERVER_ROOT> directory is C:\jakarta-tomcat-3.2\. If you have a later version of Tomcat, your <SERVER_ROOT> could be different. The next step is putting your JDK into the Tomcat’s classpath. You do this by editing the file and setting the JAVA_HOME environment variable to the location of your JDK installation. For my installation I have added the following line to the tomcat.bat file: <SERVER_ROOT>/bin/tomcat.bat
set JAVA_HOME=C:\java\jdk1.2.2\ Make sure this line is added before any references to JAVA_HOME. To test your installation, start the Tomcat server by executing the startup.bat file and open your browser to the following URL, substituting your server name:
You should now see a screen similar to Figure A.2.
A WEB APPLICATIONS AND THE SERVLET ENGINE
http://server_name:8080/
424
Appendixes PART IV
FIGURE A.2 The Tomcat default page.
The next step is to verify the installation of your JDK. You do this by executing one of the JSP examples provided with the Tomcat server. To execute a sample JSP, start from the page shown in Figure A.2 and choose JSP Examples. You should see a screen similar to Figure A.3. Now choose the JSP example Date and select the Execute link. If everything was installed properly you should see a page similar to Figure A.4 (with a different date, of course). If you do not see this page, you need to make sure the location of your JDK matches the location specified by the JAVA_HOME variable in the tomcat.bat file.
Adding the DJS Web Application The final step in setting up the djs Web application, which is also our final step in setting up the Tomcat server, is to create a new Web application entry in the <SERVER_ROOT>/conf/server.xml file. This is the configuration file for the servlet containers. To add the new entry, add the following section of text at the end of the tags:
Web Applications and Configuring the Servlet Engine APPENDIX A
425
FIGURE A.3 The JSP Examples page.
A
The JSP Date page.
WEB APPLICATIONS AND THE SERVLET ENGINE
FIGURE A.4
426
Appendixes PART IV
This entry tells the servlet containers that we have a new Web application and it is located in the <SERVER_ROOT>/djs/ directory with a document base of webapps/djs/. You should also change the port Tomcat is listening to for HTTP requests. You do this by changing the port value to 80 in the following entry of the same <SERVER_ROOT>/conf/server.xml file: <Parameter name=”handler” ➥ value=”org.apache.tomcat.service.http.HttpConnectionHandler”/> <Parameter name=”port” value=”80”/>
Now we need to add the application’s directories as follows: <SERVER_ROOT>/webapps/djs/ <SERVER_ROOT>/webapps/djs/images <SERVER_ROOT>/webapps/djs/WEB-INF
Building and Installing the BasicServlet To test your newly created Web application we will build and install the BasicServlet from Chapter 3, “Servlet Basics.” You need to complete two steps to run your newly created servlet. The first step is to compile the servlet code. The second is to install the servlet into your Web application. To compile the servlet, make sure the servlet SDK is on your CLASSPATH. You can find the JSDK classes in the C:\jakarta-tomcat\lib\servlet.jar file. After the servlet has been compiled, you need to copy the class file to the appropriate directory in the Web application and restart the Tomcat server. This directory should be the following for Tomcat: <SERVER_ROOT>/webapps/djs/WEB-INF/classes
These directories should be used throughout the book. Now open your browser to the following URL: http://localhost/djs/servlet/BasicServlet
NOTE You should not be required to restart the Tomcat server with the change or addition of a servlet, but if your changes are not reflected when you reload your servlet, go ahead and stop and restart the server.
Web Applications and Configuring the Servlet Engine APPENDIX A
427
You should now see a page similar to Figure A.5.
FIGURE A.5 Output from the BasicServlet.
Summary In this appendix we discussed Web applications and how they are built. We covered how to set up the Tomcat server, and we compiled and built the BasicServlet from Chapter 3.
A WEB APPLICATIONS AND THE SERVLET ENGINE
The javax.servlet Package
IN THIS APPENDIX • The javax.servlet Interfaces • Classes
448
• Exceptions
456
430
APPENDIX
B
430
Appendixes PART IV
The javax.servlet package is at the core of all servlet development. It contains the generic interfaces, classes, and exceptions that are implemented and extended by all servlets. Figure B.1 illustrates the javax.servlet object model. java.io.Serializable
java.lang.Throwable
javax.servlet.RequestDispatcher
java.lang.Exception
javax.servlet.Servlet
javax.servlet.ServletException
javax.servlet.ServletConfig
javax.servlet.UnavailableException
java.lang.Object javax.servlet.ServletContext
javax.servlet.GenericServlet
java.io.InputStream
java.io.OutputStream
javax.servlet.ServletInputStream
javax.servlet.ServletOutputStream
javax.servlet.ServletRequest
javax.servlet.ServletResponse
javax.servlet.SingleThreadModel
FIGURE B.1 The javax.servlet object model.
The javax.servlet Interfaces Interfaces of the javax.servlet package include RequestDispatcher, Servlet, ServletConfig, ServletContext, ServletRequest, ServletResponse, and SingleThreadModel. Each is described in the following sections, along with its methods.
The javax.servlet Package APPENDIX B
The RequestDispatcher Interface The RequestDispatcher interface defines an object that can serve as a wrapper around another resource on the server. It is most often used to forward requests to other server resources. It defines two methods.
The forward() Method public void forward(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
The forward() method is used to forward a request from one servlet to another. It allows the first servlet to perform some initial tasks on the request before forwarding it to another resource on the server. forward() returns no value. forward()
has two parameters:
•
ServletRequest
•
ServletResponse
It throws these exceptions: •
ServletException
•
java.io.IOException
The include() Method public void include(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
The include() method is used to merge content from another server resource in the response of the final servlet. include() returns no value. include()
has two parameters:
•
ServletRequest
•
ServletResponse
It throws these exceptions: •
ServletException
•
java.io.IOException
B THE JAVAX.SERVLET PACKAGE
public interface RequestDispatcher
431
432
Appendixes PART IV
The Servlet Interface public abstract interface Servlet
The Servlet interface is implemented by all servlets either through direct implementation or inheritance. It defines five methods, including the three life cycle methods, to be implemented by all servlets.
The init() Method public void init(ServletConfig config) throws ServletException
The init() method, the first life cycle method, marks the beginning of a servlet’s life. It is called only when the servlet is first loaded, and it must execute successfully before the servlet can service requests. The init() method should contain all initialization code for the servlet. It returns no value. init()
•
has one parameter:
ServletConfig
It throws this exception: •
ServletException
The getServletConfig() Method public ServletConfig getServletConfig()
The getServletConfig() method returns the servlet’s ServletConfig object, which contains the servlet’s startup configuration and initialization parameters. getServletConfig() has no parameters and throws no exceptions. It returns this value: •
ServletConfig
The service() Method public void service(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
The service() method defines the servlet’s entry point for servicing requests. It can be executed only after the servlet’s init() method has executed successfully. The service() method is the life cycle method executed for every incoming request. It returns no value.
The javax.servlet Package APPENDIX B service()
has two parameters:
ServletRequest
•
ServletResponse
It throws these exceptions: •
ServletException
•
java.io.IOException
The getServletInfo() Method public java.lang.String getServletInfo()
The getServletInfo() method provides the servlet user with information about the servlet itself. You will usually include copyright or versioning information. getServletInfo() has no parameters and throws no exceptions. It returns this value: •
String
The destroy() Method public void destroy()
The destroy() method is the life cycle method that marks the end of a servlet’s life. It is executed only once, when the servlet is removed from the service. You should place all of your clean-up functionality in this method. destroy() has no parameters, returns no value, and throws no exceptions.
The ServletConfig Interface The ServletConfig interface defines an object generated by a servlet engine and passes configuration information to a servlet during startup. It contains name/value pairs of initialization parameters for the servlet. It also contains a reference to the ServletContext object, described in the next section. The ServletConfig interface defines four methods for accessing this information.
The getServletContext() Method public ServletContext getServletContext()
The getServletContext() method returns a reference to the current ServletContext object. getServletContext() has no parameters and throws no exceptions.
B THE JAVAX.SERVLET PACKAGE
•
433
434
Appendixes PART IV
It returns this value: •
ServletContext
The getServletName() Method public java.lang.String getServletName()
The getServletName() method returns the registered servlet’s name. getServletName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getInitParameter() Method public java.lang.String getInitParameter(java.lang.String)
The getInitParameter() method returns a string containing the value of the initialization parameter’s name/value pair referenced by the passed-in string representing the name. getInitParameter() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getInitParameterNames() Method public java.util.Enumeration getInitParameterNames()
The getInitParameterNames() method returns an enumeration of strings representing all of the initialization parameters’ names. getInitParameterNames() takes no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The ServletContext Interface public interface ServletContext
The ServletContext interface defines an object to be created by a servlet engine that contains information about the servlet’s environment. This interface provides several methods to access this information.
The javax.servlet Package APPENDIX B
The getContext() Method
435
B
public ServletContext getContext(java.lang.String uripath)
It has one parameter: •
java.lang.String
It returns this value: •
ServletContext
The getInitParameter() Method public java.lang.String getInitParameter(java.lang.String name)
The getInitParameter() method returns the value for the named context parameter. getInitParameter() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getInitParameterNames() Method public Enumeration getInitParameterNames()
The getInitParameterNames() method returns an enumeration of all the context parameter names. getInitParameterNames() has no parameters and throws no exceptions. It returns this value: •
Enumeration
The getMajorVersion() Method public int getMajorVersion()
The getMajorVersion() method returns an integer representing the major version of the servlet API that the servlet engine supports. If the servlet engine supported the servlet API 2.1, the result would be 2. getMajorVersion() has no parameters and throws no exceptions. It returns this value: •
int
THE JAVAX.SERVLET PACKAGE
The getContext() method returns a reference to a ServletContext object belonging a particular URI path. getContext() throws no exceptions.
436
Appendixes PART IV
The getMinorVersion() Method public int getMinorVersion()
The getMinorVersion() method returns an integer representing the minor version of the servlet API that the servlet engine supports. If the servlet engine supported the servlet API 2.1, the result would be 1. getMinorVersion() has no parameters and throws no exceptions. It returns this value: •
int
The getMimeType() Method public java.lang.String getMimeType(java.lang.String file)
The getMimeType() method returns a string representing the MIME type of the passed-in filename, or null if the MIME type of the file is not known. getMimeType() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •java.lang.String
The getNamedDispatcher() Method public RequestDispatcher getNamedDispatcher(java.lang.String name)
The getNamedDispatcher() method returns a reference to a RequestDispatcher object belonging a particular URI path. The getNamedDispatcher() method throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
RequestDispatcher
The getResource() Method public java.net.URL getResource(java.lang.String path) throws java.net.MalformedURLException
The getResource() method returns a URL object of a resource matching the passed-in path parameter, permitting a servlet to access content from the servlet engine’s document space without system dependencies.
The javax.servlet Package APPENDIX B getResource()
java.lang.String
It returns this value: •
java.net.URL
It throws this exception: •
java.net.MalformedURLException
The getResourceAsStream() Method public java.io.InputStream getResourceAsStream(java.lang.String path)
The getResourceAsStream() method returns an InputStream object, which allows access to the resource matching the passed in URL path. getResourceAsStream() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.io.InputStream
The getRequestDispatcher() Method public RequestDispatcher getRequestDispatcher(java.lang.String urlpath)
The getRequestDispatcher() method returns a RequestDispatcher object based on the passed-in URL path. getRequestDispatcher() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
RequestDispatcher
The log(java.lang.String msg) Method public void log(java.lang.String msg)
This log() method writes the passed-in message to the context’s log. The location of the log is servlet-engine specific. log() returns no value and throws no exceptions.
B THE JAVAX.SERVLET PACKAGE
•
has one parameter:
437
438
Appendixes PART IV
It has one parameter: •
java.lang.String
The log(java.lang.String msg, java.lang.Throwable throwable) Method public void log(java.lang.String msg, java.lang.Throwable throwable)
This log() method writes the passed-in message and the stack trace of the passed-in Throwable object to the context’s log. The location of the log is servlet-engine specific. log() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
java.lang.Throwable
The getRealPath() Method public java.lang.String getRealPath(java.lang.String path)
The getRealPath() method returns a string representing the passed-in virtual path converted to the real path based on the operating system on which the servlet engine is running. getRealPath() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getServerInfo() Method public java.lang.String getServerInfo()
The getServerInfo() method returns a string representing the name and version of the servlet. getServerInfo() has no parameters and throws no exceptions. It returns this value: • java.lang.String
The getAttribute() Method public java.lang.Object getAttribute(java.lang.String name)
The javax.servlet Package APPENDIX B
It has one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The getAttributeNames() Method public java.util.Enumeration getAttributeNames()
The getAttributeNames() method returns an enumeration of strings representing the names of the attributes currently stored in the ServletContext. getAttributeNames() has no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The setAttribute() Method public void setAttribute(java.lang.String name, java.lang.Object)
The setAttribute() method stores an object in the ServletContext and binds the object to the given name. If the name already exists in the ServletContext, it is replaced. setAttribute() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
java.lang.Object
The removeAttribute() Method public void removeAttribute(java.lang.String name)
The removeAttribute() method removes the object, which is bound to the passed-in name, from the ServletContext. removeAttribute() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
B THE JAVAX.SERVLET PACKAGE
The getAttribute() method returns an object stored in the ServletContext and keyed by the name value passed in. This is one of the methods used to share resources between servlets. The returning object must be downcast to its original type before use. getAttribute() throws no exceptions.
439
440
Appendixes PART IV
The ServletRequest Interface public interface ServletRequest
The ServletRequest interface defines an object used to encapsulate information about the client’s request. Information in the ServletRequest object includes parameter name/value pairs, attributes, and an input stream. The ServletRequest interface defines the following methods to access this information.
The getAttribute() Method public java.lang.Object getAttribute(java.lang.String name)
The getAttribute() method returns the value of the object keyed by the name string for the current request. getAttribute() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The getAttributeNames() Method public java.util.Enumeration getAttributeNames()
The getAttributeNames() method returns an enumeration containing the names of all the attributes in the current request. getAttributeNames() has no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The getCharacterEncoding() Method public java.lang.String getCharacterEncoding()
The getCharacterEncoding() method returns a string representing the character set encoding for this request. getCharacterEncoding() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getContentLength() Method public int getContentLength()
The javax.servlet Package APPENDIX B
It returns this value: •
int
The getContentType() Method public java.lang.String getContentType()
The getContentType() method returns a string representing the MIME type of the request’s data. It is equivalent to the CGI variable CONTENT_TYPE. getContentType() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getInputStream() Method public ServletInputStream getInputStream() throws java.io.IOException
The getInputStream() method returns an input stream for reading binary data from the request’s body. getInputStream() has no parameters. It returns this value: •
ServletInputStream
It throws this exception: •
java.io.IOException
The getLocale() Method public Locale getLocale()
The getLocale() method returns the client’s most preferred locale. getLocale() has no parameters and throws no exceptions. It returns this value: •
Locale
The getLocales() Method public Enumeration getLocales()
B THE JAVAX.SERVLET PACKAGE
The getContentLength() method returns an integer value equal to the length of the request’s data. It is equivalent to the CGI variable CONTENT_LENGTH. getContentLength() has no parameters and throws no exceptions.
441
442
Appendixes PART IV
The getLocales() method returns an enumeration containing the client’s most preferred Locale objects. getLocales() has no parameters and throws no exceptions. It returns this value: •
Enumeration
The getParameter() Method public java.lang.String getParameter(java.lang.String name)
The getParameter() method returns the value of the requested parameter. If the parameter has or could have more than one value, use the getParameterValues() method. getParameter() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getParameterNames() Method public java.util.Enumeration getParameterNames()
The getParameterNames() method returns an enumeration of strings representing the parameter names for this request. getParameterNames() has no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The getParameterValues() Method public java.lang.String[] getParameterValues(java.lang.String name)
The getParameterValues() method returns an array of strings representing all values for the named parameter in the current request. getParameterValues() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String[]
The getProtocol() Method public java.lang.String getProtocol()
The javax.servlet Package APPENDIX B
It returns this value: •
java.lang.String
The getRequestDispatcher() Method public RequestDispatcher getRequestDispatcher(java.lang.String path)
The getRequestDispatcher() method returns a RequestDispatcher object using a relative path. getRequestDispatcher() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
RequestDispatcher
The getScheme() Method public java.lang.String getScheme()
The getScheme() method returns a string representing the scheme of the URL used in the request. Example schemes include http, https, and ftp. getScheme() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getServerName() Method public java.lang.String getServerName()
The getServerName() method returns a string representing the host name of the server that received the request. It is the same as the CGI variable SERVER_NAME. getServerName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getServerPort() Method public int getServerPort()
B THE JAVAX.SERVLET PACKAGE
The getProtocol() method returns a string representing the protocol and version of the request. It is the same as the CGI variable SERVER_PROTOCOL. getProtocol() has no parameters and throws no exceptions.
443
444
Appendixes PART IV
The getServerPort() method returns an integer representing the port number on which the request was received. It is the same as the CGI variable SERVER_PORT. getServerPort() has no parameters and throws no exceptions. It returns this value: •
int
The getReader() Method public java.io.BufferedReader getReader() throws java.io.IOException
The getReader() method returns a BufferedReader for reading text input from the request body. getReader() has no parameters. It returns this value: •
java.io.BufferedReader
It throws this exception: •
java.io.IOException
The getRemoteAddress() Method public java.lang.String getRemoteAddress()
The getRemoteAddress() method returns a string representing the IP address of the client sending the request. It is the same as the CGI variable REMOTE_ADDR. getRemoteAddress() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getRemoteHost() Method public java.lang.String getRemoteHost()
The getRemoteHost() method returns a string representing the qualified hostname of the client sending the request. It is the same as the CGI variable REMOTE_HOST. getRemoteHost() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The isSecure() Method public boolean isSecure()
The javax.servlet Package APPENDIX B
The isSecure() method returns a boolean value indicating whether the request was made with a secure channel. isSecure() has no parameters and throws no exceptions.
•
boolean
The removeAttribute() Method public void removeAttribute(java.lang.String name)
The removeAttribute() method removes the named attribute from the ServletRequest. removeAttribute() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The setAttribute() Method public void setAttribute(java.lang.String key, java.lang.Object object) throws IllegalStateException
The setAttribute() method adds an attribute to the request’s context keyed by the passed-in key string. It throws an IllegalStateException if the key already exists. setAttribute() returns no value. It has two parameters: •
java.lang.String
•
java.lang.Object
It throws this exception: •
IllegalStateException
The ServletResponse Interface public interface ServletResponse
The ServletResponse interface defines an object for sending MIME data back to the client from the servlet’s service method. The ServletResponse object is a parameter of the servlet’s service method. The ServletResponse interface defines several methods for implementing objects.
The flushBuffer() Method public void flushBuffer() throws IOException
B THE JAVAX.SERVLET PACKAGE
It returns this value:
445
446
Appendixes PART IV
The flushBuffer() method flushes and commits the response. flushBuffer() has no parameters and returns no value. It throws this exception: •
java.io.IOException
The getBufferSize() Method public int getBufferSize()
The getBufferSize() method returns the size of the response buffer. getBufferSize() has no parameters and throws no exceptions. It returns this value: •
int
The getCharacterEncoding() Method public java.lang.String getCharacterEncoding()
The getCharacterEncoding() method returns the character set encoding used for this request’s body. If there has been no content type assigned, it is, by default, set to text/plain. getCharacterEncoding() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getLocale() Method public Locale getLocale()
The getLocale() method returns the current response locale. getLocale() has no parameters and throws no exceptions. It returns this value: •
Locale
The getOutputStream() Method public ServletOutputStream getOutputStream() throws java.io.IOException
The getOutputStream() method returns an output stream used for writing binary data to the response. getOutputStream() has no parameters. It returns this value: •
ServletOutputStream
The javax.servlet Package APPENDIX B
It throws this exception: java.io.IOException
The getWriter() Method public java.io.PrintWriter getWriter() throws java.io.IOException
The getWriter() method returns a print writer used for writing formatted text to the response object. getWriter() has no parameters. It returns this value: •
java.io.PrintWriter
It throws this exception: •
java.io.IOException
The isCommitted() Method public boolean isCommitted()
The isCommitted() method returns true if part of the response has already been sent. isCommitted() has no parameters and throws no exceptions. It returns this value: •
boolean
The reset() Method public void reset()
The reset() method empties the response buffer and clears the response headers. reset() has no parameters, returns no value, and throws no exceptions.
The setBufferSize() Method public void setBufferSize(int size)
The setBufferSize() method sets the size of the response buffer. setBufferSize() returns no value and throws no exceptions. It has one parameter: •
int
The setContentLength() Method public void setContentLength(int len)
B THE JAVAX.SERVLET PACKAGE
•
447
448
Appendixes PART IV
The setContentLength() method sets the content length of the current response. setContentLength() returns no value and throws no exceptions. It has one parameter: •
int
The setContentType() Method public void setContentType(java.lang.String type)
The setContentType() method sets the content type of the current response. You can set this property only once for the current response. This method must be called before calling the getWriter() or getOuputStream() methods. setContentType() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The setLocale() Method public void setLocale(Locale locale)
The setLocale() method sets the response locale, including headers and character sets. setLocale() returns no value and throws no exceptions. It has one parameter: •
Locale
The SingleThreadModel Interface public interface SingleThreadModel
The SingleThreadModel interface defines a single threaded model for implementing the servlet’s execution. Implementing this interface makes the servlet thread safe. This guarantees that the implementing servlet’s service method will not be executed concurrently by more than one thread. No methods are defined by the SingleThreadModel interface.
Classes Classes for the javax.servlet package are GenericServlet, ServletInputStream, and ServletOutputStream. Their methods are described in the following sections.
The javax.servlet Package APPENDIX B
The GenericServlet Class
The GenericServlet() Method public GenericServlet()
The GenericServlet() method is an empty default constructor. GenericServlet() has no parameters, returns no value, and throws no exceptions.
The destroy() Method public void destroy()
The destroy() method is executed when the servlet is removed from the running service. It performs any cleanup of resources that were allocated in the init() method. destroy() has no parameters, returns no value, and throws no exceptions.
The getInitParameter() Method public java.lang.String getInitParameter( java.lang.String name)
The getInitParameter() method returns a string containing the value of the initialization parameter keyed by the passed-in name. getInitParameter() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getInitParameterNames() Method public java.util.Enumeration getInitParameterNames()
The getInitParameterNames() method returns an enumeration containing all of the names for each initialization parameter. getInitParameterNames() has no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The getServletConfig() Method public ServletConfig getServletConfig()
B THE JAVAX.SERVLET PACKAGE
The GenericServlet class was created to provide a basic foundation of new servlets. It provides default life cycle methods and default implementations of the ServletConfig’s methods.
449
450
Appendixes PART IV
The getServletConfig() method returns a ServletConfig object containing any startup configuration information for this servlet. getServletConfig() has no parameters and throws no exceptions. It returns this value: •
ServletConfig
The getServletContext() Method public ServletContext getServletContext()
The getServletContext() method returns a ServletContext object containing information about the servlet’s network service. getServletContext() has no parameters and throws no exceptions. It returns this value: •
ServletContext
The getServletInfo() Method public java.lang.String getServletInfo()
The getServletInfo() method returns a string containing servlet-specific information about the implementing servlet. getServletInfo() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The init(ServletConfig config) Method public void init(ServletConfig config) throws ServletException
This init() method marks the beginning of a servlet’s life. It is called only when the servlet is first loaded, and it must execute successfully before the servlet can service requests. The init() method should contain all initialization code for the servlet. It returns no value. It has one parameter: •
ServletConfig
(encapsulates the servlet’s startup configuration and initialization para-
meters) It throws this exception: •
ServletException
The javax.servlet Package APPENDIX B
The init() Method
This parameterless implementation of the init() method is provided only for convenience. It prevents a derived servlet from having to store the ServletConfig object. init() has no parameters and returns no value. It throws this exception: •
ServletException
The log(java.lang.String message) Method public void log(java.lang.String message)
This log() method takes the passed-in message and the name of the servlet and writes them to a log file. The location of the log is server specific. log() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The log(java.lang.String message, java.lang.Throwable t) Method public void log(java.lang.String message, java.lang.Throwable t)
This log() method takes the passed-in message and Throwable object and logs the message with a stack trace from the Throwable object. log() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
java.lang.Throwable
The service() Method public void service(ServletRequest request, ServletResponse response) throws ServletException, java.io.IOException
The service() method defines the servlet’s entry point for servicing requests. It can be executed only after the servlet’s init() method has executed successfully. The service() method is the life cycle method executed for every incoming request. It returns no value.
B THE JAVAX.SERVLET PACKAGE
public void init() throws ServletException
451
452
Appendixes PART IV
It has two parameters: •
ServletRequest
•
ServletResponse
It throws these exceptions: •
ServletException
•
java.io.IOException
The ServletInputStream Class The ServletInputStream is an abstract class defined for servlet writers to get data from the client. It is meant to be implemented by a network services writer. This class has two methods.
The ServletInputStream() Method protected ServletInputStream()
The ServletInputStream() method is the empty default constructor. It has no parameters, returns no value, and throws no exceptions.
The readLine() Method public void readLine(byte[] b, int off, int len) throws java.io.IOException
The readLine() method reads the len of bytes into the passed-in byte array b, starting at position off. If the character \n is encountered, no more bytes are read in. readLine() returns no value. It has three parameters: •
byte[]
•
int
•
int
It throws this exception: •
java.io.IOException
The ServletOutputStream Class The ServletOutputStream class is used to write responses back to the client. It is an abstract class that is implemented by the network services implementor. To access the
The javax.servlet Package APPENDIX B ServletOutputStream, you must call the ServletResponse’s getOutputStream() method. The class has several methods.
public ServletOutputStream() throws java.io.IOException
The ServletOutputStream() method is the empty default constructor. It has no parameters and returns no value. It throws this exception: •
java.io.IOException
The print(boolean value) Method public void print(boolean value) throws java.io.IOException
This version of the print() method prints the passed-in boolean value to the output stream. It has one parameter: •
boolean
NOTE The print() method always throws a java.io.IOException exception. For all print values, the print() method returns no value.
The print(char value) Method public void print(char value) throws java.io.IOException
This version of the print() method prints the passed-in char value to the output stream. It has one parameter: •
char
The print(double value) Method public void print(double value) throws java.io.IOException
This version of the print() method prints the passed-in double value to the output stream.
B THE JAVAX.SERVLET PACKAGE
The ServletOutputStream() Method
453
454
Appendixes PART IV
It has one parameter: •
double
The print(float value) Method public void print(float value) throws java.io.IOException
This version of the print() method prints the passed-in float value to the output stream. It has one parameter: •
float
The print(int value) Method public void print(int value) throws java.io.IOException
This version of the print() method prints the passed-in int value to the output stream. It has one parameter: •
int
The print(long value) Method public void print(long value) throws java.io.IOException
This version of the print() method prints the passed-in long value to the output stream. It has one parameter: •
long
The print(java.lang.String value) Method public void print(java.lang.String value) throws java.io.IOException
This version of the print() method prints the passed-in String value to the output stream. It has one parameter: •
java.lang.String
The println() Method public void println() throws java.io.IOException
The javax.servlet Package APPENDIX B
This version of the println() method prints CRLF to the output stream and has no parameters.
The println() method always throws a java.io.IOException exception. For all print values, the println() method returns no value.
The println(java.lang.String value) Method public void println(java.lang.String value) throws java.io.IOException
This version of the println() method prints the passed-in String value to the output stream, followed by a CRLF. It has one parameter: •
java.lang.String
The println(boolean value) Method public void println(boolean value) throws java.io.IOException
This version of the println() method prints the passed-in boolean value to the output stream, followed by a CRLF. It has one parameter: •
boolean
The println(char value) Method public void println(char value) throws java.io.IOException
This version of the println() method prints the passed-in char value to the output stream, followed by a CRLF. It has one parameter: •
char
The println(int value) Method public void println(int value) throws java.io.IOException
This version of the println() method prints the passed-in int value to the output stream, followed by a CRLF.
B THE JAVAX.SERVLET PACKAGE
NOTE
455
456
Appendixes PART IV
It has one parameter: •
int
The println(long value) Method public void println(long value) throws java.io.IOException
This version of the println() method prints the passed-in long value to the output stream, followed by a CRLF. It has one parameter: •
long
The println(float value) Method public void println(float value) throws java.io.IOException
This version of the println() method prints the passed-in float value to the output stream, followed by a CRLF. It has one parameter: •
float
The println(double value) Method public void println(double value) throws java.io.IOException
This version of the println() method prints the passed-in double value to the output stream, followed by a CRLF. It has one parameter: •
double
Exceptions Exceptions for the javax.servlet package are ServletException and UnavailableException. Their methods are described in the following sections.
The ServletException A ServletException object is thrown when a problem is encountered within a servlet.
The javax.servlet Package APPENDIX B
The ServletException() Method
457
B
public ServletException()
The ServletException(java.lang.String message) Method public ServletException(java.lang.String message)
This method creates a new ServletException object with the passed in string as the message. It has one parameter: •
java.lang.String
NOTE The ServletException() method always returns no value and throws no exceptions.
The ServletException(java.lang.String message, java.lang.Throwable rootCause) Method public ServletException(java.lang.String message, java.lang.Throwable rootCause)
This method creates a ServletException object with a message and a Throwable object representing the cause of the exception. It has two parameters: •
java.lang.String
•
java.lang.Throwable
The ServletException() Method public ServletException(java.lang.Throwable rootCause)
This method creates a new ServletException object with a Throwable object representing the cause of the exception. It has one parameter: •
java.lang.Throwable
The getRootCause() Method public java.lang.Throwable getRootCause()
THE JAVAX.SERVLET PACKAGE
The ServletException() method is the empty constructor. It has no parameters, returns no value, and throws no exceptions.
458
Appendixes PART IV
The getRootCause() method returns a Throwable object representing the cause of the exception. getRootCause() has no parameters and throws no exceptions. It returns this value: •
java.lang.Throwable
The UnavailableException An UnavailableException is thrown when a servlet is not available to service a request. The two types of UnavailableExceptions are permanent and temporary. When a servlet is permanently unavailable, the servlet will not be able to service requests until some administrative task is completed. When a servlet is temporarily unavailable, the servlet is expected to be able to service requests within a given period of time.
The UnavailableException(java.lang.String msg, int seconds) Constructor public UnavailableException(java.lang.String msg, int seconds)
This constructor creates an UnavailableException() with an int value, representing a estimated time of unavailability. It also receives a reference to a String representing the error message. It has two parameters: •
java.lang.String
•
int
The UnavailableException(java.lang.String msg) Method public UnavailableException(java.lang.String msg)
This constructor creates an UnavailableException() with a String representing the error message. This constructor create an UnavailableException(), denoting permanent unavailability It has one parameter: •
java.lang.String
The isPermanent() Method public boolean isPermanent()
The javax.servlet Package APPENDIX B
The isPermanent() method returns true if the servlet is permanently unavailable; otherwise, it returns false. isPermanent() has no parameters and throws no exceptions.
•
boolean
The getUnavailableSeconds() Method public int getUnavailableSeconds()
The getUnavailableSeconds() method returns an int representing the number of seconds a servlet is expected to be temporarily unavailable. getUnavailableSeconds() has no parameters and throws no exceptions. It returns this value: •
int
B THE JAVAX.SERVLET PACKAGE
It returns this value:
459
The javax.servlet.http Package
IN THIS APPENDIX • Interfaces • Classes
462
479
APPENDIX
C
462
Appendixes PART IV
The java.servlet.http package contains the interfaces and classes that are implemented and extended, respectively, to create HTTP-specific servlets. Figure C.1 illustrates the javax.servlet.http object model. java.util.EventListener
Interfaces Interfaces for the java.servlet.http package are HttpServletRequest, HttpServletResponse, HttpSession, and HttpSessionBindingListener.
The HttpServletRequest Interface public interface HttpServletRequest extends ServletRequest
The HttpServletRequest interface defines an object that provides the HttpServlet.service() method with access to HTTP-protocol specific header information sent by the client. The HttpServletRequest interface has 26 methods, described in the following sections.
The javax.servlet.http Package APPENDIX C
463
The getAuthType() Method public java.lang.String getAuthType()
The getAuthType() method returns the authentication scheme used in this request. It is the same as the AUTH_TYPE CGI variable. getAuthType() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
public java.lang.String getContextPath()
The getContextPath() method returns the context path of this request. getContextPath() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getCookies() Method public Cookie[] getCookies()
The getCookies() method returns an array of Cookie objects found in the client request. getCookies() has no parameters and throws no exceptions. It returns this value: •
Cookie[]
The getDateHeader() Method public long getDateHeader(java.lang.String name)
The getDateHeader() method returns the value of the requested date header field found in the client request. getDateHeader() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
long
The getHeader() Method public java.lang.String getHeader(java.lang.String name)
C THE JAVAX.SERVLET.HTTP PACKAGE
The getContextPath() Method
464
Appendixes PART IV
The getHeader() method returns the value of the requested header field found in the client request. getHeader() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The getHeaders() Method public Enumeration getHeaders(java.lang.String name)
The getHeaders() method returns an enumeration of strings containing all of the values for the given header. getHeaders() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
Enumeration
The getHeaderNames() Method public Enumeration getHeaderNames()
The getHeaderNames() method returns an enumeration containing all of the header names found in the client request. getHeaderNames() has no parameters and throws no exceptions. It returns this value: •
Enumeration
The getIntHeader() Method public int getIntHeader(java.lang.String name)
The getIntHeader() method returns the int value of the named header field found in the client request. getIntHeader() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
int
The javax.servlet.http Package APPENDIX C
465
The getMethod() Method public java.lang.String getMethod()
The getMethod() method returns the HTTP method used by the client request. It is the same as the CGI variable REQUEST_METHOD. getMethod() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
Method
public java.lang.String getPathInfo()
The getPathInfo() method returns a string containing any additional path information following the servlet path, but preceding the query string. It is the same as the CGI variable PATH_INFO. getPathInfo() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getPathTranslated() Method public java.lang.String getPathTranslated()
The getPathTranslated() method returns the same information as the getPathInfo() method, but translates the path to its real path name before returning it. It is the same as the CGI variable PATH_TRANSLATED. getPathTranslated() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
getQueryString()
Method
public java.lang.String getQueryString()
The getQueryString() method returns the query string from the request. It is the same as the CGI variable QUERY_STRING. getQueryString() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getRemoteUser() Method public java.lang.String getRemoteUser()
C THE JAVAX.SERVLET.HTTP PACKAGE
getPathInfo()
466
Appendixes PART IV
The getRemoteUser() method returns the name of the user making the request. If the name is not available, null is returned. It is the same as the CGI variable REMOTE_USER. getRemoteUser() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getRequestedSessionId() Method public java.lang.String getRequestedSessionId()
The getRequestedSessionId() method returns the session ID associated with the request. getRequestedSessionId() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getRequestURI() Method public java.lang.String getRequestURI()
The getRequestURI() method returns the first line of the request’s URI. This is the part of the URI that is found to the left of the query string. getRequestURI() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getUserPrincipal() Method public java.security.Principal getUserPrincipal()
The getUserPrincipal() method returns the principal of the user making the request. getUserPrincipal() has no parameters and throws no exceptions. It returns this value: •
java.security.Principal
The getServletPath() Method public java.lang.String getServletPath()
The getServletPath() method returns the part of the URI that refers to the servlet being invoked. getServletPath() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The javax.servlet.http Package APPENDIX C
467
The getSession(boolean create) Method public HttpSession getSession(boolean create)
This getSession() method returns the session associated with the request. If there is no valid session and the boolean parameter passed in is true, it will create a new session. getSession() throws no exceptions. It has one parameter: •
boolean
It returns this value: HttpSession
The getSession() Method public HttpSession getSession()
This getSession() method performs the same as the previous getSession() method; it just performs as if it were always passed a true value. getSession() has no parameters and throws no exceptions. It returns this value: •
HttpSession
The isRequestedSessionValid() Method public boolean isRequestedSessionValid()
The isRequestedSessionValid() method returns true if the session is valid in the current context; otherwise, it returns false. isRequestedSessionValid() has no parameters and throws no exceptions. It returns this value: •
boolean
The isRequestedSessionFromCookie() Method public boolean isRequestedSessionFromCookie()
The isRequestedSessionFromCookie() method returns true if the session ID from the request came in as a cookie; otherwise, it returns false. isRequestedSessionFromCookie() has no parameters and throws no exceptions. It returns this value: •
boolean
THE JAVAX.SERVLET.HTTP PACKAGE
•
C
468
Appendixes PART IV
The isRequestedSessionIdFromURL() Method public boolean isRequestedSessionIdFromURL()
The isRequestedSessionIdFromURL() method returns true if the session ID from the request came in as part of the URL; otherwise it returns false. isRequestedSessionIdFromURL() has no parameters and throws no exceptions. It returns this value: •
boolean
The HttpServletResponse Interface public interface HttpServletResponse extends ServletRequest
The HttpServletResponse interface defines an object that provides the HttpServlet.service() method with the capability to manipulate HTTP-protocol specific header information and return data to the client. The HttpServletResponse interface has 39 fields and 10 methods, described in the following sections.
The SC_CONTINUE Field public static final int SC_CONTINUE
This field represents a status code of (100), indicating that the client can continue.
The SC_SWITCHING_PROTOCOLS Field public static final int SC_SWITCHING_PROTOCOLS
This field represents a status code of (101), indicating the server is switching protocols according to the Upgrade header.
The SC_OK Field public static final int SC_OK
This field represents a status code of (200), indicating the request succeeded normally.
The SC_CREATED Field public static final int SC_CREATED
This field represents a status code of (201), indicating the request succeeded and created a new resource on the server.
The SC_ACCEPTED Field public static final int SC_ACCEPTED
The javax.servlet.http Package APPENDIX C
469
This field represents a status code of (202), indicating that a request was accepted for processing, but was not completed.
The SC_NON_AUTHORITATIVE_INFORMATION Field public static final int SC_NON_AUTHORITATIVE_INFORMATION
This field represents a status code of (203), indicating that the meta information presented by the client did not originate from the server.
The SC_NO_CONTENT Field public static final int SC_NO_CONTENT
The SC_RESET_CONTENT Field public static final int SC_RESET_CONTENT
This field represents a status code of (205), indicating that the agent should reset the document view that caused the request to be sent.
The SC_PARTIAL_CONTENT Field public static final int SC_PARTIAL_CONTENT
This field represents a status code of (206), indicating that the server has fulfilled the partial GET request for the resource.
The SC_MULTIPLE_CHOICES Field public static final int SC_MULTIPLE_CHOICES
This field represents a status code of (300), indicating that the requested resource corresponds to any one of a set of representations, each with its own specific location.
The SC_MOVED_PERMANENTLY Field public static final int SC_MOVED_PERMANENTLY
This field represents a status code of (301), indicating that the resource has permanently moved to a new location, and that future references should use a new URI with their requests.
The SC_MOVED_TEMPORARILY Field public static final int SC_MOVED_TEMPORARILY
This field represents a status code of (302), indicating that the resource has temporarily moved to another location, but that future references should still use the original URI to access the resource.
THE JAVAX.SERVLET.HTTP PACKAGE
This field represents a status code of (204), indicating that the request succeeded but that there was no new information to return.
C
470
Appendixes PART IV
The SC_SEE_OTHER Field public static final int SC_SEE_OTHER
This field represents a status code of (303), indicating that the response to the request can be found under a different URI.
The SC_NOT_MODIFIED Field public static final int SC_NOT_MODIFIED
Thistus code of (304), indicating that a conditional GET operation found that the resource was available and not modified.
The SC_USE_PROXY Field public static final int SC_USE_PROXY
This field represents a status code of (305), indicating that the requested resource must be accessed through the proxy given by the location field.
The SC_BAD_REQUEST Field public static final int SC_BAD_REQUEST
This field represents a status code of (400), indicating the request sent by the client was syntactically incorrect.
The SC_UNAUTHORIZED Field public static final int SC_UNAUTHORIZED
This field represents a status code of (401), indicating that the request requires HTTP authentication.
The SC_PAYMENT_REQUIRED Field public static final int SC_PAYMENT_REQUIRED
This field represents a status code of (402) for future use.
The SC_FORBIDDEN Field public static final int SC_FORBIDDEN
This field represents a status code of (403), indicating the server understood the request but refused to fulfill it.
The SC_NOT_FOUND Field public static final int SC_NOT_FOUND
The javax.servlet.http Package APPENDIX C
471
This field represents a status code of (404), indicating that the requested resource is not available.
The SC_METHOD_NOT_ALLOWED Field public static final int SC_METHOD_NOT_ALLOWED
This field represents a status code of (405), indicating that the method specified in the Request-Line is not allowed for the resource identified by the Request-URI.
The SC_NOT_ACCEPTABLE Field public static final int SC_NOT_ACCEPTABLE
The SC_PROXY_AUTHENTICATION_REQUIRED Field public static final int SC_PROXY_AUTHENTICATION_REQUIRED
This field represents a status code of (407), indicating that the client must first authenticate itself with the proxy.
The SC_REQUEST_TIMEOUT Field public static final int SC_REQUEST_TIMEOUT
This field represents a status code of (408), indicating that the client did not produce a request within the time that the server was prepared to wait.
The SC_CONFLICT Field public static final int SC_CONFLICT
This field represents a status code of (409), indicating that the request could not be completed because of a conflict with the current state of the resource.
The SC_GONE Field public static final int SC_GONE
This field represents a status code of (410), indicating that the resource is no longer available at the server and no forwarding address is known. This condition should be considered permanent.
The SC_LENGTH_REQUIRED Field public static final int SC_LENGTH_REQUIRED
THE JAVAX.SERVLET.HTTP PACKAGE
This field represents a status code of (406), indicating that the resource identified by the request is only capable of generating response entities which have content characteristics not acceptable according to the accept headers sent in the request.
C
472
Appendixes PART IV
This field represents a status code of (411), indicating that the request cannot be handled without a defined Content-Length.
The SC_PRECONDITION_FAILED Field public static final int SC_PRECONDITION_FAILED
This field represents a status code of (412), indicating that the precondition given in one or more of the request-header fields evaluated to false when it was tested on the server.
The SC_REQUEST_ENTITY_TOO_LARGE Field public static final int SC_REQUEST_ENTITY_TOO_LARGE
This field represents a status code of (413), indicating that the server is refusing to process the request because the request entity is larger than the server is willing or able to process.
The SC_REQUEST_URI_TOO_LONG Field public static final int SC_REQUEST_URI_TOO_LONG
This field represents a status code of (414), indicating that the server is refusing to service the request because the Request-URI is longer than the server is willing to interpret.
The SC_UNSUPPORTED_MEDIA_TYPE Field public static final int SC_UNSUPPORTED_MEDIA_TYPE
This field represents a status code of (415), indicating that the server is refusing to service the request because the entity of the request is in a format not supported by the requested resource for the requested method.
The SC_INTERNAL_SERVER_ERROR Field public static final int SC_INTERNAL_SERVER_ERROR
This field represents a status code of (500), indicating an error inside the HTTP server that prevented it from fulfilling the request.
The SC_NOT_IMPLEMENTED Field public static final int SC_NOT_IMPLEMENTED
This field represents a status code of (501), indicating the HTTP server does not support the functionality needed to fulfill the request.
The SC_BAD_GATEWAY Field public static final int SC_BAD_GATEWAY
This field represents a status code of (502), indicating that the HTTP server received an invalid response from a server it consulted when acting as a proxy or gateway.
The javax.servlet.http Package APPENDIX C
473
The SC_SERVICE_UNAVAILABLE Field public static final int SC_SERVICE_UNAVAILABLE
This field represents a status code of (503), indicating that the HTTP server is temporarily overloaded, and unable to handle the request.
The SC_GATEWAY_TIMEOUT Field public static final int SC_GATEWAY_TIMEOUT
This field represents a status code of (504), indicating that the server did not receive a timely response from the upstream server while acting as a gateway or proxy.
public static final int SC_HTTP_VERSION_NOT_SUPPORTED
This field represents a status code of (505), indicating that the server does not support or refuses to support the HTTP version found in the request.
The addCookie() Method public void addCookie(Cookie cookie)
The addCookie() method adds a Cookie to the HttpServletResponse object. addCookie() throws no exceptions and returns no value. It has one parameter: •
Cookie
The containsHeader() Method public boolean containsHeader(java.lang.String name)
The containsHeader() method returns true if the named header exists in the response. containsHeader() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
boolean
The encodeURL() Method public java.lang.String encodeURL(java.lang.String url)
The encodeURL() method’s URL encodes the passed-in string and returns it. If no changes are necessary, then it simply returns the string. encodeURL() throws no exceptions.
THE JAVAX.SERVLET.HTTP PACKAGE
The SC_HTTP_VERSION_NOT_SUPPORTED Field
C
474
Appendixes PART IV
It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The encodeRedirectURL() Method public java.lang.String encodeRedirectURL(java.lang.String url)
The encodeRedirectURL() method’s URL encodes the passed-in string for use in the sendRedirect() method. If no changes are necessary, it simply returns the string. encodeRedirectURL() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.String
The sendError(int sc, java.lang.String message) Method public void sendError(int sc, java.lang.String message) throws java.io.IOException
This sendError() method sends an error to the client in the response object. The error consists of the int status code and a string message. sendError() returns no value. It has two parameters: •
int
•
java.lang.String
It throws this exception: •
java.io.IOException
The sendError(int sc) Method public void sendError(int sc) throws java.io.IOException
This sendError() method sends an error to the client in the response object. The error consists of only the int status code. sendError() returns no value.
The javax.servlet.http Package APPENDIX C
475
It has one parameter: •
int
It throws this exception: •
java.io.IOException
The sendRedirect() Method public void sendRedirect(java.lang.String url) throws java.io.IOException
It has one parameter: •
java.lang.String
It throws this exception: •
java.io.IOException
The setDateHeader() Method public void setDateHeader(java.lang.String name, long date)
The setDateHeader() method adds a name/date-value field to the response header. The date value is a long representing milliseconds since the epoch. setDateHeader() returns no value and throws no exception. It has two parameters: •
java.lang.String
•
long
The setIntHeader() Method public void setIntHeader(java.lang.String name, int value)
The setIntHeader() method adds a name/int-value field to the response header. If the field is already present in the request, it is replaced. setIntHeader() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
int
C THE JAVAX.SERVLET.HTTP PACKAGE
The sendRedirect() method redirects the client to the passed-in URL, which must be an absolute URL. sendRedirect() returns no value.
476
Appendixes PART IV
The setStatus() Method public void setStatus(int sc)
The setStatus() method sets the status code for the response. setStatus() returns no value and throws no exceptions. It has one parameter: •
int
The HttpSession Interface public interface HttpSession
The HttpSession interface defines an object that provides an association between a client and server; this association persists over multiple connections. Using HttpSession gives you the ability to maintain state between transactions. This interface has 12 methods, described in the following sections.
The getAttribute() Method public java.lang.Object getAttribute(java.lang.String name)
The getAttribute() method returns a reference to the named object in the current session. The object must be downcasted to its original type. getAttribute() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The getAttributeNames() Method public Enumeration getAttributeNames()
The getAttributeNames() method returns an enumeration of strings representing all of the data objects bound to this session. getAttributeNames() has no parameters and throws no exceptions. It returns this value: •
Enumeration
The getCreationTime() Method public long getCreationTime()
The javax.servlet.http Package APPENDIX C
477
The getCreationTime() method returns the time in which the session was created. This time value is a long representing the milliseconds elapsed since January 1, 1970 UTC. getCreationTime() has no parameters and throws no exceptions. It returns this value: •
long
The getId() Method public java.lang.String getId()
It returns this value: •
java.lang.String
The getLastAccessedTime() Method public long getLastAccessedTime()
The getLastAccessedTime() method returns the last time, in milliseconds, the client sent a request with HttpSession. getLastAccessedTime() has no parameters and throws no exceptions. It returns this value: •
long
The getMaxIntervalTime() Method public int getMaxIntervalTime()
The getMaxIntervalTime() method returns the maximum interval between requests that the server will keep the session valid. getMaxIntervalTime() has no parameters and throws no exceptions. It returns this value: •
int
The invalidate() Method public void invalidate()
The invalidate() method forces the session to be invalidated and removed from the context. invalidate() has no parameters, returns no value, and throws no exceptions.
C THE JAVAX.SERVLET.HTTP PACKAGE
The getId() method returns a string containing a unique identifier for the current HttpSession. getId() has no parameters and throws no exceptions.
478
Appendixes PART IV
The isNew() Method public boolean isNew()
The isNew() method returns true if the server has just created the session and the session has not been acknowledged by the client. isNew() has no parameters and throws no exceptions. It returns this value: •
boolean
The setAttribute() Method public void setAttribute(java.lang.String name) java.lang.Object value)
The setAttribute() method binds the passed-in object to the passed-in string and puts the object into the session. If an object in the session is already bound to the name, it is replaced. setAttribute() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
java.lang.Object
The removeAttribute() Method public void removeAttribute(java.lang.String name)
The removeAttribute() method removes the object from the current session that is bound to the passed-in name. All objects implementing the HttpSessionBindingListener interface will have their valueUnbound() methods called. removeAttribute() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The setMaxIntervalTime() Method public void setMaxIntervalTime(int interval)
The setMaxIntervalTime() method sets the maximum interval between requests before a server invalidates the session. setMaxIntervalTime() returns no value and throws no exceptions. It has one parameter: •
int
The javax.servlet.http Package APPENDIX C
479
The HttpSessionBindingListener Interface public interface HttpSessionBindingListener extends java.util.EventListener
The HttpSessionBindingListener interface defines methods that an object can implement if it wants to be notified of an object in the session being bound or unbound. The HttpSessionBindingListener interface has two methods, described in the following sections.
The valueBound() Method public void valueBound(HttpSessionBindingEvent event)
It has one parameter: •
HttpSessionBindingEvent
The valueUnBound() Method public void valueUnBound(HttpSessionBindingEvent event)
The valueUnBound() method notifies a listener that the object is being unbound from a session. valueUnBound() returns no value and throws no exceptions. It has one parameter: •
HttpSessionBindingEvent
Classes The four classes for the java.servlet.http package are Cookie, HttpServlet, HttpSessionBindingEvent, and HttpUtils.
The Cookie Class public class Cookie extends java.lang.Object implements java.lang.Cloneable
The Cookie class represents a cookie used for session management in HTTP protocols. Cookies are name/value pairs that are created by the server and stored in the client. The Cookie class has 17 methods, described in the following sections.
The Cookie() Method public Cookie(java.lang.String name, java.lang.String value)
THE JAVAX.SERVLET.HTTP PACKAGE
The valueBound() method notifies a listener that the object is being bound into a session. valueBound() returns no value and throws no exceptions.
C
480
Appendixes PART IV
The Cookie() constructor initializes a Cookie object with the passed-in name/value pair. Names cannot contain whitespace, commas, or semicolons and should only contain ASCII alphanumeric characters. Cookie() returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
java.lang.String
The setComment() Method public void setComment(java.lang.String purpose)
The setComment() method is used to describe the cookie’s purpose when requested by the client. setComment() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The getComment() Method public java.lang.String getComment()
The getComment() method returns the comment used to describe the cookie’s purpose. getComment() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The setDomain() Method public void setDomain(java.lang.String pattern)
The setDomain() method sets the pattern to match the host’s domain. If the host does not match, the cookie will not be presented to the host. setDomain() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The getDomain() Method public java.lang.String getDomain()
The getDomain() method returns the domain pattern of this cookie. getDomain() has no parameters and throws no exceptions.
The javax.servlet.http Package APPENDIX C
481
It returns this value: •
java.lang.String
The setMaxAge() Method public void setMaxAge(int value)
The setMaxAge() method sets the maximum age of the cookie. The cookie will expire after the passed-in number of seconds. setMaxAge() returns no value and throws no exceptions. It has one parameter: int
The getMaxAge() Method public int getMaxAge()
The getMaxAge() method returns the maximum age of the cookie in seconds. getMaxAge() has no parameters and throws no exceptions. It returns this value: •
int
The setPath() Method public void setPath(java.lang.String uri)
The setPath() method sets the valid path for the cookie. If the URL does not begin with the passed-in value, it is not a valid path. setPath() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The getPath() Method public java.lang.String getPath()
The getPath() method returns the URL prefix for which this cookie is targeted. getPath() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The setSecure() Method public void setSecure(boolean flag)
C THE JAVAX.SERVLET.HTTP PACKAGE
•
482
Appendixes PART IV
The setSecure() method indicates to the user agent that the cookie should only be transmitted using a secure protocol. setSecure() returns no value and throws no exceptions. It has one parameter: •
boolean
The getSecure() Method public boolean getSecure()
The getSecure() method returns true if the cookie can only be transmitted using a secure protocol. getSecure() has no parameters and throws no exceptions. It returns this value: •
boolean
The getName() Method public java.lang.String getName()
The getName() method returns the name of the cookie. getName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The setValue() Method public void setValue(java.lang.String value)
The setValue() method sets the value of the cookie. setValue() returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The getValue() Method public java.lang.String getValue()
The getValue() method returns the value of the cookie. getValue() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The javax.servlet.http Package APPENDIX C
483
The getVersion() Method public int getVersion()
The getVersion() method returns the version number of the cookie. A zero indicates that the cookie is based on the original specification developed by Netscape. A one indicates the cookie is based on the RFC 2109. getVersion() has no parameters and throws no exceptions. It returns this value: •
int
public void setVersion(int value)
The setVersion() method sets the cookie protocol used when the cookie saves itself. setVersion() returns no value and throws no exceptions. It has one parameter: •
int
The clone() Method public java.lang.Object clone()
The clone() method returns a copy of this object. clone() has no parameters and throws no exceptions. It returns this value: •
java.lang.Object
The HttpServlet Class public class HttpServlet extends javax.servlet.GenericServlet implements java.io.Serializable
The HttpServlet class is meant to simplify the writing of HTTP servlets. It extends the GenericServlet class and implements the java.io.Serializable interface. The HttpServlet class is an abstract class; therefore it cannot be instantiated directly. The HttpServlet class has 11 methods, described in the following sections.
The HttpServlet() Method public HttpServlet()
The HttpServlet() constructor is a default empty constructor. HttpServlet() has no parameters, returns no value, and throws no exceptions.
The doGet() method services all GET requests for the servlet.
NOTE The HttpServlet class’s doGet, doPost, doPut, doDelete, doOptions, and doTrace methods all receive the same two parameters—an HttpServletRequest object, which encapsulates the client’s request, and an HttpServletResponse object, which contains the response that is sent back to the client. Each of these methods throws a ServletException if it cannot service the request and throws a java.io.IOException if there was an I/O error. These methods return no value.
The doOptions() method services all OPTIONS requests for the servlet. The default implementation automatically determines what HTTP options are supported.
The doTrace() Method
The doTrace() method services all TRACE requests for the servlet. getLastModifiedTime()
Method
protected long getLastModifiedTime(HttpServletRequest request)
The getLastModifiedTime() method returns the last time the requested entity was modified. The value returned is measured in milliseconds since January 1, 1970. getLastModifiedTime() throws no exceptions. It has one parameter: •
This is an HTTP-specific implementation of the Servlet.service() method. It handles standard HTTP requests by dispatching them to the appropriately implemented methods. The service() method throws a ServletException if it cannot service the request and throws a java.io.IOException if there was an I/O error. service() returns no value.
The service(ServletRequest request, ServletResponse response) Method public void service(ServletRequest request, ServletResponse response) throws ServletException java.io.Exception
This method implements the Servlet.service() method by delegating requests to the appropriate HTTP-specific service() method. The service() method throws a ServletException if it cannot service the request and throws a java.io.IOException if there was an I/O error. service() returns no value. It has two parameters: •
ServletRequest
•
ServletResponse
It throws these exceptions: •
ServletException
•
java.io.IOException
The HttpSessionBindingEvent Class public class HttpSessionBindingEvent extends java.util.EventObject
The HttpSessionBindingEvent class is sent to all objects that implement the HttpSessionBindingListener when a listener is bound or unbound from an HttpSession. The HttpSessionBindingEvent class has three methods, described in the following sections.
The HttpSessionBindingEvent() Method public HttpSessionBindingEvent(HttpSession session, java.lang.String name)
The javax.servlet.http Package APPENDIX C
487
The HttpSessionBindingEvent() constructor initializes the object with the session acting as the source of the event and the name of the object being bound or unbound. HttpSessionBindingEvent() returns no value and throws no exceptions. It has two parameters: •
HttpSession
•
java.lang.String
The getName() Method public java.lang.String getName()
It returns this value: •
java.lang.String
The getSession() Method public HttpSession getSession()
The getSession() method returns the session from which the listener is being bound or unbound. getSession() has no parameters and throws no exceptions. It returns this value: •
HttpSession
The HttpUtils Class public class HttpUtils extends java.util.EventObject
The HttpUtils class contains a collection of static utility methods that are useful to HTTP servlets. The HttpUtils class has four methods, described in the following sections.
The HttpUtils() Method public HttpUtils()
The HttpUtils() constructor creates an empty HttpUtility object. HttpUtils() has no parameters, returns no value, and throws no exceptions.
The parseQueryString() Method public static java.util.Hashtable parseQueryString(java.lang.String s)
THE JAVAX.SERVLET.HTTP PACKAGE
The getName() method returns the name of the object that is being bound or unbound. getName() has no parameters and throws no exceptions.
C
488
Appendixes PART IV
The parseQueryString() method takes the passed-in query string and parses it into a hash table of key/value pairs where the values are arrays of strings. parseQueryString() throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.util.Hashtable
The parsePostData() Method public static java.util.Hashtable parsePostData(int len, ServletInputStream in)
The parsePostData() method takes HTML from data that is sent to the server as a POST request, parses it, and returns a hash table of key/value pairs. If keys have multiple values, their values are stored as an array of strings. parsePostData() throws no exceptions. It has two parameters: •
int
•
ServletInputStream
It returns this value: •
java.util.Hashtable
The getRequestURL() Method public static java.lang.StringBuffer getRequestURL(HttpServletRequest request)
The getRequestURL() method takes a request object and reconstructs the URL used by the client to make the request. getRequestURL() throws no exceptions. It has one parameter: •
HttpServletRequest
It returns this value: •
java.lang.StringBuffer
The javax.servlet.jsp Package
IN THIS APPENDIX • Interfaces • Classes
490
492
• Exceptions
511
APPENDIX
D
490
Appendixes PART IV
The javax.servlet.jsp package makes up the bulk of the Java Server Pages API. It is covered completely in the following sections. Figure D.1 contains the javax.servlet.jsp object model. javax.servlet.Servlet
java.lang.Object
JspPage JspEngineInfo
HttpJspPage
JspFactory
PageContext
java.lang.Exception
java.io.Writer
JspWriter
JspException
JspError
FIGURE D.1 The javax.servlet.jsp Object Model.
Interfaces The javax.servlet.jsp package has two interfaces: HttpJspPage and JspPage.
The HttpJspPage Interface public interface HttpJspPage extends JspPage
This is the interface that a JSP processor-generated class for the HTTP protocol must satisfy. It extends JspPage and defines a single method.
The _jspService() Method public void _jspService( javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException, java.io.IOException
The javax.servlet.jsp Package APPENDIX D
491
The _jspService method corresponds to the body of the JSP page. It is defined automatically by the JSP processor and should never be redefined by the JSP author. It returns no value. It has two parameters: •
HttpServletRequest
•
HttpServletResponse
It throws these exceptions: •
javax.servlet.ServletException
•
java.io.IOException
The JspPage Interface public interface JspPage extends javax.servlet.Servlet
This is the interface that a JSP processor-generated class must implement.
A class implementing this interface is responsible for invoking these methods at the appropriate time based on the corresponding Servlet-based method invocations. The jspInit() and jspDestroy() methods can be defined by a JSP author, but the _jspService() method is defined automatically by the JSP processor based on the contents of the JSP page.
The jspInit() Method public void jspInit()
The jsp_init() method is invoked when the JspPage is initialized. After the JspPage is initialized, the getServletConfig() method will return the desired value. jsp_init() is synonymous with the init() method of a servlet. It has no parameters, returns no value, and throws no exceptions.
The jspDestroy() Method public void jspDestroy()
The jspDestroy() method is invoked when the JspPage is about to be destroyed. It is synonymous with the destroy() method of a servlet. It has no parameters, returns no value, and throws no exceptions.
D THE JAVAX.SERVLET.JSP PACKAGE
This interface defines a protocol with three methods; only two of them, jspInit() and jspDestroy(), are part of this interface. The signature of the third method, _jspService(), depends on the specific protocol used and cannot be expressed in a generic way in Java.
492
Appendixes PART IV
Classes The javax.servlet.jsp package has four classes: JspEngineInfo, JspFactory, JspWriter, and PageContext.
The JspEngineInfo Class public abstract class JspEngineInfo
The JspEngineInfo class is an abstract class that provides information on the current JSP engine. It defines two methods.
The JspEngineInfo() Method public JspEngineInfo()
The JspEngineInfo() method is an empty default constructor. It has no parameters, returns no value, and throws no exceptions.
The getImplementationVersion() Method public java.lang.String getImplementationVersion()
The getImplementationVersion() method returns the current version of the JSP specification. The version number must begin with a number. If the version is not defined, a null will be returned. It has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The JspFactory Class public abstract class JspFactory extends java.lang.Object
is an abstract class that defines a number of factory methods available to a JSP page at runtime for the purposes of creating instances of various interfaces and classes used to support the JSP implementation. It has one field and six methods.
JspFactory
The deflt Field private static JspFactory deflt
The deflt field represents the default JSPFactory implementation.
The JspFactory() Method public JspFactory()
The javax.servlet.jsp Package APPENDIX D
493
The JspFactory() method is an empty default constructor. It has no parameters, returns no value, and throws no exceptions.
The setDefaultFactory() Method public static void setDefaultFactory(JspFactory deflt)
The setDefaultFactory() method sets the default factory for this JSP implementation. It is illegal for any principal other than the JSP Engine runtime to call this method. It returns no value and throws no exceptions. It has one parameter: •
JspFactory
The getDefaultFactory() Method public static JspFactory getDefaultFactory()
The getDefaultFactory() method returns the default factory for this JSP implementation. It has no parameters and throws no exceptions. It returns this value: JspFactory
The getPageContext() Method public abstract PageContext getPageContext( javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int buffer, boolean autoflush)
The getPageContext() method obtains an instance of an implementation-dependent javax.servlet.jsp.PageContext abstract class for the calling servlet and currently pending request and response. This method is typically called early in the processing of the _jspService() method of a JSP implementation class to obtain a PageContext object for the request being processed. Invoking this method results in the PageContext.initialize() method being invoked. The returned object is a properly initialized PageContext. All PageContext objects obtained through this method must be released by invoking releasePageContext(). The getPageContext() method throws no exceptions. It has seven parameters: •
javax.servlet.Servlet
•
javax.servlet.ServletRequest
D THE JAVAX.SERVLET.JSP PACKAGE
•
494
Appendixes PART IV
•
javax.servlet.ServletResponse
•
java.lang.String
•
boolean
•
int
•
boolean
It returns this value: •
PageContext
The releasePageContext() Method public void releasePageContext(PageContext pc)
The releasePageContext() method is called to release a previously allocated PageContext object returned from a call to getPageContext(). This method should be invoked prior to returning from the _jspService() method of a JSP implementation class. It returns no value and throws no exceptions. It has one parameter: •
PageContext
The getEngineInfo() Method public JspEngineInfo getEngineInfo()
The getEngineInfo() method is called to get implementation-specific information on the current JSP engine. It has no parameters and throws no exceptions. It returns this value: •
JspEngineInfo
The JspWriter Class public abstract class JspWriter extends java.io.Writer
is an abstract class that emulates some functionality found in the and java.io.PrintWriter classes. However it differs in that it throws a java.io.IOException from the print methods where PrintWriter does not. The “out” implicit variable of a JSP implementation class is of this type. It defines four fields and 28 methods. JspWriter
java.io.BufferedWriter
The NO_BUFFER Field public static final int NO_BUFFER
The javax.servlet.jsp Package APPENDIX D
495
This field is a constant indicating that the Writer is not buffering output.
The DEFAULT_BUFFER Field public static final int DEFAULT_BUFFER
This field is a constant indicating that the Writer is buffered and is using the implementation default buffer size.
The bufferSize Field protected int bufferSize
This field gives the Writer buffer size.
The autoFlush Field protected boolean autoFlush
This field indicates whether the buffer will be automatically flushed.
The JspWriter() Method protected JspWriter(int bufferSize, boolean autoFlush)
It has two parameters: •
int
•
boolean
The newLine() Method public void newLine() throws java.io.IOException
The newLine() method writes a line separator. The line separator string is defined by the system property line.separator, and is not guaranteed to be a single new line (\n) character. This method has no parameters and returns no value. It throws this exception: •
java.io.IOException
The print(boolean b) Method public void print(boolean b) throws java.io.IOException
The print(boolean
method prints a boolean value. The string produced by is translated into bytes according to the platform’s default character encoding, and these bytes are written in exactly the manner of the Writer.write(int) method. b)
String.valueOf(boolean)
D THE JAVAX.SERVLET.JSP PACKAGE
The JspWriter() method is a protected constructor. It returns no value and throws no exceptions.
496
Appendixes PART IV
It has one parameter: •
boolean
NOTE The print() method prints data type values, which are translated into bytes. For all values, these bytes are written in exactly the same manner as the Writer.write(int) method.
NOTE The print() method’s parameter is determined by the print value. The method always throws a java.io.IOException exception. For all print values, the print() method returns no value.
The print(char c) Method public void print(char c) throws java.io.IOException
The print(char c) method prints a char value. The character is translated into one or more bytes according to the platform’s default character encoding. It has one parameter: •
char
The print(int i) Method public void print(int i) throws java.io.IOException
The print(int i) method prints an integer. The string produced by String.valueOf(int) is translated into bytes according to the platform’s default character encoding. It has one parameter: •
int
The print(long l) Method public void print(long l) throws java.io.IOException
The print(long l) method prints a long. The string produced by String.valueOf(long) is translated into bytes according to the platform’s default character encoding.
The javax.servlet.jsp Package APPENDIX D
497
It has one parameter: •
long
The print(float f) Method public void print(float f) throws java.io.IOException
The print(float f) method prints a float. The string produced by String.valueOf(float) is translated into bytes according to the platform’s default character encoding. It has one parameter: •
float
The print(double d) Method public void print(double d) throws java.io.IOException
The print(double
d)
method prints a double. The string produced by is translated into bytes according to the platform’s default character
String.valueOf(double)
encoding. It has one parameter: double
The print(char[] s) Method public void print(char[] s) throws java.io.IOException
The print(char[] s) method prints an array of characters. The characters are converted into bytes according to the platform’s default character encoding. It has one parameter: •
char[]
The print(java.lang.String s) Method public void print(java.lang.String s) throws java.io.IOException
The print(java.lang.String s) method prints a string. If the argument is null then the string “null” is printed. Otherwise, the string’s characters are converted into bytes according to the platform’s default character encoding. It has one parameter: •
java.lang.String
The print(java.lang.Object obj) Method public void print(java.lang.Object obj) throws java.io.IOException
THE JAVAX.SERVLET.JSP PACKAGE
•
D
498
Appendixes PART IV
The print(java.lang.Object obj) method prints an object. The string produced by the String.valueOf(Object) method is translated into bytes according to the platform’s default character encoding. It has one parameter: •
java.lang.Object
The println() Method public void println() throws java.io.IOException
The println() method terminates the current line by writing the line separator string. The line separator string is defined by the system property line.separator, and is not necessarily a single newline character (\n). This method has no parameters.
NOTE The println() method always throws a java.io.IOException exception. It returns no value.
The println(boolean x) Method public void println(boolean x) throws java.io.IOException
The println(boolean x) method prints a boolean value and then terminates the line. This method behaves as though it invokes print(boolean) and then println(). It has one parameter: •
boolean
The println(char x) Method public void println(char x) throws java.io.IOException
The println(char x) method prints a character and then terminates the line. This method behaves as though it invokes print(char) and then println(). It has one parameter: •
char
The println(int x) Method public void println(int x) throws java.io.IOException
The println(int x) method prints an integer and then terminates the line. This method behaves as though it invokes print(int) and then println().
The javax.servlet.jsp Package APPENDIX D
499
It has one parameter: •
int
The println(long x) Method public void println(long x) throws java.io.IOException
The println(long x) method prints a long integer and then terminates the line. This method behaves as though it invokes print(long) and then println(). It has one parameter: •
long
The println(float x) Method public void println(float x) throws java.io.IOException
The println(float x) method prints a float and then terminates the line. This method behaves as though it invokes print(float) and then println(). It has one parameter: float
The println(double x) Method public void println(double x) throws java.io.IOException
The println(double x) method prints a double-precision floating-point number and then terminates the line. This method behaves as though it invokes print(double) and then println(). It has one parameter: •
double
The println(char[] x) Method public void println(char[] x) throws java.io.IOException
The println(char[] x) method prints an array of characters and then terminates the line. This method behaves as though it invokes print(char[]) and then println(). It has one parameter: •
char[]
The println(java.lang.String x) Method public void println(java.lang.String x) throws java.io.IOException
D THE JAVAX.SERVLET.JSP PACKAGE
•
500
Appendixes PART IV
The println(java.lang.String x) method prints a string and then terminates the line. This method behaves as though it invokes print(String) and then println(). It has one parameter: •
java.lang.String
The println(java.lang.Object x) Method public void println(java.lang.Object x) throws java.io.IOException
The println(java.lang.Object x) method prints an object and then terminates the line. This method behaves as though it invokes print(Object) and then println(). It has one parameter: •
java.lang.Object
The clear() Method public void clear() throws java.io.IOException
The clear() method clears the contents of the buffer. If the buffer has been already been flushed then the clear operation throws an IOException to signal the fact that some data has already been irrevocably written to the client response stream. This method has no parameters and returns no value. It throws this exception: •
java.io.IOException
The clearBuffer() Method public void clearBuffer() throws java.io.IOException
The clearBuffer() method clears the current contents of the buffer. Unlike clear(), this method will not throw an IOException if the buffer has already been flushed. It merely clears the current contents of the buffer and returns. This method has no parameters and returns no value. It throws this exception: •
java.io.IOException
The flush() Method public void flush() throws java.io.IOException
The flush() method flushes the stream. If the stream has saved any characters from the various write() methods in a buffer, they are written immediately to their intended destination. Then, if that destination is another character or byte stream, that stream is flushed. Thus one
The javax.servlet.jsp Package APPENDIX D
501
flush() invocation will flush all the buffers in a chain of Writers and OutputStreams. This method has no parameters and returns no value.
It throws this exception: •
java.io.IOException
The close() Method public void close() throws java.io.IOException
The close() method closes the stream, flushing it first. After a stream has been closed, further write() or flush() invocations will cause an IOException to be thrown. Closing a previously closed stream, however, has no effect. This method has no parameters and returns no value. It throws this exception: •
java.io.IOException
The getBufferSize() Method public int getBufferSize() throws java.io.IOException
It returns this value: •
int
It throws this exception: •
java.io.IOException
The getRemaining() Method public int getRemaining() throws java.io.IOException
The getRemaining() method returns the number of bytes unused in the buffer. It has no parameters. It returns this value: •
int
It throws this exception: •
java.io.IOException
The isAutoFlush() Method public boolean isAutoFlush()
D THE JAVAX.SERVLET.JSP PACKAGE
The getBufferSize() method returns the size of the buffer in bytes, or 0 if there is no buffer. It has no parameters.
502
Appendixes PART IV
The isAutoFlush() method returns whether auto flush is on or not. It has no parameters. It returns this value: •
boolean
It throws this exception: •
java.io.IOException
The PageContext Class public abstract class PageContext extends java.lang.Object
The PageContext class is an abstract class, designed to be extended to provide implementation-dependent implementations by JSP engine runtime environments. A PageContext instance is obtained by a JSP implementation class by calling the JspFactory.getPageContext() method, and is released by calling JspFactory.releasePageContext(). The PageContext object provides a number of facilities to the page and/or component author and page implementer. A list of some of these facilities includes • a single API to manage the various scoped namespaces • a number of convenience APIs to access various public objects • a mechanism to obtain the JspWriter for output • a mechanism to manage session usage by the page • a mechanism to expose page directive attributes to the scripting environment • mechanisms to forward or include the current request to other active components in the application • a mechanism to handle errorpage exception processing The PageContext class has 13 fields and 25 methods.
The APPLICATION Field public static final java.lang.String APPLICATION
This field indicates a name used to store the ServletContext in the PageContext name table.
The APPLICATION_SCOPE Field public static final int APPLICATION_SCOPE
This field indicates that a named reference remains available in the ServletContext until it is reclaimed.
The javax.servlet.jsp Package APPENDIX D
503
The CONFIG Field public static final java.lang.String CONFIG
This field indicates a name used to store the ServletConfig in the PageContext name table.
The EXCEPTION Field public static final java.lang.String EXCEPTION
This field indicates a name used to store uncaught exceptions in the ServletRequest attribute list and PageContext name table.
The OUT Field public static final java.lang.String OUT
This field indicates a name used to store the current JspWriter in the PageContext name table.
The PAGE Field public static final java.lang.String PAGE
This field indicates a name used to store the servlet in this PageContext’s nametables.
public static final int PAGE_SCOPE
This field indicates that a named reference remains available in this PageContext until the return from the current Servlet.service() invocation.
The PAGECONTEXT Field public static final java.lang.String PAGECONTEXT
This field indicates a name used to store this PageContext in it’s own name tables.
The REQUEST Field public static final java.lang.String REQUEST
This field indicates a name used to store the ServletRequest in the PageContext name table.
The REQUEST_SCOPE Field public static final int REQUEST_SCOPE
This field indicates a request scope: The named reference remains available from the ServletRequest associated with the servlet until the current request is completed.
THE JAVAX.SERVLET.JSP PACKAGE
The PAGE_SCOPE Field
D
504
Appendixes PART IV
The RESPONSE Field public static final java.lang.String RESPONSE
This field indicates a name used to store the ServletResponse in the PageContext name table.
The SESSION Field public static final java.lang.String SESSION
This field indicates a name used to store the HttpSession in the PageContext name table.
The SESSION_SCOPE Field public static final int SESSION_SCOPE
This field indicates the named reference that determines the scope of the HttpSession (if any) associated with the servlet until the HttpSession is invalidated.
The PageContext() Method public PageContext()
The PageContext() method is an empty default constructor. It has no parameters, returns no value, and throws no exceptions.
The findAttribute() Method public abstract java.lang.Object findAttribute(java.lang.String name)
The findAttribute() method searches for the named attribute in page, request, session, and application scopes in order and returns the value associated or null. It throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: • java.lang.Object
The forward() Method public abstract void forward(java.lang.String relativeUrlPath) throws javax.servlet.ServletException, java.io.IOException
The forward() method is used to redirect or “forward” the current ServletRequest and ServletResponse to another active component in the application. If the relativeUrlPath begins with a “/” then the URL specified is calculated relative to the of the ServletContext for this JSP. If the path does not begin with a “/” then the URL specified is calculated relative to the URL of the request that was mapped to the calling JSP. The forward() method returns no value.
DOCROOT
The javax.servlet.jsp Package APPENDIX D
505
It has one parameter: •
java.lang.String
It throws these exceptions: •
javax.servlet.ServletException
•
java.io.IOException
The getAttribute(java.lang.String name) Method public abstract java.lang.Object getAttribute(java.lang.String name)
The getAttribute(java.lang.String name) method returns the object associated with the name in the page scope or null. It throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
D
public abstract java.lang.Object getAttribute(java.lang.String name, int scope)
The getAttribute(java.lang.String name, int scope) method returns the object associated with the name in the specified scope or null. It throws no exceptions. It has two parameters: •
java.lang.String
•
int
It returns this value: •
java.lang.Object
getAttributeNamesInScope()
Method
public abstract java.util.Enumeration getAttributeNamesInScope(int scope)
The getAttributeNamesInScope() method returns an enumeration of names of all the attributes in the specified scope. It throws no exceptions. It has one parameter: •
int
THE JAVAX.SERVLET.JSP PACKAGE
The getAttribute(java.lang.String name, int scope) Method
506
Appendixes PART IV
It returns this value: •
java.util.Enumeration
The getAttributesScope() Method public abstract int getAttributesScope(java.lang.String name)
The getAttributesScope() method returns the scope of the object associated with the name specified or 0. It throws no exceptions. It has one parameter: •
java.lang.String
It returns this value: •
int
The getException() Method public abstract java.lang.Exception getException()
The getException() method returns any exception passed to it as an errorpage. It has no parameters and throws no exceptions. It returns this value: •
java.lang.Exception
The getOut() Method public abstract JspWriter getOut()
The getOut() method returns the current JspWriter stream being used for client response. It has no parameters and throws no exceptions. It returns this value: •
javax.servlet.jsp.JspWriter
The getPage() Method public abstract java.lang.Object getPage()
The getPage() method returns the page implementation class instance associated with this PageContext. It has no parameters and throws no exceptions. It returns this value: •
java.lang.Object
The javax.servlet.jsp Package APPENDIX D
507
The getRequest() Method public abstract javax.servlet.ServletRequest getRequest()
The getRequest() method returns the ServletRequest for this PageContext. It has no parameters and throws no exceptions. It returns this value: •
javax.servlet.ServletRequest
The getResponse() Method public abstract javax.servlet.ServletResponse getResponse()
The getResponse() method returns the ServletResponse for this PageContext. It has no parameters and throws no exceptions. It returns this value: •
javax.servlet.ServletResponse
The getServletConfig() Method public abstract javax.servlet.ServletConfig getServletConfig()
It returns this value: •
javax.servlet.ServletConfig
The getServletContext() Method public abstract javax.servlet.ServletContext getServletContext()
The getServletContext() method returns the ServletContext for this PageContext. It has no parameters and throws no exceptions. It returns this value: •
javax.servlet.ServletContext
The getSession() Method public abstract javax.servlet.http.HttpSession getSession()
The getSession() method returns the HttpSession for this PageContext or null. It has no parameters and throws no exceptions.
THE JAVAX.SERVLET.JSP PACKAGE
The getServletConfig() method returns the ServletConfig for this PageContext. It has no parameters and throws no exceptions.
D
508
Appendixes PART IV
It returns this value: •
javax.servlet.http.HttpSession
The handlePageException() Method public abstract void handlePageException(java.lang.Exception e) throws javax.servlet.ServletException, java.io.IOException
The handlePageException() method is intended to process an un-handled “page” level exception by redirecting the exception to either the specified error page for this JSP, or if none was specified, to perform some implementation dependent action. This method returns no value. It has one parameter: •
java.lang.Exception
It throws these exceptions: •
javax.servlet.ServletException
•
java.io.IOException
The include() Method public abstract void include(java.lang.String relativeUrlPath) throws javax.servlet.ServletException, java.io.IOException
The include() method causes the resource specified to be processed as part of the current ServletRequest and ServletResponse being processed by the calling Thread. The output of the target resource’s processing of the request is written directly to the ServletResponse output stream. The current JspWriter “out” for this JSP is flushed as a side-effect of this call, prior to processing the include. It is only valid to call this method from a Thread executing within a _jspService() method of a JSP. This method returns no value. It has one parameter: •
java.lang.String
It throws these exceptions: •
javax.servlet.ServletException
•
java.io.IOException
The javax.servlet.jsp Package APPENDIX D
509
The initialize() Method public abstract void initialize(javax.servlet.Servlet servlet, javax.servlet.ServletRequest request, javax.servlet.ServletResponse response, java.lang.String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush) throws java.io.IOException, java.lang.IllegalStateException, java.lang.IllegalArgumentException
The initialize() method is called to initialize an un-initialized PageContext so that it can be used by a JSP Implementation class to service an incoming request and response within its _jspService() method. This method is typically called from JspFactory.getPageContext() in order to initialize state. This method is required to create an initial JspWriter, and associate the “out” name in page scope with this newly created object. It returns no value.
•
javax.servlet.Servlet
•
javax.servlet.ServletRequest
•
javax.servlet.ServletResponse
•
java.lang.String
•
boolean
•
int
•
boolean
It throws these exceptions: •
java.io.IOException
•
java.lang.IllegalStateException
•
java.lang.IllegalArgumentException
The popBody() Method public abstract JspWriter popBody()
The popBody() method returns the previous JspWriter “out” saved by the matching pushBody() method, and updates the value of the “out” attribute in the page scope attribute namespace of the PageConxtext. This method has no parameters and throws no exceptions.
THE JAVAX.SERVLET.JSP PACKAGE
It has seven parameters:
D
510
Appendixes PART IV
It returns this value: •
JspWriter
The pushBody() Method public abstract BodyJspWriter pushBody()
The pushBody() method returns a new BodyJspWriter object, saves the current “out” JspWriter, and updates the value of the “out” attribute in the page scope attribute namespace of the PageContext. It has no parameters and throws no exceptions. It returns this value: •
BodyJspWriter
The release() Method public abstract void release()
The release() method “resets” the internal state of a PageContext, releasing all internal references, and preparing the PageContext for potential reuse by a later invocation of initialize(). This method is typically called from JspFactory.releasePageContext(). It has no parameters, returns no value, and throws no exceptions.
The removeAttribute(java.lang.String name) Method public abstract void removeAttribute(java.lang.String name)
The removeAttribute(java.lang.String name) method removes the object reference associated with the specified name. It returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The removeAttribute(java.lang.String name, int scope) Method public abstract void removeAttribute(java.lang.String name, int scope)
The removeAttribute(java.lang.String name, int scope) method removes the object reference associated with the specified name and scope. It returns no value and throws no exceptions. It has two parameters: •
java.lang.String
•
int
The javax.servlet.jsp Package APPENDIX D
511
The setAttribute(java.lang.String name, java.lang.Object attribute) Method public abstract void setAttribute(java.lang.String name, java.lang.Object attribute) throws NullPointerException
The setAttribute(java.lang.String name, java.lang.Object attribute) method registers the name and object specified with page scope semantics. It returns no value. It has two parameters: •
java.lang.String
•
java.lang.Object
It throws this exception: •
NullPointerException
The setAttribute(java.lang.String name, java.lang.Object o, int scope) Method
The setAttribute(java.lang.String name, java.lang.Object o, int scope) method registers the name and object specified with appropriate scope semantics. It returns no value. It has three parameters: •
java.lang.String
•
java.lang.Object
•
int
It throws these exceptions: •
NullPointerException
•
java.lang.IllegalArgumentException
Exceptions The javax.servlet.jsp package has two exceptions: JspError and JspException. Each has two methods.
The JspError Exception public class JspError extends JspException
D THE JAVAX.SERVLET.JSP PACKAGE
public abstract void setAttribute(java.lang.String name, java.lang.Object o, int scope) throws NullPointerException, java.lang.IllegalArgumentException
512
Appendixes PART IV
When the JspError exception is caught, output generation should stop and the exception should be forwarded to errorpage.
The JspError(java.lang.String msg) Method public JspError(java.lang.String msg)
The JspError(java.lang.String value and throws no exceptions.
msg)
method is a constructor with a message. It returns no
It has one parameter: •
java.lang.String
The JspError() Method public JspError()
This method is a default empty constructor. It has no parameters, returns no value, and throws no exceptions.
The JspException Exception public class JspException extends java.lang.Exception
The JspException exception is a generic exception used by the JSP engine.
The JspException(java.lang.String msg) Method public JspException (java.lang.String msg)
This method is a constructor with a message. It returns no value and throws no exceptions. It has one parameter: •
java.lang.String
The JspException() Method public JspException ()
This method is a default empty constructor. It has no parameters, returns no value, and throws no exceptions.
The javax.servlet.jsp.tagext Package
IN THIS APPENDIX • Interfaces • Classes
514
522
APPENDIX
E
514
Appendixes PART IV
The JavaServer Pages 1.1 specification provides a portable mechanism for the description of tag libraries. Figure E.1 contains the javax.servlet.jsp.tagext object model. java.lang.Object
Tag
TagData
TagAttributeInfo
BodyTag
TagInfo
TagExtraInfo
VariableInfo
TagLibraryInfo
TagSupport
BodyTagSupport
javax.servlet.jsp.JspWriter
BodyContent
FIGURE E.1 The javax.servlet.jsp.tagext object model.
Interfaces The javax.servlet.jsp.tagext package has two interfaces: Tag and BodyTag.
The Tag Interface public interface Tag extends java.lang.Object
Actions in a tag library are defined through subclasses of the Tag interface. The interface has 13 fields and 19 methods, as described in the following sections.
The bodyOut Field protected BodyJspWriter bodyOut
This field is used to hold the reference to the BodyJspWriter.
The javax.servlet.jsp.tagext Package APPENDIX E
515
The EVAL_BODY Field public static final int EVAL_BODY
This field is used to hold the reference to the return value for doStartTag() and doAfterBody().
The EVAL_PAGE Field public static final int EVAL_PAGE
This field is used to hold the reference to the return value for doEndTag().
The libraryPrefix Field private java.lang.String libraryPrefix
This field is used to hold the prefix for the tag library of this tag.
The pageContext Field protected PageContext pageContext
This field is used to hold the reference to the current PageContext.
The parent Field private Tag parent
This field is a reference to the parent tag kept by each Tag instance, which effectively provides a runtime execution stack.
The previousOut Field private JspWriter previousOut
This field is a reference to the JspWriter and is valid when the tag is reached.
public static final int SKIP_BODY
This field indicates whether the body of the action should be evaluated.
The SKIP_PAGE Field public static final int SKIP_PAGE
This field indicates whether the action should continue to evaluate the rest of the page.
The tagData Field protected TagData tagData
This field contains the value information for a tag instance.
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
The SKIP_BODY Field
E
516
Appendixes PART IV
The tagId Field private java.lang.String tagId
This field contains the value information for a tag ID.
The tagName Field private java.lang.String tagName
This field contains a reference to the Tag’s short name.
The values Field private java.util.Hashtable values
This field contains a reference to a Hashtable containing the Tags and their associated values.
The Tag() Method public Tag(java.lang.String libraryPrefix, java.lang.String tagName)
In this default constructor, all subclasses must define a public constructor with the same signature, and to call the superclass’s constructor. This constructor is called by the code generated by the JSP translator. Tag() returns no value and throws no exceptions. It takes two parameters: •
java.lang.String
•
java.lang.String
The doAfterBody() Method public int doAfterBody() throws JspError
This method is invoked after every body evaluation. doAfterBody() has no parameters. It returns this value: •
int
It throws this exception: •
JspError
The doBeforeBody() Method public int doBeforeBody() throws JspError
This method is invoked before every body evaluation. doBeforeBody() has no parameters. It returns this value: •
int
The javax.servlet.jsp.tagext Package APPENDIX E
517
It throws this exception: •
JspError
The doEndTag() Method public int doEndTag() throws JspException
This method processes the end tag. This method will be called on all Tag objects. It returns an indication of whether the rest of the page should be evaluated or skipped. doEndTag() has no parameters. It returns this value: •
int
It throws this exception: •
JspException
The doStartTag() Method public int doStartTag() throws JspException
This method processes the start tag for this instance. The doStartTag() method assumes that initialize() has been invoked prior to its own execution. When this method is invoked, the body has not yet been invoked. doStartTag() has no parameters. It returns this value: •
int
It throws this exception: •
JspException
public static final Tag findAncestorWithClass(Tag from, java.lang.Class class)
This method finds the instance of a given class type that is closest to a given instance. This method is used for coordination among cooperating tags. findAncestorWithClass() throws no exceptions. It takes two parameters: •
Tag
•
java.lang.Class
It returns this value: •
Tag
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
The findAncestorWithClass() Method
E
518
Appendixes PART IV
The getBodyOut() Method protected final BodyJspWriter getBodyOut()
This method returns the value of the current “out” JspWriter. getBodyOut() has no parameters and throws no exceptions. It returns this value: •
BodyJspWriter
The getLibraryPrefix() Method public java.lang.String getLibraryPrefix()
This method returns the library prefix being used with this tag. getLibraryPrefix() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getPageContext() Method public PageContext getPageContext()
This method returns the PageContext for this tag. getPageContext() has no parameters and throws no exceptions. It returns this value: •
PageContext
The getParent() Method public Tag getParent()
This method returns the parent extension tag instance or null. getParent() has no parameters and throws no exceptions. It returns this value: •
Tag
The getPreviousOut() Method protected final JspWriter getPreviousOut()
This method returns the value of the “out” JspWriter prior to pushing a BodyJspWriter. getPreviousOut() has no parameters and throws no exceptions. It returns this value: •
JspWriter
The javax.servlet.jsp.tagext Package APPENDIX E
519
The getTagData() Method public TagData getTagData()
This method returns the immutable TagData for this tag. getTagData() has no parameters and throws no exceptions. It returns this value: •
TagData
The getTagId() Method public java.lang.String getTagId()
This method returns the value of the Tag Id or null. getTagId() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getTagName() Method public java.lang.String getTagName()
This method returns the short name for the Tag. getTagName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getValue() Method public java.lang.Object getValue(java.lang.String key)
It takes one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The initialize() Method public void initialize(Tag parent, TagData tagData, PageContext pc)
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
This method returns the value associated with the tag. getValue() throws no exceptions.
E
520
Appendixes PART IV
This method initializes a Tag instance so it can be used or reused. A newly created Tag instance must be prepared by invoking this method before invoking doStartTag(). A Tag instance that has been used and released by invoking release() must be reinitialized by invoking this method. initialize() returns no value and throws no exceptions. It takes three parameters: •
Tag
•
TagData
•
PageContext
The release() Method public void release()
This method releases a Tag instance so it can be used or reused. release() has no parameters, returns no value, and throws no exceptions.
The setBodyOut() Method public void setBodyOut(BodyJspWriter b)
This method sets the BodyJspWriter. It will be invoked once per action invocation at most. It will not be invoked if there is no body evaluation. setBodyOut() returns no value and throws no exceptions. It takes one parameter: •
BodyJspWriter
The setValue() Method public void setValue(java.lang.String key, java.lang.Object value)
This method sets a user-defined value on the Tag. setValue() returns no value and throws no exceptions. It takes two parameters: •
java.lang.String
•
java.lang.Object
The BodyTag Interface public interface BodyTag extends Tag
The BodyTag interface extends Tag by defining additional methods that let a Tag handler access its body.
The javax.servlet.jsp.tagext Package APPENDIX E
521
The interface provides one field and three new methods. The first is to be invoked with the BodyContent for the evaluation of the body; the second is to be reevaluated after every body evaluation.
The EVAL_BODY_TAG Field public static final int EVAL_BODY_TAG
This field requests the creation of new BodyContent on which to evaluate the body of this tag. It is returned from doStartTag and doAfterBody. This is an illegal return value for doStartTag when the class does not implement BodyTag, because BodyTag is needed to manipulate the new Writer.
The setBodyContent() Method public void setBodyContent(BodyContent b)
This method is used by the JSP engine to set the body content of the tag. It returns no value and throws no exceptions. It takes one parameter: •
BodyContent
The doInitBody() Method public void doInitBody() throws JspException
The method will be invoked once per action invocation by the page implementation. It’s invoked after a new BodyContent has been obtained and set on the tag handler through the setBodyContent() method and before the evaluation of the tag’s body into that BodyContent. It has no parameters and returns no value.
•
JspException
The doAfterBody() Method public int doAfterBody() throws JspException
The doAfterBody() method is executed after some body has been evaluated. It is not invoked in empty tags or in tags returning SKIP_BODY in doStartTag(). It has no parameters and returns no value. It throws this exception: •
JspException
E THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
It throws this exception:
522
Appendixes PART IV
Classes The nine classes defined to develop JavaServer Pages tag libraries are described in the following sections.
The BodyContent Class public abstract class BodyContent extends JspWriter
is a JspWriter subclass that can be used to process body evaluations so they can be re-extracted at a later time. It has five methods.
BodyContent
The BodyContent() Method protected BodyContent(JspWriter writer)
This method is used to construct a BodyJspWriter. It should only be used by a subclass. BodyJspWriter() returns no values and throws no exceptions. It takes one parameter: •
JspWriter
The clearBody() Method public void clearBody()
The clearBody() method is another implementation of the JspWriter method clear(). The only difference is that clearBody() is guaranteed not to throw an exception. clearBody() has no parameters, returns no value, and throws no exceptions.
The getReader() Method public abstract java.io.Reader getReader()
The getReader() method returns the value of this BodyJspWriter as a Reader, after the BodyJspWriter has been processed. getReader() has no parameters and throws no exceptions. It returns this value: •
java.io.Reader
The getString() Method public abstract java.lang.String getString()
The getString() method returns the value of this BodyJspWriter as a string after the BodyJspWriter has been processed. It has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The javax.servlet.jsp.tagext Package APPENDIX E
523
The writeOut() Method public abstract void writeOut(java.io.Writer out)
The writeOut() method writes the contents of the BodyJspWriter into a writer. It returns no value and throws no exceptions. It takes one parameter: •
java.io.Writer
The BodyTagSupport Class public class BodyTagSupport extends TagSupport implements BodyTag
The BodyTagSupport class acts as a helper class for custom tags that process body content. It provides default implementations for all the methods defined by the BodyTag interface. It has nine methods.
The BodyTagSupport() Method public BodyTagSupport()
This method is the default constructor. BodyTagSupport() takes no parameters, returns no value, and throws no exceptions.
The doAfterBody() Method public int doAfterBody() throws JspException
This is the default implementation for the doAfterBody() method defined by the BodyTag interface. The doAfterBody() method takes no parameters. It returns this value: int
It throws this exception: •
JspException
The doEndTag() Method public int doEndTag() throws JspException
This is the default implementation for the doEndTag() method defined by the BodyTag interface. The doEndTag() method takes no parameters. It returns this value: •
int
It throws this exception: •
JspException
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
•
E
524
Appendixes PART IV
The doInitBody() Method public void doInitBody() throws JspException
This is the default implementation for the doInitBody() method defined by the BodyTag interface. The doInitBody() method takes no parameters and returns no value. It throws this exception: •
JspException
The doStartTag() Method public int doStartTag() throws JspException
This is the default implementation for the doStartTag() method defined by the BodyTag interface. The doStartTag() method takes no parameters. It returns this value: •
int
It throws this exception: •
JspException
getBodyContent()
Method
public BodyContent getBodyContent()
This is the default implementation for the getBodyContent() method defined by the BodyTag interface. The getBodyContent() method takes no parameters and throws no exceptions. It returns this value: •
BodyContent
The getPreviousOut() Method public JspWriter getPreviousOut()
This is the default implementation for the getPreviousOut() method defined by the BodyTag interface. The getPreviousOut() method takes no parameters and throws no exceptions. It returns this value: •
JspWriter
The release() Method public void release()
This is the default implementation for the release() method defined by the BodyTag interface. The release() method takes no parameters, returns no value, and throws no exceptions.
The javax.servlet.jsp.tagext Package APPENDIX E
setBodyContent()
525
Method
public void setBodyContent(BodyContent b)
This is the default implementation for the setBodyContent() method defined by the BodyTag interface. The setBodyContent() method returns no values and throws no exceptions. It takes two parameters: •
BodyContent
The TagSupport Class public class TagSupport implements Tag
The TagSupport class acts as a helper class for custom tags that do not process body content. This class has 2 fields and 14 methods. It provides default implementations for all the methods defined by the Tag interface.
The id Field protected java.lang.String id
This field is used to hold the id attribute for the defined tag.
The pageContext Field protected PageContext pageContext
This field is used to hold the reference to the tag PageContext object.
The TagSupport() Method public TagSupport()
The doEndTag() Method public int doEndTag() throws JspException
This is the default implementation for the doEndTag() method defined by the Tag interface. The doEndTag() method takes no parameters. It returns this value: •
int
It throws this exception: •
JspException
E THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
This is he default constructor. TagSupport() takes no parameters, returns no value, and throws no exceptions.
526
Appendixes PART IV
The doStartTag() Method public int doStartTag() throws JspException
This is the default implementation for the doStartTag() method defined by the Tag interface. The doStartTag() method takes no parameters. It returns this value: •
int
It throws this exception: •
JspException
The findAncestorWithClass() Method public static final Tag findAncestorWithClass(Tag from, java.lang.Class klass)
The findAncestorWithClass() method finds the instance of a given class type that is closest to a given instance. This class is used for coordination among cooperating tags. This method throws no exceptions. It takes two parameters: •
Tag
•
java.lang.Class
It returns this value: •
Tag
The getId() Method public java.lang.String getId()
The getId() method returns the value of the id attribute of this tag, or null. This method takes no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getParent() Method public Tag getParent()
The getParent() method returns the Tag instance enclosing this tag instance. This method takes no parameters and throws no exceptions. It returns this value: •
Tag
The javax.servlet.jsp.tagext Package APPENDIX E
527
The getValue() Method public java.lang.Object getValue(java.lang.String k)
The getValue() method returns the value associated with the named attribute. It throws no exceptions. It takes one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The getValues() Method public java.util.Enumeration getValues()
The getValues() method returns all the attribute values in an Enumeration. It takes no parameters and throws no exceptions. It returns this value: •
java.util.Enumeration
The release() Method public void release()
This is the default implementation for the release() method defined by the Tag interface. The release() method takes no parameters, returns no value, and throws no exceptions.
The removeValue() Method public void removeValue(java.lang.String k)
It takes one parameter: •
java.lang.String
The setId() Method public void setId(java.lang.String id)
The setId() method is the basic accessor for setting the tag’s id attribute. It throws no exceptions and returns no value. It takes one parameter: •
java.lang.String
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
The removeValue() method removes the value associated with named attribute. It throws no exceptions and returns no value.
E
528
Appendixes PART IV
The setPageContext() Method public void setPageContext(PageContext pageContext)
The setPageContext() method is the basic accessor for setting the tag’s PageContext. It throws no exceptions and returns no value. It takes one parameter: •
PageContext
The setParent() Method public void setParent(Tag t)
The setParent() method is the basic accessor for setting the tag’s parent. It throws no exceptions and returns no value. It takes one parameter: •
Tag
The setValue() Method public void setValue(java.lang.String k, java.lang.Object o)
The setValue() method is the basic accessor for setting a tag’s named attribute. It throws no exceptions and returns no value. It takes two parameters: •
java.lang.String
•
java.lang.Object
The TagAttributeInfo Class public class TagAttributeInfo extends java.lang.Object
This class encapsulates information on Tag attributes. It is instantiated from the Tag Library Descriptor (TLD) file. The TagAttributeInfo class has three fields and four methods, described in the following sections.
The ID Field public static final java.lang.String ID
This field holds a reference to the tag’s ID.
The name Field private java.lang.String name
This field holds a reference to the tag’s short name.
The javax.servlet.jsp.tagext Package APPENDIX E
529
The reqTime Field private boolean reqTime
This field holds a reference to the tag’s request time.
The setValue() Method setValue(java.lang.String name, java.lang.String type, boolean reqTime)
This method is the constructor for TagAttributeInfo. There is no public constructor. This class is to be instantiated only from the tag library code under request from some JSP code that is parsing a TLD. setValue() returns no value and throws no exceptions. It takes three parameters: •
java.lang.String
•
java.lang.String
•
boolean
The getIdAttribute() Method public static TagAttributeInfo getIdAttribute(TagAttributeInfo[] a)
This method is a convenient method that goes through an array of TagAttributeInfo objects and looks for “id”. getIdAttribute() throws no exceptions. It takes one parameter: •
TagAttributeInfo[]
It returns this value: TagAttributeInfo
The getName() Method public java.lang.String getName()
This method returns the name of the attribute for the Tag. getName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
•
E
530
Appendixes PART IV
The getTypeName() Method public java.lang.String getTypeName()
This method returns the type of the attribute for the Tag. getTypeName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The TagData Class public class TagData extends java.lang.Object implements java.lang.Cloneable
This class encapsulates Tag instance attributes and values. Often, this data is fully static in the case where none of the attributes have runtime expressions as their values. Thus the TagData class is intended to expose an immutable interface to a set of immutable attribute/value pairs. This class implements Cloneable, so that implementations can create a static instance and then just clone it before adding the request-time expressions. The TagData class has two fields and five methods, described in the following sections.
The attributes Field private java.util.Hashtable attributes
This field holds a reference to a Hashtable of the tag’s attributes.
The REQUEST_TIME_VALUE Field public static final java.lang.Object REQUEST_TIME_VALUE
This field holds a reference to a distinguished value for an attribute. The value is a request-time expression, which is not yet available because this TagData instance is being used at translation-time.
The TagData() Method public TagData(java.lang.Object[][] atts)
This method is the constructor for a TagData object. It takes a single parameter, a twodimensional array of static attributes and values. TagData() returns no value and throws no exceptions. It takes one parameter: •
java.lang.Object[][]
The javax.servlet.jsp.tagext Package APPENDIX E
531
The getAttribute() Method public java.lang.Object getAttribute(java.lang.String name)
This method returns the passed-in name’s value. getAttribute() throws no exceptions. It takes one parameter: •
java.lang.String
It returns this value: •
java.lang.Object
The getAttributeString() Method public java.lang.String getAttributeString(java.lang.String name)
This method returns the value of an attribute as a java.lang.String. getAttributeString() throws no exceptions. It takes one parameter: •
java.lang.String
It returns this value: •
java.lang.String
Th getId() Method public java.lang.String getId()
This method returns the value of the id attribute or null. getID() has no parameters and throws no exceptions.
•
java.lang.String
The setAttribute() Method public void setAttribute(java.lang.String name, java.lang.Object value)
This method sets the value of an attribute/value pair. setAttribute() returns no value and throws no exceptions. It takes two parameters: •
java.lang.String
•
java.lang.Object
E THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
It returns this value:
532
Appendixes PART IV
The TagExtraInfo Class public abstract class TagExtraInfo extends java.lang.Object
This class provides extra tag information for a custom tag. It is mentioned in the TLD. This class must be used if the tag defines any scripting variables, or if the tag wants to provide translation-time validation of the tag attributes. The TagExtraInfo class has one field and five methods, described in the following sections.
The tagInfo Field protected TagInfo tagInfo
This field holds a reference to the TagInfo object.
The TagExtraInfo() Method public TagExtraInfo()
This method is the default empty constructor for the TagExtraInfo class. TagExtraInfo() has no parameters, returns no value, and throws no exceptions.
The getTagInfo() Method public TagInfo getTagInfo()
This method returns the TagInfo object for this class. getTagInfo() has no parameters and throws no exceptions. It returns this value: •
TagInfo
The getVariableInfo() Method public VariableInfo[] getVariableInfo(TagData data)
This method returns information on scripting variables defined by this tag. getVariableInfo() throws no exceptions. It takes one parameter: •
TagData
It returns this value: •
VariableInfo[]
The javax.servlet.jsp.tagext Package APPENDIX E
533
The isValid() Method public boolean isValid(TagData data)
This method performs translation-time validation of the TagData attributes, returning a boolean value indicating validity. isValid() throws no exceptions. It takes one parameter: •
TagData
It returns this value: •
boolean
The setTagInfo() Method public void setTagInfo(TagInfo info)
This method sets the TagInfo object for this class. setTagInfo() returns no value and throws no exceptions. It takes one parameter: •
TagInfo
The TagInfo Class public abstract class TagInfo extends java.lang.Object
This class provides Tag information for a tag in a tag library. It is instantiated from the TLD. The TagInfo class has nine fields and eleven methods, described in the following sections.
The attributeInfo Field This field holds a reference to an array of TagAttributeInfo objects.
The BODY_CONTENT_JSP Field public static final java.lang.String BODY_CONTENT_JSP
This field holds a reference to a static constant for getBodyContent(), when it is a JSP.
The BODY_CONTENT_TAG_DEPENDENT Field public static final java.lang.String BODY_CONTENT_TAG_DEPENDENT
This field holds a reference to a static constant for getBodyContent(), when it is Tag dependent.
E THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
private TagAttributeInfo[] attributeInfo
534
Appendixes PART IV
The bodyContent Field private java.lang.String bodyContent
This field holds a reference to a java.lang.String containing information on the body content of these tags.
The infoString Field private java.lang.String infoString
This field holds a reference to a java.lang.String containing the optional string information for this tag.
The tagClassName Field private java.lang.String tagClassName
This field holds a reference to a java.lang.String containing the name of the tag handler class.
The tagExtraInfo Field private TagExtraInfo tagExtraInfo
This field holds a reference to an instance providing extra tag info.
The tagLibrary Field private TagLibraryInfo tagLibrary
This field holds a reference to an instance of the tag library that contains this tag.
The tagName Field private java.lang.String tagName
This field holds a reference to a java.lang.String containing the name of this tag.
The TagInfo() Method public TagInfo(java.lang.String tagName, java.lang.String tagClassName, java.lang.String bodycontent, java.lang.String infoString, TagLibraryInfo tagLib, TagExtraInfo tagExtraInfo, TagAttributeInfo[] attribInfo)
This method is the constructor for TagInfo. There is no public constructor. This class is to be instantiated only from the tag library code under request from some JSP code that is parsing a TLD. TagInfo() returns no value and throws no exceptions.
The javax.servlet.jsp.tagext Package APPENDIX E
535
It takes seven parameters: •
java.lang.String
•
java.lang.String
•
java.lang.String
•
java.lang.String
•
TagLibraryInfo
•
TagExtraInfo
•
TagAttributeInfo[]
The getAttributes() Method public TagAttributeInfo[] getAttributes()
This method returns a reference to an array of TagAttributeInfo objects. If a null is returned, then there is no attribute information. getAttributes() has no parameters and throws no exceptions. It returns this value: •
TagAttributeInfo[]
The getBodyContent() Method public java.lang.String getBodyContent()
This method returns a reference to a java.lang.String containing information on the body content of these tags. getBodyContent() has no parameters and throws no exceptions. It returns this value: java.lang.String
The getInfoString() Method public java.lang.String getInfoString()
This method returns a reference to a java.lang.String containing the optional string information for this tag. getInfoString() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
E THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
•
536
Appendixes PART IV
The getTagClassName() Method public java.lang.String getTagClassName()
This method returns a reference to a java.lang.String containing the name of the tag handler class. getTagClassName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getTagExtraInfo() Method public TagExtraInfo getTagExtraInfo()
This method returns a reference the TagExtraInfo object. getTagExtraInfo() has no parameters and throws no exceptions. It returns this value: •
TagExtraInfo
The getTagLibrary() Method public TagLibraryInfo getTagLibrary()
This method returns a reference the TagLibraryInfo object. getTagLibrary() has no parameters and throws no exceptions. It returns this value: •
TagLibraryInfo
The getTagName() Method public java.lang.String getTagName()
This method returns a reference to a java.lang.String containing the name of this tag. getTagName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getVariableInfo() Method public VariableInfo[] getVariableInfo(TagData data)
This method returns information on the object created by this tag at runtime. If null is returned, then no such object was created. The default is null if the tag has no id attribute. getVariableInfo() throws no exceptions.
The javax.servlet.jsp.tagext Package APPENDIX E
537
It takes one parameter: •
TagData
It returns this value: •
VariableInfo[]
The isValid() Method public boolean isValid(TagData data)
This method performs translation-time validation of the TagData attributes. isValid() throws no exceptions. It takes one parameter: •
TagData
It returns this value: •
boolean
The TagLibraryInfo Class public abstract class TagLibraryInfo extends java.lang.Object
The TagLibraryInfo class provides information on the tag library. It is instantiated from the TLD. The TagLibraryInfo class has three fields and nine methods.
The prefix Field private java.lang.String prefix
This field holds a reference to the prefix actually used by the taglib directive.
protected java.io.InputStream tldis
This field holds a reference to the input stream to the TLD.
The uri Field private java.net.URL uri
This field holds a reference to the URI actually used by the taglib directive.
The TagLibraryInfo() Method public TagLibraryInfo(java.lang.String prefix, java.net.URL uri, java.io.InputStream tldis)
THE JAVAX. SERVLET.JSP.TAGEXT PACKAGE
The tldis Field
E
538
Appendixes PART IV
This method is the constructor for the TagLibraryInfo class. It will invoke the constructors for TagInfo and TagAttributeInfo after parsing the TLD file. TagLibraryInfo() returns no value and throws no exceptions. It takes three parameters: •
java.lang.String
•
java.net.URL
•
java.io.InputStream
The getInfoString() Method public java.lang.String getInfoString()
This method returns the information string for this tag library. getInfoString() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getPrefixString() Method public java.lang.String getPrefixString()
This method returns the prefix assigned to this tag library from the taglib directive. getPrefixString() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getReliableURN() Method public java.lang.String getReliableURN()
This method returns a reliable URN to a TLD. getReliableURN() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getRequiredVersion() Method public java.lang.String getRequiredVersion()
This method returns the required version for the taglib. getRequiredVersion() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The javax.servlet.jsp.tagext Package APPENDIX E
539
The getShortName() Method public java.lang.String getShortName()
This method returns the preferred short name for the taglib. getShortName() has no parameters and throws no exceptions. It returns this value: •
java.lang.String
The getTag() Method public TagInfo getTag(java.lang.String name)
This method returns the TagInfo for a given tag short name. getTag() throws no exceptions. It takes one parameter: •
java.lang.String
It returns this value: •
TagInfo
The getTags() Method public TagInfo[] getTags()
This method returns an array of TagInfo objects for the tags defined in this tag library. getTags() has no parameters and throws no exceptions. It returns this value: •
TagInfo[]
public java.net.URL getURI()
This method returns the URI from the “ <em>
<meta> <noop>
WML (The Wireless Markup Language) APPENDIX F
TABLE F.1
545
WML Elements
Element Name
Tag
Description
Option OptionGroup Paragraph Postfield
Pre
<pre>
Prev
<prev>
Refresh Select SetVar
Small Strong Table
<small>
TD Template Timer
TR Underline
WML
<wml>
Defines an option input field. Defines a group of option elements into a hierarchy. Defines a section of text as a paragraph. Specifies a field name and value to be used in the construction of a URL request. Signals that text within this tag should be treated as preformatted text. An action task used to force navigation to the previous URL in the stack. Forces an update of the user agent context. Creates a list of options. Specifies the variable to set in the user agent after executing a task. Renders the text in a small font. Renders the text with a strong font. Used to format content in a tabular set of rows and columns. Defines a cell element of a table. Declares a template for cards in the deck. Used to create a card timer, keeping count in tenths of a second. Defines a row in a table element. Used to add an underline effect to text. Used to define a WML deck and serve as the root for all cards within that deck.
<postfield>
<select> <setvar>
<strong>
F WML (THE WIRELESS MARKUP LANGUAGE)
APPENDIX
WMLScript
G
by Bryan Morgan
IN THIS APPENDIX • Lang Library
548
• Float Library
550
• String Library • URL Library
551
553
• WMLBrowser Library • Dialogs Library
556
557
548
Appendixes PART IV
This appendix is a reference to the libraries and functions used by WMLScript. An online version of this standard library reference (also written by Bryan Morgan) is available from Wireless Developer Network at http://www.wirelessdevnet.com/channels/coderef.phtml?catid=5.
Lang Library The Lang library contains a set of functions that are closely related to the WMLScript language core.
abort()—The abort Function abort(errorDescription)
Aborts the execution of the current WMLScript bytecode and returns the errorDescription value back to the caller of the WMLScript interpreter.
abs()—The abs Function abs(value)
Returns the absolute value of the given number. If the number is a floating-point number, the function returns a floating-point value.
characterSet()—The characterSet Function characterSet()
Returns the character set supported by the WMLScript Interpreter. The possible values returned correspond to values defined by Internet Assigned Numbers Authority (IANA); see documentation at http://www.wapforum.org on Wireless Session Protocol for more information.
exit()—The exit Function exit(value)
Forces a normal execution of a WMLScript function and returns control back to the caller.
float()—The float Function float()
Returns a boolean value indicating whether floating-point values are supported on this device.
WMLScript APPENDIX G
isFloat()—The isFloat Function
549
G
isFloat(value)
isInt()—The isInt Function isInt(value)
Returns a boolean value indicating whether the value is an integer number.
max()—The max Function max(value1, value2)
Compares two values and returns the maximum value.
maxInt()—The maxInt Function maxInt()
Returns the maximum integer value supported by the operating platform.
min()—The min Function min(value1, value2)
Compares two values and returns the minimum value.
minInt()—The minInt Function minInt();
Returns the minimum integer value supported by the operating platform.
parseFloat()—The parseFloat Function parseFloat(value)
Converts the designated string value into a floating-point value.
parseInt()—The parseInt Function parseInt(value)
Converts the designated string value into an integer value.
WMLSCRIPT
Returns a boolean value indicating whether the value is a floating-point number.
550
Appendixes PART IV
random()—The random Function random(value)
Returns a random integer value between 0 and the designated value.
seed()—The seed Function seed(value)
Initializes the random number generator sequence with a seed value.
Float Library The Float library contains a set of typical arithmetic floating-point functions that are frequently used by applications. The Float library is optional and is only supported on those clients with floating-point capabilities.
ceil()—The ceil Function ceil(value)
Analyzes the designated value and returns the smallest integer value that is greater than or equal to the designated value.
floor()—The floor Function floor(value)
Analyzes the designated value and returns the greatest integer value that is less than or equal to the designated value.
int()—The int Function int(value)
Returns the integer value of a designated value.
maxFloat()—The maxFloat Function maxFloat()
Returns the maximum floating-point value supported by [IEEEE754] single-precision, floatingpoint format.
WMLScript APPENDIX G
minFloat()—The minFloat Function
551
G
minFloat()
pow()—The pow Function pow(value1, value2)
Raises value1 to the value2 power.
round()—The round function round(value)
Rounds the designated value to the nearest integer.
sqrt()—The sqrt Function sqrt(value)
Returns the square root of the designated value.
String Library The String library contains a set of functions for performing string operations.
charAt()—The charAt Function charAt(string, index)
Retrieves the character at the index from a specified string.
compare()—The compare Function compare(string1, string2)
Returns 0 if string1 equals string2; -1 if string1 is less than string2; and 1 if string1 is greater than string2.
elementAt()—The elementAt Function elementAt(string, n, separator)
Analyzes a string for separator values and returns the nth element after the designated separator value.
WMLSCRIPT
Returns the smallest nonzero floating-point value supported by [IEEEE754] single precision, floating-point format.
552
Appendixes PART IV
elements()—The elements Function elements(string, separator)
Determines the number of separator values in a given string.
find()—The find Function find(string, substring)
Searches a string for the existence of a substring. Returns the index of the first character if the substring is found. Returns -1 if substring is not found.
format()—The format Function format(format, value)
Performs formatting on a string using a subset of the C language string formatting syntax.
insertAt()—The insertAt Function insertAt(string, element, index, separator)
Inserts an element into an existing string at the specified index.
isEmpty()—The isEmpty Function isEmpty(string)
Tests to determine whether a string is of length zero. Returns a boolean true/false based on the result of this test.
length()—The length Function length(string)
Returns the length of the designated string.
removeAt()—The removeAt Function removeAt(string, index, separator)
Removes a string (and separator, if existing) at the indicated index.
WMLScript APPENDIX G
replace()—The replace Function
553
G
replace(string, oldSubString, newSubString)
replaceAt()—The replaceAt Function replaceAt(string, element, index, separator)
Searches a string, replacing the original element with the indicated element.
squeeze()—The squeeze Function squeeze(string)
Replaces instances of multiple whitespaces within a string with a single inter-word space.
subString()—The subString Function subString(string, startIndex, length)
Returns a substring from a specified string beginning at the startIndex and traversing length characters.
toString()—The toString Function toString(value)
Converts any and all WMLScript data types to a string value.
trim()—The trim Function trim(string)
Returns a string with all leading and trailing whitespace removed.
URL Library The URL library contains a set of functions for handling both absolute URLs and relative URLs.
WMLSCRIPT
Searches a string, replacing all instances of oldSubString with newSubString.
554
Appendixes PART IV
escapeString()—The escapeString Function escapeString(string)
This function computes a new version of a string value in which special characters have been replaced by a hexadecimal escape sequence. The characters to be escaped are • Control Characters—US-ASCII–coded characters 00-1F and 7F • Space—US-ASCII–coded character 20 hexadecimal • Reserved—“;” | “/” | “?” | “:” | “@” | “&” | “=” | “+” | “$” | “,” • Unwise—“{” | “}” | “|” | “\” | “^” | “[“ | “]” | “`” • Delims—“” | “#” | “%” | • Non-US–ASCII—Characters with hex code 8F-FF The given string is escaped as such; no URL parsing is performed. Non-US–ASCII characters must be converted with the character codes used in the native character set.
getBase()—The getBase Function getBase()
Returns the absolute URL of the current WMLScript unit.
getFragment()—The getFragment Function getFragment(url)
Returns the fragment of the indicated url.
getHost()—The getHost Function getHost(url)
Returns the host of the indicated url.
getParameters()—The getParameters Function getParameters(url)
Returns the parameters used in the indicated url.
getPath()—The getPath Function getPath(url)
Returns the path used in the indicated url.
WMLScript APPENDIX G
getPort()—The getPort Function
555
G
getPort(url)
getQuery()—The getQuery Function getQuery(url)
Returns the query used in the indicated url.
getReferer()—The getReferer Function getReferer()
Returns the URL of the resource that called the current compilation unit.
getScheme()—The getScheme Function getScheme(url)
Returns the scheme of the indicated url.
isValid()—The isValid Function isValid(url)
Checks the indicated url for appropriate URL syntax, returning true if correct, false if not.
loadString()—The loadString Function loadString(url, contentType)
Returns the content specified by the url and contentType (for example, text/html).
resolve()—The resolve Function resolve(baseUrl, embeddedUrl)
Produces an absolute URL from a given baseUrl and embeddedUrl.
unescapeString()—The unescapeString Function unescapeString(string)
This function performs the opposite task of the URL.escapeString() function, returning a string with the escape characters replaced by the original characters that these escape characters represent.
WMLSCRIPT
Returns the port used in the indicated url.
556
Appendixes PART IV
WMLBrowser Library The WMLBrowser library contains functions by which WMLScript can access the associated WML context. These functions must not have any side effects and must return invalid in cases where the system does not support WMLBrowser and where the WML Browser does not invoke the interpreter.
getCurrentCard()—The getCurrentCard Function getCurrentCard()
Returns the relative URL of the current card.
getVar()—The getVar Function getVar(name)
Returns the value of the specified variable.
go()—The go Function go(url)
Loads and transfers focus to the given url.
newContext()—The newContext Function newContext()
A type of “reset” function; clears all present variables and clears the navigation history stack.
prev()—The prev Function prev()
Returns focus back to the previous WML card.
refresh()—The refresh Function refresh()
Forces a refresh of the WML Browser based on current context and variable values.
setVar()—The setVar Function setVar(name, value)
Sets the value of a local deck variable.
WMLScript APPENDIX G
Dialogs Library alert()—The alert Function alert(message)
Displays a message for the user and awaits a confirmation.
confirm()—The confirm Function confirm(message, ok, cancel)
Displays a message to the user with OK and Cancel buttons on the dialog box.
prompt()—The prompt Function prompt(message, defaultInput)
Prompts the user to input content before proceeding. defaultInput can be used to populate the box with a default value.
G WMLSCRIPT
The Dialogs library contains a set of typical user-interface functions.
J jar files deploying, 220 deploying tag handlers as, 304 packaging, 218-219 Java API for XML Processing (JAXP) downloading, 153 SAX API (Simple API for XML) SAXHandler.java handler, 155-159 XMLTest.java document, 153-155 Java Beans. See JavaBeans Java Database Connectivity. See JDBC Java Naming and Directory Interface. See JNDI Java Server Pages. See JSPs Java servlets. See servlets java.lang.Object parameter print() method, 498 println() method, 500
java.lang.String parameter print() method, 497 println() method, 500 JavaBeans, 282 BeanCounter.jsp, 265-266 <jsp:getProperty> action, 267 <jsp:setProperty> action, 266 <jsp:useBean> action, 266-268 Counter, 264-265, 282 EJB (Enterprise JavaBeans). See EJB properties referencing, 264 setting, 263-264 scope application, 289-291 page, 283 request, 284-286 session, 286-288 JavaMail downloading, 133 sending messages HTML mail forms, 137-138 MailServlet example, 138-141 SimpleSendMessage example, 133-137 store service, 132 transport service, 132 JavaScript, 18 JavaServer Pages. See JSPs JavaSoft Web site, 422 javax.servlet package, 20, 429-430. See also servlets GenericServlet class destroy() method, 449 GenericServlet() method, 449 getInitParameter() method, 449 getInitParameterNames() method, 449
URL library, 553-555 WMLBrowser library, 556 WMLScriptExample application, 409-411 scriptlets HELLO JSP WORLD example, 245-246 syntax, 244 SC_ACCEPTED field (HttpServletResponse), 469 SC_BAD_GATEWAY field (HttpServletResponse), 472 SC_BAD_REQUEST field (HttpServletResponse), 470 SC_CONFLICT field (HttpServletResponse), 471 SC_CONTINUE field (HttpServletResponse), 468 SC_CREATED field (HttpServletResponse), 468 SC_FORBIDDEN field (HttpServletResponse), 470 SC_GATEWAY_TIMEOUT field (HttpServletResponse), 473 SC_GONE field (HttpServletResponse), 471 SC_HTTP_VERSION_NOT_ SUPPORTED field (HttpServletResponse), 473 SC_INTERNAL_SERVER_ ERROR field (HttpServletResponse), 472 SC_LENGTH_REQUIRED field (HttpServletResponse), 472 SC_MOVED_PERMANENTLY field (HttpServletResponse), 469 SC_MOVED_TEMPORARILY field (HttpServletResponse), 469 SC_MULTIPLE_CHOICES field (HttpServletResponse), 469
servers
SC_NON_AUTHORITATIVE_ INFORMATION field (HttpServletResponse), 469 SC_NOT_ACCEPTABLE field (HttpServletResponse), 471 SC_NOT_ALLOWED field (HttpServletResponse), 471 SC_NOT_FOUND field (HttpServletResponse), 471 SC_NOT_IMPLEMENTED field (HttpServletResponse), 472 SC_NOT_MODIFIED field (HttpServletResponse), 470 SC_NO_CONTENT field (HttpServletResponse), 469 SC_OK field (HttpServletResponse), 468 SC_PARTIAL_CONTENT field (HttpServletResponse), 469 SC_PAYMENT_REQUIRED field (HttpServletResponse), 470 SC_PRECONDITION_FAILED field (HttpServletResponse), 472 SC_PROXY_ AUTHENTICATION_ REQUIRED field (HttpServletResponse), 471 SC_REQUEST_ENTITY_ TOO_LARGE field (HttpServletResponse), 472 SC_REQUEST_TIMEOUT field (HttpServletResponse), 471 SC_REQUEST_URI_TOO_ LONG field (HttpServletResponse), 472 SC_RESET_CONTENT field (HttpServletResponse), 469 SC_SEE_OTHER field (HttpServletResponse), 470 SC_SERVICE_UNAVAILABLE field (HttpServletResponse), 473
, 545 , 303-304 tag libraries tag handlers, 304 taglib directive, 304-306 tld files, 302-304 adding to JSPs, 305-306 adding to Web applications, 304-305
X-Z XHTML, 388 XML (Extensible Markup Language) combining with Java, 153 document tree structure, 152 incorporating into servlets, 159-161 JAXP (Java API for XML Processing), 153 maintaining wireless applications in, 414 parsing files, 153-155 processing instructions, 152
YoSpace
SAX API (Simple API for XML) SAXHandler.java handler, 155-159 XMLTest.java document, 153-155 simple example, 152-153 XMLServlet, 159-161 XMLTest.java (code listing), 153-155 YoSpace, 392
