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