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