java servletapi-2.1

8/7/2019 Java ServletAPI-2.1

1/75

901 San Antonio Road

Palo Alto , CA 94303 USA

415 960-1300 fax 415 969-9131

A Division of Sun Microsystems, Inc.

Java Servlet APISpecification

Version 2.1a

James Duncan Davidsonwith Suzanne Ahmed

Novem ber 1998

Java Software Division


2/75

Copyright Information

1998, Sun Microsyst ems , Inc. All righ ts reserved .

901 San An tonio Rd ., Palo Alto, Californ ia 94303 U.S.A.This documen t is protected by copyright. No part of this docum ent may be reprod uced in any form by any means w ithout

pr ior written au thorization of Sun and its licensors, if any.

The information described in this docum ent may be pr otected by one or more U.S. patents, foreign paten ts, or pending

applications.

LICENSE

Sun Microsystems, Inc. (SUN) hereby gr ants you at no charge a n onexclusive, nontr ansferable, worldw ide, limited license

(withou t the right to sublicense) und er SUNs intellectual prop erty rights tha t are essential to use the JavaTM Servlet API

Specification (Specification) for internal evaluation purposes only. Other than this limited license, you acquire no right, title,or interes t in or to the Specification and you sh all hav e no righ t to use the Specification for prod uctive or comm ercial use.

RESTRICTED RIGH TS LEGEND

Use, du plication , or disclosu re by th e U.S. Governm ent is su bject to restrictions of FAR 52.227-14(g)(2)(6/ 87) and FAR 52.227-

19(6/ 87), or DFAR 252.227-7015(b)(6/ 95) an d DFAR 227.7202-1(a).

TRADEMARKS

Sun, th e Sun logo, Sun M icrosystem s, Sun Microelectron ics, Sun XTL, Solaris, Java , JavaSoft, the JavaSoft logo, JavaOS,

JavaBeans, JDK, HotJava, H otJava Views, JavaChip , picoJava, microJava, Ultr aJava, JDBC, Visua l Java , Solaris, NEO, Joe,

Netr a, NFS, ONC, ON C+, OpenWindow s, PC-NFS, Embed ded Java, PersonalJava, SNM, SunN et Manager, Solaris sunbu rst

design, Solstice, SunCore, SolarN et, Sun Web, Sun Workstat ion, The Netw ork Is The Comp uter, ToolTalk, Ultra,

Ultra comp ut ing, Ultrase rver, Where The Netw ork Is Going, Sun WorkShop , XView, Java WorkShop , the Java Coffee Cup log o,

the Java Cup and Steam Logo, Write Once, Run Anyw here, JavaServer, and JavaServer Pag es are trad emar ks or registered

trad emar ks of Sun M icrosystems, Inc. in the United States and other coun tries.

UNIXis a registered trad emar k in the United States and oth er countries, exclusively licensed th rough X/ Op en Comp any, Ltd.

Adobe is a registered trad emar k of Adobe Systems, Inc.

Netscape Navigator is a tradem ark of Netscape Comm un ications Corporation.

All other prod uct names men tioned herein are the trad emar ks of their respective own ers.

THIS DOCU MENT IS PROVIDED AS IS WITHOU T WARRAN TY OF ANY KIND, EITHER EXPRESS OR IMPLIED,

INCLUDIN G, BUT NO T LIMITED TO, THE IMPLIED WARRAN TIES OF MERCHAN TABILITY, FITNESS FOR A

PARTICULAR PURPOSE, OR NON-INFRINGEMENT.

THIS DOCUMENT COULD INCLUDE TECHNICAL INACCURACIES OR TYPOGRAPHICAL ERRORS. CHANGES ARE

PERIODICALLY ADDED TO THE IN FORMATION HEREIN; THESE CHA NGES WILL BE INCO RPORATED IN NEW

EDITIONS OF TH E DOCUMENT. SUN MICROSYSTEMS, INC. MAY MAKE IMPROVEMENTS AND / OR CH AN GES IN

THE PROD UCT(S) AND/ O R THE PROGRAM(S) DESCRIBED IN THIS DOCUM ENT AT ANY TIME.

Please send all comments to servletapi -feed back@eng .sun.com .


3/75

Contents

1. About Java Servlets 9

Overview of Java Servlets 10

Servlet Lifecycle 10

Servlet Mapping Techniques 14

The Servlet Context 14

HTTP Sessions 15

2. API Class Reference 17

Interface RequestDispatcher 19

Interface Servlet 21

Interface ServletConfig 23

Interface ServletContext 24

Interface ServletRequest 29

Interface ServletResponse 33

Interface SingleThread Model 35

Class GenericServlet 36

Class ServletInpu tStream 39

Class ServletOutpu tStream 40

Class ServletException 42


4/75

Interface Http ServletRequest 45

Interface Http ServletResponse 50

Interface Http Session 55

Interface Http SessionBindingListener 59

Interface Http SessionContext 60

Class Cookie 61

Class Http Servlet 65

Class Ht tpSessionBindingEvent 69

Class HttpUtils 70


5/75

Preface

This docum ent, the JavaTM Servlet API Specification , describes Version 2.1 of the Java

Servlet API. In ad d ition to this sp ecification, the Java Servlet API h as Javad oc

docum entation and a reference imp lementation available for pu blic down load at the

followin g location:

http://java.sun.com/products/servlet/index.html

Who Should Read This Specification

This specification is intended as the definitive description of the Java Servlet API,

Version 2.1. As such, it w ill be of interest to both servlet d evelopers and servlet

engine developers.

Parts of the Java Servlet API

The Java Servlet API is divid ed int o two packagesan H TTP-specific package and a

generic, non-HTTP-specific package. The two packages w ill allow th e Java Servlet

API to be adap ted to oth er request-response p rotocols in the future.

The two packages are described in this specification, as well as in the Javadoc

docum entation and the reference implementation. The Javad oc documentation

describes how you use each method in the API.

The reference imp lementation provides a behavioral benchmark. In the case of a

discrepancy, the order of resolution is the specification (this document), then the

Javadoc d ocumentation, and finally the reference implementation.


6/75

Importan t References

You m ay be interested in th e following Inter net sp ecifications that are relevan t to the

dev elopm ent an d im plem entation of the Servlet API. You can locate online versionsof any of th ese RFCs at th e following location:

http://info.internet.isi.edu/7c/in-notes/rfc/.cache

s RFC 1738 Uniform Resource Locators (URL)

s RFC 1808 Relative Uniform Resource Locators

s RFC 1945 Hypertext Transfer Protocol (HTTP/ 1.0)

s RFC 2045 MIME Part On e: Form at of Internet M essage Bod ies

s RFC 2046 MIME Part Two: Media Types

s RFC 2047 MIME Part Three: Message H ead er Extensions for N on-ASCII Text

s RFC 2048 MIME Part Fou r: Registration Proced ures

s RFC 2049 MIME Part Five: Conform ance Cr iteria and Exam ples

s RFC 2068 Hypertext Transfer Protocol (HTTP/ 1.1)

s RFC 2069 An Extension to H TTP: Digest Access Au then tication

s RFC 2109 HTTP State Managem ent M echanism

s RFC 2145 Use and Interpretation of HTTP Version Numbers

s RFC 2324 Hyper text Coffee Pot Con trol Proto col (HTCPCP/ 1.0)1

