ContentsStatus ................................................................................................. 12
Changes in this document since v2.2........................................... 12
Preface ............................................................................................... 14
Who should read this document .................................................. 14
API Reference ............................................................................. 14
Other Java™ Platform Specifications.......................................... 14
Other Important References ........................................................ 15
Providing Feedback..................................................................... 16
Acknowledgements ..................................................................... 16
Chapter 1:Overview.......................................................................... 18
What is a Servlet?........................................................................ 18
What is a Servlet Container? ....................................................... 18
An Example................................................................................. 19
Comparing Servlets with Other Technologies ............................. 19
Relationship to Java 2 Platform Enterprise Edition ..................... 20
Chapter 2: The Servlet Interface ...................................................... 22
Request Handling Methods ......................................................... 22
HTTP Specific Request Handling Methods........................ 22
PROPOSED FINAL DRAFT
5 Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT• October 20, 2000
Conditional GET Support ...................................................23
Number of Instances ....................................................................23
Note about SingleThreadModel ..........................................24
Servlet Life Cycle ........................................................................24
Loading and Instantiation ...................................................24
Initialization........................................................................24
Request Handling ...............................................................25
End of Service ....................................................................27
Chapter 3: Servlet Context ................................................................28
Scope of a ServletContext............................................................28
Initialization Parameters ..............................................................28
Context Attributes........................................................................29
Context Attributes in a Distributed Container.....................29
Resources.....................................................................................29
Multiple Hosts and Servlet Contexts............................................30
Reloading Considerations ............................................................30
Temporary Working Directories ..................................................31
Chapter 4: The Request .....................................................................32
Parameters ...................................................................................32
Attributes .....................................................................................33
Headers ........................................................................................33
Request Path Elements.................................................................34
Path Translation Methods ............................................................35
Cookies ........................................................................................36
SSL Attributes .............................................................................36
Internationalization ......................................................................37
Request data encoding .................................................................37
PROPOSED FINAL DRAFT
Contents 6
Chapter 5: The Response .................................................................. 38
Buffering ..................................................................................... 38
Headers........................................................................................ 39
Convenience Methods ................................................................. 40
Internationalization...................................................................... 40
Closure of Response Object ........................................................ 41
Chapter 6: Servlet Filtering .............................................................. 42
What is a filter ? .......................................................................... 42
Examples of Filtering Components .................................... 43
Main Concepts............................................................................. 43
Filter Lifecycle................................................................... 43
Filter environment .............................................................. 45
Configuration of Filters in a Web Application ................... 45
Chapter 7: Sessions ............................................................................ 48
Session Tracking Mechanisms .................................................... 48
URL Rewriting................................................................... 48
Cookies .............................................................................. 49
SSL Sessions...................................................................... 49
Session Integrity................................................................. 49
Creating a Session ....................................................................... 49
Session Scope.............................................................................. 50
Binding Attributes into a Session ................................................ 50
Session Timeouts......................................................................... 50
Last Accessed Times ................................................................... 51
Important Session Semantics....................................................... 51
Threading Issues ................................................................ 51
Distributed Environments................................................... 51
PROPOSED FINAL DRAFT
7 Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT• October 20, 2000
Client Semantics .................................................................52
Chapter 8: Dispatching Requests ......................................................54
Obtaining a RequestDispatcher....................................................54
Query Strings in Request Dispatcher Paths.........................55
Using a Request Dispatcher .........................................................55
Include .........................................................................................56
Included Request Parameters ..............................................56
Forward........................................................................................56
Query String .......................................................................57
Error Handling .............................................................................57
Chapter 9:Web Applications.............................................................58
Relationship to ServletContext ....................................................58
Elements of a Web Application ...................................................58
Distinction Between Representations...........................................59
Directory Structure ......................................................................59
Sample Web Application Directory Structure.....................60
Web Application Archive File .....................................................60
Web Application Configuration Descriptor .................................61
Dependencies on extensions: Library Files.........................61
Web Application Classloader..............................................62
Replacing a Web Application ......................................................62
Error Handling .............................................................................62
Welcome Files .............................................................................63
Web Application Environment ....................................................64
Chapter 10:Application Lifecycle Events ........................................66
Introduction .................................................................................66
Event Listeners ............................................................................66
PROPOSED FINAL DRAFT
Contents 8
Configuration of Listener Classes ............................................... 68
Listener Instances and Threading ................................................ 69
Distributed Containers................................................................. 69
Session Events- Invalidation vs Timeout..................................... 69
Chapter 11: Mapping Requests to Servlets ...................................... 70
Use of URL Paths........................................................................ 70
Specification of Mappings........................................................... 71
Implicit Mappings .............................................................. 71
Example Mapping Set ........................................................ 71
Chapter 12: Security.......................................................................... 74
Introduction ................................................................................. 74
Declarative Security .................................................................... 75
Programmatic Security ................................................................ 75
Roles ........................................................................................... 76
Authentication ............................................................................. 76
HTTP Basic Authentication ............................................... 76
HTTP Digest Authentication.............................................. 77
Form Based Authentication................................................ 77
HTTPS Client Authentication ............................................ 78
Server Tracking of Authentication Information .......................... 79
Propogation of Security Identity.................................................. 79
Specifying Security Constraints .................................................. 80
Default Policies .................................................................. 80
Chapter 13: Deployment Descriptor................................................. 82
Deployment Descriptor Elements................................................ 82
Deployment Descriptor DOCTYPE ................................... 82
DTD ............................................................................................ 83
PROPOSED FINAL DRAFT
9 Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT• October 20, 2000
Examples .....................................................................................96
A Basic Example ................................................................97
An Example of Security......................................................98
Chapter 14: API Details .....................................................................100
Config.................................................................................... 104
Filter ...................................................................................... 106
FilterConfig ........................................................................... 108
GenericServlet....................................................................... 110
RequestDispatcher ................................................................ 115
Servlet ................................................................................... 117
ServletConfig ........................................................................ 120
ServletContext....................................................................... 121
ServletContextAttributeEvent ............................................... 129
ServletContextAttributesListener.......................................... 131
ServletContextEvent ............................................................. 133
ServletContextListener.......................................................... 135
ServletException ................................................................... 136
ServletInputStream................................................................ 139
ServletOutputStream............................................................. 141
ServletRequest ...................................................................... 146
ServletRequestWrapper ........................................................ 153
ServletResponse .................................................................... 159
ServletResponseWrapper ...................................................... 163
SingleThreadModel............................................................... 167
UnavailableException ........................................................... 168
Cookie ................................................................................... 173
HttpServlet ............................................................................ 179
PROPOSED FINAL DRAFT
Contents 10
HttpServletRequest ............................................................... 185
HttpServletRequestWrapper ................................................. 193
HttpServletResponse............................................................. 200
HttpServletResponseWrapper............................................... 212
HttpSession ........................................................................... 217
HttpSessionAttributesListener .............................................. 222
HttpSessionBindingEvent ..................................................... 224
HttpSessionBindingListener ................................................. 227
HttpSessionContext............................................................... 228
HttpSessionEvent .................................................................. 229
HttpSessionListener .............................................................. 231
HttpUtils................................................................................ 232
Appendix A: Deployment Descriptor Version 2.2............................ 236
Appendix B: Glossary........................................................................ 250
