Package: PageContext

PageContext

name	instruction	branch	complexity	line	method
PageContext()	M: 3 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 2 C: 0 0%	M: 1 C: 0 0%
getErrorData()	M: 30 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 5 C: 0 0%	M: 1 C: 0 0%
pushBody()	M: 2 C: 0 0%	M: 0 C: 0 100%	M: 1 C: 0 0%	M: 1 C: 0 0%	M: 1 C: 0 0%

Coverage

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