View Javadoc

1   /*
2    * Copyright 2003,2004 The Apache Software Foundation.
3    * 
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    * 
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    * 
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  /*
17   * This source code implements specifications defined by the Java
18   * Community Process. In order to remain compliant with the specification
19   * DO NOT add / change / or delete method signatures!
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 }