KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > portlet > PortletRequest


1 /**
2   * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
3   * All rights reserved.
4   * Use is subject to license terms.
5   */

6
7 package javax.portlet;
8
9
10 /**
11  * The <CODE>PortletRequest</CODE> defines the base interface to provide client
12  * request information to a portlet. The portlet container uses two specialized
13  * versions of this interface when invoking a portlet, <CODE>ActionRequest</CODE>
14  * and <CODE>RenderRequest</CODE>. The portlet container creates these objects and
15  * passes them as arguments to the portlet's <CODE>processAction</CODE> and
16  * <CODE>render</CODE> methods.
17  *
18  * @see ActionRequest
19  * @see RenderRequest
20  */

21 public interface PortletRequest
22 {
23
24   /** Used to retrieve user information attributes with the
25    * <code>getAttribute</code> call. The user information is returned
26    * as a <code>Map</code> object. The portlet must define the
27    * user information attribute it is interested in inside the
28    * <code>user-attribute</code> section of the deployment descriptor.
29    * If an attribute is not supported
30    * by the current runtime system it will not show up in the user
31    * attribute map.<BR>
32    * If the user-attribute is supported by the runtime system, but not
33    * defined for a particular user, then for that user the attribute
34    * exists in the returned map and the attribute has a <code>null</code> value.
35    * <p>
36    * If the user-attribute is not defined for the current user it
37    * will not show up in the Map.
38    * <p>
39    * The value is <code>javax.portlet.userinfo</code>.
40    */

41   public static final String JavaDoc USER_INFO = "javax.portlet.userinfo";
42
43
44   /**
45    * String identifier for Basic authentication. Value "BASIC".
46    */

47   public static final String JavaDoc BASIC_AUTH = "BASIC";
48
49   /**
50    * String identifier for Form based authentication. Value "FORM".
51    */

52   public static final String JavaDoc FORM_AUTH = "FORM";
53
54   /**
55    * String identifier for Certification based authentication. Value "CLIENT_CERT".
56    */

57   public static final String JavaDoc CLIENT_CERT_AUTH = "CLIENT_CERT";
58
59   /**
60    * String identifier for Digest based authentication. Value "DIGEST".
61    */

62   public static final String JavaDoc DIGEST_AUTH = "DIGEST";
63
64
65   /**
66    * Returns true, if the given window state is valid
67    * to be set for this portlet in the context
68    * of the current request.
69    *
70    * @param state window state to checked
71    *
72    * @return true, if it is valid for this portlet
73    * in this request to change to the
74    * given window state
75    *
76    */

77   public boolean isWindowStateAllowed(WindowState state);
78
79
80   /**
81    * Returns true, if the given portlet mode is a valid
82    * one to set for this portlet in the context
83    * of the current request.
84    *
85    * @param mode portlet mode to check
86    *
87    * @return true, if it is valid for this portlet
88    * in this request to change to the
89    * given portlet mode
90    *
91    */

92
93   public boolean isPortletModeAllowed(PortletMode mode);
94
95
96   /**
97    * Returns the current portlet mode of the portlet.
98    *
99    * @return the portlet mode
100    */

101
102   public PortletMode getPortletMode ();
103
104
105   /**
106    * Returns the current window state of the portlet.
107    *
108    * @return the window state
109    */

110
111   public WindowState getWindowState ();
112
113
114   /**
115    * Returns the preferences object associated with the portlet.
116    *
117    * @return the portlet preferences
118    */

119   public PortletPreferences getPreferences ();
120
121
122   /**
123    * Returns the current portlet session or, if there is no current session,
124    * creates one and returns the new session.
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    * @return the portlet session
130    */

131
132   public PortletSession getPortletSession ();
133
134
135   /**
136    * Returns the current portlet session or, if there is no current session
137    * and the given flag is <CODE>true</CODE>, creates one and returns
138    * the new session.
139    * <P>
140    * If the given flag is <CODE>false</CODE> and there is no current
141    * portlet session, this method returns <CODE>null</CODE>.
142    * <p>
143    * Creating a new portlet session will result in creating
144    * a new <code>HttpSession</code> on which the portlet session is based on.
145    *
146    * @param create
147    * <CODE>true</CODE> to create a new session, <BR>
148    * <CODE>false</CODE> to return <CODE>null</CODE> if there
149    * is no current session
150    * @return the portlet session
151    */

152
153   public PortletSession getPortletSession (boolean create);
154
155
156   /**
157    * Returns the value of the specified request property
158    * as a <code>String</code>. If the request did not include a property
159    * of the specified name, this method returns <code>null</code>.
160    * <p>
161    * A portlet can access portal/portlet-container specific properties
162    * through this method and, if available, the
163    * headers of the HTTP client request.
164    * <p>
165    * This method should only be used if the
166    * property has only one value. If the property might have
167    * more than one value, use {@link #getProperties}.
168    * <p>
169    * If this method is used with a multivalued
170    * parameter, the value returned is equal to the first value
171    * in the Enumeration returned by <code>getProperties</code>.
172    *
173    * @param name a <code>String</code> specifying the
174    * property name
175    *
176    * @return a <code>String</code> containing the
177    * value of the requested
178    * property, or <code>null</code>
179    * if the request does not
180    * have a property of that name.
181    *
182    * @exception java.lang.IllegalArgumentException
183    * if name is <code>null</code>.
184    */

185
186   public String JavaDoc getProperty(String JavaDoc name);
187
188
189   /**
190    * Returns all the values of the specified request property
191    * as a <code>Enumeration</code> of <code>String</code> objects.
192    * <p>
193    * If the request did not include any propertys
194    * of the specified name, this method returns an empty
195    * <code>Enumeration</code>.
196    * The property name is case insensitive. You can use
197    * this method with any request property.
198    *
199    * @param name a <code>String</code> specifying the
200    * property name
201    *
202    * @return a <code>Enumeration</code> containing
203    * the values of the requested property. If
204    * the request does not have any properties of
205    * that name return an empty <code>Enumeration</code>.
206    *
207    * @exception java.lang.IllegalArgumentException
208    * if name is <code>null</code>.
209    */

210   
211   public java.util.Enumeration JavaDoc getProperties(String JavaDoc name);
212     
213     
214   /**
215    *
216    * Returns a <code>Enumeration</code> of all the property names
217    * this request contains. If the request has no
218    * properties, this method returns an empty <code>Enumeration</code>.
219    *
220    *
221    * @return an <code>Enumeration</code> of all the
222    * property names sent with this
223    * request; if the request has
224    * no properties, an empty <code>Enumeration</code>.
225    */

226
227   public java.util.Enumeration JavaDoc getPropertyNames();
228     
229     
230   /**
231    * Returns the context of the calling portal.
232    *
233    * @return the context of the calling portal
234    */

235
236   public PortalContext getPortalContext();
237
238
239   /**
240    * Returns the name of the authentication scheme used for the
241    * connection between client and portal,
242    * for example, <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
243    * a custom one or <code>null</code> if there was no authentication.
244    *
245    * @return one of the static members <code>BASIC_AUTH</code>,
246    * <code>FORM_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
247    * <code>DIGEST_AUTH</code> (suitable for == comparison)
248    * indicating the authentication scheme,
249    * a custom one, or
250    * <code>null</code> if the request was
251    * not authenticated.
252    */

253
254   public java.lang.String JavaDoc getAuthType();
255   
256
257    /**
258     * Returns the context path which is the path prefix associated with the deployed
259     * portlet application. If the portlet application is rooted at the
260     * base of the web server URL namespace (also known as "default" context),
261     * this path must be an empty string. Otherwise, it must be the path the
262     * portlet application is rooted to, the path must start with a '/' and
263     * it must not end with a '/' character.
264     * <p>
265     * To encode a URL the {@link PortletResponse#encodeURL} method must be used.
266     *
267     * @return a <code>String</code> specifying the
268     * portion of the request URL that indicates the context
269     * of the request
270     *
271     * @see PortletResponse#encodeURL
272     */

273
274   public String JavaDoc getContextPath();
275
276
277   /**
278    * Returns the login of the user making this request, if the user
279    * has been authenticated, or null if the user has not been authenticated.
280    *
281    * @return a <code>String</code> specifying the login
282    * of the user making this request, or <code>null</code>
283    * if the user login is not known.
284    *
285    */

286
287   public java.lang.String JavaDoc getRemoteUser();
288
289
290   /**
291    * Returns a java.security.Principal object containing the name of the
292    * current authenticated user.
293    *
294    * @return a <code>java.security.Principal</code> containing
295    * the name of the user making this request, or
296    * <code>null</code> if the user has not been
297    * authenticated.
298    */

299
300   public java.security.Principal JavaDoc getUserPrincipal();
301
302
303   /**
304    * Returns a boolean indicating whether the authenticated user is
305    * included in the specified logical "role". Roles and role membership can be
306    * defined using deployment descriptors. If the user has not been
307    * authenticated, the method returns <code>false</code>.
308    *
309    * @param role a <code>String</code> specifying the name
310    * of the role
311    *
312    * @return a <code>boolean</code> indicating whether
313    * the user making this request belongs to a given role;
314    * <code>false</code> if the user has not been
315    * authenticated.
316    */

317
318   public boolean isUserInRole(java.lang.String JavaDoc role);
319
320
321   /**
322    *
323    * Returns the value of the named attribute as an <code>Object</code>,
324    * or <code>null</code> if no attribute of the given name exists.
325    * <p>
326    * Attribute names should follow the same conventions as package
327    * names. This specification reserves names matching <code>java.*</code>,
328    * and <code>javax.*</code>.
329    * <p>
330    * In a distributed portlet web application the <code>Object</code>
331    * needs to be serializable.
332    *
333    * @param name a <code>String</code> specifying the name of
334    * the attribute
335    *
336    * @return an <code>Object</code> containing the value
337    * of the attribute, or <code>null</code> if
338    * the attribute does not exist.
339    *
340    * @exception java.lang.IllegalArgumentException
341    * if name is <code>null</code>.
342    *
343    */

344
345   public Object JavaDoc getAttribute(String JavaDoc name);
346
347
348   /**
349    * Returns an <code>Enumeration</code> containing the
350    * names of the attributes available to this request.
351    * This method returns an empty <code>Enumeration</code>
352    * if the request has no attributes available to it.
353    *
354    *
355    * @return an <code>Enumeration</code> of strings
356    * containing the names
357    * of the request attributes, or an empty
358    * <code>Enumeration</code> if the request
359    * has no attributes available to it.
360    */

361   
362   public java.util.Enumeration JavaDoc getAttributeNames();
363
364
365   /**
366    * Returns the value of a request parameter as a <code>String</code>,
367    * or <code>null</code> if the parameter does not exist. Request parameters
368    * are extra information sent with the request. The returned parameter
369    * are "x-www-form-urlencoded" decoded.
370    * <p>
371    * Only parameters targeted to the current portlet are accessible.
372    * <p>
373    * This method should only be used if the
374    * parameter has only one value. If the parameter might have
375    * more than one value, use {@link #getParameterValues}.
376    * <p>
377    * If this method is used with a multivalued
378    * parameter, the value returned is equal to the first value
379    * in the array returned by <code>getParameterValues</code>.
380    *
381    *
382    *
383    * @param name a <code>String</code> specifying the
384    * name of the parameter
385    *
386    * @return a <code>String</code> representing the
387    * single value of the parameter
388    *
389    * @see #getParameterValues
390    *
391    * @exception java.lang.IllegalArgumentException
392    * if name is <code>null</code>.
393    *
394    */

395   
396   public String JavaDoc getParameter(String JavaDoc name);
397
398
399   /**
400    *
401    * Returns an <code>Enumeration</code> of <code>String</code>
402    * objects containing the names of the parameters contained
403    * in this request. If the request has
404    * no parameters, the method returns an
405    * empty <code>Enumeration</code>.
406    * <p>
407    * Only parameters targeted to the current portlet are returned.
408    *
409    *
410    * @return an <code>Enumeration</code> of <code>String</code>
411    * objects, each <code>String</code> containing
412    * the name of a request parameter; or an
413    * empty <code>Enumeration</code> if the
414    * request has no parameters.
415    */

416
417   public java.util.Enumeration JavaDoc getParameterNames();
418
419
420   /**
421    * Returns an array of <code>String</code> objects containing
422    * all of the values the given request parameter has, or
423    * <code>null</code> if the parameter does not exist.
424    * The returned parameters are "x-www-form-urlencoded" decoded.
425    * <p>
426    * If the parameter has a single value, the array has a length
427    * of 1.
428    *
429    *
430    * @param name a <code>String</code> containing the name of
431    * the parameter the value of which is requested
432    *
433    * @return an array of <code>String</code> objects
434    * containing the parameter values.
435    *
436    * @see #getParameter
437    *
438    * @exception java.lang.IllegalArgumentException
439    * if name is <code>null</code>.
440    *
441    */

442
443   public String JavaDoc[] getParameterValues(String JavaDoc name);
444
445
446   /**
447    * Returns a <code>Map</code> of the parameters of this request.
448    * Request parameters are extra information sent with the request.
449    * The returned parameters are "x-www-form-urlencoded" decoded.
450    * <p>
451    * The values in the returned <code>Map</code> are from type
452    * String array (<code>String[]</code>).
453    * <p>
454    * If no parameters exist this method returns an empty <code>Map</code>.
455    *
456    * @return an immutable <code>Map</code> containing parameter names as
457    * keys and parameter values as map values, or an empty <code>Map</code>
458    * if no parameters exist. The keys in the parameter
459    * map are of type String. The values in the parameter map are of type
460    * String array (<code>String[]</code>).
461    */

462
463   public java.util.Map JavaDoc getParameterMap();
464
465
466   /**
467    * Returns a boolean indicating whether this request was made
468    * using a secure channel between client and the portal, such as HTTPS.
469    *
470    * @return true, if the request was made using a secure channel.
471    */

472
473   public boolean isSecure();
474
475
476   /**
477    * Stores an attribute in this request.
478    *
479    * <p>Attribute names should follow the same conventions as
480    * package names. Names beginning with <code>java.*</code>,
481    * <code>javax.*</code>, and <code>com.sun.*</code> are
482    * reserved for use by Sun Microsystems.
483    *<br> If the value passed into this method is <code>null</code>,
484    * the effect is the same as calling {@link #removeAttribute}.
485    *
486    *
487    * @param name a <code>String</code> specifying
488    * the name of the attribute
489    *
490    * @param o the <code>Object</code> to be stored
491    *
492    *
493    * @exception java.lang.IllegalArgumentException
494    * if name is <code>null</code>.
495    */

496   
497   public void setAttribute(String JavaDoc name, Object JavaDoc o);
498
499
500   /**
501    *
502    * Removes an attribute from this request. This method is not
503    * generally needed, as attributes only persist as long as the request
504    * is being handled.
505    *
506    * <p>Attribute names should follow the same conventions as
507    * package names. Names beginning with <code>java.*</code>,
508    * <code>javax.*</code>, and <code>com.sun.*</code> are
509    * reserved for use by Sun Microsystems.
510    *
511    * @param name a <code>String</code> specifying
512    * the name of the attribute to be removed
513    *
514    *
515    * @exception java.lang.IllegalArgumentException
516    * if name is <code>null</code>.
517    */

518
519   public void removeAttribute(String JavaDoc name);
520
521    
522   /**
523    *
524    * Returns the session ID indicated in the client request.
525    * This session ID may not be a valid one, it may be an old
526    * one that has expired or has been invalidated.
527    * If the client request
528    * did not specify a session ID, this method returns
529    * <code>null</code>.
530    *
531    * @return a <code>String</code> specifying the session
532    * ID, or <code>null</code> if the request did
533    * not specify a session ID
534    *
535    * @see #isRequestedSessionIdValid
536    *
537    */

538
539   public String JavaDoc getRequestedSessionId();
540
541
542   /**
543    *
544    * Checks whether the requested session ID is still valid.
545    *
546    * @return <code>true</code> if this
547    * request has an id for a valid session
548    * in the current session context;
549    * <code>false</code> otherwise
550    *
551    * @see #getRequestedSessionId
552    * @see #getPortletSession
553    */

554
555   public boolean isRequestedSessionIdValid();
556
557
558   /**
559    * Returns the portal preferred content type for the response.
560    * <p>
561    * The content type only includes the MIME type, not the
562    * character set.
563    * <p>
564    * Only content types that the portlet has defined in its
565    * deployment descriptor are valid return values for
566    * this method call. If the portlet has defined
567    * <code>'*'</code> or <code>'* / *'</code> as supported content
568    * types, these may also be valid return values.
569    *
570    * @return preferred MIME type of the response
571    */

572
573   public String JavaDoc getResponseContentType();
574
575
576   /**
577    * Gets a list of content types which the portal accepts for the response.
578    * This list is ordered with the most preferable types listed first.
579    * <p>
580    * The content type only includes the MIME type, not the
581    * character set.
582    * <p>
583    * Only content types that the portlet has defined in its
584    * deployment descriptor are valid return values for
585    * this method call. If the portlet has defined
586    * <code>'*'</code> or <code>'* / *'</code> as supported content
587    * types, these may also be valid return values.
588    *
589    * @return ordered list of MIME types for the response
590    */

591
592   public java.util.Enumeration JavaDoc getResponseContentTypes();
593
594
595   /**
596    * Returns the preferred Locale in which the portal will accept content.
597    * The Locale may be based on the Accept-Language header of the client.
598    *
599    * @return the prefered Locale in which the portal will accept content.
600    */

601
602   public java.util.Locale JavaDoc getLocale();
603
604
605   /**
606    * Returns an Enumeration of Locale objects indicating, in decreasing
607    * order starting with the preferred locale in which the portal will
608    * accept content for this request.
609    * The Locales may be based on the Accept-Language header of the client.
610    *
611    * @return an Enumeration of Locales, in decreasing order, in which
612    * the portal will accept content for this request
613    */

614
615   public java.util.Enumeration JavaDoc getLocales();
616
617
618   /**
619    * Returns the name of the scheme used to make this request.
620    * For example, <code>http</code>, <code>https</code>, or <code>ftp</code>.
621    * Different schemes have different rules for constructing URLs,
622    * as noted in RFC 1738.
623    *
624    * @return a <code>String</code> containing the name
625    * of the scheme used to make this request
626    */

627
628   public String JavaDoc getScheme();
629     
630
631   /**
632    * Returns the host name of the server that received the request.
633    *
634    * @return a <code>String</code> containing the name
635    * of the server to which the request was sent
636    */

637
638   public String JavaDoc getServerName();
639     
640     
641   /**
642    * Returns the port number on which this request was received.
643    *
644    * @return an integer specifying the port number
645    */

646
647   public int getServerPort();
648
649     
650
651 }
652
Popular Tags