PageContext


1   /*
2   * Licensed to the Apache Software Foundation (ASF) under one or more
3   * contributor license agreements.  See the NOTICE file distributed with
4   * this work for additional information regarding copyright ownership.
5   * The ASF licenses this file to You under the Apache License, Version 2.0
6   * (the "License"); you may not use this file except in compliance with
7   * the License.  You may obtain a copy of the License at
8   *
9   *     http://www.apache.org/licenses/LICENSE-2.0
10  *
11  * Unless required by applicable law or agreed to in writing, software
12  * distributed under the License is distributed on an "AS IS" BASIS,
13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14  * See the License for the specific language governing permissions and
15  * limitations under the License.
16  */
17   
18  package javax.servlet.jsp;
19  
20  import java.io.IOException  ;
21  
22  import javax.servlet.Servlet  ;
23  import javax.servlet.ServletConfig  ;
24  import javax.servlet.ServletContext  ;
25  import javax.servlet.ServletException  ;
26  import javax.servlet.ServletRequest  ;
27  import javax.servlet.ServletResponse  ;
28  
29  import javax.servlet.http.HttpSession  ;
30  
31  import javax.servlet.jsp.tagext.BodyContent  ;
32  
33  /**
34   * <p>
35   * PageContext extends JspContext to provide useful context information for
36   * when JSP technology is used in a Servlet environment.
37   * <p>
38   * A PageContext instance provides access to all the namespaces associated
39   * with a JSP page, provides access to several page attributes, as well as
40   * a layer above the implementation details.  Implicit objects are added
41   * to the pageContext automatically.
42   *
43   * <p> The <code> PageContext </code> class is an abstract class, designed to be
44   * extended to provide implementation dependent implementations thereof, by
45   * conformant JSP engine runtime environments. A PageContext instance is 
46   * obtained by a JSP implementation class by calling the
47   * JspFactory.getPageContext() method, and is released by calling
48   * JspFactory.releasePageContext().
49   *
50   * <p> An example of how PageContext, JspFactory, and other classes can be
51   * used  within a JSP Page Implementation object is given elsewhere.
52   *
53   * <p>
54   * The PageContext provides a number of facilities to the page/component 
55   * author and page implementor, including:
56   * <ul>
57   * <li>a single API to manage the various scoped namespaces
58   * <li>a number of convenience API's to access various public objects
59   * <li>a mechanism to obtain the JspWriter for output
60   * <li>a mechanism to manage session usage by the page
61   * <li>a mechanism to expose page directive attributes to the scripting 
62   *     environment
63   * <li>mechanisms to forward or include the current request to other active 
64   *     components in the application
65   * <li>a mechanism to handle errorpage exception processing
66   * </ul>
67   *
68   * <p><B>Methods Intended for Container Generated Code</B>
69   * <p>Some methods are intended to be used by the code generated by the
70   * container, not by code written by JSP page authors, or JSP tag library 
71   * authors.
72   * <p>The methods supporting <B>lifecycle</B> are <code>initialize()</code>
73   * and <code>release()</code>
74   *
75   * <p>
76   * The following methods enable the <B>management of nested</B> JspWriter 
77   * streams to implement Tag Extensions: <code>pushBody()</code>
78   *
79   * <p><B>Methods Intended for JSP authors</B>
80   * <p>
81   * The following methods provide <B>convenient access</B> to implicit objects:
82   * <code>getException()</code>,  <code>getPage()</code>
83   * <code>getRequest()</code>,  <code>getResponse()</code>,
84   * <code>getSession()</code>,  <code>getServletConfig()</code>
85   * and <code>getServletContext()</code>.
86   *
87   * <p>
88   * The following methods provide support for <B>forwarding, inclusion
89   * and error handling</B>:
90   * <code>forward()</code>,  <code>include()</code>,
91   * and  <code>handlePageException()</code>.
92   */
93  
94  abstract public class PageContext 
95      extends JspContext  
96  {
97      
98      /**
99       * Sole constructor. (For invocation by subclass constructors, 
100      * typically implicit.)
101      */
102     public PageContext() {
103     }
104     
105     /**
106      * Page scope: (this is the default) the named reference remains available
107      * in this PageContext until the return from the current Servlet.service()
108      * invocation.
109      */
110 
111     public static final int PAGE_SCOPE      = 1;
112 
113     /**
114      * Request scope: the named reference remains available from the 
115      * ServletRequest associated with the Servlet until the current request 
116      * is completed.
117      */
118 
119     public static final int REQUEST_SCOPE   = 2;
120 
121     /**
122      * Session scope (only valid if this page participates in a session):
123      * the named reference remains available from the HttpSession (if any)
124      * associated with the Servlet until the HttpSession is invalidated.
125      */
126 
127     public static final int SESSION_SCOPE   = 3;
128 
129     /**
130      * Application scope: named reference remains available in the 
131      * ServletContext until it is reclaimed.
132      */
133 
134     public static final int APPLICATION_SCOPE   = 4;
135 
136     /**
137      * Name used to store the Servlet in this PageContext's nametables.
138      */
139 
140     public static final String   PAGE = "javax.servlet.jsp.jspPage";
141 
142     /**
143      * Name used to store this PageContext in it's own name table.
144      */
145 
146     public static final String   PAGECONTEXT = "javax.servlet.jsp.jspPageContext";
147 
148     /**
149      * Name used to store ServletRequest in PageContext name table.
150      */
151 
152     public static final String   REQUEST = "javax.servlet.jsp.jspRequest";
153 
154     /**
155      * Name used to store ServletResponse in PageContext name table.
156      */
157 
158     public static final String   RESPONSE = "javax.servlet.jsp.jspResponse";
159 
160     /**
161      * Name used to store ServletConfig in PageContext name table.
162      */
163 
164     public static final String   CONFIG = "javax.servlet.jsp.jspConfig";
165 
166     /**
167      * Name used to store HttpSession in PageContext name table.
168      */
169 
170     public static final String   SESSION = "javax.servlet.jsp.jspSession";
171     /**
172      * Name used to store current JspWriter in PageContext name table.
173      */
174 
175     public static final String   OUT = "javax.servlet.jsp.jspOut";
176 
177     /**
178      * Name used to store ServletContext in PageContext name table.
179      */
180 
181     public static final String   APPLICATION = "javax.servlet.jsp.jspApplication";
182 
183     /**
184      * Name used to store uncaught exception in ServletRequest attribute 
185      * list and PageContext name table.
186      */
187 
188     public static final String   EXCEPTION = "javax.servlet.jsp.jspException";
189 
190     /**
191      * <p>
192      * The initialize method is called to initialize an uninitialized PageContext
193      * so that it may be used by a JSP Implementation class to service an
194      * incoming request and response within it's _jspService() method.
195      *
196      * <p>
197      * This method is typically called from JspFactory.getPageContext() in
198      * order to initialize state.
199      *
200      * <p>
201      * This method is required to create an initial JspWriter, and associate
202      * the "out" name in page scope with this newly created object.
203      *
204      * <p>
205      * This method should not be used by page  or tag library authors.
206      *
207      * @param servlet The Servlet that is associated with this PageContext
208      * @param request The currently pending request for this Servlet
209      * @param response The currently pending response for this Servlet
210      * @param errorPageURL The value of the errorpage attribute from the page 
211      *     directive or null
212      * @param needsSession The value of the session attribute from the 
213      *     page directive
214      * @param bufferSize The value of the buffer attribute from the page 
215      *     directive
216      * @param autoFlush The value of the autoflush attribute from the page 
217      *     directive
218      *
219      * @throws IOException during creation of JspWriter
220      * @throws IllegalStateException if out not correctly initialized
221      * @throws IllegalArgumentException If one of the given parameters
222      *     is invalid
223      */
224  
225     abstract public void initialize(Servlet   servlet, ServletRequest   request, 
226         ServletResponse   response, String   errorPageURL, boolean needsSession, 
227         int bufferSize, boolean autoFlush)  
228         throws IOException  , IllegalStateException  , IllegalArgumentException  ;
229 
230     /**
231      * <p>
232      * This method shall "reset" the internal state of a PageContext, releasing
233      * all internal references, and preparing the PageContext for potential
234      * reuse by a later invocation of initialize(). This method is typically
235      * called from JspFactory.releasePageContext().
236      *
237      * <p>
238      * Subclasses shall envelope this method.
239      *
240      * <p>
241      * This method should not be used by page  or tag library authors.
242      *
243      */
244 
245     abstract public void release();
246 
247     /**
248      * The current value of the session object (an HttpSession).
249      *
250      * @return the HttpSession for this PageContext or null
251      */
252 
253     abstract public HttpSession   getSession();
254 
255     /**
256      * The current value of the page object (In a Servlet environment, 
257      * this is an instance of javax.servlet.Servlet).
258      *
259      * @return the Page implementation class instance associated 
260      *     with this PageContext
261      */
262 
263     abstract public Object   getPage();
264 
265 
266     /**
267      * The current value of the request object (a ServletRequest).
268      *
269      * @return The ServletRequest for this PageContext
270      */
271 
272     abstract public ServletRequest   getRequest();
273 
274     /**
275      * The current value of the response object (a ServletResponse).
276      *
277      * @return the ServletResponse for this PageContext
278      */
279 
280     abstract public ServletResponse   getResponse();
281 
282     /**
283      * The current value of the exception object (an Exception).
284      *
285      * @return any exception passed to this as an errorpage
286      */
287 
288     abstract public Exception   getException();
289 
290     /**
291      * The ServletConfig instance.
292      *
293      * @return the ServletConfig for this PageContext
294      */
295 
296     abstract public ServletConfig   getServletConfig();
297 
298     /**
299      * The ServletContext instance.
300      * 
301      * @return the ServletContext for this PageContext
302      */
303 
304     abstract public ServletContext   getServletContext();
305 
306     /**
307      * <p>
308      * This method is used to re-direct, or "forward" the current 
309      * ServletRequest and ServletResponse to another active component in 
310      * the application.
311      * </p>
312      * <p>
313      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
314      * is calculated relative to the DOCROOT of the <code> ServletContext </code>
315      * for this JSP. If the path does not begin with a "/" then the URL 
316      * specified is calculated relative to the URL of the request that was
317      * mapped to the calling JSP.
318      * </p>
319      * <p>
320      * It is only valid to call this method from a <code> Thread </code>
321      * executing within a <code> _jspService(...) </code> method of a JSP.
322      * </p>
323      * <p>
324      * Once this method has been called successfully, it is illegal for the
325      * calling <code> Thread </code> to attempt to modify the <code>
326      * ServletResponse </code> object.  Any such attempt to do so, shall result
327      * in undefined behavior. Typically, callers immediately return from 
328      * <code> _jspService(...) </code> after calling this method.
329      * </p>
330      *
331      * @param relativeUrlPath specifies the relative URL path to the target 
332      *     resource as described above
333      *
334      * @throws IllegalStateException if <code> ServletResponse </code> is not 
335      *     in a state where a forward can be performed
336      * @throws ServletException if the page that was forwarded to throws
337      *     a ServletException
338      * @throws IOException if an I/O error occurred while forwarding
339      */
340 
341     abstract public void forward(String   relativeUrlPath) 
342         throws ServletException  , IOException  ;
343 
344     /**
345      * <p>
346      * Causes the resource specified to be processed as part of the current
347      * ServletRequest and ServletResponse being processed by the calling Thread.
348      * The output of the target resources processing of the request is written
349      * directly to the ServletResponse output stream.
350      * </p>
351      * <p>
352      * The current JspWriter "out" for this JSP is flushed as a side-effect
353      * of this call, prior to processing the include.
354      * </p>
355      * <p>
356      * If the <I> relativeUrlPath </I> begins with a "/" then the URL specified
357      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
358      * for this JSP. If the path does not begin with a "/" then the URL 
359      * specified is calculated relative to the URL of the request that was
360      * mapped to the calling JSP.
361      * </p>
362      * <p>
363      * It is only valid to call this method from a <code> Thread </code>
364      * executing within a <code> _jspService(...) </code> method of a JSP.
365      * </p>
366      *
367      * @param relativeUrlPath specifies the relative URL path to the target 
368      *     resource to be included
369      *
370      * @throws ServletException if the page that was forwarded to throws
371      *     a ServletException
372      * @throws IOException if an I/O error occurred while forwarding
373      */
374     abstract public void include(String   relativeUrlPath) 
375         throws ServletException  , IOException  ;
376 
377     /**
378      * <p>
379      * Causes the resource specified to be processed as part of the current
380      * ServletRequest and ServletResponse being processed by the calling Thread.
381      * The output of the target resources processing of the request is written
382      * directly to the current JspWriter returned by a call to getOut().
383      * </p>
384      * <p>
385      * If flush is true, The current JspWriter "out" for this JSP 
386      * is flushed as a side-effect of this call, prior to processing 
387      * the include.  Otherwise, the JspWriter "out" is not flushed.
388      * </p>
389      * <p>
390      * If the <i>relativeUrlPath</i> begins with a "/" then the URL specified
391      * is calculated relative to the DOCROOT of the <code>ServletContext</code>
392      * for this JSP. If the path does not begin with a "/" then the URL 
393      * specified is calculated relative to the URL of the request that was
394      * mapped to the calling JSP.
395      * </p>
396      * <p>
397      * It is only valid to call this method from a <code> Thread </code>
398      * executing within a <code> _jspService(...) </code> method of a JSP.
399      * </p>
400      *
401      * @param relativeUrlPath specifies the relative URL path to the 
402      *     target resource to be included
403      * @param flush True if the JspWriter is to be flushed before the include,
404      *     or false if not.
405      *
406      * @throws ServletException if the page that was forwarded to throws
407      *     a ServletException
408      * @throws IOException if an I/O error occurred while forwarding
409      * @since 2.0
410      */
411     abstract public void include(String   relativeUrlPath, boolean flush) 
412     throws ServletException  , IOException  ;
413 
414     /**
415      * <p>
416      * This method is intended to process an unhandled 'page' level
417      * exception by forwarding the exception to the specified
418      * error page for this JSP.  If forwarding is not possible (for
419      * example because the response has already been committed), an
420      * implementation dependent mechanism should be used to invoke
421      * the error page (e.g. "including" the error page instead).
422      *
423      * <p>
424      * If no error page is defined in the page, the exception should
425      * be rethrown so that the standard servlet error handling
426      * takes over.
427      *
428      * <p>
429      * A JSP implementation class shall typically clean up any local state
430      * prior to invoking this and will return immediately thereafter. It is
431      * illegal to generate any output to the client, or to modify any 
432      * ServletResponse state after invoking this call.
433      *
434      * <p>
435      * This method is kept for backwards compatiblity reasons.  Newly
436      * generated code should use PageContext.handlePageException(Throwable).
437      *
438      * @param e the exception to be handled
439      *
440      * @throws ServletException if an error occurs while invoking the error page
441      * @throws IOException if an I/O error occurred while invoking the error
442      *     page
443      * @throws NullPointerException if the exception is null
444      *
445      * @see #handlePageException(Throwable)
446      */
447 
448     abstract public void handlePageException(Exception   e) 
449         throws ServletException  , IOException  ;
450 
451     /**
452      * <p>
453      * This method is intended to process an unhandled 'page' level
454      * exception by forwarding the exception to the specified
455      * error page for this JSP.  If forwarding is not possible (for
456      * example because the response has already been committed), an
457      * implementation dependent mechanism should be used to invoke
458      * the error page (e.g. "including" the error page instead).
459      *
460      * <p>
461      * If no error page is defined in the page, the exception should
462      * be rethrown so that the standard servlet error handling
463      * takes over.
464      *
465      * <p>
466      * This method is intended to process an unhandled "page" level exception
467      * by redirecting the exception to either the specified error page for this
468      * JSP, or if none was specified, to perform some implementation dependent
469      * action.
470      *
471      * <p>
472      * A JSP implementation class shall typically clean up any local state
473      * prior to invoking this and will return immediately thereafter. It is
474      * illegal to generate any output to the client, or to modify any 
475      * ServletResponse state after invoking this call.
476      *
477      * @param t the throwable to be handled
478      *
479      * @throws ServletException if an error occurs while invoking the error page
480      * @throws IOException if an I/O error occurred while invoking the error
481      *     page
482      * @throws NullPointerException if the exception is null
483      *
484      * @see #handlePageException(Exception)
485      */
486 
487     abstract public void handlePageException(Throwable   t) 
488         throws ServletException  , IOException  ;
489 
490     /**
491      * Return a new BodyContent object, save the current "out" JspWriter,
492      * and update the value of the "out" attribute in the page scope
493      * attribute namespace of the PageContext.
494      *
495      * @return the new BodyContent
496      */
497 
498     public BodyContent   pushBody() {
499         return null; // XXX to implement
500     }
501          
502 
503     /**
504      * Provides convenient access to error information.
505      *
506      * @return an ErrorData instance containing information about the 
507      * error, as obtained from the request attributes, as per the 
508      * Servlet specification.  If this is not an error page (that is,
509      * if the isErrorPage attribute of the page directive is not set
510      * to "true"), the information is meaningless.
511      *
512      * @since 2.0
513      */
514     public ErrorData   getErrorData() {
515     return new ErrorData  ( 
516         (Throwable  )getRequest().getAttribute( "javax.servlet.error.exception" ),
517         ((Integer  )getRequest().getAttribute( 
518         "javax.servlet.error.status_code" )).intValue(),
519         (String  )getRequest().getAttribute( "javax.servlet.error.request_uri" ),
520         (String  )getRequest().getAttribute( "javax.servlet.error.servlet_name" ) );
521     }
522     
523 }
524
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags