servlet 3.1规范（servlet-3_1-final.pdf）

【实例截图】

【核心代码】

Contents
Contents ix
1. Overview 1
1.1 What is a Servlet? 1
1.2 What is a Servlet Container? 1
1.3 An Example 2
1.4 Comparing Servlets with Other Technologies 3
1.5 Relationship to Java Platform, Enterprise Edition 3
1.6 Compatibility with Java Servlet Specification Version 2.5 4
1.6.1 Processing annotations 4
2. The Servlet Interface 5
2.1 Request Handling Methods 5
2.1.1 HTTP Specific Request Handling Methods 5
2.1.2 Additional Methods 6
2.1.3 Conditional GET Support 6
2.2 Number of Instances 6
2.2.1 Note About The Single Thread Model 7
2.3 Servlet Life Cycle 7
2.3.1 Loading and Instantiation 7
x Java Servlet Specification • April 2013
2.3.2 Initialization 8
2.3.2.1 Error Conditions on Initialization 8
2.3.2.2 Tool Considerations 8
2.3.3 Request Handling 9
2.3.3.1 Multithreading Issues 9
2.3.3.2 Exceptions During Request Handling 9
2.3.3.3 Asynchronous processing 10
2.3.3.4 Thread Safety 20
2.3.3.5 Upgrade Processing 20
2.3.4 End of Service 21
3. The Request 23
3.1 HTTP Protocol Parameters 23
3.1.1 When Parameters Are Available 24
3.2 File upload 24
3.3 Attributes 25
3.4 Headers 25
3.5 Request Path Elements 26
3.6 Path Translation Methods 27
3.7 Non Blocking IO 28
3.8 Cookies 29
3.9 SSL Attributes 30
3.10 Internationalization 30
3.11 Request data encoding 31
3.12 Lifetime of the Request Object 31
4. Servlet Context 33
4.1 Introduction to the ServletContext Interface 33
4.2 Scope of a ServletContext Interface 33
Contents xi
4.3 Initialization Parameters 34
4.4 Configuration methods 34
4.4.1 Programmatically adding and configuring Servlets 35
4.4.1.1 addServlet(String servletName, String className) 35
4.4.1.2 addServlet(String servletName, Servlet servlet) 35
4.4.1.3 addServlet(String servletName, Class <? extends
Servlet> servletClass) 35
4.4.1.4 <T extends Servlet> T createServlet(Class<T> clazz) 35
4.4.1.5 ServletRegistration getServletRegistration(String
servletName) 36
4.4.1.6 Map<String, ? extends ServletRegistration>
getServletRegistrations() 36
4.4.2 Programmatically adding and configuring Filters 36
4.4.2.1 addFilter(String filterName, String className) 36
4.4.2.2 addFilter(String filterName, Filter filter) 36
4.4.2.3 addFilter(String filterName, Class <? extends Filter>
filterClass) 37
4.4.2.4 <T extends Filter> T createFilter(Class<T> clazz) 37
4.4.2.5 FilterRegistration getFilterRegistration(String
filterName) 37
4.4.2.6 Map<String, ? extends FilterRegistration>
getServletRegistrations() 37
4.4.3 Programmatically adding and configuring Listeners 38
4.4.3.1 void addListener(String className) 38
4.4.3.2 <T extends EventListener> void addListener(T t) 38
4.4.3.3 void addListener(Class <? extends EventListener>
listenerClass) 39
4.4.3.4 <T extends EventListener> void
createListener(Class<T> clazz) 39
4.4.3.5 Annotation processing requirements for
programmatically added Servlets, Filters and
Listeners 40
xii Java Servlet Specification • April 2013
4.5 Context Attributes 40
4.5.1 Context Attributes in a Distributed Container 41
4.6 Resources 41
4.7 Multiple Hosts and Servlet Contexts 42
4.8 Reloading Considerations 42
4.8.1 Temporary Working Directories 42
5. The Response 45
5.1 Buffering 45
5.2 Headers 46
5.3 Non Blocking IO 47
5.4 Convenience Methods 48
5.5 Internationalization 49
5.6 Closure of Response Object 50
5.7 Lifetime of the Response Object 50
6. Filtering 51
6.1 What is a filter? 51
6.1.1 Examples of Filtering Components 52
6.2 Main Concepts 52
6.2.1 Filter Lifecycle 52
6.2.2 Wrapping Requests and Responses 54
6.2.3 Filter Environment 54
6.2.4 Configuration of Filters in a Web Application 55
6.2.5 Filters and the RequestDispatcher 58
7. Sessions 61
7.1 Session Tracking Mechanisms 61
7.1.1 Cookies 61
7.1.2 SSL Sessions 62
Contents xiii
7.1.3 URL Rewriting 62
7.1.4 Session Integrity 62
7.2 Creating a Session 62
7.3 Session Scope 63
7.4 Binding Attributes into a Session 64
7.5 Session Timeouts 64
7.6 Last Accessed Times 65
7.7 Important Session Semantics 65
7.7.1 Threading Issues 65
7.7.2 Distributed Environments 65
7.7.3 Client Semantics 66
8. Annotations and pluggability 67
8.1 Annotations and pluggability 67
8.1.1 @WebServlet 67
8.1.2 @WebFilter 69
8.1.3 @WebInitParam 69
8.1.4 @WebListener 69
8.1.5 @MultipartConfig 70
8.1.6 Other annotations / conventions 70
8.2 Pluggability 71
8.2.1 Modularity of web.xml 71
8.2.2 Ordering of web.xml and web-fragment.xml 72
8.2.3 Assembling the descriptor from web.xml, web-fragment.xml and
annotations 78
8.2.4 Shared libraries / runtimes pluggability 91
8.3 JSP container pluggability 93
8.4 Processing annotations and fragments 93
9. Dispatching Requests 95
xiv Java Servlet Specification • April 2013
9.1 Obtaining a RequestDispatcher 95
9.1.1 Query Strings in Request Dispatcher Paths 96
9.2 Using a Request Dispatcher 96
9.3 The Include Method 97
9.3.1 Included Request Parameters 97
9.4 The Forward Method 98
9.4.1 Query String 98
9.4.2 Forwarded Request Parameters 98
9.5 Error Handling 99
9.6 Obtaining an AsyncContext 99
9.7 The Dispatch Method 100
9.7.1 Query String 100
9.7.2 Dispatched Request Parameters 100
10. Web Applications 103
10.1 Web Applications Within Web Servers 103
10.2 Relationship to ServletContext 103
10.3 Elements of a Web Application 104
10.4 Deployment Hierarchies 104
10.5 Directory Structure 104
10.5.1 Example of Application Directory Structure 106
10.6 Web Application Archive File 106
10.7 Web Application Deployment Descriptor 106
10.7.1 Dependencies On Extensions 107
10.7.2 Web Application Class Loader 107
10.8 Replacing a Web Application 108
10.9 Error Handling 108
10.9.1 Request Attributes 108
10.9.2 Error Pages 109
Contents xv
10.9.3 Error Filters 111
10.10 Welcome Files 111
10.11 Web Application Environment 112
10.12 Web Application Deployment 113
10.13 Inclusion of a web.xml Deployment Descriptor 113
11. Application Lifecycle Events 115
11.1 Introduction 115
11.2 Event Listeners 115
11.2.1 Event Types and Listener Interfaces 116
11.2.2 An Example of Listener Use 117
11.3 Listener Class Configuration 117
11.3.1 Provision of Listener Classes 117
11.3.2 Deployment Declarations 118
11.3.3 Listener Registration 118
11.3.4 Notifications At Shutdown 118
11.4 Deployment Descriptor Example 118
11.5 Listener Instances and Threading 119
11.6 Listener Exceptions 119
11.7 Distributed Containers 120
11.8 Session Events 120
12. Mapping Requests to Servlets 121
12.1 Use of URL Paths 121
12.2 Specification of Mappings 122
12.2.1 Implicit Mappings 122
12.2.2 Example Mapping Set 123
13. Security 125
13.1 Introduction 125
xvi Java Servlet Specification • April 2013
13.2 Declarative Security 126
13.3 Programmatic Security 126
13.4 Programmatic Security Policy Configuration 128
13.4.1 @ServletSecurity Annotation 128
13.4.1.1 Examples 132
13.4.1.2 Mapping @ServletSecurity to security-constraint 133
13.4.1.3 Mapping @HttpConstraint and
@HttpMethodConstraint to XML. 135
13.4.2 setServletSecurity of ServletRegistration.Dynamic 136
13.5 Roles 137
13.6 Authentication 138
13.6.1 HTTP Basic Authentication 138
13.6.2 HTTP Digest Authentication 138
13.6.3 Form Based Authentication 139
13.6.3.1 Login Form Notes 140
13.6.4 HTTPS Client Authentication 141
13.6.5 Additional Container Authentication Mechanisms 141
13.7 Server Tracking of Authentication Information 141
13.8 Specifying Security Constraints 142
13.8.1 Combining Constraints 143
13.8.2 Example 144
13.8.3 Processing Requests 146
13.8.4 Uncovered HTTP Protocol Methods 147
13.8.4.1 Rules for Security Constraint Configuration 149
13.8.4.2 Handling Uncovered HTTP Methods 149
13.9 Default Policies 150
13.10 Login and Logout 151
14. Deployment Descriptor 153
Contents xvii
14.1 Deployment Descriptor Elements 153
14.2 Rules for Processing the Deployment Descriptor 154
14.3 Deployment Descriptor 155
14.4 Deployment Descriptor Diagram 155
14.5 Examples 178
14.5.1 A Basic Example 179
14.5.2 An Example of Security 180
15. Requirements related to other Specifications 183
15.1 Sessions 183
15.2 Web Applications 183
15.2.1 Web Application Class Loader 183
15.2.2 Web Application Environment 184
15.2.3 JNDI Name for Web Module Context Root URL 184
15.3 Security 185
15.3.1 Propagation of Security Identity in EJB™ Calls 186
15.3.2 Container Authorization Requirements 186
15.3.3 Container Authentication Requirements 186
15.4 Deployment 187
15.4.1 Deployment Descriptor Elements 187
15.4.2 Packaging and Deployment of JAX-WS Components 187
15.4.3 Rules for Processing the Deployment Descriptor 189
15.5 Annotations and Resource Injection 189
15.5.1 @DeclareRoles 190
15.5.2 @EJB Annotation 191
15.5.3 @EJBs Annotation 192
15.5.4 @Resource Annotation 192
15.5.5 @PersistenceContext Annotation 193
15.5.6 @PersistenceContexts Annotation 193
xviii Java Servlet Specification • April 2013
15.5.7 @PersistenceUnit Annotation 194
15.5.8 @PersistenceUnits Annotation 194
15.5.9 @PostConstruct Annotation 194
15.5.10 @PreDestroy Annotation 195
15.5.11 @Resources Annotation 195
15.5.12 @RunAs Annotation 196
15.5.13 @WebServiceRef Annotation 197
15.5.14 @WebServiceRefs Annotation 197
15.5.15 Contexts and Dependency Injection for Java EE requirements 197
A. Change Log 199
A.1 Changes since Servlet 3.0 199
A.2 Changes since Servlet 3.0 Proposed Final Draft 201
A.3 Changes since Servlet 3.0 Public Review 202
A.4 Changes since Servlet 3.0 EDR 202
A.5 Changes since Servlet 2.5 MR6 202
A.6 Changes since Servlet 2.5 MR 5 203
A.6.1 Clarify SRV 8.4 "The Forward Method" 203
A.6.2 Update Deployment descriptor "http-method values allowed"
203
A.6.3 Clarify SRV 7.7.1 "Threading Issues" 204
A.7 Changes Since Servlet 2.5 MR 2 204
A.7.1 Updated Annotation Requirements for Java EE containers 204
A.7.2 Updated Java Enterprise Edition Requirements 204
A.7.3 Clarified HttpServletRequest.getRequestURL() 204
A.7.4 Removal of IllegalStateException from HttpSession.getId() 205
A.7.5 ServletContext.getContextPath() 205
A.7.6 Requirement for web.xml in web applications 206
A.8 Changes Since Servlet 2.4 206
Contents xix
A.8.1 Session Clarification 206
A.8.2 Filter All Dispatches 207
A.8.3 Multiple Occurrences of Servlet Mappings 207
A.8.4 Multiple Occurrences Filter Mappings 208
A.8.5 Support Alternative HTTP Methods with Authorization
Constraints 209
A.8.6 Minimum J2SE Requirement 210
A.8.7 Annotations and Resource Injection 210
A.8.8 SRV.9.9 ("Error Handling") Requirement Removed 210
A.8.9 HttpServletRequest.isRequestedSessionIdValid() Clarification
210
A.8.10 SRV.5.5 ("Closure of Response Object") Clarification 210
A.8.11 ServletRequest.setCharacterEncoding() Clarified 211
A.8.12 Java Enterprise Edition Requirements 211
A.8.13 Servlet 2.4 MR Change Log Updates Added 211
A.8.14 Synchronized Access Session Object Clarified 211
A.9 Changes Since Servlet 2.3 211