[Beehive Wiki] Update of "PortletScoping" by RichFeit

[Apache Wiki <wi...@apache.org>]

Dear Wiki user,

You have subscribed to a wiki page or wiki category on "Beehive Wiki" for change notification.

The following page has been changed by RichFeit:
http://wiki.apache.org/beehive/PortletScoping

New page:
== Introduction ==
As underlying support for running NetUI applications within portlets (originally within BEA's proprietary Portal), the idea of ''scoping'' is present throughout the NetUI framework.
 * ''Session Scoping'':  Simple.  It means that things like page flow instances are stored in the session under "scoped" names, which are the usual internal attribute names with a Scope ID (portlet ID) prefix.
 * ''Request Scoping'':  More complicated underneath, but simple in concept: prefix all request parameter and attribute names with the Scope ID (portlet ID).


== Session Scoping ==
=== Details ===
All getting/setting of session-scoped attributes for page flow, page flow nesting stack, shared flow, and JSF backing bean instances uses {{{ScopedServletUtils.getScopedSessionAttrName()}}} to construct the actual session attribute name.  By default, this API returns the attribute name unmodified.  If either of the following two conditions are true, then the Scope ID is prefixed to the attribute name:
  * The current request is a ScopedRequest.  ScopedRequest is a wrapper over ```HttpServletRequest``` that we use when running inside a portal (more details below).
  * A special request parameter (ScopedServletUtils.SCOPE_ID_PARAM) exists.  This is used to support multiple active page flows in the session, usually for multiple browser frames/windows.  It's important to note that the scoping mechanism is exactly the same as what it is for ScopedRequest/Portal, so a browser window using this mechanism could talk to the page flow from a ''portlet'' with the same Scope ID.

=== Future Directions ===
If NetUI changes to go through a NetUI-controlled ''context object'' for things like request/session access, then this context object can be smart about whether to create scoped attribute names.  It would eliminate the need for calling ScopedServletUtils.getScopedSessionAttrName() whenever setting a managed session attribute.

== Request Scoping ==
=== URL Rewriting ===
A portal framework can register a ''URL rewriter'' that will prefix request parameters with the current Scope ID in any page rendered using NetUI tags.  This makes the names unique, and targeted to a particular portlet.  Some examples (assuming a portlet ID of "portletA":
 * {{{<input type="text" name="portletAfoo">}}} instead of {{{<input type="text" name="foo">}}}
 * {{{<a href="/myApp/someurl?portletAbar=someValue}}} instead of {{{<a href="/myApp/someurl?bar=someValue}}}

The URL rewriter may rewrite the URL in other ways, but this is its main function as it relates to scoping.

=== ScopedRequest ===
A portal framework can create a ScopedRequest wrapper around a basic HttpServletRequest in order to decode scoped requests (normally requests that come from a page rewritten with a URL rewriter, above).  The ScopedRequest does two main things:
  * keeps track of a Scope ID (portlet ID)
  * ''filters'' request parameters and attributes to return only ones that have the desired Scope ID.  In the URL rewriter examples above, a ScopedRequest with Scope ID of "portletA" would see request parameters "foo" and "bar", respectively.

In general, a ScopedRequest would be created/initialized by a portal framework in framework code (or even in a Servlet Filter) before NetUI ever sees the request.

=== Future Directions ===
A {{{URLRewriter}}} should be responsible for '''decoding''' scoped parameter names, in addition to its current responsibility for rewriting parameter names to be scoped.  Currently, our ScopedRequest (and the rest of the scoping package) assumes that scoping is done by prefixing the Scope ID to the name.  A portal URL rewriter currently has to know this implicitly.