Transcription
PROPOSED FINAL DRAFTJava Servlet SpecificationVersion 2.3Please send technical comments to:Please send business comments .comProposed Final Draft - October 20th 2000 Danny Coward (danny.coward@sun.com)PROPOSED FINAL DRAFT
Java(TM) Servlet API Specification ("Specification")Version: 2.3Status: Pre-FCSRelease: October 20th, 2000Copyright 2000 Sun Microsystems, Inc.901 San Antonio Road, Palo Alto, California 94303, U.S.A.All rights reserved.NOTICEThe Specification is protected by copyright and the informationdescribed therein may be protected by one or more U.S. patents, foreign patents, or pendingapplications. Except as provided under the following license, nopart of the Specification may be reproduced in any form by anymeans without the priorwritten authorization of Sun Microsystems, Inc. ("Sun") and itslicensors, if any. Any use of the Specification and the information described therein will begoverned by the terms and conditions of this license and theExport Control and General Terms as set forth in Sun’s websiteLegal Terms. By viewing,downloading or otherwise copying the Specification, you agreethat you have read, understood, and will comply with all of theterms and conditions set forthherein.Subject to the terms and conditions of this license, Sun herebygrants you a fully-paid, non-exclusive, non-transferable, worldwide, limited license (withoutthe right to sublicense) under Sun’s intellectual property rightsto review the Specification internally for the purposes of evaluation only. Other than thislimited license, you acquire no right, title or interest in or to theSpecification or any other Sun intellectual property. The Specification contains theproprietary and confidential information of Sun and may only beused in accordance with the license terms set forth herein. Thislicense will expire ninety(90) days from the date of Release listed above and will terminate immediately without notice from Sun if you fail to complywith any provision of thislicense. Upon termination, you must cease use of or destroythe Specification.TRADEMARKSNo right, title, or interest in or to any trademarks, service marks,or trade names of Sun or Sun’s licensors is granted hereunder.Sun, Sun Microsystems, theSun logo, Java, and the Java Coffee Cup logo, are trademarksor registered trademarks of Sun Microsystems, Inc. in the U.S.and other countries.DISCLAIMER OF WARRANTIESTHE SPECIFICATION IS PROVIDED "AS IS" AND IS EXPERIMENTAL AND MAY CONTAIN DEFECTS OR DEFICIENCIESWHICHCANNOT OR WILL NOT BE CORRECTED BY SUN. SUNMAKES NO REPRESENTATIONS OR WARRANTIES, EITHEREXPRESS ORIMPLIED, INCLUDING BUT NOT LIMITED TO, WARRANTIESOF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, ORNON-INFRINGEMENT THAT THE CONTENTS OF THE SPECIFICATION ARE SUITABLE FOR ANY PURPOSE OR THATANY PRACTICEOR IMPLEMENTATION OF SUCH CONTENTS WILL NOTINFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS,TRADE SECRETS OROTHER RIGHTS. This document does not represent any commitment to release or implement any portion of the Specificationin any product.THE SPECIFICATION COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGESARE PERIODICALLYADDED TO THE INFORMATION THEREIN; THESECHANGES WILL BE INCORPORATED INTO NEW VERSIONSOF THE SPECIFICATION,IF ANY. SUN MAY MAKE IMPROVEMENTS AND/ORCHANGES TO THE PRODUCT(S) AND/OR THE PROGRAM(S) DESCRIBED IN THESPECIFICATION AT ANY TIME. Any use of such changes inthe Specification will be governed by the then-current license forthe applicable version ofthe Specification.LIMITATION OF LIABILITYTO THE EXTENT NOT PROHIBITED BY LAW, IN NO EVENTWILL SUN OR ITS LICENSORS BE LIABLE FOR ANY DAMAGES, INCLUDINGWITHOUT LIMITATION, LOST REVENUE, PROFITS OR DATA,OR FOR SPECIAL, INDIRECT, CONSEQUENTIAL, INCIDENTAL ORPUNITIVE DAMAGES, HOWEVER CAUSED AND REGARDLESS OF THE THEORY OF LIABILITY, ARISING OUT OF ORRELATED TO ANYFURNISHING, PRACTICING, MODIFYING OR ANY USE OFTHE SPECIFICATION, EVEN IF SUN AND/OR ITS LICENSORS HAVE BEENADVISED OF THE POSSIBILITY OF SUCH DAMAGES.You will indemnify, hold harmless, and defend Sun and its licensors from any claims based on your use of the Specification forany purposes other than thoseof internal evaluation, and from any claims that later versions orreleases of any Specification furnished to you are incompatiblewith the Specificationprovided to you under this license.RESTRICTED RIGHTS LEGENDIf this Software is being acquired by or on behalf of the U.S.Government or by a U.S. Government prime contractor or subcontractor (at any tier), then theGovernment’s rights in the Software and accompanyingdocumentation shall be only as set forth in this license; this is inaccordance with 48 C.F.R. 227.7201 through 227.7202-4 (forDepartment of Defense (DoD)acquisitions) and with 48 C.F.R. 2.101 and 12.212 (for non-DoDacquisitions).REPORTYou may wish to report any ambiguities, inconsistencies or inaccuracies you may find in connection with your evaluation of theSpecification ("Feedback").To the extent that you provide Sun with any Feedback, youhereby: (i) agree that such Feedback is provided on a non-proprietary and non-confidential
basis, and (ii) grant Sun a perpetual, non-exclusive, worldwide,fully paid-up, irrevocable license, with the right to sublicensethrough multiple levels ofsublicensees, to incorporate, disclose, and use without limitation the Feedback for any purpose related to the Specificationand future versions,implementations, and test suites thereof.
PROPOSED FINAL DRAFTContentsStatus . 12Changes in this document since v2.2. 12Preface . 14Who should read this document . 14API Reference . 14Other Java Platform Specifications. 14Other Important References . 15Providing Feedback . 16Acknowledgements . 16Chapter 1: Overview. 18What is a Servlet?. 18What is a Servlet Container? . 18An Example. 19Comparing Servlets with Other Technologies . 19Relationship to Java 2 Platform Enterprise Edition . 20Chapter 2: The Servlet Interface . 22Request Handling Methods . 22HTTP Specific Request Handling Methods. 22Contents4
PROPOSED FINAL DRAFTConditional GET Support .23Number of Instances .23Note about SingleThreadModel .24Servlet Life Cycle .24Loading and Instantiation .24Initialization.24Request Handling .25End of Service .27Chapter 3: Servlet Context .28Scope of a ServletContext.28Initialization Parameters .28Context Attributes.29Context Attributes in a Distributed Container.29Resources.29Multiple Hosts and Servlet Contexts.30Reloading Considerations .30Temporary Working Directories .31Chapter 4: The Request .32Parameters .32Attributes .33Headers .33Request Path Elements.34Path Translation Methods .35Cookies .36SSL Attributes .36Internationalization .37Request data encoding .375Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTChapter 5: The Response . 38Buffering . 38Headers. 39Convenience Methods . 40Internationalization. 40Closure of Response Object . 41Chapter 6: Servlet Filtering . 42What is a filter ? . 42Examples of Filtering Components . 43Main Concepts. 43Filter Lifecycle. 43Filter environment . 45Configuration of Filters in a Web Application . 45Chapter 7: Sessions . 48Session Tracking Mechanisms . 48URL Rewriting. 48Cookies . 49SSL Sessions . 49Session Integrity. 49Creating a Session . 49Session Scope. 50Binding Attributes into a Session . 50Session Timeouts. 50Last Accessed Times . 51Important Session Semantics. 51Threading Issues . 51Distributed Environments. 51Contents6
PROPOSED FINAL DRAFTClient Semantics .52Chapter 8: Dispatching Requests .54Obtaining a RequestDispatcher.54Query Strings in Request Dispatcher Paths.55Using a Request Dispatcher .55Include .56Included Request Parameters .56Forward.56Query String .57Error Handling .57Chapter 9: Web Applications.58Relationship to ServletContext .58Elements of a Web Application .58Distinction Between Representations.59Directory Structure .59Sample Web Application Directory Structure.60Web Application Archive File .60Web Application Configuration Descriptor .61Dependencies on extensions: Library Files.61Web Application Classloader.62Replacing a Web Application .62Error Handling .62Welcome Files .63Web Application Environment .64Chapter 10: Application Lifecycle Events .66Introduction .66Event Listeners .667Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTConfiguration of Listener Classes . 68Listener Instances and Threading . 69Distributed Containers. 69Session Events- Invalidation vs Timeout. 69Chapter 11: Mapping Requests to Servlets . 70Use of URL Paths. 70Specification of Mappings. 71Implicit Mappings . 71Example Mapping Set . 71Chapter 12: Security. 74Introduction . 74Declarative Security . 75Programmatic Security . 75Roles . 76Authentication . 76HTTP Basic Authentication . 76HTTP Digest Authentication. 77Form Based Authentication. 77HTTPS Client Authentication . 78Server Tracking of Authentication Information . 79Propogation of Security Identity. 79Specifying Security Constraints . 80Default Policies . 80Chapter 13: Deployment Descriptor. 82Deployment Descriptor Elements. 82Deployment Descriptor DOCTYPE . 82DTD . 83Contents8
PROPOSED FINAL DRAFTExamples .96A Basic Example .97An Example of Security.98Chapter 14: API Details .100Config. 104Filter . 106FilterConfig . 108GenericServlet. 110RequestDispatcher . 115Servlet . 117ServletConfig . 120ServletContext. 121ServletContextAttributeEvent . 129ServletContextAttributesListener. 131ServletContextEvent . 133ServletContextListener. 135ServletException . 136ServletInputStream. 139ServletOutputStream . 141ServletRequest . 146ServletRequestWrapper . 153ServletResponse . 159ServletResponseWrapper . 163SingleThreadModel. 167UnavailableException . 168Cookie . 173HttpServlet . 1799Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTHttpServletRequest . 185HttpServletRequestWrapper . 193HttpServletResponse . 200HttpServletResponseWrapper . 212HttpSession . 217HttpSessionAttributesListener . 222HttpSessionBindingEvent . 224HttpSessionBindingListener . 227HttpSessionContext. 228HttpSessionEvent . 229HttpSessionListener . 231HttpUtils. 232Appendix A: Deployment Descriptor Version 2.2. 236Appendix B: Glossary . 250Contents10
PROPOSED FINAL DRAFT11Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTStatusThis specification is being developed following the Java Community Process. This documentis the Proposed Final Draft version of the Java Servlet 2.3 Specification.Changes in this document since version 2.2 Incorporation of Javadoc API definitions into the specification document Application Events Servlet Filtering Requirement of J2SE as the underlying platform for web containers Dependencies on installed extensions Internationalization fixes Incorporation of Servlet 2.2 errata and numerous other clarificationsChanges since Public DraftHere is a summary of the main items that have changed in the specification since public draftbased on a large amount of feedback.Specification document changes Added 2.2 deployment descriptor as appendix Added change list Many editorial changesStatus12
PROPOSED FINAL DRAFTServlets - Chapter 2 Added doHead() method back to HttpServlet (see API)ServletContexts - Chapter 3 added getServletContextName() (see API) added getResourcePaths() (see API)Request - Chapter 4 Add attributes for error processing Added UnsupportedCharacterEncoding to throws clause of setCharacterEncoding() (seeAPI) getQueryString() - specify value is not decoded (see API) getParameterMap() - return value is immutable (see API) clarify getAuthType() javadoc, added statics for authentication types (see API) clarify default character encoding clarify behavior of getRealPath() (see API) clarification of HttpServletRequest.getHeaders() when name not found (see API)Response - Chapter 5 clarify status code on response when errors occur (see API) added resetBuffer() method to ServletResponse (see API) sendError clarifrications (see API)) disallow container defaulting the content type of a response clarify behavior of flush() on PrintWriter and ServletOutputStream (see API) clarify default character encoding of response clarify what container does with headers on setStatus() (see API) sendRedirect() clarification for non-absolute URLs (API doc) sendError() clarifications (API doc)13Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTFilters - Chapter 6 Scoping of filter instances Clarification of filters acting on static resources Added FilterChain interface and minor refactoring Removed Config interface Added set{Response,Request} methods to filter wrapper classesSessions - Chapter 7 Addition of HttpSessionActivationListener interface used in distributed containers (alsosee API) Clarification of semantics for persisting & migrating sessions in distributed containers many clarifications of session expiry and notification, order of notification (see API)Application Event Listeners - Chapter 10 Clarifying notifications on shutdown and ordering thereofRequestMappings - Chapter 11 clarified servlet mapped to /foo/* is called by a request for /foo Request matching is done by case-sensitive string matchSecurity - Chapter 12 Specify a default behavior for isUserInRole() in absernce of role-refs Clarify interaction between RequestDispatcher and security model Clarify policy for processing multiple security constraints Added security attributes for SSL algorithm Specify status code for failed form login Specify allowed methods of return for form login error pageStatus14
PROPOSED FINAL DRAFTDeployment Descriptor - Chapter 13 corrected bad comment for ejb-ref-type clarifying web container policy for whitespace in the deployment descriptor clarifying paths in deployment descriptor are assumed decoded recommend validation of deployment descriptor documents and some semantic checkingby web containers as aid to developers policy for paths refering to resources in the WAR: must start with ’/’ clarify policy for relativizing policy of paths in web.xml added display name to security-constraint for tool manipulation fix security example Use of "*" to mean ’all roles’ in the security-constraint element syntax for specifying sharing scope for connection factory connections syntax for declaring dependencies on administered objects in J2EE clarify error-page path usage clarify jsp-file path usage snyc with EJB and EE specs on allowed strings in res-auth element clarify 2.2 dtd must be supported for backwards compatibility15Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTPrefaceThis document, the Java Servlet Specification, v2.3 the Java Servlet API. The referenceimplementation provides a behavioral benchmark. In the case of an area where thespecification leaves implementation of a particular feature open to interpretation,implementors should look first to the reference implementation and then to the compatibilitytest suite. If further clarification is required, the working group for the Java Servlet APIunder the Java Community Process should be consulted and is the final arbiter of such issues.Who should read this documentThis document is intended for consumption by: Web Server and Application Server vendors that want to provide Servlet Engines thatconform with this specification. Web Authoring Tool developers that want to generate Web Applications that conform tothis specification Sophisticated Servlet authors who want to understand the underlying mechanisms ofServlet technology.Please note that this specification is not a User’s Guide and is not intended to be used assuch.API ReferenceThe Java Servlet API Reference, v2.3 provides the complete description of all the interfaces,classes, exceptions, and methods that compose the Servlet API. This document contains thefull specification of class, interfaces, method signatures and accompanying javadoc thatdefines the Servlet API.Preface14
PROPOSED FINAL DRAFTOther Java Platform SpecificationsThe following Java API Specifications are referenced throughout this specification: Java2 Platform Enterprise Edition, v1.3 (J2EE) JavaServer Pages , v1.2 (JSP) Java Naming and Directory Interface (JNDI)These specifications may be found at the Java2 Enterprise Edition website:http://java.sun.com/j2ee/Other Important ReferencesThe following Internet Specifications provide relevant information to the development andimplementation of the Servlet API and engines which support the Servlet API: RFC 1630 Uniform Resource Identifiers (URI) RFC 1738 Uniform Resource Locators (URL) RFC 2396 Uniform Resource Identifiers (URI): Generic Syntax RFC 1808 Relative Uniform Resource Locators RFC 1945 Hypertext Transfer Protocol (HTTP/1.0) RFC 2045 MIME Part One: Format of Internet Message Bodies RFC 2046 MIME Part Two: Media Types RFC 2047 MIME Part Three: Message Header Extensions for non-ASCII text RFC 2048 MIME Part Four: Registration Procedures RFC 2049 MIME Part Five: Conformance Criteria and Examples RFC 2109 HTTP State Management Mechanism RFC 2145 Use and Interpretation of HTTP Version Numbers RFC 2324 Hypertext Coffee Pot Control Protocol (HTCPCP/1.0) 1 RFC 2616 Hypertext Transfer Protocol (HTTP/1.1) RFC 2617 HTTP Authentication: Basic and Digest AuthenticationYou can locate the online versions of any of these RFCs at:http://www.rfc-editor.org/The World Wide Web Consortium (http://www.w3.org/) is a definitive source ofHTTP related information that affects this specification and its implementations.1. This reference is mostly tongue-in-cheek although most of the concepts described in the HTCPCPRFC are relevant to all well designed web servers.15Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTThe Extensible Markup Language (XML) is utilized by the Deployment Descriptorsdescribed in this specification. More information about XML can be found at the ml.org/Providing FeedbackThe success of the Java Community Process depends on your participation in the community.We welcome any and all feedback about this specification. Please e-mail your comments to:servletapi-feedback@eng.sun.comPlease note that due to the volume of feedback that we receive, you will not normally receivea reply from an engineer. However, each and every comment is read, evaluated, and archivedby the specification team.AcknowledgementsThis public draft represents the team work of the JSR053 expert group.Preface16
PROPOSED FINAL DRAFT17Java Servlet 2.3 Specification - PROPOSED FINAL DRAFT October 20, 2000
PROPOSED FINAL DRAFTCHAPTER1OverviewThis chapter provides an overview of the Servlet API.1.1What is a Servlet?A servlet is a web component, managed by a container, that generates dynamic content.Servlets are small, platform independent Java classes compiled to an architecture neutralbytecode that can be loaded dynamically into and run by a web server. Servlets interact withweb clients via a request response paradigm implemented by the servlet container. Thisrequest-response model is based on the behavior of the Hypertext Transfer Protocol (HTTP).1.2What is a Servlet Container?The servlet container, in conjunction with a web server or application server, provides thenetwork services over which requests and responses are set, decodes MIME based requests,and formats MIME based responses. A servlet container also contains and manages servletsthrough their lifecycle.A servlet container can either be built into a host web server or installed as an add-oncomponent to a Web Server via that server’s native extension API. Se
This specification is being developed following the Java Community Process. This document is the Proposed Final Draft version of the Java Servlet 2.3 Specification. Changes in this document since version 2.2 Incorporation of Javadoc API definitions into the specification document Application Events Servlet Filtering
