Save This Page
1 /*
2 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
3 *
4 * Copyright 1997-2007 Sun Microsystems, Inc. All rights reserved.
5 *
6 * The contents of this file are subject to the terms of either the GNU
7 * General Public License Version 2 only ("GPL") or the Common Development
8 * and Distribution License("CDDL") (collectively, the "License"). You
9 * may not use this file except in compliance with the License. You can obtain
10 * a copy of the License at https://glassfish.dev.java.net/public/CDDL+GPL.html
11 * or glassfish/bootstrap/legal/LICENSE.txt. See the License for the specific
12 * language governing permissions and limitations under the License.
13 *
14 * When distributing the software, include this License Header Notice in each
15 * file and include the License file at glassfish/bootstrap/legal/LICENSE.txt.
16 * Sun designates this particular file as subject to the "Classpath" exception
17 * as provided by Sun in the GPL Version 2 section of the License file that
18 * accompanied this code. If applicable, add the following below the License
19 * Header, with the fields enclosed by brackets [] replaced by your own
20 * identifying information: "Portions Copyrighted [year]
21 * [name of copyright owner]"
22 *
23 * Contributor(s):
24 *
25 * If you wish your version of this file to be governed by only the CDDL or
26 * only the GPL Version 2, indicate your decision by adding "[Contributor]
27 * elects to include this software in this distribution under the [CDDL or GPL
28 * Version 2] license." If you don't indicate a single choice of license, a
29 * recipient has the option to distribute your version of this file under
30 * either the CDDL, the GPL Version 2 or to extend the choice of license to
31 * its licensees as provided above. However, if you add GPL Version 2 code
32 * and therefore, elected the GPL Version 2 license, then the option applies
33 * only if the new code is made subject to such option by the copyright
34 * holder.
35 */
36
37 /*
38 * $Id: ExternalContext.java,v 1.30.4.1 2007/12/17 21:14:38 rlubke Exp $
39 */
40
41 /*
42 * Licensed Material - Property of IBM
43 * (C) Copyright IBM Corp. 2002, 2003 - All Rights Reserved.
44 * US Government Users Restricted Rights - Use, duplication or disclosure
45 * restricted by GSA ADP Schedule Contract with IBM Corp.
46 */
47
48 package javax.faces.context;
49
50 import java.io.IOException;
51 import java.io.InputStream;
52 import java.io.UnsupportedEncodingException;
53 import java.net.MalformedURLException;
54 import java.net.URL;
55 import java.security.Principal;
56 import java.util.Iterator;
57 import java.util.Locale;
58 import java.util.Set;
59 import java.util.Map;
60
61
62
63 /**
64 * <p>This class allows the Faces API to be unaware of the nature of its
65 * containing application environment. In particular, this class allows
66 * JavaServer Faces based appications to run in either a Servlet or a Portlet
67 * environment.</p>
68 *
69 * <p>In the method descriptions below, paragraphs starting with
70 * <em>Servlet:</em> and <em>Portlet:</em> denote behavior that is
71 * specific to that particular environment.</p>
72 */
73
74 public abstract class ExternalContext {
75
76
77 // ------------------------------------------------------ Manifest Constants
78
79
80 /**
81 * <p>String identifier for BASIC authentication.</p>
82 */
83 public static final String BASIC_AUTH = "BASIC";
84
85
86 /**
87 * <p>String identifier for CLIENT_CERT authentication.</p>
88 */
89 public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
90
91
92 /**
93 * <p>String identifier for DIGEST authentication.</p>
94 */
95 public static final String DIGEST_AUTH = "DIGEST";
96
97
98 /**
99 * <p>String identifier for FORM authentication.</p>
100 */
101 public static final String FORM_AUTH = "FORM";
102
103
104
105 // ---------------------------------------------------------- Public Methods
106
107
108 /**
109 * <p>Dispatch a request to the specified resource to create output
110 * for this response.</p>
111 *
112 * <p><em>Servlet:</em> This must be accomplished by calling the
113 * <code>javax.servlet.ServletContext</code> method
114 * <code>getRequestDispatcher(path)</code>, and calling the
115 * <code>forward()</code> method on the resulting object.</p>
116 *
117 * <p><em>Portlet:</em> This must be accomplished by calling the
118 * <code>javax.portlet.PortletContext</code> method
119 * <code>getRequestDispatcher()</code>, and calling the
120 * <code>include()</code> method on the resulting object.</p>
121 *
122 * @param path Context relative path to the specified resource,
123 * which must start with a slash ("/") character
124 *
125 * @throws FacesException thrown if a <code>ServletException</code>
126 * or <code>PortletException</code> occurs
127 * @throws IllegalArgumentException if no request dispatcher
128 * can be created for the specified path
129 * @throws IllegalStateException if this method is called in a portlet
130 * environment, and the current request is an <code>ActionRequest</code>
131 * instead of a <code>RenderRequest</code>
132 * @throws IOException if an input/output error occurs
133 * @throws NullPointerException if <code>path</code>
134 * is <code>null</code>
135 */
136 public abstract void dispatch(String path)
137 throws IOException;
138
139
140 /**
141 * <p>Return the input URL, after performing any rewriting needed to
142 * ensure that it will correctly identify an addressable action in the
143 * current application.<p>
144 *
145 * <p><em>Servlet:</em> This must be the value returned by the
146 * <code>javax.servlet.http.HttpServletResponse</code> method
147 * <code>encodeURL(url)</code>.</p>
148 *
149 * <p><em>Portlet:</em> This must be the value returned by the
150 * <code>javax.portlet.PortletResponse</code> method
151 * <code>encodeURL(url)</code>.</p>
152 *
153 * @param url The input URL to be encoded
154 *
155 * @throws NullPointerException if <code>url</code>
156 * is <code>null</code>
157 */
158 public abstract String encodeActionURL(String url);
159
160
161 /**
162 * <p>Return the specified name, after prefixing it with a namespace
163 * that ensures that it will be unique within the context of a
164 * particular page.</p>
165 *
166 * <p><em>Servlet:</em> The input value must be returned unchanged.</p>
167 *
168 * <p><em>Portlet:</em> The returned value must be the input value
169 * prefixed by the value returned by the
170 * <code>javax.portlet.RenderResponse</code> method
171 * <code>getNamespace()</code>.</p>
172 *
173 * @param name Name to be encoded
174 *
175 * @throws IllegalStateException if this method is called in a portlet
176 * environment, and the current response is an <code>ActionResponse</code>
177 * instead of a <code>RenderResponse</code>
178 * @throws NullPointerException if <code>name</code>
179 * is <code>null</code>
180 */
181 public abstract String encodeNamespace(String name);
182
183
184 /**
185 * <p>Return the input URL, after performing any rewriting needed to
186 * ensure that it will correctly identify an addressable resource in the
187 * current application.<p>
188 *
189 * <p><em>Servlet:</em> This must be the value returned by the
190 * <code>javax.servlet.http.HttpServletResponse</code> method
191 * <code>encodeURL(url)</code>.</p>
192 *
193 * <p><em>Portlet:</em> This must be the value returned by the
194 * <code>javax.portlet.PortletResponse</code> method
195 * <code>encodeURL(url)</code>.</p>
196 *
197 * @param url The input URL to be encoded
198 *
199 * @throws NullPointerException if <code>url</code>
200 * is <code>null</code>
201 */
202 // PENDING(craigmcc) - Currently identical to encodeActionURL()
203 public abstract String encodeResourceURL(String url);
204
205
206 /**
207 * <p>Return a mutable <code>Map</code> representing the application
208 * scope attributes for the current application. The returned
209 * <code>Map</code> must implement the entire contract for a
210 * modifiable map as described in the JavaDocs for
211 * <code>java.util.Map</code>. Modifications made in the
212 * <code>Map</code> must cause the corresponding changes in the set
213 * of application scope attributes. Particularly the
214 * <code>clear()</code>, <code>remove()</code>, <code>put()</code>,
215 * <code>putAll()</code>, and <code>get()</code> operations must
216 * take the appropriate action on the underlying data structure.</p>
217 *
218 * <p>For any of the <code>Map</code> methods that cause an element
219 * to be removed from the underlying data structure, the following
220 * action regarding managed-beans must be taken. If the element to
221 * be removed is a managed-bean, and it has one or more public
222 * no-argument void return methods annotated with
223 * <code>javax.annotation.PreDestroy</code>, each such method must
224 * be called before the element is removed from the underlying data
225 * structure. Elements that are not managed-beans, but do happen to
226 * have methods with that annotation must not have those methods
227 * called on removal. Any exception thrown by the
228 * <code>PreDestroy</code> annotated methods must by caught and not
229 * rethrown. The exception may be logged.</p>
230 *
231 * <p><em>Servlet:</em> This must be the set of attributes available via
232 * the <code>javax.servlet.ServletContext</code> methods
233 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
234 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.</p>
235 *
236 * <p><em>Portlet:</em> This must be the set of attributes available via
237 * the <code>javax.portlet.PortletContext</code> methods
238 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
239 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.</p>
240 */
241 public abstract Map<String, Object> getApplicationMap();
242
243
244 /**
245 * <p>Return the name of the authentication scheme used to authenticate
246 * the current user, if any; otherwise, return <code>null</code>.
247 * For standard authentication schemes, the returned value will match
248 * one of the following constants:
249 * <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
250 * <code>DIGEST_AUTH</code>, or <code>FORM_AUTH</code>.</p>
251 *
252 * <p><em>Servlet:</em> This must be the value returned by the
253 * <code>javax.servlet.http.HttpServletRequest</code> method
254 * <code>getAuthType()</code>.</p>
255 *
256 * <p><em>Portlet:</em> This must be the value returned by the
257 * <code>javax.portlet.http.PortletRequest</code> method
258 * <code>getAuthType()</code>.</p>
259 */
260 public abstract String getAuthType();
261
262
263 /**
264 * <p>Return the application environment object instance for the current
265 * appication.</p>
266 *
267 * <p><em>Servlet:</em> This must be the current application's
268 * <code>javax.servlet.ServletContext</code> instance.</p>
269 *
270 * <p><em>Portlet:</em> This must be the current application's
271 * <code>javax.portlet.PortletContext</code> instance.</p>
272 */
273 public abstract Object getContext();
274
275
276 /**
277 * <p>Return the value of the specified application initialization
278 * parameter (if any).</p>
279 *
280 * <p><em>Servlet:</em> This must be the result of the
281 * <code>javax.servlet.ServletContext</code> method
282 * <code>getInitParameter(name)</code>.</p>
283 *
284 * <p><em>Portlet:</em> This must be the result of the
285 * <code>javax.portlet.PortletContext</code> method
286 * <code>getInitParameter(name)</code>.</p>
287 *
288 * @param name Name of the requested initialization parameter
289 *
290 * @throws NullPointerException if <code>name</code>
291 * is <code>null</code>
292 */
293 public abstract String getInitParameter(String name);
294
295
296 /**
297 * <p>Return an immutable <code>Map</code> whose keys are the set of
298 * application initialization parameter names configured for this
299 * application, and whose values are the corresponding parameter
300 * values. The returned <code>Map</code> must implement the entire
301 * contract for an unmodifiable map as described in the JavaDocs
302 * for <code>java.util.Map</code>.</p>
303 *
304 * <p><em>Servlet:</em> This result must be as if it were synthesized
305 * by calling the <code>javax.servlet.ServletContext</code>
306 * method <code>getInitParameterNames</code>, and putting
307 * each configured parameter name/value pair into the result.</p>
308 *
309 * <p><em>Portlet:</em> This result must be as if it were synthesized
310 * by calling the <code>javax.portlet.PortletContext</code>
311 * method <code>getInitParameterNames</code>, and putting
312 * each configured parameter name/value pair into the result.</p>
313 */
314 public abstract Map getInitParameterMap();
315
316
317 /**
318 * <p>Return the login name of the user making the current request
319 * if any; otherwise, return <code>null</code>.</p>
320 *
321 * <p><em>Servlet:</em> This must be the value returned by the
322 * <code>javax.servlet.http.HttpServletRequest</code> method
323 * <code>getRemoteUser()</code>.</p>
324 *
325 * <p><em>Portlet:</em> This must be the value returned by the
326 * <code>javax.portlet.http.PortletRequest</code> method
327 * <code>getRemoteUser()</code>.</p>
328 */
329 public abstract String getRemoteUser();
330
331
332 /**
333 * <p>Return the environment-specific object instance for the current
334 * request.</p>
335 *
336 * <p><em>Servlet:</em> This must be the current request's
337 * <code>javax.servlet.http.HttpServletRequest</code> instance.</p>
338 *
339 * <p><em>Portlet:</em> This must be the current request's
340 * <code>javax.portlet.PortletRequest</code> instance, which
341 * will be either an <code>ActionRequest</code> or a
342 * <code>RenderRequest</code> depending upon when this method
343 * is called.</p>
344 */
345 public abstract Object getRequest();
346
347 /**
348 * <p>Set the environment-specific request to be returned by
349 * subsequent calls to {@link #getRequest}. This may be used to
350 * install a wrapper for the request.</p>
351 *
352 * <p>The default implementation throws
353 * <code>UnsupportedOperationException</code> and is provided
354 * for the sole purpose of not breaking existing applications that extend
355 * this class.</p>
356 *
357 *
358 * @since 1.2
359 */
360 public void setRequest(Object request) {
361
362 ExternalContext impl = getDefaultExternalContext();
363 if (impl != null) {
364 impl.setRequest(request);
365 return;
366 }
367
368 throw new UnsupportedOperationException();
369
370 }
371
372 /**
373 *
374 * <p>Overrides the name of the character
375 * encoding used in the body of this request.</p>
376 *
377 * <p>Calling this method after the request has been accessed will have no
378 * no effect, unless a <code>Reader</code> or <code>Stream</code> has been
379 * obtained from the request, in which case an <code>IllegalStateException</code>
380 * is thrown.</p>
381 *
382 * <p><em>Servlet:</em> This must call through to the
383 * <code>javax.servlet.ServletRequest</code> method
384 * <code>setCharacterEncoding()</code>.</p>
385 *
386 * <p><em>Portlet:</em> This must call through to the
387 * <code>javax.portlet.ActionRequest</code> method
388 * <code>setCharacterEncoding()</code>.</p>
389 *
390 * <p>The default implementation throws
391 * <code>UnsupportedOperationException</code> and is provided
392 * for the sole purpose of not breaking existing applications that extend
393 * this class.</p>
394 *
395 * @throws java.io.UnsupportedEncodingException if this is not a valid
396 * encoding
397 *
398 * @since 1.2
399 *
400 */
401 public void setRequestCharacterEncoding(String encoding) throws UnsupportedEncodingException {
402
403 ExternalContext impl = getDefaultExternalContext();
404 if (impl != null) {
405 impl.setRequestCharacterEncoding(encoding);
406 return;
407 }
408
409 throw new UnsupportedOperationException();
410 }
411
412
413
414 /**
415 * <p>Return the portion of the request URI that identifies the web
416 * application context for this request.</p>
417 *
418 * <p><em>Servlet:</em> This must be the value returned by the
419 * <code>javax.servlet.http.HttpServletRequest</code> method
420 * <code>getContextPath()</code>.</p>
421 *
422 * <p><em>Portlet:</em> This must be the value returned by the
423 * <code>javax.portlet.PortletRequest</code> method
424 * <code>getContextPath()</code>.</p>
425 */
426 public abstract String getRequestContextPath();
427
428
429 /**
430 * <p>Return an immutable <code>Map</code> whose keys are the set of
431 * cookie names included in the current request, and whose
432 * values (of type <code>javax.servlet.http.Cookie</code>)
433 * are the first (or only) cookie for each cookie name
434 * returned by the underlying request. The returned
435 * <code>Map</code> must implement the entire contract for an unmodifiable
436 * map as described in the JavaDocs for <code>java.util.Map</code>.</p>
437 *
438 * <p><em>Servlet:</em> This must be the value returned by the
439 * <code>javax.servlet.http.HttpServletRequest</code> method
440 * <code>getCookies()</code>, unless <code>null</code> was returned,
441 * in which case this must be a zero-length array.</p>
442 *
443 * <p><em>Portlet:</em> Ths must be an empty Map.</p>
444 */
445 public abstract Map<String, Object> getRequestCookieMap();
446
447
448 /**
449 * <p>Return an immutable <code>Map</code> whose keys are the set of
450 * request header names included in the current request, and whose
451 * values (of type String) are the first (or only) value for each
452 * header name returned by the underlying request. The returned
453 * <code>Map</code> must implement the entire contract for an unmodifiable
454 * map as described in the JavaDocs for <code>java.util.Map</code>. In
455 * addition, key comparisons must be performed in a case insensitive
456 * manner.</p>
457 *
458 * <p><em>Servlet:</em> This must be the set of headers available via
459 * the <code>javax.servlet.http.HttpServletRequest</code> methods
460 * <code>getHeader()</code> and <code>getHeaderNames()</code>.</p>
461 *
462 * <p><em>Portlet:</em> This must be the set of properties available via
463 * the <code>javax.portlet.PortletRequest</code> methods
464 * <code>getProperty()</code> and <code>getPropertyNames()</code>.
465 * As such, HTTP headers will only be included if they were provided
466 * by the portlet container, and additional properties provided by
467 * the portlet container may also be included.</p>
468 */
469 public abstract Map<String, String> getRequestHeaderMap();
470
471
472 /**
473 * <p>Return an immutable <code>Map</code> whose keys are the set of
474 * request header names included in the current request, and whose
475 * values (of type String[]) are all of the value for each
476 * header name returned by the underlying request. The returned
477 * <code>Map</code> must implement the entire contract for an unmodifiable
478 * map as described in the JavaDocs for <code>java.util.Map</code>. In
479 * addition, key comparisons must be performed in a case insensitive
480 * manner.</p>
481 *
482 * <p><em>Servlet:</em> This must be the set of headers available via
483 * the <code>javax.servlet.http.HttpServletRequest</code> methods
484 * <code>getHeaders()</code> and <code>getHeaderNames()</code>.</p>
485 *
486 * <p><em>Portlet:</em> This must be the set of properties available via
487 * the <code>javax.portlet.PortletRequest</code> methods
488 * <code>getProperties()</code> and <code>getPropertyNames()</code>.
489 * As such, HTTP headers will only be included if they were provided
490 * by the portlet container, and additional properties provided by
491 * the portlet container may also be included.</p>
492 */
493 public abstract Map<String, String []> getRequestHeaderValuesMap();
494
495
496 /**
497 * <p>Return the preferred <code>Locale</code> in which the client
498 * will accept content.</p>
499 *
500 * <p><em>Servlet:</em> This must be the value returned by the
501 * <code>javax.servlet.ServletRequest</code> method
502 * <code>getLocale()</code>.</p>
503 *
504 * <p><em>Portlet:</em> This must be the value returned by the
505 * <code>javax.portlet.PortletRequest</code> method
506 * <code>getLocale()</code>.</p>
507 */
508 public abstract Locale getRequestLocale();
509
510
511 /**
512 * <p>Return an <code>Iterator</code> over the preferred
513 * <code>Locale</code>s specified in the request, in decreasing
514 * order of preference.</p>
515 *
516 * <p><em>Servlet:</em> This must be an <code>Iterator</code>
517 * over the values returned by the <code>javax.servlet.ServletRequest</code>
518 * method <code>getLocales()</code>.</p>
519 *
520 * <p><em>Portlet:</em> This must be an <code>Iterator</code>
521 * over the values returned by the <code>javax.portlet.PortletRequest</code>
522 * method <code>getLocales()</code>.</p>
523 */
524 public abstract Iterator<Locale> getRequestLocales();
525
526
527 /**
528 * <p>Return a mutable <code>Map</code> representing the request
529 * scope attributes for the current application. The returned
530 * <code>Map</code> must implement the entire contract for a
531 * modifiable map as described in the JavaDocs for
532 * <code>java.util.Map</code>. Modifications made in the
533 * <code>Map</code> must cause the corresponding changes in the set
534 * of request scope attributes. Particularly the
535 * <code>clear()</code>, <code>remove()</code>, <code>put()</code>,
536 * <code>putAll()</code>, and <code>get()</code> operations must
537 * take the appropriate action on the underlying data structure.</p>
538 *
539 * <p>For any of the <code>Map</code> methods that cause an element
540 * to be removed from the underlying data structure, the following
541 * action regarding managed-beans must be taken. If the element to
542 * be removed is a managed-bean, and it has one or more public
543 * no-argument void return methods annotated with
544 * <code>javax.annotation.PreDestroy</code>, each such method must
545 * be called before the element is removed from the underlying data
546 * structure. Elements that are not managed-beans, but do happen to
547 * have methods with that annotation must not have those methods
548 * called on removal. Any exception thrown by the
549 * <code>PreDestroy</code> annotated methods must by caught and not
550 * rethrown. The exception may be logged.</p>
551 *
552 * <p><em>Servlet:</em> This must be the set of attributes available via
553 * the <code>javax.servlet.ServletRequest</code> methods
554 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
555 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.</p>
556 *
557 * <p><em>Portlet:</em> This must be the set of attributes available via
558 * the <code>javax.portlet.PortletRequest</code> methods
559 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
560 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.</p>
561 */
562 public abstract Map<String, Object> getRequestMap();
563
564
565 /**
566 * <p>Return an immutable <code>Map</code> whose keys are the set of
567 * request parameters names included in the current request, and whose
568 * values (of type String) are the first (or only) value for each
569 * parameter name returned by the underlying request. The returned
570 * <code>Map</code> must implement the entire contract for an unmodifiable
571 * map as described in the JavaDocs for <code>java.util.Map</code>.</p>
572 *
573 * <p><em>Servlet:</em> This must be the set of parameters available via
574 * the <code>javax.servlet.ServletRequest</code> methods
575 * <code>getParameter()</code> and <code>getParameterNames()</code>.</p>
576 *
577 * <p><em>Portlet:</em> This must be the set of parameters available via
578 * the <code>javax.portlet.PortletRequest</code> methods
579 * <code>getParameter()</code> and <code>getParameterNames()</code>.</p>
580 */
581 public abstract Map<String, String> getRequestParameterMap();
582
583
584 /**
585 * <p>Return an <code>Iterator</code> over the names of all request
586 * parameters included in the current request.</p>
587 *
588 * <p><em>Servlet:</em> This must be an <code>Iterator</code> over the
589 * values returned by the <code>javax.servlet.ServletRequest</code>
590 * method <code>getParameterNames()</code>.</p>
591 *
592 * <p><em>Portlet:</em> This must be an <code>Iterator</code> over the
593 * values returned by the <code>javax.portlet.PortletRequest</code>
594 * method <code>getParameterNames()</code>.</p>
595 */
596 public abstract Iterator<String> getRequestParameterNames();
597
598
599 /**
600 * <p>Return an immutable <code>Map</code> whose keys are the set of
601 * request parameters names included in the current request, and whose
602 * values (of type String[]) are all of the values for each
603 * parameter name returned by the underlying request. The returned
604 * <code>Map</code> must implement the entire contract for an unmodifiable
605 * map as described in the JavaDocs for <code>java.util.Map</code>.</p>
606 *
607 * <p><em>Servlet:</em> This must be the set of parameters available via
608 * the <code>javax.servlet.ServletRequest</code> methods
609 * <code>getParameterValues()</code> and
610 * <code>getParameterNames()</code>.</p>
611 *
612 * <p><em>Portlet:</em> This must be the set of parameters available via
613 * the <code>javax.portlet.PortletRequest</code> methods
614 * <code>getParameterValues()</code> and
615 * <code>getParameterNames()</code>.</p>
616 */
617 public abstract Map<String, String []> getRequestParameterValuesMap();
618
619
620 /**
621 * <p>Return the extra path information (if any) included in the
622 * request URI; otherwise, return <code>null</code>.</p>
623 *
624 * <p><em>Servlet:</em> This must be the value returned by the
625 * <code>javax.servlet.http.HttpServletRequest</code> method
626 * <code>getPathInfo()</code>.</p>
627 *
628 * <p><em>Portlet:</em> This must be <code>null</code>.</p>
629 */
630 public abstract String getRequestPathInfo();
631
632
633 /**
634 * <p>Return the servlet path information (if any) included in the
635 * request URI; otherwise, return <code>null</code>.</p>
636 *
637 * <p><em>Servlet:</em> This must be the value returned by the
638 * <code>javax.servlet.http.HttpServletRequest</code> method
639 * <code>getServletPath()</code>.</p>
640 *
641 * <p><em>Portlet:</em> This must be <code>null</code>.</p>
642 */
643 public abstract String getRequestServletPath();
644
645 /**
646 *
647 * <p> Return the character encoding currently being used
648 * to interpret this request.</p>
649 *
650 * <p><em>Servlet:</em> This must return the value returned by the
651 * <code>javax.servlet.ServletRequest</code> method
652 * <code>getCharacterEncoding()</code>.</p>
653 *
654 * <p><em>Portlet:</em> This must return the value returned by the
655 * <code>javax.portlet.ActionRequest</code> method
656 * <code>getCharacterEncoding()</code>.</p>
657 *
658 * <p>The default implementation throws
659 * <code>UnsupportedOperationException</code> and is provided
660 * for the sole purpose of not breaking existing applications that extend
661 * this class.</p>
662 *
663 * @since 1.2
664 *
665 */
666 public String getRequestCharacterEncoding() {
667
668 ExternalContext impl = getDefaultExternalContext();
669 if (impl != null) {
670 return impl.getRequestCharacterEncoding();
671 }
672 throw new UnsupportedOperationException();
673
674 }
675
676 /**
677 *
678 * <p>Return the MIME Content-Type for this request. If not
679 * available, return <code>null</code>.</p>
680 *
681 * <p><em>Servlet:</em> This must return the value returned by the
682 * <code>javax.servlet.ServletRequest</code> method
683 * <code>getContentType()</code>.</p>
684 *
685 * <p><em>Portlet:</em> This must return <code>null</code>.</p>
686 *
687 * <p>The default implementation throws
688 * <code>UnsupportedOperationException</code> and is provided
689 * for the sole purpose of not breaking existing applications that extend
690 * this class.</p>
691 *
692 * @since 1.2
693 */
694 public String getRequestContentType() {
695
696 ExternalContext impl = getDefaultExternalContext();
697 if (impl != null) {
698 return impl.getRequestContentType();
699 }
700
701 throw new UnsupportedOperationException();
702
703 }
704
705 /**
706 *
707 * <p>Returns the name of the character encoding (MIME charset) used for
708 * the body sent in this response. </p>
709 *
710 * <p><em>Servlet:</em> This must return the value returned by the
711 * <code>javax.servlet.ServletResponse</code> method
712 * <code>getCharacterEncoding()</code>.</p>
713 *
714 * <p><em>Portlet:</em> This must return <code>null</code>.</p>
715 *
716 * <p>The default implementation throws
717 * <code>UnsupportedOperationException</code> and is provided
718 * for the sole purpose of not breaking existing applications that extend
719 * this class.</p>
720 *
721 * @since 1.2
722 */
723 public String getResponseCharacterEncoding() {
724
725 ExternalContext impl = getDefaultExternalContext();
726 if (impl != null) {
727 return impl.getResponseCharacterEncoding();
728 }
729
730 throw new UnsupportedOperationException();
731
732 }
733
734
735 /**
736 *
737 * <p>Return the MIME Content-Type for this response. If not
738 * available, return <code>null</code>.</p>
739 *
740 * <p><em>Servlet:</em> This must return the value returned by the
741 * <code>javax.servlet.ServletResponse</code> method
742 * <code>getContentType()</code>.</p>
743 *
744 * <p><em>Portlet:</em> This must return <code>null</code>.</p>
745 *
746 * <p>The default implementation throws
747 * <code>UnsupportedOperationException</code> and is provided
748 * for the sole purpose of not breaking existing applications that extend
749 * this class.</p>
750 *
751 * @since 1.2
752 */
753 public String getResponseContentType() {
754
755 ExternalContext impl = getDefaultExternalContext();
756 if (impl != null) {
757 return impl.getResponseContentType();
758 }
759
760 throw new UnsupportedOperationException();
761
762 }
763
764
765
766 /**
767 * <p>Return a <code>URL</code> for the application resource mapped to the
768 * specified path, if it exists; otherwise, return <code>null</code>.</p>
769 *
770 * <p><em>Servlet:</em> This must be the value returned by the
771 * <code>javax.servlet.ServletContext</code> method
772 * <code>getResource(path)</code>.</p>
773 *
774 * <p><em>Portlet:</em> This must be the value returned by the
775 * <code>javax.portlet.PortletContext</code> method
776 * <code>getResource(path)</code>.</p>
777 *
778 * @param path The path to the requested resource, which must
779 * start with a slash ("/" character
780 *
781 * @throws MalformedURLException if the specified path
782 * is not in the correct form
783 * @throws NullPointerException if <code>path</code>
784 * is <code>null</code>
785 */
786 public abstract URL getResource(String path) throws MalformedURLException;
787
788
789 /**
790 * <p>Return an <code>InputStream</code> for an application resource
791 * mapped to the specified path, if it exists; otherwise, return
792 * <code>null</code>.</p>
793 *
794 * <p><em>Servlet:</em> This must be the value returned by the
795 * <code>javax.servlet.ServletContext</code> method
796 * <code>getResourceAsStream(path)</code>.</p>
797 *
798 * <p><em>Portlet:</em> This must be the value returned by the
799 * <code>javax.portlet.PortletContext</code> method
800 * <code>getResourceAsStream(path)</code>.</p>
801 *
802 * @param path The path to the requested resource, which must
803 * start with a slash ("/" character
804 *
805 * @throws NullPointerException if <code>path</code>
806 * is <code>null</code>
807 */
808 public abstract InputStream getResourceAsStream(String path);
809
810
811 /**
812 * <p>Return the <code>Set</code> of resource paths for all application
813 * resources whose resource path starts with the specified argument.</p>
814 *
815 * <p><em>Servlet:</em> This must be the value returned by the
816 * <code>javax.servlet.ServletContext</code> method
817 * <code>getResourcePaths(path).</code></p>
818 *
819 * <p><em>Portlet:</em> This must be the value returned by the
820 * <code>javax.portlet.PortletContext</code> method
821 * <code>getResourcePaths(path).</code></p>
822 *
823 * @param path Partial path used to match resources, which must
824 * start with a slash ("/") character
825 *
826 * @throws NullPointerException if <code>path</code>
827 * is <code>null</code>
828 */
829 public abstract Set<String> getResourcePaths(String path);
830
831
832 /**
833 * <p>Return the environment-specific object instance for the current
834 * response.</p>
835 *
836 * <p><em>Servlet:</em> This is the current request's
837 * <code>javax.servlet.http.HttpServletResponse</code> instance.</p>
838 *
839 * <p><em>Portlet:</em> This is the current request's
840 * <code>javax.portlet.PortletResponse</code> instance, which
841 * will be either an <code>ActionResponse</code> or a
842 * <code>RenderResponse</code> depending upon when this method
843 * is called.</p>
844 */
845 public abstract Object getResponse();
846
847 /**
848 * <p>Set the environment-specific response to be returned by
849 * subsequent calls to {@link #getResponse}. This may be used to
850 * install a wrapper for the response.</p>
851 *
852 * <p>The default implementation throws
853 * <code>UnsupportedOperationException</code> and is provided
854 * for the sole purpose of not breaking existing applications that extend
855 * this class.</p>
856 *
857 *
858 * @since 1.2
859 */
860 public void setResponse(Object response) {
861
862 ExternalContext impl = getDefaultExternalContext();
863 if (impl != null) {
864 impl.setResponse(response);
865 return;
866 }
867
868 throw new UnsupportedOperationException();
869
870 }
871
872
873 /**
874 *
875 * <p>Sets the character encoding (MIME charset) of the response being sent
876 * to the client, for example, to UTF-8.</p>
877 *
878 * <p><em>Servlet:</em> This must call through to the
879 * <code>javax.servlet.ServletResponse</code> method
880 * <code>setCharacterEncoding()</code>.</p>
881 *
882 * <p><em>Portlet:</em> This method must take no action.</p>
883 *
884 * <p>The default implementation throws
885 * <code>UnsupportedOperationException</code> and is provided
886 * for the sole purpose of not breaking existing applications that extend
887 * this class.</p>
888 *
889 *
890 * @since 1.2
891 *
892 */
893 public void setResponseCharacterEncoding(String encoding) {
894
895 ExternalContext impl = getDefaultExternalContext();
896 if (impl != null) {
897 impl.setResponseCharacterEncoding(encoding);
898 return;
899 }
900
901 throw new UnsupportedOperationException();
902
903 }
904
905
906
907
908
909 /**
910 * <p>If the <code>create</code> parameter is <code>true</code>,
911 * create (if necessary) and return a session instance associated
912 * with the current request. If the <code>create</code> parameter
913 * is <code>false</code> return any existing session instance
914 * associated with the current request, or return <code>null</code> if
915 * there is no such session.</p>
916 *
917 * <p><em>Servlet:</em> This must return the result of calling
918 * <code>getSession(create)</code> on the underlying
919 * <code>javax.servlet.http.HttpServletRequest</code> instance.</p>
920 *
921 * <p>em>Portlet:</em> This must return the result of calling
922 * <code>getPortletSession(create)</code> on the underlying
923 * <code>javax.portlet.PortletRequest</code> instance.</p>
924 *
925 * @param create Flag indicating whether or not a new session should be
926 * created if there is no session associated with the current request
927 */
928 public abstract Object getSession(boolean create);
929
930
931 /**
932 * <p>Return a mutable <code>Map</code> representing the session
933 * scope attributes for the current application. The returned
934 * <code>Map</code> must implement the entire contract for a
935 * modifiable map as described in the JavaDocs for
936 * <code>java.util.Map</code>. Modifications made in the
937 * <code>Map</code> must cause the corresponding changes in the set
938 * of session scope attributes. Particularly the
939 * <code>clear()</code>, <code>remove()</code>, <code>put()</code>,
940 * and <code>get()</code> operations must take the appropriate
941 * action on the underlying data structure. Accessing attributes
942 * via this <code>Map</code> must cause the creation of a session
943 * associated with the current request, if such a session does not
944 * already exist.</p>
945 *
946 * <p>For any of the <code>Map</code> methods that cause an element
947 * to be removed from the underlying data structure, the following
948 * action regarding managed-beans must be taken. If the element to
949 * be removed is a managed-bean, and it has one or more public
950 * no-argument void return methods annotated with
951 * <code>javax.annotation.PreDestroy</code>, each such method must
952 * be called before the element is removed from the underlying data
953 * structure. Elements that are not managed-beans, but do happen to
954 * have methods with that annotation must not have those methods
955 * called on removal. Any exception thrown by the
956 * <code>PreDestroy</code> annotated methods must by caught and not
957 * rethrown. The exception may be logged.</p>
958 *
959 * <p><em>Servlet:</em> This must be the set of attributes available via
960 * the <code>javax.servlet.http.HttpServletSession</code> methods
961 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
962 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.</p>
963 *
964 * <p><em>Portlet:</em> This must be the set of attributes available via
965 * the <code>javax.portlet.PortletSession</code> methods
966 * <code>getAttribute()</code>, <code>getAttributeNames()</code>,
967 * <code>removeAttribute()</code>, and <code>setAttribute()</code>.
968 * All session attribute access must occur in PORTLET_SCOPE scope
969 * within the session.</p>
970 */
971 public abstract Map<String, Object> getSessionMap();
972
973
974 /**
975 * <p>Return the <code>Principal</code> object containing the name of
976 * the current authenticated user, if any; otherwise, return
977 * <code>null</code>.</p>
978 *
979 * <p><em>Servlet:</em> This must be the value returned by the
980 * <code>javax.servlet.http.HttpServletRequest</code> method
981 * <code>getUserPrincipal()</code>.</p>
982 *
983 * <p><em>Portlet:</em> This must be the value returned by the
984 * <code>javax.portlet.http.PortletRequest</code> method
985 * <code>getUserPrincipal()</code>.</p>
986 */
987 public abstract Principal getUserPrincipal();
988
989
990 /**
991 * <p>Return <code>true</code> if the currently authenticated user is
992 * included in the specified role. Otherwise, return <code>false</code>.
993 * </p>
994 *
995 * <p><em>Servlet:</em> This must be the value returned by the
996 * <code>javax.servlet.http.HttpServletRequest</code> method
997 * <code>isUserInRole(role)</code>.</p>
998 *
999 * <p><em>Portlet:</em> This must be the value returned by the
1000 * <code>javax.portlet.http.PortletRequest</code> method
1001 * <code>isUserInRole(role)</code>.</p>
1002 *
1003 * @param role Logical role name to be checked
1004 *
1005 * @throws NullPointerException if <code>role</code>
1006 * is <code>null</code>
1007 */
1008 public abstract boolean isUserInRole(String role);
1009
1010
1011 /**
1012 * <p>Log the specified message to the application object.</p>
1013 *
1014 * <p><em>Servlet:</em> This must be performed by calling the
1015 * <code>javax.servlet.ServletContext</code> method
1016 * <code>log(String)</code>.</p>
1017 *
1018 * <p><em>Portlet:</em> This must be performed by calling the
1019 * <code>javax.portlet.PortletContext</code> method
1020 * <code>log(String)</code>.</p>
1021 *
1022 * @param message Message to be logged
1023 *
1024 * @throws NullPointerException if <code>message</code>
1025 * is <code>null</code>
1026 */
1027 public abstract void log(String message);
1028
1029
1030 /**
1031 * <p>Log the specified message and exception to the application object.</p>
1032 *
1033 * <p><em>Servlet:</em> This must be performed by calling the
1034 * <code>javax.servlet.ServletContext</code> method
1035 * <code>log(String,Throwable)</code>.</p>
1036 *
1037 * <p><em>Portlet:</em> This must be performed by calling the
1038 * <code>javax.portlet.PortletContext</code> method
1039 * <code>log(String,Throwable)</code>.</p>
1040 *
1041 * @param message Message to be logged
1042 * @param exception Exception to be logged
1043 *
1044 * @throws NullPointerException if <code>message</code>
1045 * or <code>exception</code> is <code>null</code>
1046 */
1047 public abstract void log(String message, Throwable exception);
1048
1049
1050 /**
1051 * <p>Redirect a request to the specified URL, and cause the
1052 * <code>responseComplete()</code> method to be called on the
1053 * {@link FacesContext} instance for the current request.</p>
1054 *
1055 * <p><em>Servlet:</em> This must be accomplished by calling the
1056 * <code>javax.servlet.http.HttpServletResponse</code> method
1057 * <code>sendRedirect()</code>.</p>
1058 *
1059 * <p><em>Portlet:</em> This must be accomplished by calling the
1060 * <code>javax.portlet.ActionResponse</code> method
1061 * <code>sendRedirect()</code>.</p>
1062 *
1063 * @param url Absolute URL to which the client should be redirected
1064 *
1065 * @throws IllegalArgumentException if the specified url is relative
1066 * @throws IllegalStateException if, in a portlet environment,
1067 * the current response object is a <code>RenderResponse</code>
1068 * instead of an <code>ActionResponse</code>
1069 * @throws IllegalStateException if, in a servlet environment,
1070 * the current response has already been committed
1071 * @throws IOException if an input/output error occurs
1072 */
1073 public abstract void redirect(String url)
1074 throws IOException;
1075
1076
1077 // --------------------------------------------------------- Private Methods
1078
1079 private ExternalContext getDefaultExternalContext() {
1080 ExternalContext extCtx = null;
1081 Map m = (Map) getRequestMap().get("com.sun.faces.util.RequestStateManager");
1082 if (m != null) {
1083 extCtx = (ExternalContext) m.get("com.sun.faces.ExternalContextImpl");
1084 }
1085 return extCtx;
1086
1087 }
1088 }