Java™ Servlet Specification.pdf download

Java™ Servlet Specification
Version 2.4
Please send technical comments to: servletapi-feedback@eng.sun.com
Please send business comments to: danny.coward@sun.com
Public Draft June 24th 2002
Danny Coward (danny.coward@sun.com)
Yutaka Yoshida (yutaka.yoshida@sun.com)

Java™ Servlet Specification Version 2.4 . . . . . . . . . . . . . . . .i
Changes since version 2.3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Changes in this document since version 2.3 . . . . . . . . . . . . . . . . . xiii
Preface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Additional Sources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xv
Who Should Read This Specification . . . . . . . . . . . . . . . . . . . . . . xvi
API Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvi
Other Java™ Platform Specifications . . . . . . . . . . . . . . . . . . . . . . xvi
Other Important References . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Providing Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xviii
SRV.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
SRV.1.1 What is a Servlet? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
SRV.1.2 What is a Servlet Container? . . . . . . . . . . . . . . . . . . . . . . 19
SRV.1.3 An Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
SRV.1.4 Comparing Servlets with Other Technologies . . . . . . . . 20
SRV.1.5 Relationship to Java 2, Platform Enterprise Edition . . . . 21
SRV.2 The Servlet Interface . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 23
SRV.2.1 Request Handling Methods . . . . . . . . . . . . . . . . . . . . . . . 23
SRV.2.1.1 HTTP Specific Request Handling Methods . . . . 23
SRV.2.1.2 Additional Methods . . . . . . . . . . . . . . . . . . . . . . 24
SRV.2.1.3 Conditional GET Support . . . . . . . . . . . . . . . . . . 24
CONTENTS vi
SRV.2.2 Number of Instances . . . . . . . . . . . . . . . . . . . . . . . . . . . . 24
SRV.2.2.1 Note About The Single Thread Model . . . . . . . . 25
SRV.2.3 Servlet Life Cycle . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
SRV.2.3.1 Loading and Instantiation . . . . . . . . . . . . . . . . . . 25
SRV.2.3.2 Initialization . . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
SRV.2.3.3 Request Handling . . . . . . . . . . . . . . . . . . . . . . . . 26
SRV.2.3.4 End of Service . . . . . . . . . . . . . . . . . . . . . . . . . . . 28
SRV.3 Servlet Context . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29
SRV.3.1 Introduction to the ServletContext Interface . . . . . . . . . . 29
SRV.3.2 Scope of a ServletContext Interface . . . . . . . . . . . . . . . . 29
SRV.3.3 Initialization Parameters . . . . . . . . . . . . . . . . . . . . . . . . . 30
SRV.3.4 Context Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SRV.3.4.1 Context Attributes in a Distributed Container . . 30
SRV.3.5 Resources . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
SRV.3.6 Multiple Hosts and Servlet Contexts . . . . . . . . . . . . . . . 31
SRV.3.7 Reloading Considerations . . . . . . . . . . . . . . . . . . . . . . . . 31
SRV.3.7.1 Temporary Working Directories . . . . . . . . . . . . . 32
SRV.4 The Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33
SRV.4.1 HTTP Protocol Parameters . . . . . . . . . . . . . . . . . . . . . . . 33
SRV.4.1.1 When Parameters Are Available . . . . . . . . . . . . . 34
SRV.4.2 Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
SRV.4.3 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35
SRV.4.4 Request Path Elements . . . . . . . . . . . . . . . . . . . . . . . . . . 35
SRV.4.5 Path Translation Methods . . . . . . . . . . . . . . . . . . . . . . . . 37
SRV.4.6 Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
SRV.4.7 SSL Attributes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
SRV.4.8 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
SRV.4.9 Request data encoding . . . . . . . . . . . . . . . . . . . . . . . . . . 39
SRV.4.10 Lifetime of the Request Object . . . . . . . . . . . . . . . . . . . . 39
SRV.5 The Response . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SRV.5.1 Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
SRV.5.2 Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
SRV.5.3 Convenience Methods . . . . . . . . . . . . . . . . . . . . . . . . . . . 43
CONTENTS vii
SRV.5.4 Internationalization . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44
SRV.5.5 Closure of Response Object . . . . . . . . . . . . . . . . . . . . . . 44
SRV.5.6 Lifetime of the Response Object . . . . . . . . . . . . . . . . . . . 45
SRV.6 Filtering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
SRV.6.1 What is a filter? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
SRV.6.1.1 Examples of Filtering Components . . . . . . . . . . 48
SRV.6.2 Main Concepts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48
SRV.6.2.1 Filter Lifecycle . . . . . . . . . . . . . . . . . . . . . . . . . . 48
SRV.6.2.2 Wrapping Requests and Responses . . . . . . . . . . 50
SRV.6.2.3 Filter Environment . . . . . . . . . . . . . . . . . . . . . . . 50
SRV.6.2.4 Configuration of Filters in a Web Application . . 51
SRV.6.2.5 Filters and the RequestDispatcher . . . . . . . . . . . 52
SRV.7 Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SRV.7.1 Session Tracking Mechanisms . . . . . . . . . . . . . . . . . . . . 55
SRV.7.1.1 Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SRV.7.1.2 SSL Sessions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55
SRV.7.1.3 URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . 56
SRV.7.1.4 Session Integrity . . . . . . . . . . . . . . . . . . . . . . . . . 56
SRV.7.2 Creating a Session . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
SRV.7.3 Session Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
SRV.7.4 Binding Attributes into a Session . . . . . . . . . . . . . . . . . . 57
SRV.7.5 Session Timeouts . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
SRV.7.6 Last Accessed Times . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
SRV.7.7 Important Session Semantics . . . . . . . . . . . . . . . . . . . . . 58
J2EE.7.7.1 Threading Issues . . . . . . . . . . . . . . . . . . . . . . . . . 58
SRV.7.7.2 Distributed Environments . . . . . . . . . . . . . . . . . . 58
SRV.7.7.3 Client Semantics . . . . . . . . . . . . . . . . . . . . . . . . . 59
SRV.8 Dispatching Requests. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 61
SRV.8.1 Obtaining a RequestDispatcher . . . . . . . . . . . . . . . . . . . . 61
SRV.8.1.1 Query Strings in Request Dispatcher Paths . . . . 62
SRV.8.2 Using a Request Dispatcher . . . . . . . . . . . . . . . . . . . . . . 62
SRV.8.3 The Include Method . . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
SRV.8.3.1 Included Request Parameters . . . . . . . . . . . . . . . 63
SRV.8.4 The Forward Method . . . . . . . . . . . . . . . . . . . . . . . . . . . 63
CONTENTS viii
SRV.8.4.1 Query String . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
SRV.8.5 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
SRV.9 Web Applications . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 65
SRV.9.1 Web Applications Within Web Servers . . . . . . . . . . . . . 65
SRV.9.2 Relationship to ServletContext . . . . . . . . . . . . . . . . . . . 65
SRV.9.3 Elements of a Web Application . . . . . . . . . . . . . . . . . . . 66
SRV.9.4 Deployment Hierarchies . . . . . . . . . . . . . . . . . . . . . . . . 66
SRV.9.5 Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 66
SRV.9.5.1 Example of Application Directory Structure . . . 67
SRV.9.6 Web Application Archive File . . . . . . . . . . . . . . . . . . . . 68
SRV.9.7 Web Application Deployment Descriptor . . . . . . . . . . . 68
SRV.9.7.1 Dependencies On Extensions . . . . . . . . . . . . . . . 68
SRV.9.7.2 Web Application Classloader . . . . . . . . . . . . . . 69
SRV.9.8 Replacing a Web Application . . . . . . . . . . . . . . . . . . . . 69
SRV.9.9 Error Handling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
SRV.9.9.1 Request Attributes . . . . . . . . . . . . . . . . . . . . . . . 70
SRV.9.9.2 Error Pages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 70
SRV.9.10 Welcome Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 71
SRV.9.11 Web Application Environment . . . . . . . . . . . . . . . . . . . 73
SRV.10 Application Lifecycle Events . . . . . . . . . . . . . . . . . . . . . . . 75
SRV.10.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
SRV.10.2 Event Listeners . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 75
SRV.10.2.1 Event Types and Listener Interfaces . . . . . . . . . 75
SRV.10.2.2 An Example of Listener Use . . . . . . . . . . . . . . . 77
SRV.10.3 Listener Class Configuration . . . . . . . . . . . . . . . . . . . . . 77
SRV.10.3.1 Provision of Listener Classes . . . . . . . . . . . . . . . 77
SRV.10.3.2 Deployment Declarations . . . . . . . . . . . . . . . . . . 77
SRV.10.3.3 Listener Registration . . . . . . . . . . . . . . . . . . . . . 77
SRV.10.3.4 Notifications At Shutdown . . . . . . . . . . . . . . . . 78
SRV.10.4 Deployment Descriptor Example . . . . . . . . . . . . . . . . . . 78
SRV.10.5 Listener Instances and Threading . . . . . . . . . . . . . . . . . 78
SRV.10.6 Listener Exceptions . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SRV.10.7 Distributed Containers . . . . . . . . . . . . . . . . . . . . . . . . . . 79
CONTENTS ix
SRV.10.8 Session Events . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 79
SRV.11 Mapping Requests to Servlets . . . . . . . . . . . . . . . . . . . . . . 81
SRV.11.1 Use of URL Paths . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 81
SRV.11.2 Specification of Mappings . . . . . . . . . . . . . . . . . . . . . . . 82
SRV.11.2.1 Implicit Mappings . . . . . . . . . . . . . . . . . . . . . . . 82
SRV.11.2.2 Example Mapping Set . . . . . . . . . . . . . . . . . . . . 83
SRV.12 Security. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
SRV.12.1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 85
SRV.12.2 Declarative Security . . . . . . . . . . . . . . . . . . . . . . . . . . . . 86
SRV.12.3 Programmatic Security . . . . . . . . . . . . . . . . . . . . . . . . . . 86
SRV.12.4 Roles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
SRV.12.5 Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 88
SRV.12.5.1 HTTP Basic Authentication . . . . . . . . . . . . . . . . 88
SRV.12.5.2 HTTP Digest Authentication . . . . . . . . . . . . . . . 89
SRV.12.5.3 Form Based Authentication . . . . . . . . . . . . . . . . 89
SRV.12.5.4 HTTPS Client Authentication . . . . . . . . . . . . . . 91
SRV.12.6 Server Tracking of Authentication Information . . . . . . . 91
SRV.12.7 Propagation of Security Identity in EJBTM Calls . . . . . 91
SRV.12.8 Specifying Security Constraints . . . . . . . . . . . . . . . . . . . 92
SRV.12.9 Default Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SRV.12.10Login and Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SRV.12.10.1 Login . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SRV.12.10.2 Logout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 93
SRV.13 Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
SRV.13.1 Extensibility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 95
SRV.13.1.1 Example of Extensibility: ACME servlets . . . . . 96
SRV.13.2 Deployment Descriptor Elements . . . . . . . . . . . . . . . . . 98
SRV.13.3 Rules for Processing the Deployment Descriptor . . . . . 99
SRV.13.4 Deployment Descriptor . . . . . . . . . . . . . . . . . . . . . . . . . 99
SRV.13.5 Picture of the structure of a Deployment Descriptor . . 132
SRV.13.6 DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
SRV.13.7 Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 135
SRV.13.7.1 A Basic Example . . . . . . . . . . . . . . . . . . . . . . . 135
SRV.13.7.2 An Example of Security . . . . . . . . . . . . . . . . . . 136
CONTENTS x
SRV.14 javax.servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 139
SRV.14.1 Generic Servlet Interfaces and Classes . . . . . . . . . . . . . 139
SRV.14.2 The javax.servlet package . . . . . . . . . . . . . . . . . . . . . . . 139
SRV.14.2.1 Filter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 142
SRV.14.2.2 FilterChain . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
SRV.14.2.3 FilterConfig . . . . . . . . . . . . . . . . . . . . . . . . . . . . 144
SRV.14.2.4 GenericServlet . . . . . . . . . . . . . . . . . . . . . . . . . . 145
SRV.14.2.5 RequestDispatcher . . . . . . . . . . . . . . . . . . . . . . 149
SRV.14.2.6 Servlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 151
SRV.14.2.7 ServletConfig . . . . . . . . . . . . . . . . . . . . . . . . . . 153
SRV.14.2.8 ServletContext . . . . . . . . . . . . . . . . . . . . . . . . . . 154
SRV.14.2.9 ServletContextAttributeEvent . . . . . . . . . . . . . . 163
SRV.14.2.10 ServletContextAttributeListener . . . . . . . . . . . 164
SRV.14.2.11 ServletContextEvent . . . . . . . . . . . . . . . . . . . . 164
SRV.14.2.12 ServletContextListener . . . . . . . . . . . . . . . . . . . 165
SRV.14.2.13 ServletException . . . . . . . . . . . . . . . . . . . . . . . 166
SRV.14.2.14 ServletInputStream . . . . . . . . . . . . . . . . . . . . . . 167
SRV.14.2.15 ServletOutputStream . . . . . . . . . . . . . . . . . . . . 168
SRV.14.2.16 ServletRequest . . . . . . . . . . . . . . . . . . . . . . . . . 172
SRV.14.2.17 ServletRequestAttributeEvent . . . . . . . . . . . . . 179
SRV.14.2.18 ServletRequestAttributeListener . . . . . . . . . . . 180
SRV.14.2.19 ServletRequestEvent . . . . . . . . . . . . . . . . . . . . 181
SRV.14.2.20 ServletRequestListener . . . . . . . . . . . . . . . . . . 182
SRV.14.2.21 ServletRequestWrapper . . . . . . . . . . . . . . . . . . 182
SRV.14.2.22 ServletResponse . . . . . . . . . . . . . . . . . . . . . . . . 187
SRV.14.2.23 ServletResponseWrapper . . . . . . . . . . . . . . . . . 192
SRV.14.2.24 SingleThreadModel . . . . . . . . . . . . . . . . . . . . . 196
SRV.14.2.25 UnavailableException . . . . . . . . . . . . . . . . . . . 196
SRV.15 javax.servlet.http . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 199
SRV.15.1 Servlets Using HTTP Protocol . . . . . . . . . . . . . . . . . . . 199
SRV.15.1.1 Cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 201
SRV.15.1.2 HttpServlet . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
SRV.15.1.3 HttpServletRequest . . . . . . . . . . . . . . . . . . . . . . 214
SRV.15.1.4 HttpServletRequestWrapper . . . . . . . . . . . . . . . 221
SRV.15.1.5 HttpServletResponse . . . . . . . . . . . . . . . . . . . . . 226
SRV.15.1.6 HttpServletResponseWrapper . . . . . . . . . . . . . . 237
SRV.15.1.7 HttpSession . . . . . . . . . . . . . . . . . . . . . . . . . . . . 241
CONTENTS xi
SRV.15.1.8 HttpSessionActivationListener . . . . . . . . . . . . . 246
SRV.15.1.9 HttpSessionAttributeListener . . . . . . . . . . . . . . 247
SRV.15.1.10 HttpSessionBindingEvent . . . . . . . . . . . . . . . . 248
SRV.15.1.11 HttpSessionBindingListener . . . . . . . . . . . . . . 249
SRV.15.1.12 HttpSessionContext . . . . . . . . . . . . . . . . . . . . . 250
SRV.15.1.13 HttpSessionEvent . . . . . . . . . . . . . . . . . . . . . . . 250
SRV.15.1.14 HttpSessionListener . . . . . . . . . . . . . . . . . . . . . 251
SRV.15.1.15 HttpUtils . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
SRV.A Deployment Descriptor Version 2.2 . . . . . . . . . . . . . . . . 255
SRV.A.1 Deployment Descriptor DOCTYPE . . . . . . . . . . . . . . . 255
SRV.A.2 DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 255
SRV.A.1 Deployment Descriptor DOCTYPE . . . . . . . . . . . . . . . 269
SRV.A.2 DTD . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 269
SRV.B Glossary . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 295

DOWNLOAD