Section B.4. javax.servlet.http Interfaces and Classes
B.4 javax.servlet.http Interfaces and Classes
The javax.servlet.http package allows a convenient way for developers to create servlets that are to be used specifically for the HTTP protocol. Session tracking, access to cookies, and methods for processing a variety of HTTP request types are made available here.
B.4.1 javax.servlet.http Interfaces
B.4.1.1 HttpServletRequest
public abstract interface HttpServletRequest extends Servlet
HttpServletRequest extends the ServletRequest interface to provide information to servlets regarding HTTP requests . The servlet container creates an HttpServletRequest object and passes it as an argument to the servlet's service methods, such as doGet() and doPost() .
The following fields are made available; each is a String identifier for Basic authentication:
public static final java.lang.String BASIC_AUTH public static final java.lang.String CLIENT_CERT_AUTH public static final java.lang.String FORM_AUTH public static final java.lang.String DIGEST_AUTH public String getAuthType()
getAuthType() returns the name of the authentication scheme in use for this resource, and it returns null if no scheme is in use. This is the same as the CGI variable AUTH_TYPE .
public String getContextPath()
getContextPath() returns the portion of the request URI that indicates the request context.
Returns "" for servlets in the root context.
public Cookie[] getCookies()
getCookies() returns an array of all Cookie objects sent by the client with this request. It returns null if no cookies were sent.
public long getDateHeader(String name) throws java.lang.IllegalArgumentException
getDateHeader() returns a long representing a Date object of the request header of headers that contain dates. The Date is returned as the number of milliseconds since January 1, 1970. If the request did not have an available Date header as specified, it returns -1 .
public String getHeader(String name)
getHeader() returns the value of the specified header name as a String object. It returns null if the specified header does not exist.
public Enumeration getHeaders(String name)
getHeaders() returns an enumeration of strings of the specified header. It returns an empty enumeration if the request did not include any headers of the specified name.
public Enumeration getHeaderNames()
getHeaderNames() returns an enumeration of all header names in this request. If your servlet container does not allow this method, it returns null .
public int getIntHeader(String name) throws NumberFormatException
getIntHeader() returns the value of the specified header as an int . It throws NumberFormatException if the header cannot be converted to an int , and it returns -1 if the request does not have a header of the name specified.
public String getMethod()
getMethod() returns the name of the HTTP method used to make the current request (for instance, GET , POST , PUT , or DELETE ).
public String getPathInfo()
getPathInfo() returns any extra path information associated with the URL sent by the client when the request was made. This information precedes the query string and follows the servlet path. It returns null if there is no extra path information and is the same as calling the CGI variable PATH_INFO .
public String getPathTranslated()
getPathTranslated() returns any extra path information associated with the URL sent by the client when the request was made, and translates it to a real path. It returns null if there is no extra path information and is the same as the CGI variable PATH_TRANSLATED .
public String getQueryString()
getQueryString() returns the query string in the URL of the current request following the path. It returns null if the URL contains no query string and returns the same information as the CGI variable QUERY_STRING .
public String getRemoteUser()
getRemoteUser() returns the login of the requesting user if that user has been authenticated. It returns null otherwise and is the same as the value of the CGI variable REMOTE_USER .
public String getRequestSessionId()
getRequestSessionId() returns the session ID specified by the client, which may not be the same as the ID of the actual session in use. It returns null if the request does not specify a session ID.
public String getRequestURI()
getRequestURI() returns the part of the URL from the protocol name up to the query string.
public StringBuffer getRequestURL()
getRequestURL() returns a StringBuffer object of the URL requested by the client without the query string.
public String getServletPath()
getServletPath() returns the part of the URL containing the servlet call. It includes the servlet name or path to the servlet and does not include any query string. It is the same as the CGI variable SCRIPT_NAME .
public HttpSession getSession()
getSession() gets the current session associated with this request. It creates a session if none is so associated.
public HttpSession getSession(boolean create)
getSession() gets the current session associated with this request. If there is no current session so associated and create is true , it returns a new session. If there is no valid session associated with the request and create is false , it returns null .
public java.security.Principal getUserPrincipal()
getUserPrincipal() returns the name of the current authenticated user as a Principal object. It returns null if the user is not authenticated.
public boolean isRequestedSessionIdFromCookie()
isRequestedSessionIdFromCookie() checks whether the requested session ID came from a cookie.
public boolean isRequestedSessionIdFromUrl()
Deprecated; use isRequestedSessionIdFromURL() instead.
public boolean isRequestedSessionIdFromUrl()
isRequestedSessionIdFromURL() checks whether the requested session ID came in as part of the URL.
public boolean isRequestedSessionIdValid()
isRequestedSessionIdValid() checks whether the requested session ID is still valid.
public boolean isUserInRole(String role)
isUserInRole() returns a boolean indicating whether the authenticated user is allowed in the specified logical role. Roles and membership therein can be described using deployment descriptors. It returns false if the user has not been authenticated.
B.4.1.2 HttpServletResponse
public interface HttpServletResponse extends ServletResponse
The HttpServletResponse interface extends the funtionality of the ServletReponse interface by providing methods for accessing HTTP-specific features. Such features include headers and cookies.
The servlet container creates an HttpServletRequest object and passes it as an argument to the servlet's service methods, such as doGet and doPost .
The following constants represent status codes defined in the HTTP specification. Each status code is followed by its numeric value and its meaning in HTTP.
public static final int SC_CONTINUE
100. The client should continue with his or her request.
public static final int SC_SWITCHING_PROTOCOLS
101. The server understands the client's request for a change in application protocol.
public static final int SC_OK
200. Success. The server's response contains the requested data.
public static final int SC_CREATED
201. A new resource has been created.
public static final int SC_ACCEPTED
202. The request has been accepted but not entirely processed .
public static final int SC_NON_AUTHORITATIVE_INFORMATION
203. Information returned in the entity header is not definitive. It comes from a copy.
public static final int SC_NO_CONTENT
204. The server has fulfilled the request, but it needn't return an entity body.
public static final int SC_RESET_CONTENT
205. The browser should clear the form that caused the request.
public static final int SC_PARTIAL_CONTENT
206. The server has carried out a partial GET request.
public static final int SC_MULTIPLE_CHOICES
300. The requested resource corresponds to any one of a set of representations.
public static final int SC_MOVED_PERMANENTLY
301. The requested resource has been moved permanently.
public static final int SC_MOVED_TEMPORARILY
302. The requested resource resides temporarily in another location.
public static final int SC_SEE_OTHER
303. The response to the request can be found at another location, as specified in the header.
public static final int SC_NOT_MODIFIED
304. The client has performed a conditional GET request, but the document is unchanged.
public static final int SC_USE_PROXY
305. The requested resource must be accessed through the proxy given in the Location field.
public static final int SC_BAD_REQUEST
400. The request contained malformed syntax and could not be understood .
public static final int SC_UNAUTHORIZED
401. The request lacks proper authorization to access the specified resource.
public static final int SC_PAYMENT_REQUIRED
402. The request is reserved for future use.
public static final int SC_FORBIDDEN
403. The server understood the request, but it refuses to fulfill it.
public static final int SC_NOT_FOUND
404. The server does not have a resource matching the one requested.
public static final int SC_METHOD_NOT_ALLOWED
405. The method specified in the request line is not allowed for the resource that has been identified.
public static final int SC_NOT_ACCEPTABLE
406. This resource can only generate incompatible responses for these request headers.
public static final int SC_PROXY_AUTHENTICATION_REQUIRED
407. The client must first authenticate itself with the proxy.
public static final int SC_REQUEST_TIMEOUT
408. The client did not produce a request within the server's time limit.
public static final int SC_CONFLICT
409. The request could not be completed because of a conflict with the resource.
public static final int SC_GONE
410. The resource is not available at this address and no forwarding information is known.
public static final int SC_LENGTH_REQUIRED
411. The server refuses to accept the request without a defined Content-Length .
public static final int SC_PRECONDITION_FAILED
412. The precondition given in one or more of the IF request-header fields evaluated to false.
public static final int SC_REQUEST_ENTITY_TOO_LARGE
413. The request entity is larger than the server can or will process.
public static final int SC_REQUEST_URI_TOO_LONG
414. The request URI is longer than the server will interpret.
public static final int SC_UNSUPPORTED_MEDIA_TYPE
415. The entity body of the request is in an unsupported format.
public static final int SC_REQUESTED_RANGE_NOT_SATISFIABLE
416. The server cannot serve the requested byte range.
public static final int SC_EXPECTATION_FAILED
417. The server could not meet the expectation given in the Expectation header.
public static final int SC_INTERNAL_SERVER_ERROR
500. The server encountered an error that prevented it from fulfilling the request.
public static final int SC_NOT_IMPLEMENTED
501. The server does not support the functionality required to fulfill the request.
public static final int SC_BAD_GATEWAY
502. The server received an invalid response from a server it consulted as a proxy.
public static final int SC_SERVICE_UNAVAILABLE
503. The server cannot handle the request because of temporary overloading or maintenance.
public static final int SC_GATEWAY_TIMEOUT
504. The server did not receive a response from the upstream server while acting as proxy.
public static final int SC_HTTP_VERSION_NOT_SUPPORTED
505. The server does not support the request version of HTTP.
public void addCookie(Cookie cookie)
addCookie() adds the specified cookie to the response. Multiple cookies can be added.
public void addDateHeader(String name, long date)
addDateHeader() adds a response header with the given name and date value.
public void addHeader(String name, String value)
addHeader() adds a response header with the given name and value.
addIntHeader(String name, int value)
addIntHeader() adds a response header with the given name and int value.
public boolean containsHeader(String name)
containsHeader() returns true if the response header includes the specified header name. It can be used before calling a set() method to determine if the value has already been set.
public String encodeRedirectURL(String url)
encodeRedirectURL() encodes the specified URL by including the session ID in it. If encoding is not necessary, it returns the URL unchanged.
public String encodeURL(String url)
encodeURL() encodes the specified URL by including the session ID in it. If encoding is not necessary, it returns the URL unchanged.
public void sendError(int sc, String msg)
sendError() sends an error response to the client with the specified status code. It clears the buffer.
public void sendRedirect(String location)
sendRedirect() sends a temporary redirect response to the client using the specified location.
public void setDateHeader(String name, long date)
setDateHeader() sets a response header with the given name and date value.
public void setIntHeader(String name, int value)
setIntHeader() sets a response header with the given name and integer value.
public void setStatus(int sc)
setStatus() sets the status code for this response.
B.4.1.3 HttpSession
The HttpSession interface provides a way to identify a user across mulitple requests and to store information about that user. The information can be maintained by using cookies or by rewriting URLs. The HttpSession interface allows servlets to read and manipulate session information (such as the session identifier, creation time, and last accessed time). It also allows servlets to bind objects to sessions so that user information persists across multiple requests. Session information is scoped only to the current Web application (ServletContext), so information is not shared between them.
public Object getAttribute(String name)
getAttribute() returns the object bound with the specified name in this session. If none is found, it returns null .
public java.util.Enumeration getAttributeNames()
getAttributeNames() returns an enumeration of String objects containing the names of all of the objects bound to this session.
public long getCreationTime()
getCreationTime() returns a long of the time this session was created. It is represented as the number of milliseconds since midnight, January 1, 1970.
public String getID()
getID() returns a string containing this session's unique identifier.
public long getLastAccessedTime()
getLastAccessedTime() returns a long containing the last time the client sent a request associated with this session. It is represented as the number of milliseconds since midnight, January 1, 1970, and it is marked by the time the container received the request.
public int getMaxInactiveInterval()
getMaxInactiveInterval() returns the maximum time interval (in seconds) that the container will keep the session open between requests.
public ServletContext getServletContext()
getServletContext() returns the servlet context to which this session belongs.
public void invalidate()
invalidate() invalidates the current session and unbinds any associated objects.
public boolean isNew()
isNew() returns a boolean indicating whether the client has joined the session yet.
public void removeAttribute(String)
removeAttribute() removes the object bound with the name specified from this session.
public void setAttribute(String name, Object value)
setAtrribute() binds an object to the session using the specified name.
public void setMaxInactiveInterval(int interval)
setMaxInactiveInterval() specifies the time in seconds between client requests before the container will invalidate the session.
B.4.1.4 HttpSessionActivationListener
public abstract interface HttpSessionActivationListener extends java.util.EventListener
An object bound to a session that implements this interface can be registered to receive notification regarding when its session will be passivated and activated. A container that migrates a session, for example, to another Virtual Machine must make such notification.
public void sessionDidActivate(HttpSessionEvent hse)
sessionDidActivate() is called when the session has just successfully been activated.
public void sessionWillPassivate(HttpSessionEvent hse)
sessionWillPassivate() is called when the session is about to be passivated.
B.4.1.5 HttpSessionAttributeListener
public interface HttpSessionAttributeListener extends java.util.EventListener
An object that implements this interface can receive notifications of changes to the attribute lists of sessions within this Web application.
public void attributeAdded(HttpSessionBindingEvent sbe)
attributeAdded() is called when an attribute has been added to the session.
public void attributeRemoved(HttpSessionBindingEvent sbe)
attributeRemoved() is called when an attribute has been removed from the session.
public void attributeReplaced(HttpSessionBindingEvent sbe)
attributeReplaced() is called when an attribute in a session is replaced .
B.4.1.6 HttpSessionBindingListener
public interface HttpSessionBindingListener extends java.util.EventListener
HttpSessionBindingListener causes an object to be notified when it is bound to or unbound from a session. This is typically the result of a session timing out or a session being invalidated.
public void valueBound(HttpSessionBindingEvent event)
valueBound() is called when an object is bound to a session.
public void valueUnbound(HttpSessionBindingEvent event)
valueUnbound() is called when the object is being unbound from a session.
B.4.1.7 HttpSessionListener
public interface HttpSessionListener
An object that implements this interface can be registered to receive notification when an HttpSession is created or destroyed .
public void sessionCreated(HttpSessionEvent se)
sessionCreated() is called when a session is created. It receives an HttpSessionEvent that contains information regarding the event.
public void sessionDestroyed(HttpSessionEvent se)
sessionDestroyed() is called when a session is destroyed. It receives an HttpSessionEvent that contains information about the event.
B.4.2 javax.servlet.http Classes
B.4.2.1 Cookie
public class Cookie extends java.lang.Object implements java.lang.Cloneable
Cookie creates a cookie object. Because cookies can uniquely identify clients , they are commonly used for session management. A cookie consists of a name, a single value, and some other optional information such as a comment, a path and domain qualifier, a maximum age, and a version number. The maximum age acts as an expiration date. If no date is supplied, the cookie is deleted when the session ends.
A cookie is sent to the browser by a servlet using the HttpServlet - Response.addCookie() method. Browsers are expected to support 20 cookies for each Web server ”300 cookies total ”and to impose a limit of 4 kB to each cookie.
Cookies can be retrieved from the request header using the HttpServlet - Request.getCookies() method.
Note that this class does not support HTTP 1.1 cache control. It does support version 0 (defined by Netscape) and version 1 (defined by RFC 2109) cookie specifications. The default is version 0.
public Cookie(String name, String value)
This constructor creates a cookie with the name and value specified.
public Object clone()
clone() overrides the standard cloning method as available in java.lang.Object.clone . It returns a copy of the current cookie.
public String getComment()
getComment() returns the comment describing this cookie's purpose. If no comment is present, it returns null .
public String getDomain()
getDomain() returns this cookie's domain name.
public int getMaxAge()
getMaxAge() returns the length of time in seconds that the cookie will persist on the client. Its value is -1 by default, indicating that it will persist until the browser is closed.
public String getPath()
getPath() returns the server path to which the browser returns the current Cookie object.
public boolean getSecure()
getSecure() returns true if the browser is sending cookies only over a secure protocol. It returns false if the browser can send cookies via any protocol.
public String getValue()
getValue() returns the value of the cookie.
public int getVersion()
getVersion() returns the version of the protocol this cookie complies with.
public void setComment(String purpose)
setComment() updates or sets the comment associated with the cookie. The comment is generally used to describe the purpose of the cookie.
public void setDomain(String pattern)
setDomain() specifies the domain within which this cookie should be visible.
public void setMaxAge(int expr)
setMaxAge() sets the maximum age of the cookie in seconds.
public void setPath(String uri)
setPath() specifies the path on the server to which the browser should return the cookie object. The cookie will be available to this directory as well as all subdirectories of the specified path.
public void setSecure(boolean flag)
setSecure() indicates to the browser whether the cookie should only be set using a secure protocol such as HTTPS.
public void setValue(String newValue)
setValue() assigns a new value to the cookie after it has been created.
public void setVersion(int ver)
setVersion() sets the version number of the cookie protocol with which this cookie complies.
B.4.2.2 HttpServlet
public abstract class HttpServlet extends GenericServlet implements java.io.Serializable
HttpServlet provides an abstract class, the concrete classes of which must override at least one of the methods defined in HttpServlet or Generic-Servlet classes. The doGet() , doPost() , doDelete() , and doPut() are the methods most frequently overridden.
public HttpServlet()
HttpServlet() is the constructor. However, it does nothing, as this is an abstract class.
protected doDelete(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doDelete() is called by the server via the service() method to handle an HTTP DELETE request.
protected void doGet(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doGet() is called by the server via the service() method to handle an HTTP GET request.
protected void doHead(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doHead() is called by the server via the service() method to handle an HTTP HEAD request.
protected void doOptions(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doOptions() is called by the server via the service() method to handle an HTTP OPTIONS request.
protected void doPost(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doPost() is called by the server via the service() method to handle an HTTP POST request.
protected void doPut(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doPut() is called by the server via the service() method to handle an HTTP PUT request.
protected void doTrace(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
doTrace() is called by the server via the service() method to handle an HTTP TRACE request. This is not generally overridden.
protected void getLastModified(HttpServletRequest req) throws ServletException, java.io.IOException
getLastModified() returns the time, in milliseconds since midnight, January 1, 1970, that the resource was last modified.
protected void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException public void service(HttpServletRequest req, HttpServletResponse res) throws ServletException, java.io.IOException
The service() methods both receive HTTP requests and send them to the appropriate do() method. These are not generally overridden.
B.4.2.3 HttpServletRequestWrapper
public class HttpServletRequestWrapper extends ServletRequestWrapper implements HttpServletRequest
HttpServletRequestWrapper provides an implementation of Http-ServletRequest that can be subclassed when the programmer needs to adapt the request to a servlet. Methods default to calling through to the wrapped request object.
public HttpServletRequestWrapper(HttpServletRequest req)
This constructor creates an HttpServletRequestWrapper around the specified HttpServletRequest object.
Unless they are overridden in a subclass, the following methods of Http-ServletResponseWrapper call the equivalent method on the wrapped HttpServletResponse :
public String getAuthType() public String getContextPath() public Cookie[] getCookies() public long getDateHeader() public java.util.Enumeration getHeaderNames() public java.util.Enumeration getHeaders() public int getIntHeader() public String getPathInfo() public String getPathTranslated() public String getQueryString() public String getRemoteUser() public String getRequestedSessionId() public String getRequestURI() public StringBuffer getRequestURL() public String getServletPath() public HttpSession getSession() public HttpSession getSession(boolean create) public java.security.Principal getUserPrincipal() public boolean isRequestedSessionIdFromCookie() public boolean isRequestedSessionIdFromUrl() public boolean isRequestedSessionIdFromURL() public boolean isRequestedSessionIdValid() public boolean isUserInRole(String role)
B.4.2.4 HttpServletResponseWrapper
public class HttpServletResponseWrapper extends ServletResponseWrapper implements HttpServletResponse
HttpServletResponseWrapper provides an implementation of Http-ServletResponse that can be subclassed when the programmer needs to adapt the response to a servlet. Methods default to calling through to the wrapped request object.
public HttpServletResponseWrapper(HttpServletResponse res)
This constructor creates an HttpServletResponseWrapper around the specified HttpServletResponse object.
Unless they are overridden in a subclass, the following methods of Http-ServletResponseWrapper call the equivalent method on the wrapped HttpServletResponse :
public void addCookie(Cookie cookie) public void addDateHeader(String name, long date) public void addHeader(String name, String value) public void addIntHeader(String name, int value) public boolean constainsHeader() public String encodeRedirectUrl(String url) public String encodeRedirectURL(String url) public String encodeUrl(String url) public String encodeURL(String url) public void sendError(int sc) public void sendError(int sc, String msg) public void sendRedirect(String location) public void setDateHeader(String name, long date) public void setHeader(String name, String value) public void setIntHeader(String name, int value)public void setStatus(int sc) public void setStatus(int sc, String sm)
B.4.2.5 HttpSessionBindingEvent
public class HttpSessionBindingEvent extends HttpSessionEvent
An HttpSessionBindingEvent is the type of event that is sent to an object implementing HttpSessionBindingListener when it is bound or unbound from a session or to an HttpSessionAttributeListener that has been configured in the deployment descriptor when any attribute is bound, unbound, or updated in a session.
HttpSessionBindingEvent(HttpSession session, String name) HttpSessionBindingEvent(HttpSession session, String name, Object value)
The constructors create an HttpSessionBindingEvent object. The session and name are the parameters to which the object is bound or unbound.
B.4.2.6 HttpSessionEvent
public class HttpSessionEvent extends java.util.EventObject
An HttpSessionEvent represents event notifications for changes to a session.
HttpSessionEvent(HttpSession source)
HttpSessionEvent constructs a given session. It must be passed from a reference to the HttpSession to which the event relates .
public HttpSession getSession()
getSession() returns the session associated with this event.
B.4.3 javax.servlet.jsp Interfaces
The javax.servlet.jsp package contains interfaces and classes of the Java-Server Pages specification. Many of these are intended for use by the JSP engine ”not within an actual JSP.
B.4.3.1 HttpJspPage
public interface HttpJspPage extends JspPage
This interface provides two methods that initialize and destroy a JSP; this class is generated by the processor and must satisfy them both. It extends JspPage and defines one method.
_jspService() is an implementation of the service() method specific to the HTTP protocol.
public void _jspService( javax.servlet.http.HttpServletRequest request, javax.servlet.http.HttpServletResponse response) throws javax.servlet.ServletException, java.io.IOException
_jspService() method corresponds to the body of the JSP page. The JSP processor defines this automatically. It returns no value.
B.4.3.2 JspPage
public interface JspPage extends javax.servlet.Servlet
This interface must be implemented by a class generated by the JSP processor.
public void jspDestroy()
jspDetroy() is invoked when the JSP page is about to be removed. It corresponds to a servlet's destroy() method.
public void jspInit()
jspInit() is called when the JSP page is created, and can initialize the JspPage . It corresponds to a servlet's init() method.
B.4.4 javax.servlet.jsp Classes
B.4.4.1 JspEngineInfo
public abstract class JspEngineInfo
This is an abstract class that obtains information regarding the JSP engine.
public abstract String getSpecificationVersion()
getSpecificationVersion() returns a string containing the version number of the JSP specification supported by the engine; for example, 1.2 . If the version is unknown, it returns null .
public JspEngineInfo()
JspEngineInfo() is the default constructor. Because this class is abstract, only subclasses call this constructor.
B.4.4.2 JspFactory
public abstract class JspFactory extends java.lang.Object
JspFactory is an abstract class that allows for the creation of instances of classes and interfaces required to support the JSP implementation.
public JspFactory()
JspFactory() is the default constructor. Because this class is abstract, only subclasses call this constructor.
public static JspFactory getDefaultFactory()
getDefaultFactory() returns the default factory object reference for this implementation.
public abstract PageContext getPageContext(Servlet servlet, ServletRequest request, ServletResponse response, String errorpageurl, boolean needsSession, int buffer, boolean autoflush)
getPageContext() returns a javax.servlet.jsp.PageContext object for the calling servlet and pending request and response to be processed.
public abstract void releasePageContext(PageContext pc)
releasePageContext() releases the specified, previously allocated javax.servlet.jsp.PageContext object. This results in a call to the PageContext.release() method.
public static void setDefaultFactory(JspFactory dflt)
setDefaultFactory() sets the default JSP factory object for this JSP implementation. Only the JSP engine runtime may call this method.
B.4.4.3 JspWriter
public abstract class JspWriter extends java.io.Writer
The JspWriter class is abstract and provides a character output stream usable by a JSP object. It is similar to java.io.PrintWriter in functionality.
public static final int DEFAULT_BUFFER public static NO_BUFFER public static final int UNBOUNDED_BUFFER
The above constants define different buffer sizes passable to the JspWriter 's constructor.
protected int bufferSize protected boolean autoFlush
These fields indicate the Writer buffer size and whether the buffer will be automatically flushed, repsectively.
protected JspWriter(int bufferSize, boolean autoFlush)
This is a protected constructor that can be used by subclasses of JspWriter .
public abstract void clear() throws java.io.IOException
clear() clears the buffer. If data has been written to the output stream prior to the method call, an exception is thrown.
public abstract void clearBuffer() throws java.io.IOException
clearBuffer() clears the buffer. It does not throw an exception if data has been written to the output stream prior to the method call.
public void close() throws java.io.IOException
close() flushes and then closes the stream. Once closed, any write() or flush() invocations will throw a java.io.IOException .
public abstract void flush() throws java.io.IOException
flush() flushes the output buffer, writing any data in the buffer to their intended destination. If the intended destination is another data stream, it too is flushed. In this manner, all buffers in a chain of writers and output streams will be flushed.
public int getBufferSize() throws java.io.IOException
getBufferSize() returns the buffer size in bytes (as in int ). It returns 0 if there is no buffer.
public int getRemaining() throws java.io.IOException
getRemaining() returns the number of bytes that are still left unused in the buffer.
public boolean isAutoFlush()
isAutoFlush() returns true if the buffer flushes automatically.
public abstract void newLine() throws java.io.IOException
newLine() writes a new line character to the output stream. The line separator is defined by line.separator and, as such, may not be a single new line character.
public abstract void print(boolean b) throws java.io.IOException public abstract void print(char c) throws java.io.IOException public abstract void print(int i) throws java.io.IOException public abstract void print(long l) throws java.io.IOException public abstract void print(float f) throws java.io.IOException public abstract void print(double d) throws java.io.IOException public abstract void print(char[] ca) throws java.io.IOException public abstract void print(String s) throws java.io.IOException public abstract void print(Object o) throws java.io.IOException
print() prints the primitive, object, or string as specified to the client without a new line character ( \n ). When an object is passed as the argument, it is converted to a string using String.valueOf() .
public abstract void println() throws java.io.IOException public abstract void println(boolean b) throws java.io.IOException public abstract void println(char c) throws java.io.IOException public abstract void println(int i) throws java.io.IOException public abstract void println(long l) throws java.io.IOException public abstract void println(float f) throws java.io.IOException public abstract void println(double d) throws java.io.IOException public abstract void println(char[] ca) throws java.io.IOException public abstract void println(String s) throws java.io.IOException public abstract void println(Object o) throws java.io.IOException
println() prints the primitive, Object , or String as specified to the client with a carriage return/new line character ( \n ). When no argument is passed to the method, a carriage return/line feed is written. When an object is passed as the argument, it is converted to a String using String.valueOf() .
B.4.4.4 PageContext
public abstract class PageContext extends java.lang.Object
PageContext is an abstract class to be extended for providing access to the various JSP scopes, as well as JSP utility methods. These utilities include convenience APIs for public objects, a JspWriter mechanism, session management, a way to include or forward pages, and errorpage exception processing.
public static final int APPLICATION_SCOPE public static final int PAGE_SCOPE public static final int REQUEST_SCOPE public static final int SESSION_SCOPE
The above constants represent the JSP accessible scopes.
public static final String APPLICATION public static final String CONFIG publis static final String EXCEPTION public static final String OUT public static final String PAGE public static final String PAGECONTEXT public static final String REQUEST public static final String RESPONSE
PageContext uses the above constants in an internal table.
public PageContext()
PageContext() is an empty default constructor. Because it is abstract, it can be used by subclasses of PageContext .
public abstract Object findAttribute(String name)
findAttribute() looks for the specified attribute in the page, request, session, and application scopes (in that order). It returns the value as an object or returns null if the attribute name is not found.
public abstract void forward(String relativeURLPath) throws javax.servlet.ServletException, java.io.IOException
forward() redirects the current ServletRequest and Servlet-Response to the application component at the specified URL.
getAttribute(String name) throws NullPointerException
getAttribute() returns the object associated with the name in the page scope. It returns null if it is not found.
public abstract Object getAttribute(String name, int scope) throws NullPointerException, java.lang.IllegalArgumenttException
getAttribute() returns the object associated with the name in the specified scope and returns null if it is not found. The page scope is searched when no scope is specified. Use the constants defined for scope as the argument.
public abstract java.util.Enumeration getAttributeNamesInScope(int scope)
getAttributeNamesInScope() returns an enumeration of names of all of the attributes in the specified scope.
public abstract int getAttributesScope(String name)
getAttributesScope() returns the scope of the specified attribute. is returned if the attribute is not found.
public abstract java.lang.Exception getException()
getException() returns any exception passed to the method as an errorpage .
public abstract javax.servlet.jsp.JspWriter getOut()
getOut() returns the current JspWriter stream object used to generate the client response.
public abstract java.lang.Object getPage()
getPage() returns the Page implementation class instance associated with the current PageContext .
public abstract javax.servlet.ServletRequest getRequest()
getRequest() returns the ServletRequest object for the current PageContext .
public abstract javax.servlet.ServletResponse getResponse()
getResponse() returns the ServletResponse object for the current PageContext .
public abstract javax.servlet.ServletConfig getServletConfig()
getServletConfig() returns the ServletConfig object for the current PageContext .
public abstract javax.servlet.ServletContext getServletContext()
getServletContext() returns the ServletConfig object for the current PageContext .
public abstract javax.servlet.http.HttpSession getSession()
getSession() returns the HttpSession object for the current PageContext . It returns null if no session is active in this context.
public abstract void handlePageException(java.lang.Exception e) throws javax.servlet.ServletException, java.io.IOException
handlePageException() processes exceptions at the page level. The exception can be redirected to the specified error page for this JSP or by performing an implementation-dependent action inside the method itself.
public abstract void include(java.lang.String relativeUrlPath) throws javax.servlet.ServletException, java.lang.SecurityException, java.lang.IllegalArgumentException, java.io.IOException
include() causes the specified resource at the relative URL to be included as part of the ServletRequest and ServletResponse . The current JspWriter "out" is flushed prior to processing the include.
public abstract void initialize(javax.servlet.Servlet servlet, javax.servlet.ServletRequest req, javax.servlet.ServletResponse res, java.lang.String errorPageURL, boolean needsSession, throws java.io.IOException, java.lang.IllegalStateException, java.lang.IllegalArgumentException)
initialize() initializes an unitialized PageContext object. The errorPageURL represents the errorPageURL of this JSP. It can be set to null . If the JSP is participating in a session, needsSession is true . This method is typically called by JspFactory.getPageContext() to initialize state.
public abstract JspWriter popBody()
popBody() returns the previous JspWriter "out" saved by a previous call to the corresponding pushBody() , and it updates the value of the "out" attribute in the page scope attribute namespace.
public abstract BodyJspWriter pushBody()
pushBody() returns a new BodyContent object, saves the current JspWriter object, and updates the "out" attribute in the page scope attribute namespace.
public abstract void release()
release() resets the internal state of the PageContext by releasing all internal references and readying the PageContext for use. It is typically called from the releasePageContext() method of the JspFactory .
public abstract void removeAttribute(String name)
removeAttribute() removes the object reference associated with the specified name.
public abstract void removeAttribute(String name, int scope)
removeAttribute() removes the object reference associated with the specified name and in the specified scope.
public abstract void setAttribute(String name, Object attrib) throws NullPointerException
setAttribute() stores the attribute name and associate object in the page scope.
public abstract void setAttribute(String name, Object obj, int scope) throws NullPointerException, java.lang.IllegalArgumentException
setAttribute() stores the attribute name and associate object in the specified scope.
B.4.4.5 javax.servlet.jsp EXCEPTIONS
public class JspError extends JspException public class JspError(String msg)
When caught, the JspError exception stops generation and forwards the exception to the errorpage.
public JspException() public JspException(String msg) public JspException(String msg, Throwable cause) public JspException(Throwable cause)
JspException() is a constructor that returns no value.
B.4.5 javax.servlet.jsp. tagext Interfaces
javax.servlet.jsp.tagext is the package that provides classes and interfaces to support definition of JSP tag libraries.
B.4.5.1 Tag
public interface Tag
Tag is the interface to be implemented by a Tag handler class. It provides life cycle methods.
public int doEndTag() throws JspException
doEndTag() processes the custom tag's end tag. It returns EVAL_PAGE to continue processing or SKIP_PAGE to skip processing the remainder of the page.
public int doStartTag() throws JspException
doStartTag() processes the custom tag's start tag. It returns EVAL_BODY_INCLUDE or BodyTag .
public static final int EVAL_BODY_INCLUDE
EVAL_BODY_INCLUDE indicates that the tag body should be evaluated into the output stream.
public static final int EVAL_PAGE
EVAL_PAGE indicates that the evaluation of the page should continue.
public tag getParent()
getParent() returns the parent tag of the current tag.
public void release()
release() releases the tag handler once it has been used.
public void setPageContext(PageContext pc)
setPageContext() specifies the current PageContext . It is called before calling doStartTag() .
public void setParent(Tag t)
setParent() specifies the parent Tag of the current Tag .
public static final int SKIP_BODY
SKIP_BODY indicates that the tag body should not be evaluated into the output stream.
public static final int SKIP_PAGE
SKIP_PAGE indicates that the remainder of the page should be skipped and not processed.
B.4.5.2 IterationTag
public interface IterationTag extends Tag
IterationTag is the interface to be implemented by the Tag handler class when creating an iteration tag.
public static final int EVAL_BODY_AGAIN
EVAL_BODY_AGAIN indicates that the tag body should be evaluated again.
public int doAfterBody() throws JspException
doAfterBody() gets called after the content of the tag body has been processed. It returns EVAL_BODY_AGAIN to submit another evaluation of the tag body and SKIP_BODY to submit that no further processing of the tag body should occur.
B.4.5.3 BodyTag
public interface BodyTag extends IterationTag
public static final int EVAL_BODY_BUFFERED indicates that a new BodyContent object should be created for evaluation of the body content.
public void doInitBody() throws JspException
doInitBody() is called before evaluation of the tag's body to initialize it.
public void setBodyContent(BodyContent b)
setBodyContent() sets the BodyContent object to be used with the evaluation of the tag's body.
B.4.5.4 TryCatchFinally
public interface TryCatchFinally
TryCatchFinally is implemented by a tag handler requiring extra exception handling.
public void doCatch(Throwable t) throws Throwable
doCatch() is called if a Throwable exception occurs within a tag body or in any of the following methods: Tag.doStartTag() , Tag.doEndTag() , IterationTag.doAfterBody() , or BodyTag.doInitBody( ).
public void doFinally()
doFinally() is invoked after every invocation of doEndTag() for any tag handler class that implements Tag , IterationTag , or BodyTag .
B.4.6 javax.servlet.jsp.tagext Classes
B.4.6.1 BodyContent
public abstract class BodyContent extends JspWriter
BodyContent extends the ability of JspWriter , allowing body evaluations to be processed and accessed.
protected BodyContent(JspWriter e)
This constructor is called by the generated servlet.
public void clearBody()
clearBody() clears the body associated with the invoking BodyContent object.
public void flush() throws java.io.IOException
flush() overrides JspWriter 's flush() method; no BodyContent object may flush.
public JspWriter getEnclosingWriter()
getEnclosingWriter() returns the JspWriter that encloses this BodyContent object.
public abstract java.io.Reader getReader()
getReader() returns the result of the body evaluation as a java.io.Reader .
public abstract void writeOut(java.io.Writer out) throws java.io.IOException
writeOut() writes the body content to the "out" stream specified.
B.4.6.2 BodyTagSupport
public class BodyTagSupport extends TagSupport implements BodyTag
BodyTag extends TagSupport , providing a base class for body tag handlers.
protected BodyContent bodyContent
bodyContent references the current BodyContent object.
public BodyTagSupport()
The BodyTagSupport() constructor creates a BodyTagSupport object. Subclasses of BodyTagSupport must provide a no-arg constructor that calls this constructor.
public int doAfterBody() throws JspException
doAfterBody() returns SKIP_BODY . It should be overridden if necessary.
public in doEndTag() throws JspException
doEndTag() returns EVAL_PAGE . It should be overridden if necessary.
public void doInitBody()
doInitBody() does nothing. It should be overridden if necessary.
public int doStartTag() throws JspException
doStartTag() returns EVAL_BODY_BUFFERED . It should be overriden if necessary.
public BodyContent getBodyContent()
getBodyContent() returns the BodyContent object for this tag handler.
public JspWriter getPreviousOut()
getPreviousOut() returns the enclosing JspWriter object.
public void release()
release() resets the tag handler's state.
public void setBodyContent(BodyContent b)
setBodyContent() stores the BodyContent object to be used in conjunction with the tag body's evaluation.
B.4.6.3 BodyJspWriter
public abstract class BodyJspWriter extends JspWriter
BodyJspWriter is a subclass of JspWriter , and it can be used for processing body evaluations.
protected BodyJspWriter(int buffersize, boolean autoflush)
B.4.6.4 PageData
public abstract class PageData extends java.lang.Object
A PageData object contains translation-time information about a JSP's XML document form.
public PageData()
A PageData() constructor takes no arguments.
public abstract java.io.InputStream getInputStream()
getInputStream() returns an InputStream that can make the XML document form of the JSP accessible.
B.4.6.5 TagAttributeInfo
public class TagAttributeInfo extends java.lang.Object
A TagAttributeInfo object represents a tag attribute at translation time.
public static final String ID
ID represents the ID.
public TagAttributeInfo(String name, boolean required, String type, boolean reqTime)
TagAttributeInfo() creates a TagAttributeInfo object. reqTime returns true if the attribute can be a request-time attribute.
public boolean canBeRequestTime()
canBeRequestTime() returns true if the attribute can hold a request-time value.
public static TagAttributeInfo getIdAttribute(TagAttributeInfo[] a)
getIdAttribute() is a convenience method that retrieves the ID from an array of TagAttributeInfo objects.
public String getName()
getName() returns the attribute name.
public String getTypeName()
getTypeName() returns the name of the attribute type.
public boolean isRequired()
isRequired() returns true if the attribute is required.
public String toString()
toString() returns a String representation of the TagAttributeInfo object.
B.4.6.6 TagData
public class TagData extends Object implements Cloneable
A TagData object contains the name-value pairs of the attributes associated with a tag at translation time.
public Object getAttribute(String attrName)
getAttribute() returns the value of the specified attribute.
public java.util.Enumeration getAttributes()
getAttributes() returns an enumeration containing all the attributes of this tag.
public String getAttributeString()
getAttirbuteString() returns the value of the specified attribute as a String .
public String getID()
getId() returns the value of the id attribute. If it does not exist, it returns null .
public static final Object REQUEST_TIME_VALUE
REQUEST_TIME_VALUE represents an attribute value that is a runtime expression. It is therefore not known at translation time.
public void setAttribute(String attName, Object value)
setAttribute() sets the value of the attribute specified.
public TagData(Object[][] attrs) public TagData(java.util.Hashtable attrs)
TagData() creates a TagData object. The name-value pairs representing the attributes of the TagData can be provided as a two-dimensional Object array or as a Hashtable .
B.4.6.7 TagExtraInfo
public abstract class TagExtraInfo extends Object
A TagExtraInfo object contains extra information regarding a custom tag.
public TagExtraInfo()
This class is abstract. Subclasses may call this constructor.
public final TagInfo getTagInfo()
getTagInfo() returns the TagInfo object associated with the Tag-ExtraInfo object.
public VariableInfo[] getVariableInfo(TagData data)
getVariableInfo() returns an array of VariableInfo objects containing information on scripting variables defined by the tag.
public boolean isValid(TagData data)
isValid() returns true if the attributes associated with the specified TagData object are valid at translation time. Request-time attributes are indicated.
public final void setTagInfo(TagInfo tagInfo)
setTagInfo() sets the TagInfo object that is associated with the invoking TagExtraInfo object.
B.4.6.8 TagInfo
public class TagInfo extends java.lang.Object
A TagInfo object contains any information associated with a custom tag.
public static final String BODY_CONTENT_JSP public static final String BODY_CONTENT_TAG_DEPENDENT public static final String BODY_CONTENT_EMPTY
The above constants denote JSP, tag dependent, or empty tag body content.
public TagInfo(String tagName, String tagClassName, String bodyContent, String infoString, TagLibraryInfo taglib, TagExtraInfo, tagExtraInfo, TagAttributeInfo[] attribInfo, String displayName, String smallIcon, String largeIcon, TagVariableInfo[] tvi)
TagInfo creates a TagInfo object from the information contained in a JSP 1.2 format TLD. Another signature is used for creating the object from a JSP 1.1 format TLD (that signature is the same, except without all of the arguments following attributeInfo ). The tagName is the name of the tag, tagClass is the name of the tag handler class, the bodyContent has information about the body content in the form of one of the constants, and infoString is optional.
public String getTagName()
getTagName() returns the tag name.
public TagAttributeInfo[] getAttributes()
getAttributes() returns an array of TagAttributeInfo objects that contain information on the tag's attributes.
public VariableInfo[] getVariableInfo(TagData data)
getVariableInfo() returns an array of VariableInfo objects that contain information on the scripting objects that are created by the tag at runtime.
public boolean isValid(TagData data)
isValid() returns true if the attributes associated with the specified TagData object are valid at translation time.
public void setTagExtraInfo(TagExtraInfo tei)
setTagExtraInfo() sets extra information for the tag.
public TagExtraInfo getTagExtraInfo()
getTagExtraInfo() returns the TagExtraInfo object associated with the tag.
public String getTagClassName()
getTagClassName() returns the name of the tag handler class.
public String getBodyContent()
getBodyContent() returns a string of information regarding the body content.
public String getInfoString()
getInfoString() returns the information string associated with the tag.
public void setTagLibrary(TagLibraryInfo tl)
setTagLibrary() sets the TagLibraryInfo object associated with the tag.
public TagLibraryInfo getTagLibrary()
getTagLibrary() returns the TagLibraryInfo object associated with the tag.
public String getDisplayName()
getDisplayName() returns the display name of the tag.
public String getSmallIcon()
getSmallIcon() returns the path to the tag's small icon.
public String getLargeIcon()
getLargeIcon() returns the path to the tag's large icon.
public TagVariableInfo[] getTagVariableInfos()
getTagVariableInfos() returns the array of TagVariableInfo objects associated with the tag.
public String toString()
toString() returns a String representation of the invoking TagInfo object.
B.4.6.9 TagLibraryInfo
public abstract class TagLibraryInfo extends Object
A TagLibraryInfo object contains information about the tag library associated with a tag.
protected String prefix protected String uri protected TagInfo[] tags protected String tlibversion protected String jspversion protected String shortname protected String urn protected String info
These instance variables hold information regarding the tag library.
protected TagLibraryInfo(String prefix, String uri)
This creates a TagLibraryInfo object.
public String getURI()
getURI() returns a string containing the URI as shown in the taglib directive for this library.
public String getShortName()
getShortName() returns the short name for this library.
public String getReliableURN()
getReliableURN() returns a reliable URN for this library.
public String getInfoString()
getInfoString() returns the information string associated with this library.
public String getRequiredVersion()
getRequiredVersion() returns the required version of the JSP container.
public TagInfo[] getTags()
getTags() returns an array of TagInfo objects containing information about all of the tags in the library.
public TagInfo getTag(String shortname)
getTag() returns a TagInfo object for the tag specified by its short name.
B.4.6.10 TagLibraryValidator
public abstract class TagLibraryValidator extends Object
A TagLibraryValidator performs translation-time validation for a tag library.
public TagLibraryValidator()
This is an abstract class, so this constructor is not generally directly called.
public void setInitParameters(java.util.Map map)
setInitParameters() sets the initialization parameters for the TagLibraryValidator .
public java.util.Map getInitParameters()
getInitParameters() returns the initialization parameters for the TagLibraryValidator .
public String validate(String prefix, String uri, PageData page)
validate() validates a JSP. It returns an error message; if there were no errors, it returns null .
public void release()
release() releases any data held by the TagLibraryValidator .
B.4.6.11 TagSupport
public class TagSupport extends Object implements IterationTag, java.io.Serializable
The TagSupport class provides a convenient implementation of the IterationTag interface.
protected String id protected PageContext pageContext
TagSupport uses these instance variables to store the id and PageContext associated with this tag.
public TagSupport()
This creates a TagSupport object. Subclasses must provide a no-arg constructor that calls this constructor.
public static final Tag findAncestorWithClass(Tag from, Class c)
findAncestorWithClass() uses Tag 's getParent() method to find the instance of a given tag class that is closest to this tag.
public int doStartTag() throws JspException
doStartTag() returns SKIP_BODY . It should be overridden if necessary.
public int doEndTag() throwsJspException
doEndTag() returns EVAL_PAGE . It should be overridden if necessary.
public int doAfterBody() throws JspException
doAfterBody() does nothing. It should be overridden if necessary.
public void release()
release() resets the tag state.
public void setParent(Tag t)
setParent() sets the parent tag of this tag.
public tag getParent()
getParent() returns the parent tag of this tag.
public void setId(String id)
setId() sets the value of the id attribute to String .
public String getID()
getId() returns the value of the id attribute.
public void setPageContext(PageContext pc)
setPageContext() specifies the PageContext object associated with the tag.
public void setValue(String k, Object o)
setValue() sets the value of the attribute specified.
public Object getValue(String k)
getValue() returns the value of the attribute specified.
public void removeValue(String k)
removeValue() removes the specified attribute from the tag.
public java.util.Enumeration getValues()
getValues() returns an enumeration of all tag attributes.
B.4.6.12 TagVariableInfo
public class TagVariableInfo extends Object
A TagVariableInfo object holds translation-time variable information, which it accesses from the Tag Library Descriptor (TLD).
public TagVariableInfo(String nameGiven, String nameFromAttribute, String className, boolean declare, int scope)
The constructor creates a TagVariableInfo object based on the TLD.
pubic String getNameGiven()
getNameGiven() returns the value of the <name-given> element in the TLD.
public String getNameFromAttribute()
getNameFromAttribute() returns the value of the <name-from-attribute> element of the TLD.
public String getClassName()
getClassName() returns the value of the <variable-class> element of the TLD.
public boolean getDeclare()
getDeclare() returns the value of the <declare> element of the TLD.
public int getScope()
getScope() returns the value of the <scope> element of the TLD.
B.4.6.13 VariableInfo
public class VariableInfo extends Object
At runtime, a tag creates certain scripting variables. The VariableInfo object holds this data.
public static final int NESTED public static final int AT_BEGIN public static final int AT_END
The above constants define scopes available to scripting variables. NESTED defines a variable as visible within the start and end tags. AT_BEGIN defines a variable as visible after the start tag. AT_END defines a variable as visible after the end tag.
public VariableInfo(String varName, String className, boolean declare, int scope)
This creates a VariableInfo object. If the variable is new, it may require declaration, which is indicated by setting the declare parameter to true .
public String getVarName()
getVarName() returns the scripting variable name.
public String getClassName()
getClassName() returns the scripting variable class name.
public boolean getDeclare()
getDeclare() returns true if the variable is new, as it may then need a declaration.
public int getScope()
getScope() returns the scripting variable scope.
| |
| Top |
EAN: 2147483647
Pages: 206