javax.servlet.jsp

The javax.servlet.jsp package contains a number of classes and interfaces that describe and define the contracts between a JSP page implementation class and the runtime environment provided for an instance of such a class by a conforming JSP container.

JSP Page Implementation Object Contract

This section describes the basic contract between a JSP Page implementation object and its container.

The main contract is defined by the classes {@link javax.servlet.jsp.JspPage} and {@link javax.servlet.jsp.HttpJspPage}. The {@link javax.servlet.jsp.JspFactory} class describes the mechanism to portably instantiate all needed runtime objects, and {@link javax.servlet.jsp.JspEngineInfo} provides basic information on the current JSP container. Class {@link javax.servlet.jsp.JspApplicationContext} stores application-scoped information relevant to JSP containers. It was added in JSP 2.1 to support the integration of the unified Expression Language.

None of these classes are intended to be used by JSP page authors; an example of how these classes may be used is included below.

Implicit Objects

Exceptions

The {@link javax.servlet.jsp.JspException} class is the base class for all JSP exceptions. The {@link javax.servlet.jsp.JspTagException} and {@link javax.servlet.jsp.SkipPageException} exceptions are used by the tag extension mechanism.

An Implementation Example

An instance of an implementation dependent subclass of the {@link javax.servlet.jsp.PageContext} abstract base class can be created by a JSP implementation class at the beginning of it's _jspService() method via an implementation default {@link javax.servlet.jsp.JspFactory}.

Here is one example of how to use these classes

 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);
    }
}

JspContext serves as the base class for the PageContext class and abstracts all information that is not specific to servlets.

The JspFactory is an abstract class that defines a number of factory methods available to a JSP page at runtime for the purposes of creating instances of various interfaces and classes used to support the JSP implementation.

Two plus One Methods

The interface defines a protocol with 3 methods; only two of them: jspInit() and jspDestroy() are part of this interface as the signature of the third method: _jspService() depends on the specific protocol used and cannot be expressed in a generic way in Java.

A class implementing this interface is responsible for invoking the above methods at the appropriate time based on the corresponding Servlet-based method invocations.

The jspInit() and jspDestroy() methods can be defined by a JSP author, but the _jspService() method is defined automatically by the JSP processor based on the contents of the JSP page.

_jspService()

The _jspService()method corresponds to the body of the JSP page.

The actions and template data in a JSP page is written using the JspWriter object that is referenced by the implicit variable out which is initialized automatically using methods in the PageContext object.

This abstract class emulates some of the functionality found in the java.io.BufferedWriter and java.io.PrintWriter classes, however it differs in that it throws java.io.IOException from the print methods while PrintWriter does not.

Buffering

The initial JspWriter object is associated with the PrintWriter object of the ServletResponse in a way that depends on whether the page is or is not buffered.

PageContext extends JspContext to provide useful context information for when JSP technology is used in a Servlet environment.

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.