Home » gridsphere-3.1-src » javax.portlet » [javadoc | source]

    1   /**
    2    * Copyright 2003 IBM Corporation and Sun Microsystems, Inc.
    3    * All rights reserved.
    4    * Use is subject to license terms.
    5    */
    6   package javax.portlet;
    7   
    8   /**
    9    * The <CODE>PortletRequest</CODE> defines the base interface to provide client
   10    * request information to a portlet. The portlet container uses two specialized
   11    * versions of this interface when invoking a portlet, <CODE>ActionRequest</CODE>
   12    * and <CODE>RenderRequest</CODE>. The portlet container creates these objects and
   13    * passes them as  arguments to the portlet's <CODE>processAction</CODE> and
   14    * <CODE>render</CODE> methods.
   15    *
   16    * @see ActionRequest
   17    * @see RenderRequest
   18    */
   19   public interface PortletRequest {
   20   
   21       /**
   22        * Used to retrieve user information attributes with the
   23        * <code>getAttribute</code> call. The user information is returned
   24        * as a <code>Map</code> object. The portlet must define the
   25        * user information attribute it is interested in inside the
   26        * <code>user-attribute</code> section of the deployment descriptor.
   27        * If an attribute is not supported
   28        * by the current runtime system it will not show up in the user
   29        * attribute map.<BR>
   30        * If the user-attribute is supported by the runtime system, but not
   31        * defined for a particular user, then for that user the attribute
   32        * exists in the returned map and the attribute has a <code>null</code> value.
   33        * <p/>
   34        * If the user-attribute is not defined for the current user it
   35        * will not show up in the Map.
   36        * <p/>
   37        * The value is <code>javax.portlet.userinfo</code>.
   38        */
   39       public static final String USER_INFO = "javax.portlet.userinfo";
   40   
   41       /**
   42        * String identifier for Basic authentication. Value "BASIC".
   43        */
   44       public static final String BASIC_AUTH = "BASIC";
   45   
   46       /**
   47        * String identifier for Form based authentication. Value "FORM".
   48        */
   49       public static final String FORM_AUTH = "FORM";
   50   
   51       /**
   52        * String identifier for Certification based authentication. Value "CLIENT_CERT".
   53        */
   54       public static final String CLIENT_CERT_AUTH = "CLIENT_CERT";
   55   
   56       /**
   57        * String identifier for Digest based authentication. Value "DIGEST".
   58        */
   59       public static final String DIGEST_AUTH = "DIGEST";
   60   
   61       /**
   62        * Returns true, if the given window state is valid
   63        * to be set for this portlet in the context
   64        * of the current request.
   65        *
   66        * @param state window state to checked
   67        * @return true, if it is valid for this portlet
   68        *         in this request to change to the
   69        *         given window state
   70        */
   71       public boolean isWindowStateAllowed(WindowState state);
   72   
   73       /**
   74        * Returns true, if the given portlet mode is a valid
   75        * one to set for this portlet  in the context
   76        * of the current request.
   77        *
   78        * @param mode portlet mode to check
   79        * @return true, if it is valid for this portlet
   80        *         in this request to change to the
   81        *         given portlet mode
   82        */
   83       public boolean isPortletModeAllowed(PortletMode mode);
   84   
   85       /**
   86        * Returns the current portlet mode of the portlet.
   87        *
   88        * @return the portlet mode
   89        */
   90       public PortletMode getPortletMode();
   91   
   92       /**
   93        * Returns the current window state of the portlet.
   94        *
   95        * @return the window state
   96        */
   97       public WindowState getWindowState();
   98   
   99       /**
  100        * Returns the preferences object associated with the portlet.
  101        *
  102        * @return the portlet preferences
  103        */
  104       public PortletPreferences getPreferences();
  105   
  106       /**
  107        * Returns the current portlet session or, if there is no current session,
  108        * creates one and returns the new session.
  109        * <p/>
  110        * Creating a new portlet session will result in creating
  111        * a new <code>HttpSession</code> on which the portlet session is based on.
  112        *
  113        * @return the portlet session
  114        */
  115       public PortletSession getPortletSession();
  116   
  117   
  118       /**
  119        * Returns the current portlet session or, if there is no current session
  120        * and the given flag is <CODE>true</CODE>, creates one and returns
  121        * the new session.
  122        * <P>
  123        * If the given flag is <CODE>false</CODE> and there is no current
  124        * portlet session, this method returns <CODE>null</CODE>.
  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        * @param create <CODE>true</CODE> to create a new session, <BR>
  130        *               <CODE>false</CODE> to return <CODE>null</CODE> if there
  131        *               is no current session
  132        * @return the portlet session
  133        */
  134   
  135       public PortletSession getPortletSession(boolean create);
  136   
  137   
  138       /**
  139        * Returns the value of the specified request property
  140        * as a <code>String</code>. If the request did not include a property
  141        * of the specified name, this method returns <code>null</code>.
  142        * <p/>
  143        * A portlet can access portal/portlet-container specific properties
  144        * through this method and, if available, the
  145        * headers of the HTTP client request.
  146        * <p/>
  147        * This method should only be used if the
  148        * property has only one value. If the property might have
  149        * more than one value, use {@link #getProperties}.
  150        * <p/>
  151        * If this method is used with a multivalued
  152        * parameter, the value returned is equal to the first value
  153        * in the Enumeration returned by <code>getProperties</code>.
  154        *
  155        * @param name a <code>String</code> specifying the
  156        *             property name
  157        * @throws java.lang.IllegalArgumentException
  158        *          if name is <code>null</code>.
  159        * @return			a <code>String</code> containing the
  160        * value of the requested
  161        * property, or <code>null</code>
  162        * if the request does not
  163        * have a property of that name.
  164        */
  165       public String getProperty(String name);
  166   
  167       /**
  168        * Returns all the values of the specified request property
  169        * as a <code>Enumeration</code> of <code>String</code> objects.
  170        * <p/>
  171        * If the request did not include any propertys
  172        * of the specified name, this method returns an empty
  173        * <code>Enumeration</code>.
  174        * The property name is case insensitive. You can use
  175        * this method with any request property.
  176        *
  177        * @param name a <code>String</code> specifying the
  178        *             property name
  179        * @throws java.lang.IllegalArgumentException
  180        *          if name is <code>null</code>.
  181        * @return		a <code>Enumeration</code> containing
  182        * the values of the requested property. If
  183        * the request does not have any properties of
  184        * that name return an empty <code>Enumeration</code>.
  185        */
  186       public java.util.Enumeration getProperties(String name);
  187   
  188       /**
  189        * Returns a <code>Enumeration</code> of all the property names
  190        * this request contains. If the request has no
  191        * properties, this method returns an empty <code>Enumeration</code>.
  192        *
  193        * @return			an <code>Enumeration</code> of all the
  194        * property names sent with this
  195        * request; if the request has
  196        * no properties, an empty <code>Enumeration</code>.
  197        */
  198       public java.util.Enumeration getPropertyNames();
  199   
  200       /**
  201        * Returns the context of the calling portal.
  202        *
  203        * @return the context of the calling portal
  204        */
  205       public PortalContext getPortalContext();
  206   
  207       /**
  208        * Returns the name of the authentication scheme used for the
  209        * connection between client and portal,
  210        * for example, <code>BASIC_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
  211        * a custom one or <code>null</code> if there was no authentication.
  212        *
  213        * @return		one of the static members <code>BASIC_AUTH</code>,
  214        * <code>FORM_AUTH</code>, <code>CLIENT_CERT_AUTH</code>,
  215        * <code>DIGEST_AUTH</code> (suitable for == comparison)
  216        * indicating the authentication scheme,
  217        * a custom one, or
  218        * <code>null</code> if the request was
  219        * not authenticated.
  220        */
  221       public java.lang.String getAuthType();
  222   
  223       /**
  224        * Returns the context path which is the path prefix associated with the deployed
  225        * portlet application. If the portlet application is rooted at the
  226        * base of the web server URL namespace (also known as "default" context),
  227        * this path must be an empty string. Otherwise, it must be the path the
  228        * portlet application is rooted to, the path must start with a '/' and
  229        * it must not end with a '/' character.
  230        * <p/>
  231        * To encode a URL the {@link PortletResponse#encodeURL} method must be used.
  232        *
  233        * @return		a <code>String</code> specifying the
  234        * portion of the request URL that indicates the context
  235        * of the request
  236        * @see PortletResponse#encodeURL
  237        */
  238       public String getContextPath();
  239   
  240       /**
  241        * Returns the login of the user making this request, if the user
  242        * has been authenticated, or null if the user has not been authenticated.
  243        *
  244        * @return		a <code>String</code> specifying the login
  245        * of the user making this request, or <code>null</code>
  246        * if the user login is not known.
  247        */
  248       public java.lang.String getRemoteUser();
  249   
  250       /**
  251        * Returns a java.security.Principal object containing the name of the
  252        * current authenticated user.
  253        *
  254        * @return		a <code>java.security.Principal</code> containing
  255        * the name of the user making this request, or
  256        * <code>null</code> if the user has not been
  257        * authenticated.
  258        */
  259       public java.security.Principal getUserPrincipal();
  260   
  261       /**
  262        * Returns a boolean indicating whether the authenticated user is
  263        * included in the specified logical "role".  Roles and role membership can be
  264        * defined using deployment descriptors.  If the user has not been
  265        * authenticated, the method returns <code>false</code>.
  266        *
  267        * @param role a <code>String</code> specifying the name
  268        *             of the role
  269        * @return		a <code>boolean</code> indicating whether
  270        * the user making this request belongs to a given role;
  271        * <code>false</code> if the user has not been
  272        * authenticated.
  273        */
  274       public boolean isUserInRole(java.lang.String role);
  275   
  276       /**
  277        * Returns the value of the named attribute as an <code>Object</code>,
  278        * or <code>null</code> if no attribute of the given name exists.
  279        * <p/>
  280        * Attribute names should follow the same conventions as package
  281        * names. This specification reserves names matching <code>java.*</code>,
  282        * and <code>javax.*</code>.
  283        * <p/>
  284        * In a distributed portlet web application the <code>Object</code>
  285        * needs to be serializable.
  286        *
  287        * @param name a <code>String</code> specifying the name of
  288        *             the attribute
  289        * @throws java.lang.IllegalArgumentException
  290        *          if name is <code>null</code>.
  291        * @return		an <code>Object</code> containing the value
  292        * of the attribute, or <code>null</code> if
  293        * the attribute does not exist.
  294        */
  295       public Object getAttribute(String name);
  296   
  297       /**
  298        * Returns an <code>Enumeration</code> containing the
  299        * names of the attributes available to this request.
  300        * This method returns an empty <code>Enumeration</code>
  301        * if the request has no attributes available to it.
  302        *
  303        * @return		an <code>Enumeration</code> of strings
  304        * containing the names
  305        * of the request attributes, or an empty
  306        * <code>Enumeration</code> if the request
  307        * has no attributes available to it.
  308        */
  309       public java.util.Enumeration getAttributeNames();
  310   
  311       /**
  312        * Returns the value of a request parameter as a <code>String</code>,
  313        * or <code>null</code> if the parameter does not exist. Request parameters
  314        * are extra information sent with the request. The returned parameter
  315        * are "x-www-form-urlencoded" decoded.
  316        * <p/>
  317        * Only parameters targeted to the current portlet are accessible.
  318        * <p/>
  319        * This method should only be used if the
  320        * parameter has only one value. If the parameter might have
  321        * more than one value, use {@link #getParameterValues}.
  322        * <p/>
  323        * If this method is used with a multivalued
  324        * parameter, the value returned is equal to the first value
  325        * in the array returned by <code>getParameterValues</code>.
  326        *
  327        * @param name a <code>String</code> specifying the
  328        *             name of the parameter
  329        * @throws java.lang.IllegalArgumentException
  330        *          if name is <code>null</code>.
  331        * @return		a <code>String</code> representing the
  332        * single value of the parameter
  333        * @see #getParameterValues
  334        */
  335       public String getParameter(String name);
  336   
  337       /**
  338        * Returns an <code>Enumeration</code> of <code>String</code>
  339        * objects containing the names of the parameters contained
  340        * in this request. If the request has
  341        * no parameters, the method returns an
  342        * empty <code>Enumeration</code>.
  343        * <p/>
  344        * Only parameters targeted to the current portlet are returned.
  345        *
  346        * @return		an <code>Enumeration</code> of <code>String</code>
  347        * objects, each <code>String</code> containing
  348        * the name of a request parameter; or an
  349        * empty <code>Enumeration</code> if the
  350        * request has no parameters.
  351        */
  352       public java.util.Enumeration getParameterNames();
  353   
  354       /**
  355        * Returns an array of <code>String</code> objects containing
  356        * all of the values the given request parameter has, or
  357        * <code>null</code> if the parameter does not exist.
  358        * The returned parameters are "x-www-form-urlencoded" decoded.
  359        * <p/>
  360        * If the parameter has a single value, the array has a length
  361        * of 1.
  362        *
  363        * @param name a <code>String</code> containing the name of
  364        *             the parameter the value of which is requested
  365        * @throws java.lang.IllegalArgumentException
  366        *          if name is <code>null</code>.
  367        * @return		an array of <code>String</code> objects
  368        * containing the parameter values.
  369        * @see		#getParameter
  370        */
  371       public String[] getParameterValues(String name);
  372   
  373       /**
  374        * Returns a <code>Map</code> of the parameters of this request.
  375        * Request parameters are extra information sent with the request.
  376        * The returned parameters are "x-www-form-urlencoded" decoded.
  377        * <p/>
  378        * The values in the returned <code>Map</code> are from type
  379        * String array (<code>String[]</code>).
  380        * <p/>
  381        * If no parameters exist this method returns an empty <code>Map</code>.
  382        *
  383        * @return an immutable <code>Map</code> containing parameter names as
  384        *         keys and parameter values as map values, or an empty <code>Map</code>
  385        *         if no parameters exist. The keys in the parameter
  386        *         map are of type String. The values in the parameter map are of type
  387        *         String array (<code>String[]</code>).
  388        */
  389       public java.util.Map getParameterMap();
  390   
  391       /**
  392        * Returns a boolean indicating whether this request was made
  393        * using a secure channel between client and the portal, such as HTTPS.
  394        *
  395        * @return true, if the request was made using a secure channel.
  396        */
  397       public boolean isSecure();
  398   
  399       /**
  400        * Stores an attribute in this request.
  401        * <p/>
  402        * <p>Attribute names should follow the same conventions as
  403        * package names. Names beginning with <code>java.*</code>,
  404        * <code>javax.*</code>, and <code>com.sun.*</code> are
  405        * reserved for use by Sun Microsystems.
  406        * <br> If the value passed into this method is <code>null</code>,
  407        * the effect is the same as calling {@link #removeAttribute}.
  408        *
  409        * @param name a <code>String</code> specifying
  410        *             the name of the attribute
  411        * @param o    the <code>Object</code> to be stored
  412        * @throws java.lang.IllegalArgumentException
  413        *          if name is <code>null</code>.
  414        */
  415       public void setAttribute(String name, Object o);
  416   
  417   
  418       /**
  419        * Removes an attribute from this request.  This method is not
  420        * generally needed, as attributes only persist as long as the request
  421        * is being handled.
  422        * <p/>
  423        * <p>Attribute names should follow the same conventions as
  424        * package names. Names beginning with <code>java.*</code>,
  425        * <code>javax.*</code>, and <code>com.sun.*</code> are
  426        * reserved for use by Sun Microsystems.
  427        *
  428        * @param name a <code>String</code> specifying
  429        *             the name of the attribute to be removed
  430        * @throws java.lang.IllegalArgumentException
  431        *          if name is <code>null</code>.
  432        */
  433       public void removeAttribute(String name);
  434   
  435       /**
  436        * Returns the session ID indicated in the client request.
  437        * This session ID may not be a valid one, it may be an old
  438        * one that has expired or has been invalidated.
  439        * If the client request
  440        * did not specify a session ID, this method returns
  441        * <code>null</code>.
  442        *
  443        * @return		a <code>String</code> specifying the session
  444        * ID, or <code>null</code> if the request did
  445        * not specify a session ID
  446        * @see		#isRequestedSessionIdValid
  447        */
  448       public String getRequestedSessionId();
  449   
  450       /**
  451        * Checks whether the requested session ID is still valid.
  452        *
  453        * @return			<code>true</code> if this
  454        * request has an id for a valid session
  455        * in the current session context;
  456        * <code>false</code> otherwise
  457        * @see			#getRequestedSessionId
  458        * @see			#getPortletSession
  459        */
  460       public boolean isRequestedSessionIdValid();
  461   
  462       /**
  463        * Returns the portal preferred content type for the response.
  464        * <p/>
  465        * The content type only includes the MIME type, not the
  466        * character set.
  467        * <p/>
  468        * Only content types that the portlet has defined in its
  469        * deployment descriptor are valid return values for
  470        * this method call. If the portlet has defined
  471        * <code>'*'</code> or <code>'* / *'</code> as supported content
  472        * types, these may also be valid return values.
  473        *
  474        * @return preferred MIME type of the response
  475        */
  476       public String getResponseContentType();
  477   
  478       /**
  479        * Gets a list of content types which the portal accepts for the response.
  480        * This list is ordered with the most preferable types listed first.
  481        * <p/>
  482        * The content type only includes the MIME type, not the
  483        * character set.
  484        * <p/>
  485        * Only content types that the portlet has defined in its
  486        * deployment descriptor are valid return values for
  487        * this method call. If the portlet has defined
  488        * <code>'*'</code> or <code>'* / *'</code> as supported content
  489        * types, these may also be valid return values.
  490        *
  491        * @return ordered list of MIME types for the response
  492        */
  493       public java.util.Enumeration getResponseContentTypes();
  494   
  495   
  496       /**
  497        * Returns the preferred Locale in which the portal will accept content.
  498        * The Locale may be based on the Accept-Language header of the client.
  499        *
  500        * @return the prefered Locale in which the portal will accept content.
  501        */
  502       public java.util.Locale getLocale();
  503   
  504   
  505       /**
  506        * Returns an Enumeration of Locale objects indicating, in decreasing
  507        * order starting with the preferred locale in which the portal will
  508        * accept content for this request.
  509        * The Locales may be based on the Accept-Language header of the client.
  510        *
  511        * @return an Enumeration of Locales, in decreasing order, in which
  512        *         the portal will accept content for this request
  513        */
  514       public java.util.Enumeration getLocales();
  515   
  516   
  517       /**
  518        * Returns the name of the scheme used to make this request.
  519        * For example, <code>http</code>, <code>https</code>, or <code>ftp</code>.
  520        * Different schemes have different rules for constructing URLs,
  521        * as noted in RFC 1738.
  522        *
  523        * @return		a <code>String</code> containing the name
  524        * of the scheme used to make this request
  525        */
  526       public String getScheme();
  527   
  528   
  529       /**
  530        * Returns the host name of the server that received the request.
  531        *
  532        * @return		a <code>String</code> containing the name
  533        * of the server to which the request was sent
  534        */
  535       public String getServerName();
  536   
  537   
  538       /**
  539        * Returns the port number on which this request was received.
  540        *
  541        * @return		an integer specifying the port number
  542        */
  543       public int getServerPort();
  544   
  545   }

Home » gridsphere-3.1-src » javax.portlet » [javadoc | source]