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