1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21 package javax.portlet;
22
23
24 /***
25 * The <CODE>PortletRequest</CODE> defines the base interface to provide client
26 * request information to a portlet. The portlet container uses two specialized
27 * versions of this interface when invoking a portlet, <CODE>ActionRequest</CODE>
28 * and <CODE>RenderRequest</CODE>. The portlet container creates these objects and
29 * passes them as arguments to the portlet's <CODE>processAction</CODE> and
30 * <CODE>render</CODE> methods.
31 *
32 * @see ActionRequest
33 * @see RenderRequest
34 */
35 public interface PortletRequest
36 {
37
38
39 /*** Used to retrieve user information attributes with the
40 * <code>getAttribute</code> call. The user information is returned
41 * as a <code>Map</code> object. The portlet must define the
42 * user information attribute it is interested in inside the
43 * <code>user-attribute</code> section of the deployment descriptor.
44 * If an attribute is not supported
45 * by the current runtime system it will not show up in the user
46 * attribute map.<BR>
47 * If the user-attribute is supported by the runtime system, but not
48 * defined for a particular user, then for that user the attribute
49 * exists in the returned map and the attribute has a <code>null</code> value.
50 * <p>
51 * If the user-attribute is not defined for the current user it
52 * will not show up in the Map.
53 * <p>
54 * The value is <code>javax.portlet.userinfo</code>.
55 */
56 public static final String USER_INFO = "javax.portlet.userinfo";
57
58
59 /***
60 * String identifier for Basic authentication. Value "BASIC".
61 */
62 public static final String BASIC_AUTH = "BASIC";
63
64 /***
65 * String identifier for Form based authentication. Value "FORM".
66 */
67 public static final String FORM_AUTH = "FORM";
68
69 /***
70 * String identifier for Certification based authentication. Value "CLIENT_CERT".
71 */
72 public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
73
74 /***
75 * String identifier for Digest based authentication. Value "DIGEST".
76 */
77 public static final String DIGEST_AUTH = "DIGEST";
78
79
80 /***
81 * Returns true, if the given window state is valid
82 * to be set for this portlet in the context
83 * of the current request.
84 *
85 * @param state window state to checked
86 *
87 * @return true, if it is valid for this portlet
88 * in this request to change to the
89 * given window state
90 *
91 */
92 public boolean isWindowStateAllowed(WindowState state);
93
94
95 /***
96 * Returns true, if the given portlet mode is a valid
97 * one to set for this portlet in the context
98 * of the current request.
99 *
100 * @param mode portlet mode to check
101 *
102 * @return true, if it is valid for this portlet
103 * in this request to change to the
104 * given portlet mode
105 *
106 */
107
108 public boolean isPortletModeAllowed(PortletMode mode);
109
110
111 /***
112 * Returns the current portlet mode of the portlet.
113 *
114 * @return the portlet mode
115 */
116
117 public PortletMode getPortletMode ();
118
119
120 /***
121 * Returns the current window state of the portlet.
122 *
123 * @return the window state
124 */
125
126 public WindowState getWindowState ();
127
128
129 /***
130 * Returns the preferences object associated with the portlet.
131 *
132 * @return the portlet preferences
133 */
134 public PortletPreferences getPreferences ();
135
136
137 /***
138 * Returns the current portlet session or, if there is no current session,
139 * creates one and returns the new session.
140 * <p>
141 * Creating a new portlet session will result in creating
142 * a new <code>HttpSession</code> on which the portlet session is based on.
143 *
144 * @return the portlet session
145 */
146
147 public PortletSession getPortletSession ();
148
149
150 /***
151 * Returns the current portlet session or, if there is no current session
152 * and the given flag is <CODE>true</CODE>, creates one and returns
153 * the new session.
154 * <P>
155 * If the given flag is <CODE>false</CODE> and there is no current
156 * portlet session, this method returns <CODE>null</CODE>.
157 * <p>
158 * Creating a new portlet session will result in creating
159 * a new <code>HttpSession</code> on which the portlet session is based on.
160 *
161 * @param create
162 * <CODE>true</CODE> to create a new session, <BR>
163 * <CODE>false</CODE> to return <CODE>null</CODE> if there
164 * is no current session
165 * @return the portlet session
166 */
167
168 public PortletSession getPortletSession (boolean create);
169
170
171 /***
172 * Returns the value of the specified request property
173 * as a <code>String</code>. If the request did not include a property
174 * of the specified name, this method returns <code>null</code>.
175 * <p>
176 * A portlet can access portal/portlet-container specific properties
177 * through this method and, if available, the
178 * headers of the HTTP client request.
179 * <p>
180 * This method should only be used if the
181 * property has only one value. If the property might have
182 * more than one value, use {@link #getProperties}.
183 * <p>
184 * If this method is used with a multivalued
185 * parameter, the value returned is equal to the first value
186 * in the Enumeration returned by <code>getProperties</code>.
187 *
188 * @param name a <code>String</code> specifying the
189 * property name
190 *
191 * @return a <code>String</code> containing the
192 * value of the requested
193 * property, or <code>null</code>
194 * if the request does not
195 * have a property of that name.
196 *
197 * @exception java.lang.IllegalArgumentException
198 * if name is <code>null</code>.
199 */
200
201 public String getProperty(String name);
202
203
204 /***
205 * Returns all the values of the specified request property
206 * as a <code>Enumeration</code> of <code>String</code> objects.
207 * <p>
208 * If the request did not include any propertys
209 * of the specified name, this method returns an empty
210 * <code>Enumeration</code>.
211 * The property name is case insensitive. You can use
212 * this method with any request property.
213 *
214 * @param name a <code>String</code> specifying the
215 * property name
216 *
217 * @return a <code>Enumeration</code> containing
218 * the values of the requested property. If
219 * the request does not have any properties of
220 * that name return an empty <code>Enumeration</code>.
221 *
222 * @exception java.lang.IllegalArgumentException
223 * if name is <code>null</code>.
224 */
225
226 public java.util.Enumeration getProperties(String name);
227
228
229 /***
230 *
231 * Returns a <code>Enumeration</code> of all the property names
232 * this request contains. If the request has no
233 * properties, this method returns an empty <code>Enumeration</code>.
234 *
235 *
236 * @return an <code>Enumeration</code> of all the
237 * property names sent with this
238 * request; if the request has
239 * no properties, an empty <code>Enumeration</code>.
240 */
241
242 public java.util.Enumeration getPropertyNames();
243
244
245 /***
246 * Returns the context of the calling portal.
247 *
248 * @return the context of the calling portal
249 */
250
251 public PortalContext getPortalContext();
252
253
254 /***
255 * Returns the name of the authentication scheme used for the
256 * connection between client and portal,
257 * for example, <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
258 * a custom one or <code>null</code> if there was no authentication.
259 *
260 * @return one of the static members <code>BASIC_AUTH</code>,
261 * <code>FORM_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
262 * <code>DIGEST_AUTH</code> (suitable for == comparison)
263 * indicating the authentication scheme,
264 * a custom one, or
265 * <code>null</code> if the request was
266 * not authenticated.
267 */
268
269 public java.lang.String getAuthType();
270
271
272 /***
273 * Returns the context path which is the path prefix associated with the deployed
274 * portlet application. If the portlet application is rooted at the
275 * base of the web server URL namespace (also known as "default" context),
276 * this path must be an empty string. Otherwise, it must be the path the
277 * portlet application is rooted to, the path must start with a '/' and
278 * it must not end with a '/' character.
279 * <p>
280 * To encode a URL the {@link PortletResponse#encodeURL} method must be used.
281 *
282 * @return a <code>String</code> specifying the
283 * portion of the request URL that indicates the context
284 * of the request
285 *
286 * @see PortletResponse#encodeURL
287 */
288
289 public String getContextPath();
290
291
292 /***
293 * Returns the login of the user making this request, if the user
294 * has been authenticated, or null if the user has not been authenticated.
295 *
296 * @return a <code>String</code> specifying the login
297 * of the user making this request, or <code>null</code>
298 * if the user login is not known.
299 *
300 */
301
302 public java.lang.String getRemoteUser();
303
304
305 /***
306 * Returns a java.security.Principal object containing the name of the
307 * current authenticated user.
308 *
309 * @return a <code>java.security.Principal</code> containing
310 * the name of the user making this request, or
311 * <code>null</code> if the user has not been
312 * authenticated.
313 */
314
315 public java.security.Principal getUserPrincipal();
316
317
318 /***
319 * Returns a boolean indicating whether the authenticated user is
320 * included in the specified logical "role". Roles and role membership can be
321 * defined using deployment descriptors. If the user has not been
322 * authenticated, the method returns <code>false</code>.
323 *
324 * @param role a <code>String</code> specifying the name
325 * of the role
326 *
327 * @return a <code>boolean</code> indicating whether
328 * the user making this request belongs to a given role;
329 * <code>false</code> if the user has not been
330 * authenticated.
331 */
332
333 public boolean isUserInRole(java.lang.String role);
334
335
336 /***
337 *
338 * Returns the value of the named attribute as an <code>Object</code>,
339 * or <code>null</code> if no attribute of the given name exists.
340 * <p>
341 * Attribute names should follow the same conventions as package
342 * names. This specification reserves names matching <code>java.*</code>,
343 * and <code>javax.*</code>.
344 * <p>
345 * In a distributed portlet web application the <code>Object</code>
346 * needs to be serializable.
347 *
348 * @param name a <code>String</code> specifying the name of
349 * the attribute
350 *
351 * @return an <code>Object</code> containing the value
352 * of the attribute, or <code>null</code> if
353 * the attribute does not exist.
354 *
355 * @exception java.lang.IllegalArgumentException
356 * if name is <code>null</code>.
357 *
358 */
359
360 public Object getAttribute(String name);
361
362
363 /***
364 * Returns an <code>Enumeration</code> containing the
365 * names of the attributes available to this request.
366 * This method returns an empty <code>Enumeration</code>
367 * if the request has no attributes available to it.
368 *
369 *
370 * @return an <code>Enumeration</code> of strings
371 * containing the names
372 * of the request attributes, or an empty
373 * <code>Enumeration</code> if the request
374 * has no attributes available to it.
375 */
376
377 public java.util.Enumeration getAttributeNames();
378
379
380 /***
381 * Returns the value of a request parameter as a <code>String</code>,
382 * or <code>null</code> if the parameter does not exist. Request parameters
383 * are extra information sent with the request. The returned parameter
384 * are "x-www-form-urlencoded" decoded.
385 * <p>
386 * Only parameters targeted to the current portlet are accessible.
387 * <p>
388 * This method should only be used if the
389 * parameter has only one value. If the parameter might have
390 * more than one value, use {@link #getParameterValues}.
391 * <p>
392 * If this method is used with a multivalued
393 * parameter, the value returned is equal to the first value
394 * in the array returned by <code>getParameterValues</code>.
395 *
396 *
397 *
398 * @param name a <code>String</code> specifying the
399 * name of the parameter
400 *
401 * @return a <code>String</code> representing the
402 * single value of the parameter
403 *
404 * @see #getParameterValues
405 *
406 * @exception java.lang.IllegalArgumentException
407 * if name is <code>null</code>.
408 *
409 */
410
411 public String getParameter(String name);
412
413
414 /***
415 *
416 * Returns an <code>Enumeration</code> of <code>String</code>
417 * objects containing the names of the parameters contained
418 * in this request. If the request has
419 * no parameters, the method returns an
420 * empty <code>Enumeration</code>.
421 * <p>
422 * Only parameters targeted to the current portlet are returned.
423 *
424 *
425 * @return an <code>Enumeration</code> of <code>String</code>
426 * objects, each <code>String</code> containing
427 * the name of a request parameter; or an
428 * empty <code>Enumeration</code> if the
429 * request has no parameters.
430 */
431
432 public java.util.Enumeration getParameterNames();
433
434
435 /***
436 * Returns an array of <code>String</code> objects containing
437 * all of the values the given request parameter has, or
438 * <code>null</code> if the parameter does not exist.
439 * The returned parameters are "x-www-form-urlencoded" decoded.
440 * <p>
441 * If the parameter has a single value, the array has a length
442 * of 1.
443 *
444 *
445 * @param name a <code>String</code> containing the name of
446 * the parameter the value of which is requested
447 *
448 * @return an array of <code>String</code> objects
449 * containing the parameter values.
450 *
451 * @see #getParameter
452 *
453 * @exception java.lang.IllegalArgumentException
454 * if name is <code>null</code>.
455 *
456 */
457
458 public String[] getParameterValues(String name);
459
460
461 /***
462 * Returns a <code>Map</code> of the parameters of this request.
463 * Request parameters are extra information sent with the request.
464 * The returned parameters are "x-www-form-urlencoded" decoded.
465 * <p>
466 * The values in the returned <code>Map</code> are from type
467 * String array (<code>String[]</code>).
468 * <p>
469 * If no parameters exist this method returns an empty <code>Map</code>.
470 *
471 * @return an immutable <code>Map</code> containing parameter names as
472 * keys and parameter values as map values, or an empty <code>Map</code>
473 * if no parameters exist. The keys in the parameter
474 * map are of type String. The values in the parameter map are of type
475 * String array (<code>String[]</code>).
476 */
477
478 public java.util.Map getParameterMap();
479
480
481 /***
482 * Returns a boolean indicating whether this request was made
483 * using a secure channel between client and the portal, such as HTTPS.
484 *
485 * @return true, if the request was made using a secure channel.
486 */
487
488 public boolean isSecure();
489
490
491 /***
492 * Stores an attribute in this request.
493 *
494 * <p>Attribute names should follow the same conventions as
495 * package names. Names beginning with <code>java.*</code>,
496 * <code>javax.*</code>, and <code>com.sun.*</code> are
497 * reserved for use by Sun Microsystems.
498 *<br> If the value passed into this method is <code>null</code>,
499 * the effect is the same as calling {@link #removeAttribute}.
500 *
501 *
502 * @param name a <code>String</code> specifying
503 * the name of the attribute
504 *
505 * @param o the <code>Object</code> to be stored
506 *
507 *
508 * @exception java.lang.IllegalArgumentException
509 * if name is <code>null</code>.
510 */
511
512 public void setAttribute(String name, Object o);
513
514
515 /***
516 *
517 * Removes an attribute from this request. This method is not
518 * generally needed, as attributes only persist as long as the request
519 * is being handled.
520 *
521 * <p>Attribute names should follow the same conventions as
522 * package names. Names beginning with <code>java.*</code>,
523 * <code>javax.*</code>, and <code>com.sun.*</code> are
524 * reserved for use by Sun Microsystems.
525 *
526 * @param name a <code>String</code> specifying
527 * the name of the attribute to be removed
528 *
529 *
530 * @exception java.lang.IllegalArgumentException
531 * if name is <code>null</code>.
532 */
533
534 public void removeAttribute(String name);
535
536
537 /***
538 *
539 * Returns the session ID indicated in the client request.
540 * This session ID may not be a valid one, it may be an old
541 * one that has expired or has been invalidated.
542 * If the client request
543 * did not specify a session ID, this method returns
544 * <code>null</code>.
545 *
546 * @return a <code>String</code> specifying the session
547 * ID, or <code>null</code> if the request did
548 * not specify a session ID
549 *
550 * @see #isRequestedSessionIdValid
551 *
552 */
553
554 public String getRequestedSessionId();
555
556
557 /***
558 *
559 * Checks whether the requested session ID is still valid.
560 *
561 * @return <code>true</code> if this
562 * request has an id for a valid session
563 * in the current session context;
564 * <code>false</code> otherwise
565 *
566 * @see #getRequestedSessionId
567 * @see #getPortletSession
568 */
569
570 public boolean isRequestedSessionIdValid();
571
572
573 /***
574 * Returns the portal preferred content type for the response.
575 * <p>
576 * The content type only includes the MIME type, not the
577 * character set.
578 * <p>
579 * Only content types that the portlet has defined in its
580 * deployment descriptor are valid return values for
581 * this method call. If the portlet has defined
582 * <code>'*'</code> or <code>'* / *'</code> as supported content
583 * types, these may also be valid return values.
584 *
585 * @return preferred MIME type of the response
586 */
587
588 public String getResponseContentType();
589
590
591 /***
592 * Gets a list of content types which the portal accepts for the response.
593 * This list is ordered with the most preferable types listed first.
594 * <p>
595 * The content type only includes the MIME type, not the
596 * character set.
597 * <p>
598 * Only content types that the portlet has defined in its
599 * deployment descriptor are valid return values for
600 * this method call. If the portlet has defined
601 * <code>'*'</code> or <code>'* / *'</code> as supported content
602 * types, these may also be valid return values.
603 *
604 * @return ordered list of MIME types for the response
605 */
606
607 public java.util.Enumeration getResponseContentTypes();
608
609
610 /***
611 * Returns the preferred Locale in which the portal will accept content.
612 * The Locale may be based on the Accept-Language header of the client.
613 *
614 * @return the prefered Locale in which the portal will accept content.
615 */
616
617 public java.util.Locale getLocale();
618
619
620 /***
621 * Returns an Enumeration of Locale objects indicating, in decreasing
622 * order starting with the preferred locale in which the portal will
623 * accept content for this request.
624 * The Locales may be based on the Accept-Language header of the client.
625 *
626 * @return an Enumeration of Locales, in decreasing order, in which
627 * the portal will accept content for this request
628 */
629
630 public java.util.Enumeration getLocales();
631
632
633 /***
634 * Returns the name of the scheme used to make this request.
635 * For example, <code>http</code>, <code>https</code>, or <code>ftp</code>.
636 * Different schemes have different rules for constructing URLs,
637 * as noted in RFC 1738.
638 *
639 * @return a <code>String</code> containing the name
640 * of the scheme used to make this request
641 */
642
643 public String getScheme();
644
645
646 /***
647 * Returns the host name of the server that received the request.
648 *
649 * @return a <code>String</code> containing the name
650 * of the server to which the request was sent
651 */
652
653 public String getServerName();
654
655
656 /***
657 * Returns the port number on which this request was received.
658 *
659 * @return an integer specifying the port number
660 */
661
662 public int getServerPort();
663
664
665
666 }