001: /**
002: * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
003: * All rights reserved.
004: * Use is subject to license terms.
005: */package javax.portlet;
006:
007: /**
008: * The <CODE>PortletRequest</CODE> defines the base interface to provide client
009: * request information to a portlet. The portlet container uses two specialized
010: * versions of this interface when invoking a portlet, <CODE>ActionRequest</CODE>
011: * and <CODE>RenderRequest</CODE>. The portlet container creates these objects and
012: * passes them as arguments to the portlet's <CODE>processAction</CODE> and
013: * <CODE>render</CODE> methods.
014: *
015: * @see ActionRequest
016: * @see RenderRequest
017: */
018: public interface PortletRequest {
019:
020: /** Used to retrieve user information attributes with the
021: * <code>getAttribute</code> call. The user information is returned
022: * as a <code>Map</code> object. The portlet must define the
023: * user information attribute it is interested in inside the
024: * <code>user-attribute</code> section of the deployment descriptor.
025: * If an attribute is not supported
026: * by the current runtime system it will not show up in the user
027: * attribute map.<BR>
028: * If the user-attribute is supported by the runtime system, but not
029: * defined for a particular user, then for that user the attribute
030: * exists in the returned map and the attribute has a <code>null</code> value.
031: * <p>
032: * If the user-attribute is not defined for the current user it
033: * will not show up in the Map.
034: * <p>
035: * The value is <code>javax.portlet.userinfo</code>.
036: */
037: public static final String USER_INFO = "javax.portlet.userinfo";
038:
039: /**
040: * String identifier for Basic authentication. Value "BASIC".
041: */
042: public static final String BASIC_AUTH = "BASIC";
043:
044: /**
045: * String identifier for Form based authentication. Value "FORM".
046: */
047: public static final String FORM_AUTH = "FORM";
048:
049: /**
050: * String identifier for Certification based authentication. Value "CLIENT_CERT".
051: */
052: public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
053:
054: /**
055: * String identifier for Digest based authentication. Value "DIGEST".
056: */
057: public static final String DIGEST_AUTH = "DIGEST";
058:
059: /**
060: * Returns true, if the given window state is valid
061: * to be set for this portlet in the context
062: * of the current request.
063: *
064: * @param state window state to checked
065: *
066: * @return true, if it is valid for this portlet
067: * in this request to change to the
068: * given window state
069: *
070: */
071: public boolean isWindowStateAllowed(WindowState state);
072:
073: /**
074: * Returns true, if the given portlet mode is a valid
075: * one to set for this portlet in the context
076: * of the current request.
077: *
078: * @param mode portlet mode to check
079: *
080: * @return true, if it is valid for this portlet
081: * in this request to change to the
082: * given portlet mode
083: *
084: */
085:
086: public boolean isPortletModeAllowed(PortletMode mode);
087:
088: /**
089: * Returns the current portlet mode of the portlet.
090: *
091: * @return the portlet mode
092: */
093:
094: public PortletMode getPortletMode();
095:
096: /**
097: * Returns the current window state of the portlet.
098: *
099: * @return the window state
100: */
101:
102: public WindowState getWindowState();
103:
104: /**
105: * Returns the preferences object associated with the portlet.
106: *
107: * @return the portlet preferences
108: */
109: public PortletPreferences getPreferences();
110:
111: /**
112: * Returns the current portlet session or, if there is no current session,
113: * creates one and returns the new session.
114: * <p>
115: * Creating a new portlet session will result in creating
116: * a new <code>HttpSession</code> on which the portlet session is based on.
117: *
118: * @return the portlet session
119: */
120:
121: public PortletSession getPortletSession();
122:
123: /**
124: * Returns the current portlet session or, if there is no current session
125: * and the given flag is <CODE>true</CODE>, creates one and returns
126: * the new session.
127: * <P>
128: * If the given flag is <CODE>false</CODE> and there is no current
129: * portlet session, this method returns <CODE>null</CODE>.
130: * <p>
131: * Creating a new portlet session will result in creating
132: * a new <code>HttpSession</code> on which the portlet session is based on.
133: *
134: * @param create
135: * <CODE>true</CODE> to create a new session, <BR>
136: * <CODE>false</CODE> to return <CODE>null</CODE> if there
137: * is no current session
138: * @return the portlet session
139: */
140:
141: public PortletSession getPortletSession(boolean create);
142:
143: /**
144: * Returns the value of the specified request property
145: * as a <code>String</code>. If the request did not include a property
146: * of the specified name, this method returns <code>null</code>.
147: * <p>
148: * A portlet can access portal/portlet-container specific properties
149: * through this method and, if available, the
150: * headers of the HTTP client request.
151: * <p>
152: * This method should only be used if the
153: * property has only one value. If the property might have
154: * more than one value, use {@link #getProperties}.
155: * <p>
156: * If this method is used with a multivalued
157: * parameter, the value returned is equal to the first value
158: * in the Enumeration returned by <code>getProperties</code>.
159: *
160: * @param name a <code>String</code> specifying the
161: * property name
162: *
163: * @return a <code>String</code> containing the
164: * value of the requested
165: * property, or <code>null</code>
166: * if the request does not
167: * have a property of that name.
168: *
169: * @exception java.lang.IllegalArgumentException
170: * if name is <code>null</code>.
171: */
172:
173: public String getProperty(String name);
174:
175: /**
176: * Returns all the values of the specified request property
177: * as a <code>Enumeration</code> of <code>String</code> objects.
178: * <p>
179: * If the request did not include any propertys
180: * of the specified name, this method returns an empty
181: * <code>Enumeration</code>.
182: * The property name is case insensitive. You can use
183: * this method with any request property.
184: *
185: * @param name a <code>String</code> specifying the
186: * property name
187: *
188: * @return a <code>Enumeration</code> containing
189: * the values of the requested property. If
190: * the request does not have any properties of
191: * that name return an empty <code>Enumeration</code>.
192: *
193: * @exception java.lang.IllegalArgumentException
194: * if name is <code>null</code>.
195: */
196:
197: public java.util.Enumeration getProperties(String name);
198:
199: /**
200: *
201: * Returns a <code>Enumeration</code> of all the property names
202: * this request contains. If the request has no
203: * properties, this method returns an empty <code>Enumeration</code>.
204: *
205: *
206: * @return an <code>Enumeration</code> of all the
207: * property names sent with this
208: * request; if the request has
209: * no properties, an empty <code>Enumeration</code>.
210: */
211:
212: public java.util.Enumeration getPropertyNames();
213:
214: /**
215: * Returns the context of the calling portal.
216: *
217: * @return the context of the calling portal
218: */
219:
220: public PortalContext getPortalContext();
221:
222: /**
223: * Returns the name of the authentication scheme used for the
224: * connection between client and portal,
225: * for example, <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
226: * a custom one or <code>null</code> if there was no authentication.
227: *
228: * @return one of the static members <code>BASIC_AUTH</code>,
229: * <code>FORM_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
230: * <code>DIGEST_AUTH</code> (suitable for == comparison)
231: * indicating the authentication scheme,
232: * a custom one, or
233: * <code>null</code> if the request was
234: * not authenticated.
235: */
236:
237: public java.lang.String getAuthType();
238:
239: /**
240: * Returns the context path which is the path prefix associated with the deployed
241: * portlet application. If the portlet application is rooted at the
242: * base of the web server URL namespace (also known as "default" context),
243: * this path must be an empty string. Otherwise, it must be the path the
244: * portlet application is rooted to, the path must start with a '/' and
245: * it must not end with a '/' character.
246: * <p>
247: * To encode a URL the {@link PortletResponse#encodeURL} method must be used.
248: *
249: * @return a <code>String</code> specifying the
250: * portion of the request URL that indicates the context
251: * of the request
252: *
253: * @see PortletResponse#encodeURL
254: */
255:
256: public String getContextPath();
257:
258: /**
259: * Returns the login of the user making this request, if the user
260: * has been authenticated, or null if the user has not been authenticated.
261: *
262: * @return a <code>String</code> specifying the login
263: * of the user making this request, or <code>null</code>
264: * if the user login is not known.
265: *
266: */
267:
268: public java.lang.String getRemoteUser();
269:
270: /**
271: * Returns a java.security.Principal object containing the name of the
272: * current authenticated user.
273: *
274: * @return a <code>java.security.Principal</code> containing
275: * the name of the user making this request, or
276: * <code>null</code> if the user has not been
277: * authenticated.
278: */
279:
280: public java.security.Principal getUserPrincipal();
281:
282: /**
283: * Returns a boolean indicating whether the authenticated user is
284: * included in the specified logical "role". Roles and role membership can be
285: * defined using deployment descriptors. If the user has not been
286: * authenticated, the method returns <code>false</code>.
287: *
288: * @param role a <code>String</code> specifying the name
289: * of the role
290: *
291: * @return a <code>boolean</code> indicating whether
292: * the user making this request belongs to a given role;
293: * <code>false</code> if the user has not been
294: * authenticated.
295: */
296:
297: public boolean isUserInRole(java.lang.String role);
298:
299: /**
300: *
301: * Returns the value of the named attribute as an <code>Object</code>,
302: * or <code>null</code> if no attribute of the given name exists.
303: * <p>
304: * Attribute names should follow the same conventions as package
305: * names. This specification reserves names matching <code>java.*</code>,
306: * and <code>javax.*</code>.
307: * <p>
308: * In a distributed portlet web application the <code>Object</code>
309: * needs to be serializable.
310: *
311: * @param name a <code>String</code> specifying the name of
312: * the attribute
313: *
314: * @return an <code>Object</code> containing the value
315: * of the attribute, or <code>null</code> if
316: * the attribute does not exist.
317: *
318: * @exception java.lang.IllegalArgumentException
319: * if name is <code>null</code>.
320: *
321: */
322:
323: public Object getAttribute(String name);
324:
325: /**
326: * Returns an <code>Enumeration</code> containing the
327: * names of the attributes available to this request.
328: * This method returns an empty <code>Enumeration</code>
329: * if the request has no attributes available to it.
330: *
331: *
332: * @return an <code>Enumeration</code> of strings
333: * containing the names
334: * of the request attributes, or an empty
335: * <code>Enumeration</code> if the request
336: * has no attributes available to it.
337: */
338:
339: public java.util.Enumeration getAttributeNames();
340:
341: /**
342: * Returns the value of a request parameter as a <code>String</code>,
343: * or <code>null</code> if the parameter does not exist. Request parameters
344: * are extra information sent with the request. The returned parameter
345: * are "x-www-form-urlencoded" decoded.
346: * <p>
347: * Only parameters targeted to the current portlet are accessible.
348: * <p>
349: * This method should only be used if the
350: * parameter has only one value. If the parameter might have
351: * more than one value, use {@link #getParameterValues}.
352: * <p>
353: * If this method is used with a multivalued
354: * parameter, the value returned is equal to the first value
355: * in the array returned by <code>getParameterValues</code>.
356: *
357: *
358: *
359: * @param name a <code>String</code> specifying the
360: * name of the parameter
361: *
362: * @return a <code>String</code> representing the
363: * single value of the parameter
364: *
365: * @see #getParameterValues
366: *
367: * @exception java.lang.IllegalArgumentException
368: * if name is <code>null</code>.
369: *
370: */
371:
372: public String getParameter(String name);
373:
374: /**
375: *
376: * Returns an <code>Enumeration</code> of <code>String</code>
377: * objects containing the names of the parameters contained
378: * in this request. If the request has
379: * no parameters, the method returns an
380: * empty <code>Enumeration</code>.
381: * <p>
382: * Only parameters targeted to the current portlet are returned.
383: *
384: *
385: * @return an <code>Enumeration</code> of <code>String</code>
386: * objects, each <code>String</code> containing
387: * the name of a request parameter; or an
388: * empty <code>Enumeration</code> if the
389: * request has no parameters.
390: */
391:
392: public java.util.Enumeration getParameterNames();
393:
394: /**
395: * Returns an array of <code>String</code> objects containing
396: * all of the values the given request parameter has, or
397: * <code>null</code> if the parameter does not exist.
398: * The returned parameters are "x-www-form-urlencoded" decoded.
399: * <p>
400: * If the parameter has a single value, the array has a length
401: * of 1.
402: *
403: *
404: * @param name a <code>String</code> containing the name of
405: * the parameter the value of which is requested
406: *
407: * @return an array of <code>String</code> objects
408: * containing the parameter values.
409: *
410: * @see #getParameter
411: *
412: * @exception java.lang.IllegalArgumentException
413: * if name is <code>null</code>.
414: *
415: */
416:
417: public String[] getParameterValues(String name);
418:
419: /**
420: * Returns a <code>Map</code> of the parameters of this request.
421: * Request parameters are extra information sent with the request.
422: * The returned parameters are "x-www-form-urlencoded" decoded.
423: * <p>
424: * The values in the returned <code>Map</code> are from type
425: * String array (<code>String[]</code>).
426: * <p>
427: * If no parameters exist this method returns an empty <code>Map</code>.
428: *
429: * @return an immutable <code>Map</code> containing parameter names as
430: * keys and parameter values as map values, or an empty <code>Map</code>
431: * if no parameters exist. The keys in the parameter
432: * map are of type String. The values in the parameter map are of type
433: * String array (<code>String[]</code>).
434: */
435:
436: public java.util.Map getParameterMap();
437:
438: /**
439: * Returns a boolean indicating whether this request was made
440: * using a secure channel between client and the portal, such as HTTPS.
441: *
442: * @return true, if the request was made using a secure channel.
443: */
444:
445: public boolean isSecure();
446:
447: /**
448: * Stores an attribute in this request.
449: *
450: * <p>Attribute names should follow the same conventions as
451: * package names. Names beginning with <code>java.*</code>,
452: * <code>javax.*</code>, and <code>com.sun.*</code> are
453: * reserved for use by Sun Microsystems.
454: *<br> If the value passed into this method is <code>null</code>,
455: * the effect is the same as calling {@link #removeAttribute}.
456: *
457: *
458: * @param name a <code>String</code> specifying
459: * the name of the attribute
460: *
461: * @param o the <code>Object</code> to be stored
462: *
463: *
464: * @exception java.lang.IllegalArgumentException
465: * if name is <code>null</code>.
466: */
467:
468: public void setAttribute(String name, Object o);
469:
470: /**
471: *
472: * Removes an attribute from this request. This method is not
473: * generally needed, as attributes only persist as long as the request
474: * is being handled.
475: *
476: * <p>Attribute names should follow the same conventions as
477: * package names. Names beginning with <code>java.*</code>,
478: * <code>javax.*</code>, and <code>com.sun.*</code> are
479: * reserved for use by Sun Microsystems.
480: *
481: * @param name a <code>String</code> specifying
482: * the name of the attribute to be removed
483: *
484: *
485: * @exception java.lang.IllegalArgumentException
486: * if name is <code>null</code>.
487: */
488:
489: public void removeAttribute(String name);
490:
491: /**
492: *
493: * Returns the session ID indicated in the client request.
494: * This session ID may not be a valid one, it may be an old
495: * one that has expired or has been invalidated.
496: * If the client request
497: * did not specify a session ID, this method returns
498: * <code>null</code>.
499: *
500: * @return a <code>String</code> specifying the session
501: * ID, or <code>null</code> if the request did
502: * not specify a session ID
503: *
504: * @see #isRequestedSessionIdValid
505: *
506: */
507:
508: public String getRequestedSessionId();
509:
510: /**
511: *
512: * Checks whether the requested session ID is still valid.
513: *
514: * @return <code>true</code> if this
515: * request has an id for a valid session
516: * in the current session context;
517: * <code>false</code> otherwise
518: *
519: * @see #getRequestedSessionId
520: * @see #getPortletSession
521: */
522:
523: public boolean isRequestedSessionIdValid();
524:
525: /**
526: * Returns the portal preferred content type for the response.
527: * <p>
528: * The content type only includes the MIME type, not the
529: * character set.
530: * <p>
531: * Only content types that the portlet has defined in its
532: * deployment descriptor are valid return values for
533: * this method call. If the portlet has defined
534: * <code>'*'</code> or <code>'* / *'</code> as supported content
535: * types, these may also be valid return values.
536: *
537: * @return preferred MIME type of the response
538: */
539:
540: public String getResponseContentType();
541:
542: /**
543: * Gets a list of content types which the portal accepts for the response.
544: * This list is ordered with the most preferable types listed first.
545: * <p>
546: * The content type only includes the MIME type, not the
547: * character set.
548: * <p>
549: * Only content types that the portlet has defined in its
550: * deployment descriptor are valid return values for
551: * this method call. If the portlet has defined
552: * <code>'*'</code> or <code>'* / *'</code> as supported content
553: * types, these may also be valid return values.
554: *
555: * @return ordered list of MIME types for the response
556: */
557:
558: public java.util.Enumeration getResponseContentTypes();
559:
560: /**
561: * Returns the preferred Locale in which the portal will accept content.
562: * The Locale may be based on the Accept-Language header of the client.
563: *
564: * @return the prefered Locale in which the portal will accept content.
565: */
566:
567: public java.util.Locale getLocale();
568:
569: /**
570: * Returns an Enumeration of Locale objects indicating, in decreasing
571: * order starting with the preferred locale in which the portal will
572: * accept content for this request.
573: * The Locales may be based on the Accept-Language header of the client.
574: *
575: * @return an Enumeration of Locales, in decreasing order, in which
576: * the portal will accept content for this request
577: */
578:
579: public java.util.Enumeration getLocales();
580:
581: /**
582: * Returns the name of the scheme used to make this request.
583: * For example, <code>http</code>, <code>https</code>, or <code>ftp</code>.
584: * Different schemes have different rules for constructing URLs,
585: * as noted in RFC 1738.
586: *
587: * @return a <code>String</code> containing the name
588: * of the scheme used to make this request
589: */
590:
591: public String getScheme();
592:
593: /**
594: * Returns the host name of the server that received the request.
595: *
596: * @return a <code>String</code> containing the name
597: * of the server to which the request was sent
598: */
599:
600: public String getServerName();
601:
602: /**
603: * Returns the port number on which this request was received.
604: *
605: * @return an integer specifying the port number
606: */
607:
608: public int getServerPort();
609:
610: }
|