The World Wide Web Consortium (http://www.w3.org) is a source of HTTP-

related information that affects this specification and its implementations.

1A tongu e in cheek reference


7/75

What Typographic Changes Mean

The following table describes the typ ograph ic changes u sed in this book.

Acknowledgements

Many ind ividuals and companies have given of their valuable skills and talent to

this specification and the Java Servlet API.

The author gratefully acknow ledges each of the following companies for

contribut ing to th e definition of the Java Servlet APIArt Technology Grou p, BEA

Weblogic, IBM, Gefion Software, Live Software, N etscape Comm un ications

Corporation, New Atlanta Comm unications, The Apache Group , and Sun

Microsystems, Inc.

The author also gratefully acknowledges the following individu als, each of whom

has contributed in h is or her u nique w ayAdam Messinger, Anselm Baird-Smith,

Bob Pask er, Jason Hun ter, Alan Williamson , Jon Stevens, Robert Clark, RodMcChesney, Satish Dh arm araj, Nath an A bram son, Stefano Mazzocchi, Jim Dr iscoll,

Connie Weiss, and Suzann e Ahm ed.

TABLE P-1 Typographic Conventions

Typeface or

Symbol Meaning Example

AaBbCc123 The nam es of command s, files,

and directories; on-screen

computer output

Edit your .login file.

Use ls -a to list all files.

machine_name% You have mail.

AaBbCc123 What you typ e, contrasted with

on-screen computer output

machine_name% su

Password:

A aBbCc123 Command-line placeholder:

replace with a real name or

value

To d elete a file, type rm filename.

A aBbCc123 Book titles, new w ord s or terms,

or words to be emphasized

Read Chap ter 6 in Users Guide.

These are called class options.

You must be root to do th is.


8/75


9/75

CHAPTER 1

Abou t Java Servlets

JavaTM servlets are small, platform-ind epend ent Java p rograms th at can be u sed to

extend the functionality of a Web server in a variety of ways. Servlets are to the

server w hat ap plets are to the clientsmall Java p rograms comp iled to bytecode

that can be loaded dyn amically and that extend th e capabilities of the host.

Servlets differ from ap plets in that servlets do not ru n in a Web browser or with a

graphical user interface. Instead, servlets interact with the servlet engine running on

the Web server throu gh requ ests and responses. The request-response parad igm ismodeled on the behavior of the HyperText Transfer Protocol (HTTP).

A client program, w hich could be a Web browser or some other p rogram th at can

make connections across the Internet, accesses a Web server and makes a request.

This request is processed by the servlet engine that runs with the Web server, which

returns a response to a servlet. The servlet in turn sends a response in HTTP form to

the client.

In functionality, servlets lie somewhere between Common Gateway Interface (CGI)

program s and propr ietary server extensions such as the N etscape Server API

(NSAPI). Unlike CGI programs an d NSAPI modu les, you d o not need to mod ify

servlets to be specific to either a platform or a server.


10/75

Overview of Java Servlets

Servlets have the following advan tages over other common server extension

mechanisms:

s They are faster th an CGI scripts because th ey use a different process model.

s They use a standard API that is supp orted by m any Web servers.

s They have all of the ad vantages of the Java language, includ ing ease of

development and platform independence.

s They can access the large set of APIs available for the Java platform.

Note The methods described in this specification are methods in the classes andinterfaces of the Java Servlet API. For more in format ion, refer to the API reference in

Chapter 2.

Servlet Lifecycle

A Java servlet has a lifecycle that defines how the servlet is loaded and initialized,

how it receives and responds to requests, and how it is taken out of service. In code,

the serv let lifecycle is defined by the javax.servlet.Servlet interface.

All Java servlets must, either directly or indirectly, implement the

javax.servlet.Servlet interface so that they can run in a servlet engine. The

servlet engine is a custom ized extension to a Web server for processing serv lets, built

in conformance with the Java Servlet API by the Web server vendor. The servlet

engine provides netw ork services, understand s MIME requests, and ru ns servlet

containers.

The javax.servlet.Servlet interface defines methods that are called at specific

times an d in a sp ecific order du ring th e servlet lifecycle. The en tire servlet lifecycle is

shown in FIGURE 1-1.


11/75

FIGURE 1-1 The Servlet Lifecycle


12/75

How a Servlet is Loaded and Instantiated

The servlet engine instantiates and loads a servlet. The instantiation and loading can

occur wh en the engine starts, when it needs th e servlet in order to respond to arequest, or any time in between.

The servlet engin e loads a servlet u sing th e Java class load ing facility. The serv let

engine can load the servlet from the local file system, a remote file system, or a

network source.

How a Servlet is InitializedAfter the servlet engine loads the servlet, the engine m ust initialize the servlet.

Initialization is a good time for a servlet to read any p ersistent d ata it may have

stored , initialize JDBC d atabase connections, and establish references to other costly

resources.

During initialization, the init method of the javax.servlet.Servlet interface

gives the servlet initialization information, so that th e servlet has an opp ortunity toconfigure itself.

The init method takes a servlet configuration object (of type ServletConfig) as

a parameter. The servlet configuration object is implemented in the servlet engine

and allows th e servlet to access name-value p arameters from the engines

configuration information. The servlet configuration object also gives the servlet

access to a servlet context ob ject, of type ServletContext.

How a Servlet Hand les Requests

After the servlet is initialized, it is ready to handle requests from the client. Each

client request that is made of a servlet is represented by a servlet request object (of

type ServletRequest). The response the servlet sends to the client is represented

by a servlet response object (of type ServletResponse).

When the client m akes a requ est, the servlet engine p asses both the servlet request

object and the servlet response object to the servlet. The objects are passed as

param eters to the service method , defined in the Service interface and w hich the

servlet imp lements.

The servlet can also imp lement the ServletRequest or ServletResponse

interfaces, or both. The ServletRequest interface gives the serv let access to the

request par ameters the client send s, such as form data, request information, and

l h d Th l d h d f i bj


13/75

The ServletResponse interface allows th e servlet to set response head ers and

status codes. By implementing ServletResponse, the servlet has access to an

output stream object (of type ServletOutputStream) that it can use to return d ata

to the client.

Multithreading and Mapping

In a multithreaded environment, most servlets must be w ritten to handle mu ltiple

concurrent requests. The exception is a servlet that implements the

SingleThreadModel interface. Such a servlet will execute only one request thread

at a time.

A servlet responds to a client request according to the servlet engines map ping. A

map ping p airs a servlet instance with an URL to wh ich the servlet returns d ata, for

example, HelloServlet with /hello/index.html.

How ever, a mapp ing might p air an URL with more than one servlet instance. For

example, a distributed servlet engine running on m ore than one server might hav e a

servlet instance running on each server, to balance the processing load. As a servlet

developer, you cannot assu me th at a servlet has only one instance.

How a Servlet is Destroyed

The servlet engine is not required to keep a servlet loaded for any p eriod of time or

for the life of the server. Servlet engin es are free to use servlets or retire them at an y

time. Therefore, you should not rely on class or instance members to store state

information.

When the servlet engine determines that a servlet should be destroyed (for examp le,

if the engine is shu t dow n or need s to conserve resources), the engine m ust allow the

servlet to release any resources it is using and save persistent state. To do this, the

engine calls the servlets destroy method.

The servlet engine m ust allow a ny calls to the service method either to comp lete

or to end with a time out (as the engine d efines a time out) before the engine can

destroy the servlet. Once the engine d estroys a servlet, the engine cannot rou te any

more requ ests to the servlet. The engine mu st release the servlet and m ake it eligible

for garb age collection.


14/75

Servlet Mapping Techniques

As a servlet engine d eveloper, you have a great d eal of flexibility in h ow you m ap

client requests to servlets. This specification d oes not m and ate how the m app ing

should take place. However, you should feel free to u se any of the following

techniques:

s You can ma p a servlet to just one URL.

For example, you can specify that a particular servlet is only called by requests

from th e file URL /feedback/index.html.

s You can m ap a servlet to any URL that begins w ith a certain directory nam e.

For examp le, if you m ap a servlet to the URL /catalog, requests from

/catalog/, /catalog/garden, and /catalog/housewares/index.html

wou ld also map to the servlet. How ever, requests from /catalogtwo or

/catalog.html would not.

s You can m ap a servlet to any URL that end s with a certain file name extension.

For example, you can map a request for any file whose nam e ends in .thtml to a

particular servlet. If you u se both file name extension m app ing and directory

mapping in your servlet engine, design the engine so that the file name resolution

takes place after the directory name resolution fails.

s You can m ap a servlet by using th e special URL /servlet/servlet_name.

For examp le, if you create a servlet w ith the n ame listattributes, you can

access the servlet by using the URL /servlet/listattributes.s You can invoke a servlet by its class nam e.

For example, if a servlet engine receives a request from the URL

/servlet/com.foo.servlet.MailServlet, the servlet engine can load th e

class com.foo.servlet.MailServlet, instantiate it, cast the instance to a

servlet, and th en let the servlet hand le the request.

The Servlet Context

The ServletContext interface d efines a servlet context object, that is, an object

that defines the servlets view of the servlet engine. By using a servlet context,

servlets can log events and obtain resources and objects (such as


15/75

If a servlet engine sup ports virtu al hosts, each virtual host h as a servlet context. A

servlet context cannot be shared across virtual hosts.

Servlet engines can allow a servlet context to have as its scope p art of a server s URL

path.

For example, a servlet context belonging to a bank application can be mapped to the

path /bank. In this case, a call to the getContext method (/bank/foo) would

return the servlet context for /bank. Such a m app ing will become part of the

upcoming Deployment Descriptor specification.

HTTP Sessions

The H yp erText Tran sfer Protocol (HTTP) is a stateless p rotocol. To bu ild effective

Web server ap plications, you mu st be able to identify a series of unique requests

from a remote client as being from the same client. Many strategies for session

tracking h ave evolved over time, but all are difficult or trou blesome to use.

The Java Servlet API provides a simple interface that allows a servlet engine to use

any nu mber of app roaches to track a user session.

Creating a Session

Because HTTP is a request-response protocol, a session is considered new until the

client joins it. Join means that th e client returns session tracking information to theserver, ind icating that a session has been established. Un til the client joins a session,

you cannot assum e that th e next client response is part of the current session.

The session is considered to be new if either of the following is true:

s The client d oes not yet know about th e session.

s The client chooses not to join a session, for example, if the client declines to accept

cookies sent by the server.

As a servlet developer, you m ust d esign you r Web application to hand le situations

in which a client has not, or can not, join a session. The server will maintain the

session object for a period of time specified by the Web server or a servlet. When a

session expires, the serv er w ill release the session object and all other objects boun d

du ring the session.


16/75

Bind ing Objects into a Session

You m ight w ant to bind objects into a session, if it helps you h and le your

ap plications da ta requ irement s. You can bind any object into a session by a u niqu e

nam e, using the HttpSession object. Any object boun d in to a session is available to

any other servlet that han dles a request from the same session.

Some objects may requ ire that you know wh en they are placed into, or removed

from, a session. You can obtain th is inform ation by u sing the

HttpSessionBindingListener interface. When your application stores data in or

removes d ata from the session, the servlet engine checks wh ether the object being

bound or unbound imp lements HttpSessionBindingListener. If it does,

method s in the interface notify the object that it has been boun d or unbou nd .


17/75

CHAPTER 2

API Class Reference

This section contains the detailed specification for each class and interface in the

Java Servlet API. The API reference in th is specification is sim ilar to th e Javad oc API

reference, but this specification provides more information.

The API consists of 2 packages, 12 interfaces, and 9 classes, as show n in Table 2-1.


18/75

TABLE 2-1 Packages in the Java Servlet API

Package javax.servlet

Type Name Page Number

Interface RequestDispatcher Page 20

Interface Servlet Page 22

Interface ServletConfig Page 24

Interface ServletContext Page 25

Interface ServletRequest Page 30

Interface ServletResponse Page 34

Interface SingleThreadModel Page 36

Class GenericServlet Page 37

Class ServletInputStream Page 40

Class ServletOutputStream Page 41

Class ServletException Page 43

Class UnavailableException Page 44

Package javax.servlet.http

Type Name Page Number

Interface HttpServletRequest Page 46

Interface HttpServletResponse Page 51

Interface HttpSession Page 56

Interface HttpSessionBindingListener Page 60

Interface HttpSessionContext Page 61

Class Cookie Page 62

Class HttpServlet Page 66

Class HttpSessionBindingEvent Page 70

Class HttpUtils Page 71


19/75

Interface Requ estDispatcher

Definition

public interface RequestDispatcher;

Defines a request dispatcher object that receives requests from the client and sends

them to an y resou rce (such as a servlet, CGI script, HTML file, or JSP file) available

on th e Web server. The requ est disp atcher object is created by the serv let engine an d

serves as a wrap per arou nd a server resource defined by a p articular URL.

The RequestDispatcher interface is defined p rimarily to w rap servlets, but a

servlet engine can create request d ispatcher objects to w rap any typ e of resource.

Request dispatcher objects are created by the servlet engine, not by the servlet

developer.

Methods

forward

public void forward(ServletRequest request, ServletReponse response)

throws ServletException, IOException;

Used for forward ing a request from th is servlet to another resource on the Web

server. This method is useful w hen on e servlet does preliminary p rocessing of a

request and wan ts to let another object generate the response.

The request object passed to the target object will have its request URL path and

other p ath p arameters ad justed to reflect the target URL path of the target object.

You cann ot use this m ethod if a ServletOutputStream object or PrintWriterobject has been obtained from the response. In that case, the m ethod th rows an

IllegalStateException.


20/75

include

public void include(ServletRequest request, ServletResponse response)

throws ServletException, IOException

Used for including the content generated by another server resource in the body of a

response. In essence, this method enables program matic server-side includ es.

The request object passed to the target object will reflect the request URL path and

pa th info of the calling requ est. The resp onse object only h as access to the calling

servlets ServletOutputStream object or PrintWriter object.

An included servlet cannot set head ers. If the includ ed servlet calls a method that

needs to set head ers (such as cookies), the m ethod is not gu aranteed to w ork. As aservlet developer, you m ust ensure th at any m ethods that m ight need d irect access

to headers are properly resolved. To ensure that a session works correctly, start the

session outside the included servlet, even if you use session tracking.


21/75

Interface Servlet

Definition

public interface Servlet

The Servlet interface defines a servlet, a Java object that extends the functionality

of a Web server.

Methods

init

public void init(ServletConfig config) throws ServletException;

The servlet engine calls the init method exactly once on a servlet, after the servlet

is instantiated but before it is placed into service. The init method must exit

successfully before you can call the service method.

If the init method throws a ServletException, you mu st not place the servlet

into serv ice. If the init method does not complete within the timeout period, you

can assume the servlet is nonfunctional and not in service.

service

public void service(ServletRequest request, ServletResponse response)

throws ServletException, IOException;

Called by the servlet engine to allow the servlet to respond to a request. This meth od

must not be called until the servlet has been successfully initialized. The servlet

engine mu st block p ending requests to this servlet until such time as it is initialized.

After a servlet object has been destroyed, the servlet engine must not call service

until a new servlet is initialized.


22/75

destroy

public void destroy();

Called by the servlet engine when the servlet is removed from service. The servletengine may not call this method until all threads within the objects service method

have exited or th e engines timeout period has passed.

getServletConfig

public ServletConfig getServletConfig();

Return s a ServletConfig object. As a servlet developer, you must store theServletConfig object passed to th e init method so that the getServletConfig

method can return the object. For you r convenience, the GenericServlet

implementation of this interface already does th is.

getServletInfo

public String getServletInfo();

Allows the servlet to provide information about itself to the host servlet runner. The

returned string must be of plain text form an d n ot comp osed of markup of any kind

(such as HTML, XML, etc).


23/75

Interface ServletConfig

Definition

public interface ServletConfig

This interface defines an object that a servlet engine generates to configure a servlet

and allow the servlet to obtain a reference to its ServletContext interface. Each

ServletConfig object the servlet receives is unique to that servlet.

Methods

getInitParameterpublic String getInitParameter(String name);

This method returns a String containing the value of the servlets nam ed

initialization pa rameter, or nu ll if this par ameter does n ot exist.

getInitParameterNames

public Enumeration getInitParameterNames();

This method returns an en um eration of String objects containing th e nam es of the

initialization parameters for the calling servlet. If the calling servlet has no

initialization param eters, getInitParameterNames returns an empty

enumeration.

getServletContextpublic ServletContext getServletContext();

Return s the ServletContext object for th is servlet.


24/75

Interface ServletContext

Definition

public interface ServletContext

Defines a servlet context object that the servlet engine generates to provide a servlet

with information about its environment.

A servlet context object is at least as unique as the host in which it resides. In a

servlet engine tha t han dles mu ltiple virtual h osts (for example, by using the HTTP

1.1 host head er), each virtual host mu st be treated as a separate context. Servlet

engines can a lso provid e context objects that are u niqu e to a grou p of servlets. You

can group the servlets administratively or define them with a d eployment

descriptor.

Methods

getAttribute

public Object getAttribute(String name);

Return s an object that is know n to the serv let context object by a given nam e, or null

if there is no such object associated with the name. This method allows access to

add itional information abou t the servlet engine not already p rovided by other

method s in th is interface.

You shou ld u se the same n aming conventions for attributes as for p ackage names.

Nam es matching java.*, javax.*, and sun.* are reserved for definition by this

specification or the reference implementation.

getAttributeNames

public Enumeration getAttributeNames();

Return s an en um eration of the attribute nam es present in the calling servlet context

object.


25/75

getContext

public ServletContext getContext(String uripath);

Return s the servlet context object that contains servlets and resources for a part icularURI pat h, or nu ll if a context cann ot be provid ed for the p ath. The format of the URI

path is /dir/dir/filename.ext.

For security, the servlet context object that a sandboxed or otherwise restricted

servlet has access to should return null to this method call.

getMajorVersion

public int getMajorVersion();

Return s the m ajor version of the Servlet API that th is servlet engine sup por ts. All 2.1

compliant imp lementations must return th e integer 2 to this method.

getMinorVersion

public int getMinorVersion();

Return s the minor version of the Servlet API that this servlet engine su pp orts. All 2.1

compliant imp lementations must return th e integer 1 to this method.

getMimeType

public String getMimeType(String file);

Return s the MIME type of the sp ecified file, or nu ll if not know n. The MIME type is

determ ined according to the configuration of the servlet engine.

getRealPath

public String getRealPath(String path);

App lies alias ru les to the specified virtual path in URL path format, that is,/dir/dir/filename.ext. Return s a String representing the correspond ing real

path in the format tha t is app ropriate for the ma chine (including the prop er path

separators) that the servlet engine is running on .

Return s nu ll if the translation could n ot be performed for any reason.


26/75

getResource

public URL getResource(String uripath);

Returns an URL object to a resource known to the servlet context object located at

the given URL path (of form at /dir/dir/filename.ext). The servlet engine m ust

implement wh atever URLStreamH and lers are necessary to access the given context.

If there is no resource know n to a servlet context for a p articular p ath,

getResource returns null.

This method does not fill the same p urp ose as the getResource method in

java.lang.Class. The m ethod in java.lang.Class looks up resources based on

Class class loader. This allows the server to make content visible to any servlet

from any source without regard to class loaders, location, and so on.

getResourceAsStream

public InputStream getResourceAsStream(String uripath);

Return s an InputStream object that refers to content known to the servlet context

object at the specified th e URL, or n ull if the servlet context object is not fou nd . The

URL path is of the form /dir/dir/filename.ext.

This method is a convenient way to obtain an URL object from the getResource

method and open a stream. Note that m eta-information such as content length and

content type are lost when you use getResourceAsStream.

getRequestDispatcher

public RequestDispatcher getRequestDispatcher(String uripath);

Return s a RequestDispatcher object for the specified URL if the context k now s of

an active source (such as a ser vlet, JSP p age, CGI script, etc.) of content for t he

particular path , or null otherwise. The format of the URL path is /dir/dir/

filename.ext). The servlet engine implements whatever functionality is needed to

wr ap the target pa th w ith a request dispatcher object that can perform request

forwarding and programmatic server side includes.

getServerInfo

public String getServerInfo();

Returns a String object containing at least the name and version of the servlet

engine.


27/75

log

public void log(String msg);

public void log(String msg, Throwable t);

public void log(Exception exception, String msg); // deprecated

Writes the specified messag e to th e log file for th is servlet context object. The log

written to is specific to the servlet engine, but is usually an event log. When this

method is called w ith an exception, the stack trace should be includ ed in th e log.

setAttribute

public void setAttribute(String name, Object o);

Binds the object you specify to the name you specify in the servlet context object.

Attribute nam es should follow th e same convention as package names. Nam es

beginning w ith the prefixes java.*, javax.*, and sun.* are reserved for

definition by this specification or the reference implementation

removeAttribute

public void removeAttribute(String name);

Removes an attribute from the specified servlet context object.

Deprecated Methods

getServlet

// deprecated

public Servlet getServlet(String name) throws ServletException;

Originally defined to return a servlet with the specified n ame, or nu ll if not found.

When th e servlet is return ed it is already initialized and ready to accept servicerequests.

This is a dan gerous m ethod. When this method is called, the state of the servlet may

not be know n and this could cause p roblems w ith the servers state machine. It is

also a security risk to allow any servlet to be able to access the m ethods of anoth er

servlet.


28/75

All servlet implementations should always retur n n ull to this call. As this method is

defined to always retu rn n ull, it will not be removed at this time to preserve binary

compatibility with previous versions of the API. This method will be removed in a

future revision of the API.

Deprecated as of Version 2.0.

getServletNames

// deprecated

public Enumeration getServletNames();

Originally defined to return an enumeration of String objects containing all theservlet object names know n to this servlet context. The enu meration always includ es

the servlet itself.

This is a dangerous m ethod, for the same reasons the getServlet method is

dangerous.

All servlet imp lementations should retur n an emp ty enum eration to this call. As this

method is defined to return an emp ty enum eration, it will not be removed at this

time to p reserve binary compa tibility w ith p revious versions of the API. Thismethod will be removed in a future revision of the API.


getServlets

// deprecated

public Enumeration getServlets();

Originally defined to return an enumeration of all the Servlet objects which are

know n to this servlet context. The enum eration always includ es the servlet itself.

This is a dangerous m ethod, for the same reasons the getServlet method is

dangerous.

All servlet imp lementations should retur n an emp ty enum eration to this call. As this

method is defined to return an emp ty enum eration, it will not be removed at this

time to p reserve binary compa tibility w ith p revious versions of the API. This

method will be removed in a future revision of the API.



29/75

Interface ServletRequ est

Definition

public interface ServletRequest

Defines a servlet engine generated object that enables the servlet to get data about a

client request. The d ata p rovided by this object includ es param eter nam es and

values, attributes, and an inp ut stream to read d ata from the requests body.

Methods

getAttributepublic Object getAttribute(String name);

Return s the value of the n amed attribute of this request, or nu ll if the attribute d oes

not exist. This method allows access to request information not already provided by

other methods in this interface or data that was placed in the request object by other

servlets. Attribute n ames shou ld follow the same convention as p ackage names. The

attribute nam es matching a p refix ofjava.*, javax.*, and sun.* are reserved for

definition by Sun Microsystems.

getAttributeNames

public Enumeration getAttributeNames();

Return s an enu meration of all the attribute nam es contained in the requ est.

getCharacterEncoding

public String getCharacterEncoding();

Return s the character set encoding for the inp ut body of this request, or null if no

character en coding is defined.


30/75

getContentLength

public int getContentLength();

Returns the MIME-specified content length, or -1 if not known.

getContentType

public String getContentType();

Return s the Multipurp ose Internet Mail Extension (MIME) type of the requ est body

data, or nu ll if not know n.

getInputStream

public ServletInputStream getInputStream() throws IOException;

Return s an inpu t stream for reading binary d ata from the request body. This method

will throw an IllegalStateException if a reader w as previously obtained via

th e getReader method.

getParameter

public String getParameter(String name);

Return s a string containing a single value of the specified param eter, or n ull if the

param eter does not exist. For examp le, in an H TTP servlet, this method wou ld

return th e value of a specified qu ery string param eter or posted form da ta

param eter. In the event th at there are mu ltiple param eter values for a single name,the value returned should be the first value in the array returned by the

getParameterValues method . If the param eter has (or could h ave) multiple

values, servlet writers should u se the getParameterValues method.

getParameterNames

public Enumeration getParameterNames();

Returns all the parameter names for this request as an enumeration of String objects,

or an empty enumeration if there are no input parameters.


31/75

getParameterValues

public String[] getParameterValues(String name);

Returns the values of the specified parameter as an array of String objects, or null if

the named parameter does not exist.

getProtocol

public String getProtocol();

Return s the p rotocol being u sed for this request as a string of the form protocol/

major_version.minor_version. An HTTP 1.0 request, as defined by the HTTP1.0 specification, should return the string HTTP/1.0.

getReader

public BufferedReader getReader() throws IOException;

This method returns a bu ffered read er for reading text data from the request body.

The character encoding of the read er is set according to the request d ata. Thismethod mu st throw an IllegalStateException if the inpu t stream of the request

had been obtained with the getInputStream call.

getRemoteAddr

public String getRemoteAddr();

Return s the IP add ress of the agent that sent th e request.

getRemoteHost

public String getRemoteHost();

Returns the fully qualified host name of the agent that sent the request. If the engine

cannot or chooses not to resolve the hostnam e (to improve p erformance), this

method returns the d otted-string form of the IP add ress.

getScheme

public String getScheme();

Return s the scheme of the URL used in th is request. For examp le, in an HTTP


32/75

getServerName

public String getServerName();

Return s the host nam e of the server that received th e request.

getServerPort

public int getServerPort();

Return s the port nu mber on w hich this request was received.

setAttribute

public void setAttribute(String name, Object object);

This method places an attribute into the request for later use by other objects which

will have access to this request object such as nested servlets.

Deprecated Methods

getRealPath

// deprecated

public String getRealPath(String path);

App lies alias rules to the specified virtu al path an d retu rns the corresponding real

path, or n ull if the translation cannot be performed for any reason.

This method has been dep recated in p reference to the getRealPath method in the

ServletContext interface. In Version 2.1, the ServletContext interface w as

clarified to contain all the p ath m app ing information available to a servlet.

Implementations should return the same string as the getRealPath method in

ServletContext.



33/75

Interface ServletResponse

Definition

public interface ServletResponse

Defines an object generated by the servlet engine that allows a servlet to respond to

a client requ est. This respon se is a MIME entity and could be an HTML page, image

data, or an y other MIME format.

Methods

getCharacterEncoding

public String getCharacterEncoding();

Return s the character set encodin g used for this MIME bod y. The character en coding

is either the one specified in the assigned conten t type, or the best match determin ed

in part by the request h eader information from th e client indicating w hat character

encoding s are accepta ble to the client. In H TTP, this inform ation is transm itted to th e

servlet engine via the Accept-Charset head er.

See RFC 2047 for more information about character encoding and MIME.

getOutputStream

public ServletOutputStream getOutputStream() throws IOException;

Returns an output stream for writing binary response data.

Throws IllegalStateException ifgetWriter has already been called on therespon se object.


34/75

getWriter

public PrintWriter getWriter throws IOException;

This method returns a print w riter for w riting formatted text responses. The MIME

type of the response will be modified, if necessary, to reflect the character encoding

being used th rough the charset property. The content type of the response shou ld be

set before calling this method.

Throws UnsupportedEncodingException if no such encoding can be provided .

Throws IllegalStateException ifgetOutputStream has already been called

on this same request.

setContentLength

public void setContentLength(int length);

Sets the content length for this response. This method will overwrite any previously

set content length.

In order for this meth od to successfully set the content length h eader of the

response, this method mu st be called before the response is comm itted to theund erlying output stream.

setContentType

public void setContentType(String type);

This method sets the content typ e for this response. This type m ay later be imp licitly

mod ified by the ad dition of properties such as the MIME charset p roperty if theservice finds it necessary and the app ropriate property h as not been set.

In order for this method to successfully set the content typ e head er of the response,

this method mu st be called before the response is committed to the u nd erlying

output stream.


35/75

Interface SingleThread Mod el

Definition

public interface SingleThreadModel;

This emp ty interface allows servlet implements to sp ecify how the system shou ld

handle concurrent calls to the same servlet. If the target servlet is flagged with this

interface, the servlet programm er is guaranteed that no tw o threads w ill executeconcurrently th e service method of the servlet.

This guaran tee can be accomp lished by the servlet engine by maintaining a p ool of

separate servlet instances of each servlet so m arked, or by only letting on e thread

execute the service method of the servlet at a time.


36/75

Class GenericServlet

Definition

public abstract class GenericServlet implements Servlet,

ServletConfig, Serializable;

This class is a convenience implementation to aid servlet writers. It provides simple

implementations of the servlet lifecycle m ethods as w ell as holds a reference to theServletConfig an d ServletContext objects provided at initialization time.

Select methods from the context object is exposed via methods in this class.

Methods

destroy

public void destroy();

This implementation of the destroy method does nothing.

getInitParameterpublic String getInitParameter(String name);

Convenience method wh ich in turn s calls the method of the same nam e on the

stored servlet configuration object.

getInitParameterNames

public Enumeration getInitParameterNames();


stored ServletConfig object.


37/75

getServletConfig

public ServletConfig getServletConfig();

Return s a reference to the ServletConfig object stored by th e init method of this

class.

getServletContext

public ServletContext getServletContext();


stored ServletConfig object.

getServletInfo

public String getServletInfo();

Return s an em pty servlet info string.

init

public void init() throws ServletException;

public void init(ServletConfig config) throws ServletException;

The init(ServletConfig config) method is a simp le imp lementation of the

servlet lifecycle initialization method. This is the version of this method that the

servlet engine calls w hen th e servlet is loaded .

The init() method is provided so that if you extend the GenericServlet class,

you d o not need to store the config object prop erly or call super.init(config).

The init(ServletConfig config) method saves the config object and calls

init(). If you write a method that overrides init(ServletConfig config),

you m ust call super.init(config), so that the other method s in the

GenericServlet class function correctly.

log

public void log(String msg);

public void log(String msg, Throwable cause);

Writes the class name of the servlet and the given message to the log accessible via

the servlet context ob ject.


38/75

service

public abstract void service(ServletRequest request, ServletResponse

response) throws ServletException, IOException;

Abstract method th at you m ust imp lement if you extend th is class, in ord er to

handle network requests.


39/75

Class ServletInputStream

Definition

public abstract class ServletInputStream extends InputStream

This class defines an input stream for reading requests from a client. This is an

abstract class that a servlet engine provides. A servlet obtains a reference to a

ServletInputStream object by using the ServletRequest interface.

Subclasses of this class must p rovide an implementation of the read method from

th e InputStream interface.

Methods

readLine

public int readLine(byte[] b, int off, int len) throws IOException;

Reads into the p ortion of the given array specified by the offset and length

param eters bytes from the inpu t until all requested bytes have been read or a new

line character is encountered, in w hich case the new line character is read into the

array as well and then stops.


40/75

Class ServletOutputStream

Definition

public abstract class ServletOutputStream extends OutputStream

This is an abstr act class for servlet engines to imp lement . Servlet d evelopers obt ain a

reference to an object of this type through the ServletResponse interface and u se

this outpu t stream to return d ata to clients.

Subclasses of this class mu st provid e an imp lement ation of the write(int) method

of the OutputStream interface.

When a flush or close method is called on an implementation of this interface, any

data buffered by th e servlet engine is sent to the client and the response is

considered to be committed. Note that calling close on an object of this type

doesnt necessarily close the underlying socket stream.

Methods

print

public void print(String s) throws IOException;public void print(boolean b) throws IOException;

public void print(char c) throws IOException;

public void print(int i) throws IOException;

public void print(long l) throws IOException;

public void print(float f) throws IOException;

public void print(double d) throws IOException;

Prints the argument provided to the u nderlying outp ut stream.

i tl


41/75

println

public void println() throws IOException;

public void println(String s) throws IOException;

public void println(boolean b) throws IOException;

public void println(char c) throws IOException;

public void println(int i) throws IOException;

public void println(long l) throws IOException;

public void println(float f) throws IOException;

public void println(double d) throws IOException;

Prints the argum ent provided to the un derlying outpu t stream followed by a CRLF.


42/75

Class ServletException

Definition

public class ServletException extends Exception

This exception is thrown to indicate a servlet problem.

Constructors

public ServletException();

public ServletException(String message);

public ServletException(String message, Throwable cause);

public ServletException(Throwable cause);

Constructs a new ServletException. If this constructor is called with aThrowable para meter, the Throwable object is registered as th e original cause of

this exception.

Methods

getRootCause

public Throwable getRootCause();

If the original cause of this exception w as set, this method returns th e cause;

otherwise, the method returns null.


43/75

Class UnavailableException

Definition

public class UnavailableException extends ServletException

This exception is throw n to indicate a servlet is either temp orarily or perm anently

una vailable. Servlets may repor t this exception at a ny time and the servlet engine

run ning the servlet mu st behave approp riately.

Temp orary u navailability is wh en the servlet cannot hand le requests at the current

time du e to some tran sient p roblem. For example, a server on a different app lication

layer, such as a database, may not be available. The problem may be self-correcting

or m ay requ ire further corrective action.

Permanen t u navailability is w hen the servlet will not be able to han dle client

requests until some ad ministrative action is taken. For examp le, the servlet may be

misconfigured , or the state of the servlet ma y be corrup ted.

Servlet engines may safely treat both types of exceptions as thou gh th ey are

perm anent, but good treatment of tempora ry un availability leads to more robust

servlet engin es. Specifically, requests to th e servlet m ay be blocked (or otherw ise

deferred) for a servlet suggested am ount of time, rather than being rejected until the

service itself restarts.

Constructors

public UnavailableException(Servlet servlet, String message);

public UnavailableException(int seconds, Servlet servlet,

String message);

Constru cts a new exception w ith the specified descrip tive message. If the constru ctor

is called w ith a given nu mber of second s, the unavailability is temp orary an d the

value given is an estimate of wh en the servlet w ill be able to hand le requests again.

If the constructor is called w ithout this argu ment, the servlet is perm anently

unavailable.

Methods


44/75

Methods

getServletpublic Servlet getServlet();

This method returns the servlet that is reporting its unavailability. This is used by

the servlet engine to identify the servlet that is affected.

getUnavailableSeconds

public int getUnavailableSeconds();

Return s the am ount of time th e servlet expects to be un available. Returns -1 if the

servlet is perm anently u navailable.

isPermanent

public boolean isPermanent();

Return s true if the servlet is perm anently u navailable, ind icating that some

adm inistrative action m ust be taken to make th e servlet u sable.


45/75

Interface HttpServletRequest

Definition

public interface HttpServletRequest extends ServletRequest;

Provid es access to HTTP-specific request inform ation to a servlet in an HTTP-based

request.

Methods

getAuthType

public String getAuthType();

Return s the au thentication scheme of this request.

getCookies

public Cookie[] getCookies();

Return s an array containing all the cookies present in this request. If there are no

cookies in the requ est, then an emp ty array is returned .

getDateHeader

public long getDateHeader(String name);

Return s the value of the requested head er converted to a long representing a date

expressed in milliseconds since January 1, 1970, 00:00:00GMT. The match betweenthe given nam e and the request head er is case insensitive.

If the head er cannot be converted, this method will throw an

IllegalArgumentException. If the head er requested does not exist, this method

returns -1.

getHeader


46/75

g

public String getHeader(String name);

Return s the value of the requested head er. The match between the given nam e and

the request header is case-insensitive.

If the head er requested d oes not exist, this method return s null.

getHeaderNames

public Enumeration getHeaderNames();

This method returns an enum eration of String objects representing the header n amesfor this request.

Some server im plementations m ay not allow headers to be accessed in th is way, in

which case this method can return an empty enumeration.

getIntHeader

public int getIntHeader(String name);

This method returns th e value of the specified head er converted to an integer. The

match betw een the given nam e and the request head er is case insensitive.

If the head er cannot be converted to an integer, this method throws a

NumberFormatException. If the head er requested does not exist, this m ethod

returns -1.

getMethod

public String getMethod();

Return s the H TTP m ethod (for exam ple, GET, POST, PUT) by w hich this requ est was

made.

getPathInfo

public String getPathInfo();

This method returns an y extra path information of the requ est URL following the

servlet path of this requests URL. If there is a query string as part of the request

URL, it is not includ ed in the return value. The p ath m ust be URL decoded before

being returned . This method returns n ull if there is no path information following

getPathTranslated


47/75

g

public String getPathTranslated();

This method gets any extra path informa tion following th e servlet path of this

requests URL and translates it into a real path. The request URL must be URLdecoded before the tran slation is attemp ted. If there is no extra path information

following the servlet p ath of the URL, this method returns nu ll.

getQueryString

public String getQueryString();

Return s query string present in the request URL if any. A query string is defined as

any information following a ? character in the URL. If there is no query string, this

method returns null.

getRemoteUser

public String getRemoteUser

Gets the name of the u ser making this request. This information m ay be provided by

HTTP au thentication.

This method returns n ull if there is no user nam e information in the requ est.

getRequestedSessionId

public String getRequestedSessionId();

Return s the session id specified w ith this requ est. This may d iffer from the session id

in the current session if the session id given by the client was invalid for whatever

reason and a n ew session w as created.

This method will return null if the request does not have a session associated with it.

getRequestURIpublic String getRequestURI();

Returns, from the first line of the HTTP request, the part of this requests URL that

defines the resource being requested. If there is a query string, it is not included in

the return value. For example a requ est accessed via the URL path of/catalog/

books?id=1 would return /catalog/books. The return value of this method

contains both the servlet path an d th e path info

If any p art of the URL path was URL encoded , the path m ust be d ecoded before

b i t d b thi th d


48/75

being returned by this method.

getServletPathpublic String getServletPath();

This method returns th e par t of the request URL that refers to the servlet being

invoked . For examp le, if a servlet is mapp ed to th e URL pa th of/catalog/summer

and a request of the path /catalog/summer/casual is made, the servlet path

would be /catalog/summer.

If the servlet was invoked by some other m echanism th an by a p ath m atch (such asan extension m atch), then this method retu rns nu ll.

getSession

public HttpSession getSession();

public HttpSession getSession(boolean create);

Return s the current valid session associated w ith this request. If this method iscalled w ith no argu ments, a session w ill be created for the request if there is not

allready a session associated w ith the requ est. If this meth od is called w ith a boolean

argum ent, then the session w ill be createdonly if the argum ent is true.

To ensure the session is prop erly maintained, the servlet d eveloper mu st call this

method before the response is committed.

If the create flag is set to false and no session is associated with this request, then

this method w ill return nu ll.

isRequestedSessionIdValid

public boolean isRequestedSessionIdValid();

This method checks whether this request is associated with a session that is

curren tly valid. If the session used by the requ est is not valid , it will not be return ed

via the getSession method.

isRequestedSessionIdFromCookie

public boolean isRequestedSessionIdFromCookie();

Returns true if the session id for this request was p rovided from the client as a

ki f l h i

isRequestedSessionIdFromURL


49/75

public boolean isRequestedSessionIdFromURL();

Return s true if the session id for this request was p rovided from the client as p art of

a URL; false otherwise. Note that th e spelling URL in the method n ame indicates thatthe method is new.

Deprecated Methods

isRequestedSessionIdFromUrl

// deprecated

public boolean isRequestedSessionIdFromUrl();

Deprecated in favor ofisRequestedSessionIdFromURL for nam ing consistency.

Note that the spelling Url in the method name indicates that the method is

deprecated.

This method is deprecat ed as of Version 2.1.


50/75

Interface HttpServletResponse

Definition

public interface HttpServletResponse extends ServletResponse

Represents an HTTP response back to the client. This interface allows a servlet

program mer to m anipu late H TTP-protocol-specific head er information. It is

implemented by servlet engine d evelopers for use w ithin servlets.

Member Variables

public static final int SC_CONTINUE = 100;

public static final int SC_SWITCHING_PROTOCOLS = 101;

public static final int SC_OK = 200;

public static final int SC_CREATED = 201;public static final int SC_ACCEPTED = 202;

public static final int SC_NON_AUTHORITATIVE_INFORMATION = 203;

public static final int SC_NO_CONTENT = 204;

public static final int SC_RESET_CONTENT = 205;

public static final int SC_PARTIAL_CONTENT = 206;

public static final int SC_MULTIPLE_CHOICES = 300;

public static final int SC_MOVED_PERMANENTLY = 301;

public static final int SC_MOVED_TEMPORARILY = 302;

public static final int SC_SEE_OTHER = 303;

public static final int SC_NOT_MODIFIED = 304;

public static final int SC_USE_PROXY = 305;

public static final int SC_BAD_REQUEST = 400;

public static final int SC_UNAUTHORIZED = 401;

public static final int SC_PAYMENT_REQUIRED = 402;

public static final int SC_FORBIDDEN = 403;

public static final int SC_NOT_FOUND = 404;

public static final int SC_METHOD_NOT_ALLOWED = 405;public static final int SC_NOT_ACCEPTABLE = 406;

public static final int SC_PROXY_AUTHENTICATION_REQUIRED = 407;

public static final int SC_REQUEST_TIMEOUT = 408;

public static final int SC_CONFLICT = 409;

public static final int SC_GONE = 410;

public static final int SC_LENGTH_REQUIRED = 411;

public static final int SC_PRECONDITION_FAILED = 412;

public static final int SC REQUEST ENTITY TOO LARGE = 413;

public static final int SC_UNSUPPORTED_MEDIA_TYPE = 415;

public static final int SC INTERNAL SERVER ERROR = 500;


51/75

public static final int SC_INTERNAL_SERVER_ERROR 500;

public static final int SC_NOT_IMPLEMENTED = 501;

public static final int SC_BAD_GATEWAY = 502;

public static final int SC_SERVICE_UNAVAILABLE = 503;

public static final int SC_GATEWAY_TIMEOUT = 504;

public static final int SC_HTTP_VERSION_NOT_SUPPORTED = 505;

Constants representing H TTP status codes as d efined by the H TTP/ 1.1 working

drafts.

Methods

addCookie

public void addCookie(Cookie cookie);

Adds the specified cookie to the response. This method can be called multiple times

to set more th an one cookie. This method mu st be called before the response is

committed so that the app ropriate headers can be set.

containsHeader

public boolean containsHeader(String name);

Checks wh ether or not a given response head er has been set.

encodeRedirectURL

public String encodeRedirectURL(String url);

Encodes the specified URL for use in the sendRedirect method or, if encoding is

not needed , return s the URL unchanged . This add itional encoding method is

provided because the rules for determ ining whether or not to encode the URL may

be d ifferent in th e red irect case. The given URL must be an absolute U RL. RelativeURLs are not permitted and must throw an IllegalArgumentException.

All URLs sent to th e sendRedirect method should be run through this method to

ensure th at session tracking is seamless w ith all browsers.

encodeURL


52/75

public String encodeURL(String url);

Encodes the URL by including the session ID in it, or if encoding is not needed,

returns th e URL un changed. URL encoding mu st be provided by the servlet engineif URL rewriting is present and enabled and there is a valid session for the requ est

that this response is part of and th e session is not being maintained via a cookie or

other non U RL means.

All URLs emitted by a servlet should be ru n throu gh this method to ensure that

session tracking is seamless with all browsers.

sendError

public void sendError(int statusCode) throws IOException;

public void sendError(int statusCode, String message) throws

IOException;

Sends an error response to the client using the specified status code. If a message is

provided to this method , it is emitted as the respon se body, otherwise the server

should return a standard message body for the error code given.

This is a convenience method that imm ediately comm its the response. No further

outp ut shou ld be mad e by the servlet after calling this method .

sendRedirect

public void sendRedirect(String location) throws IOException;

Sends a tempora ry red irect response to the client (SC_MOVED_TEMPORARILY) using

the sp ecified location. The given location m ust be an absolute U RL. Relative URLs

are not permitted and throw an IllegalArgumentException.

This method will must be called before the response is committed. This is a

convenience method th at immed iately commits the response. No furth er outp ut is be

mad e by the servlet after calling this method .

setDateHeader

public void setDateHeader(String name, long date);

Sets a response header w ith the specified n ame an d d ate valued field app ropriate for

that head er. The da te is specified in t erm s of milliseconds since Januar y 1, 1970,

00:00:00GMT. If the header has already been set, the new value overwrites the

previous one

setHeader

bli id d ( i i l )


53/75

public void setHeader(String name, String value);

Sets a response h eader with the specified nam e and field. If the field has already

been set, the new value overw rites the previous one.

setIntHeader

public void setIntHeader(String name, int value);

Sets a response header w ith the specified n ame an d integer value. If the head er has

already been set, the new value overw rites the previous one.

setStatus

public void setStatus(int statusCode);

This method sets the status code of the response. If the status code has already been

set, the new value overrides the p revious valu e. If a message is provided, it is sent

back as the body of the response.

Deprecated Methods

encodeRedirectUrl

// deprecated

public String encodeRedirectUrl(String url);

Deprecated in favor ofencodeRedirectURL for nam ing consistency.


encodeUrl// deprecated

public String encodeUrl(String url);

Deprecated in favor ofencodeURL for nam ing consistency.


setStatus

// deprecated


54/75

// deprecated

public void setStatus(int statusCode, String message);

This method sets the status code of the response. If the status code h as already beenset, the new value overrides the p revious value. If a message is provided, it is sent

back as the body of the respon se.



55/75

Interface H ttpSession

Definition

public interface HttpSession

This interface is implemented by servlet engine to provide an associates between an

HTTP client and an H TTP session. This association, or session, persists over m ultiple

connection and / or requests du ring a given time p eriod. Sessions are used tomaintain state and user identity across mu ltiple page requests over the norm ally

stateless HTTP protocol.

A session can be maintained by either using cookies or URL rewriting.

Methods

getCreationTime

public long getCreationTime();

Returns the time at which this session was created in milliseconds since January 1,

1970, 00:00:00GMT.

getId

public String getId();

Returns the identifier assigned to this session. An HTTP sessions identifier is a

uniqu e string that is created and maintained by the server.

getLastAccessedTime

public long getLastAccessedTime();

Return s the last time th e client sent a request carrying the id entifier assigned to the

session, or -1 if the session is n ew. Time is expressed a s m illisecond s since

00:00:00GMT January 1, 1970.

getMaxInactiveInterval

public int getMaxInactiveInterval();


56/75

public int getMaxInactiveInterval();

Return s the maximu m a mou nt of time, in seconds, that a session is guaran teed to be

maintained in the servlet engine without a request from the client. After themaximum inactive time, the session m ay be expired by the servlet engine. If this

session will not expire, this method will return -1.

This method should throw an IllegalStateException if it is called after this

session has been invalidated .

getValuepublic Object getValue(String name);

Return s the object bound to a given n ame in the session. Returns nu ll if there is no

such binding.

This method must throw an IllegalStateException if it is called a fter this


getValueNames

public String[] getValueNames();

Return s an ar ray of the nam es of all the values bound into this session.

This method should throw an IllegalStateException if it is called after this


invalidate

public void invalidate();

This meth od will invalidate this session. All values boun d in the session are

removed. Any values that implement the HttpSessionBindingListener

interface will be notified via the valueUnbound method.

isNew

public boolean isNew();


57/75

p ();

Returns a Boolean value indicating whether this session is considered to be new. A

session is considered to be new if it has been created by the server and not receivedfrom the client as p art of this request. This means that th e client has n ot

acknowledged or joined the session and may not ever return the appropriate

session identification information when it makes its next request.

This method should throw an IllegalStateException if it is called after t his


putValue

public void putValue(String name, Object value);

Bind s the specified object into the session with the given n am e. Any existing bind ing

with th e same n ame is replaced. Objects placed into the session wh ich imp lement

th e HttpSessionBindingListener interface w ill call its valueBound method.

Some servlet engine im plementations w ill persist session d ata or distribute it

amongst m ultiple network n odes. For an object bound into the session to be

distributed or p ersisted to disk, it mu st imp lement the Serializable interface.



removeValue

public void removeValue(String name);

Unbinds an object in the session with the given name. If there is no object bound to

the given nam e, this method does nothing. If the object boun d to th e name

implements the HttpSessionBindingListener, its valueUnbound method will

be called.



setMaxInactiveInterval

public int setMaxInactiveInterval(int interval);

Sets the amount of time that a session can be inactive before the servlet engine is

allowed to expire it.

Deprecated Methods


58/75

getSessionContext// deprecated

public HttpSessionContext getSessionContext();

Return s the context object within w hich sessions on the server are held . This meth od

has been dep recated as all the methods ofHttpSessionContext are deprecated.

This method shou ld now return an object wh ich has an emp ty implementation of the

HttpSessionContext interface.


Interface HttpSessionBind ingListener


59/75

Interface HttpSessionBind ingListener

Definition

public interface HttpSessionBindingListener

Object that are meant to be placed into HTTP sessions can implement this interface

to be notified w hen they are being bound or un bound from an H TTP session.

Methods

valueBound

public void valueBound(HttpSessionBindingEvent event);

Method called when an object is bound into a session. This method must be called

by the servlet engine du ring the putValue method call in HTTP session.

valueUnbound

public void valueUnbound(HttpSessionBindingEvent event);

Method called w hen an object is unbou nd from a session. This method mu st becalled by the servlet engine du ring the removeValue method call in HTTP session.

It is possible that another servlet instance may have a reference to the object when

the object is unbound. The object that is being removed from the session must

behave app ropriately.

Interface Http SessionContext


60/75

Interface Http SessionContext

Definition

// deprecated

public interface HttpSessionContext

An HttpSessionContext object is a grouping of HTTP sessions associated with a

single entity.

This interface has been d eprecated for security reasons an d is only present in the

current version of the API to preserve compatibility. The methods of this interface

have been d efined to return values wh ich are legal according to the previous

definition of the API.


Methods

getSession

public HttpSession getSession(String sessionId);

Return s the session associated w ith a p articular session id. It should always retur nnull.

getIds

public Enumeration getIds();

Return s an enum eration of all of the session ids in this context. This method should

always return an empty enum eration.

Class Cookie


61/75

Class Cookie

Definition

public class Cookie implements Cloneable

This class represen ts a cookie as d efined by the original cookie specification from

Netscape Comm un ications Corporation as w ell as the u pd ated RFC 2109

specification.

Constructors

public Cookie(String name, String value);

Defines a cookie with an initial name-value pair. The name must be an HTTP/ 1.1

token value; alphanu meric strings w ork.

Names starting with a $ character are reserved by RFC 2109.

This method w ill throw an IllegalArgumentException if the given nam e is not

a va lid H TTP/ 1.1 token.

Methods

getComment

public String getComment();

Return s the commen t describing th e pu rpose of this cookie, or null if a comment has

not been defined.

getDomain

public String getDomain();

Return s the d omain of this cookie, or nu ll if not d efined.

getMaxAge

public int getMaxAge();


62/75

public int getMaxAge();

This method returns th e maximu m specified age of the cookie. If no maximu m age

was specified, this method returns -1.

getName

public String getName();

This method returns th e nam e of the cookie.

getPath

public String getPath();

Returns the prefix of all the URL paths for which this cookie is valid, or null if not

defined.

getSecure

public boolean getSecure();

Returns true if this cookie is only to be transmitted via secure channels, false

otherwise.

getValue

public String getValue();

This method returns th e value of the cookie.

getVersion

public int getVersion();

Return s th e ver sion of th e cookie. Version 1 com piles w ith RFC 2109. Version 0

indicates that the cookie complies with the original Netscape cookie specification.

Newly constructed cookies use version 0 by default to maximize interoperability.

setComment

public void setComment(String purpose);


63/75

If a user agent presents this cookie to a user, the cookies purpose will be described

by this comm ent. Version 0 cookies do n ot sup port this attribute.

setDomain

public void setDomain(String pattern);

This method sets the d omain attribute of the cookie. This attribute d efines which

hosts the cookie should be presented to by the client. A dom ain begins with a d ot

(.foo.com) and m eans that hosts in that DNS zone (www.foo.com but nota.b.foo.com) should see the cookie. By default, cookies are only returned to the

host which saved them.

See RFC 2109 for a m ore comp lete discussion of d oma ins and cookies.

setMaxAge

public void setMaxAge(int expiry);

This method sets the maximum age of the cookie. The cookie will expire after the

given num ber of seconds have p assed. Negative values will ensure that the cookie

will not persist on the client. A zero value causes the cookie to be deleted from the

client.

setPathpublic void setPath(String uri);

This method sets the path attribute of the cookie. The client shou ld only retu rn

cookies to paths th at begin with the given p ath string.

setSecure

public void setSecure(boolean flag);

Indicates to the user agent that th is cookie should only be sent via secure channels

(such as HTTPS). This should only be set when the cookies originating server used

a secure p rotocol to set the cookies valu e.

setValue

public void setValue(String newValue);


64/75

Sets the value of the cookie. BASE64 encoding is suggested for use with binary

values.

Version 0 cookies should not use whitespace, brackets, parentheses, the equals sign,

commas, dou ble quotes, slashes, question marks, the @ character, colons or

semicolons. Empty values m ay not behave the sam e way on all browsers.

setVersion

public void setVersion(int v);

Sets the version of the cookie format used with the cookie is written to the client.

Since the IETF stand ard s are still being finalized, consider version 1 as experim ental.

Class HttpServlet


65/75

Class HttpServlet

Definition

public class HttpServlet extends GenericServlet implements

Serializable

This class is an abstract class that simp lifies the p rocess of writing H TTP servlets. It

extend s the GenericServlet base class and provides a framew ork for handling the

HTTP protocol. A servlet writer can subclass this class and provide an

implementation for an y m ethod. This allows a convenient base class from wh ich to

build HTTP servlets.

The service method provided in this class supp orts standard HTTP methods such as

GET and POST by dispatching them to app ropriate method s such as doGet an d

doPost.

Methods

doDelete

protected void doDelete(HttpServletRequest request,

HttpServletResponse response) throws ServletException,

IOException;

Called by the service method of this class to handle an HTTP DELETE operation.

This operation allows a client to request that an URL be removed from the server.

Op erations requ ested th roug h DELETE can have side effects, for wh ich users may be

held accountable.

The default implementation of this method returns an HTTP BAD_REQUEST error.

A servlet mu st explicitly implement this method in order to han dle a DELETEmethod request.

doGet

protected void doGet(HttpServletRequest request,



66/75

IOException;

Called by the service meth od of this class to han dle an H TTP GET operation. This

operation allows the client to simply get a resource from an HTTP server. Users

that override this method autom atically allow su pp ort for the HEAD method.

The GET operation is expected to be safe without any side effects for which users

might be held responsible. For example, most form queries have no side effects.

Requests intend ed to change stored d ata should use some other H TTP method . This

operation is also expected to be repeated safely.


doHead

protected void doHead(HttpServletRequest request,


IOException;

Called by the service meth od of this class to hand le an HTTP HEAD opera tion. By

default, this is done in terms of a uncond itional GET method bu t returning n o data

to the client. Only the h eaders, includ ing content length, are returned .

As w ith the GET operation, this operation shou ld be safe (withou t side effects) and

repeatable.

The default implementation of this method autom atically han dles the H TTP H EAD

operation and does not need to be implemented by a subclass.

doOptions

protected void doOptions(HttpServletRequest request,


IOException;

Called by the service meth od of this class to han dle an HTTP OPTION S operation.This operation autom atically determ ines what H TTP method s are supp orted. For

example, if a servlet writer subclasses HttpServlet and overrides the doGet

method, then doOptions returns the following h eader:

Allow: GET,HEAD,TRACE,OPTIONS

You d o not ord inarily need to override the doOptions method.

doPost

protected void doPost(HttpServletRequest request,



67/75

IOException;

Called by the service method of this class to handle an HTTP POST operation. This

operation includ es data in the request body tha t should be acted up on by the servlet.

Operations requested through POST can h ave side effects for w hich the user can be

held accountable. Specific examples includ e up dating store d ata or buying items

online.


When you develop servlets, you mu st explicitly implement this method in th eHttpServlet subclass in order to sup port POST operations.

doPut

protected void doPut(HttpServletRequest request,


IOException;

Called by the service meth od of this class to hand le an HTTP PUT operation. This

operation is analogous to sending a file via FTP.

Operations requested through PUT can h ave side effects for w hich the user can be

held accountable. Specific examples includ e up dating store d ata or buying items

online.

The default implementation of this method returns a HTTP BAD_REQUEST error.

The servlet programm er mu st explicitly implement this method in a HttpServletsubclass in order to sup port POST operations.

doTrace

protected void doTrace(HttpServletRequest request,


IOException;

Called by the service method of this class to ha nd le a H TTP TRACE operation.

The default imp lementation of this method causes a response w ith a message

containing all of the head ers sent in th e trace request.

When you develop servlets, you override this method in most cases.

getLastModified

protected long getLastModified(HttpServletRequest request);

Return s the time the requ ested entity wa s last modified Implementations


68/75

Return s the time the requ ested entity wa s last modified. Implementations

supp orting the GET request should override th is method to provide an accurateobject mod ification time. This helps brow ser and proxy caches wor k more effectively

redu cing the load on server a nd netw ork resources. The return value is milliseconds

since January

java servletapi-2.1

Documents