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   USER_INFO = "javax.portlet.userinfo";
42  
43  
44    /**
45     * String identifier for Basic authentication. Value "BASIC".
46     */
47    public static final String   BASIC_AUTH = "BASIC";
48  
49    /**
50     * String identifier for Form based authentication. Value "FORM".
51     */
52    public static final String   FORM_AUTH = "FORM";
53  
54    /**
55     * String identifier for Certification based authentication. Value "CLIENT_CERT".
56     */
57    public static final String   CLIENT_CERT_AUTH = "CLIENT_CERT";
58  
59    /**
60     * String identifier for Digest based authentication. Value "DIGEST".
61     */
62    public static final String   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   getProperty(String   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   getProperties(String   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   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   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   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   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   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   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   getAttribute(String   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   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   getParameter(String   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   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  [] getParameterValues(String   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   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   name, Object   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   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   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   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   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   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   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   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   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
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags