javax.servlet.jsp

Class PageContext


public abstract class PageContext
extends java.lang.Object

A PageContext instance provides access to all the namespaces associated with a JSP page, provides access to several page attributes, as well as a layer above the implementation details.

An instance of an implementation dependent subclass of this abstract base class is created by a JSP implementation class at the begining of it's _jspService() method via an implementation default JspFactory , as follows:

 public class foo implements Servlet {

 // ...

public void _jspService(HttpServletRequest request,
			HttpServletResponse response)
       throws IOException, ServletException {

    JspFactory  factory     = JspFactory.getDefaultFactory();
    PageContext pageContext = factory.getPageContext(
this,
request,
response,
null,  // errorPageURL
false, // needsSession
JspWriter.DEFAULT_BUFFER,
true   // autoFlush
);

    // initialize implicit variables for scripting env ...

    HttpSession session = pageContext.getSession();
    JspWriter   out     = pageContext.getOut();
    Object      page    = this;

    try {
        // body of translated JSP here ...
    } catch (Exception e) {
        out.clear();
        pageContext.handlePageException(e);
    } finally {
        out.close();
	  factory.releasePageContext(pageContext);
    }
}

The PageContext class is an abstract class, designed to be extended to provide implementation dependent implementations thereof, by conformant JSP engine runtime environments. A PageContext instance is obtained by a JSP implementation class by calling the JspFactory.getPageContext() method, and is released by calling JspFactory.releasePageContext().

The PageContext provides a number of facilities to the page/component author and page implementor, including:

  • a single API to manage the various scoped namespaces
  • a number of convenience API's to access various public objects
  • a mechanism to obtain the JspWriter for output
  • a mechanism to manage session usage by the page
  • a mechanism to expose page directive attributes to the scripting environment
  • mechanisms to forward or include the current request to other active components in the application
  • a mechanism to handle errorpage exception processing
  • Field Summary

    static String
    APPLICATION
    name used to store ServletContext in PageContext name table
    static int
    APPLICATION_SCOPE
    application scope: named reference remains available in the ServletContext until it is reclaimed.
    static String
    CONFIG
    name used to store ServletConfig in PageContext name table
    static String
    EXCEPTION
    name used to store uncaught exception in ServletRequest attribute list and PageContext name table
    static String
    OUT
    name used to store current JspWriter in PageContext name table
    static String
    PAGE
    name used to store the Servlet in this PageContext's nametables
    static String
    PAGECONTEXT
    name used to store this PageContext in it's own name tables
    static int
    PAGE_SCOPE
    page scope: (this is the default) the named reference remains available in this PageContext until the return from the current Servlet.service() invocation.
    static String
    REQUEST
    name used to store ServletRequest in PageContext name table
    static int
    REQUEST_SCOPE
    request scope: the named reference remains available from the ServletRequest associated with the Servlet that until the current request is completed.
    static String
    RESPONSE
    name used to store ServletResponse in PageContext name table
    static String
    SESSION
    name used to store HttpSession in PageContext name table
    static int
    SESSION_SCOPE
    session scope (only valid if this page participates in a session): the named reference remains available from the HttpSession (if any) associated with the Servlet until the HttpSession is invalidated.

    Method Summary

    Object
    findAttribute(String name)
    Searches for the named attribute in page, request, session (if valid), and application scope(s) in order and returns the value associated or null.
    void
    forward(String relativeUrlPath)
    This method is used to re-direct, or "forward" the current ServletRequest and ServletResponse to another active component in the application.
    Object
    getAttribute(String name)
    return the object associated with the name in the page scope or null
    Object
    getAttribute(String name, int scope)
    return the object associated with the name in the specifed scope or null
    Enumeration
    getAttributeNamesInScope(int scope)
    int
    getAttributesScope(String name)
    Exception
    getException()
    JspWriter
    getOut()
    Object
    getPage()
    ServletRequest
    getRequest()
    ServletResponse
    getResponse()
    ServletConfig
    getServletConfig()
    ServletContext
    getServletContext()
    HttpSession
    getSession()
    void
    handlePageException(Exception e)
    This method is intended to process an unhandled "page" level exception by redirecting the exception to either the specified error page for this JSP, or if none was specified, to perform some implementation dependent action.
    void
    include(String relativeUrlPath)
    Causes the resource specified to be processed as part of the current ServletRequest and ServletResponse being processed by the calling Thread.
    void
    initialize(Servlet servlet, ServletRequest request, ServletResponse response, String errorPageURL, boolean needsSession, int bufferSize, boolean autoFlush)
    The initialize emthod is called to initialize an uninitialized PageContext so that it may be used by a JSP Implementation class to service an incoming request and response wihtin it's _jspService() method.
    JspWriter
    popBody()
    Return the previous JspWriter "out" saved by the matching pushBody(), and update the value of the "out" attribute in the page scope attribute namespace of the PageConxtext
    BodyContent
    pushBody()
    Return a new BodyContent object, save the current "out" JspWriter, and update the value of the "out" attribute in the page scope attribute namespace of the PageContext
    void
    release()
    This method shall "reset" the internal state of a PageContext, releasing all internal references, and preparing the PageContext for potential reuse by a later invocation of initialize().
    void
    removeAttribute(String name)
    remove the object reference associated with the specified name
    void
    removeAttribute(String name, int scope)
    remove the object reference associated with the specified name
    void
    setAttribute(String name, Object attribute)
    register the name and object specified with page scope semantics
    void
    setAttribute(String name, Object o, int scope)
    register the name and object specified with appropriate scope semantics

    Field Details

    APPLICATION

    public static final String APPLICATION
    name used to store ServletContext in PageContext name table


    APPLICATION_SCOPE

    public static final int APPLICATION_SCOPE
    application scope: named reference remains available in the ServletContext until it is reclaimed.

    Field Value:
    4


    CONFIG

    public static final String CONFIG
    name used to store ServletConfig in PageContext name table


    EXCEPTION

    public static final String EXCEPTION
    name used to store uncaught exception in ServletRequest attribute list and PageContext name table


    OUT

    public static final String OUT
    name used to store current JspWriter in PageContext name table


    PAGE

    public static final String PAGE
    name used to store the Servlet in this PageContext's nametables


    PAGECONTEXT

    public static final String PAGECONTEXT
    name used to store this PageContext in it's own name tables


    PAGE_SCOPE

    public static final int PAGE_SCOPE
    page scope: (this is the default) the named reference remains available in this PageContext until the return from the current Servlet.service() invocation.

    Field Value:
    1


    REQUEST

    public static final String REQUEST
    name used to store ServletRequest in PageContext name table


    REQUEST_SCOPE

    public static final int REQUEST_SCOPE
    request scope: the named reference remains available from the ServletRequest associated with the Servlet that until the current request is completed.

    Field Value:
    2


    RESPONSE

    public static final String RESPONSE
    name used to store ServletResponse in PageContext name table


    SESSION

    public static final String SESSION
    name used to store HttpSession in PageContext name table


    SESSION_SCOPE

    public static final int SESSION_SCOPE
    session scope (only valid if this page participates in a session): the named reference remains available from the HttpSession (if any) associated with the Servlet until the HttpSession is invalidated.

    Field Value:
    3

    Method Details

    findAttribute

    public Object findAttribute(String name)
    Searches for the named attribute in page, request, session (if valid), and application scope(s) in order and returns the value associated or null.

    Returns:
    the value associated or null


    forward

    public void forward(String relativeUrlPath)
                throws ServletException,
                       IOException
    This method is used to re-direct, or "forward" the current ServletRequest and ServletResponse to another active component in the application.

    If the relativeUrlPath begins with a "/" then the URL specified is calculated relative to the DOCROOT of the ServletContext for this JSP. If the path does not begin with a "/" then the URL specified is calculated relative to the URL of the request that was mapped to the calling JSP.

    It is only valid to call this method from a Thread executing within a _jspService(...) method of a JSP.

    Once this method has been called successfully, it is illegal for the calling Thread to attempt to modify the ServletResponse object. Any such attempt to do so, shall result in undefined behavior. Typically, callers immediately return from _jspService(...) after calling this method.

    Parameters:
    relativeUrlPath - specifies the relative URL path to the target resource as described above

    Throws:
    ServletException -


    getAttribute

    public Object getAttribute(String name)
    return the object associated with the name in the page scope or null

    Parameters:
    name - the name of the attribute to get


    getAttribute

    public Object getAttribute(String name,
                               int scope)
    return the object associated with the name in the specifed scope or null

    Parameters:
    name - the name of the attribute to set
    scope - the scope with which to associate the name/object


    getAttributeNamesInScope

    public Enumeration getAttributeNamesInScope(int scope)

    Returns:
    an enumeration of names (java.lang.String) of all the attributes the specified scope


    getAttributesScope

    public int getAttributesScope(String name)

    Returns:
    the scope of the object associated with the name specified or 0


    getException

    public Exception getException()

    Returns:
    any exception passed to this as an errorpage


    getOut

    public JspWriter getOut()

    Returns:
    the current JspWriter stream being used for client response


    getPage

    public Object getPage()

    Returns:
    the Page implementation class instance (Servlet) associated with this PageContext


    getRequest

    public ServletRequest getRequest()

    Returns:
    The ServletRequest for this PageContext


    getResponse

    public ServletResponse getResponse()

    Returns:
    the ServletResponse for this PageContext


    getServletConfig

    public ServletConfig getServletConfig()

    Returns:
    the ServletConfig for this PageContext


    getServletContext

    public ServletContext getServletContext()

    Returns:
    the ServletContext for this PageContext


    getSession

    public HttpSession getSession()

    Returns:
    the HttpSession for this PageContext or null


    handlePageException

    public void handlePageException(Exception e)
                throws ServletException,
                       IOException
    This method is intended to process an unhandled "page" level exception by redirecting the exception to either the specified error page for this JSP, or if none was specified, to perform some implementation dependent action.

    A JSP implementation class shall typically clean up any local state prior to invoking this and will return immediately thereafter. It is illegal to generate any output to the client, or to modify any ServletResponse state after invoking this call.

    Parameters:
    e - the exception to be handled

    Throws:
    ServletException -


    include

    public void include(String relativeUrlPath)
                throws ServletException,
                       IOException
    Causes the resource specified to be processed as part of the current ServletRequest and ServletResponse being processed by the calling Thread. The output of the target resources processing of the request is written directly to the ServletResponse output stream.

    The current JspWriter "out" for this JSP is flushed as a side-effect of this call, prior to processing the include.

    If the relativeUrlPath begins with a "/" then the URL specified is calculated relative to the DOCROOT of the ServletContext for this JSP. If the path does not begin with a "/" then the URL specified is calculated relative to the URL of the request that was mapped to the calling JSP.

    It is only valid to call this method from a Thread executing within a _jspService(...) method of a JSP.

    Parameters:
    relativeUrlPath - specifies the relative URL path to the target resource to be included

    Throws:
    ServletException -


    initialize

    public void initialize(Servlet servlet,
                           ServletRequest request,
                           ServletResponse response,
                           String errorPageURL,
                           boolean needsSession,
                           int bufferSize,
                           boolean autoFlush)
                throws IOException,
                       IllegalStateException,
                       IllegalArgumentException
    The initialize emthod is called to initialize an uninitialized PageContext so that it may be used by a JSP Implementation class to service an incoming request and response wihtin it's _jspService() method.

    This method is typically called from JspFactory.getPageContext() in order to initialize state.

    This method is required to create an initial JspWriter, and associate the "out" name in page scope with this newly created object.

    Parameters:
    servlet - The Servlet that is associated with this PageContext
    request - The currently pending request for this Servlet
    response - The currently pending response for this Servlet
    errorPageURL - The value of the errorpage attribute from the page directive or null
    needsSession - The value of the session attribute from the page directive
    bufferSize - The value of the buffer attribute from the page directive
    autoFlush - The value of the autoflush attribute from the page directive


    popBody

    public JspWriter popBody()
    Return the previous JspWriter "out" saved by the matching pushBody(), and update the value of the "out" attribute in the page scope attribute namespace of the PageConxtext

    Returns:
    the saved JspWriter.


    pushBody

    public BodyContent pushBody()
    Return a new BodyContent object, save the current "out" JspWriter, and update the value of the "out" attribute in the page scope attribute namespace of the PageContext

    Returns:
    the new BodyContent


    release

    public void release()
    This method shall "reset" the internal state of a PageContext, releasing all internal references, and preparing the PageContext for potential reuse by a later invocation of initialize(). This method is typically called from JspFactory.releasePageContext().

    subclasses shall envelope this method


    removeAttribute

    public void removeAttribute(String name)
    remove the object reference associated with the specified name


    removeAttribute

    public void removeAttribute(String name,
                                int scope)
    remove the object reference associated with the specified name


    setAttribute

    public void setAttribute(String name,
                             Object attribute)
    register the name and object specified with page scope semantics


    setAttribute

    public void setAttribute(String name,
                             Object o,
                             int scope)
    register the name and object specified with appropriate scope semantics

    Parameters:
    name - the name of the attribute to set
    o - the object to associate with the name
    scope - the scope with which to associate the name/object


    Copyright © 1999-2000 The Apache Software Foundation. All Rights Reserved.