As already mentioned by Eelco a few days ago, I'd like to propose a new plan
for Wicket Portlet support.
Preliminary warning: this mail ended up to be quite long :)
For those of you familiar with the Portlet API some of the following is
probably a bit verbose, but please bear with me.
Good portlet support for Wicket isn't going to be easy and will need quite a few changes/enhancements to the core of the framework and I think it is utmost
important that everyone involved is aware of the reasons behind them to be able to properly evaluate the choices available.
I also want to make clear that I don't consider this proposal to be final, complete or 100% perfect. It will need further refinement and probably major changes
further down the road. Although I have already started with implementing part of this proposal, it is certainly not finished yet and I expect to hit a few
technical road blocks as well.
Any critics, good or bad, I'd very much appreciate and I will try to respond to
them as good as I can.
Note though I'm *not* a hard-core Wicket expert yet so I'll be especially
depending on the review and evaluation from those who are :)
I definitely will welcome simpler/easier/better solutions and I'll be happy to
incorporate them!
One more remark upfront: as the current trunk is now in API freeze mode for the
1.3 release, none of the following will be applied to the current trunk.
Although I am working against the current trunk momentarily, as soon as I get a minimum working version ready I'll create a separate branch off the trunk to
commit my changes. And only after a reasonable working version is established there and is reviewed positively, that branch might be merged back into a future
trunk (> 1.3) for bringing portlet support back into the Wicket core.
Now let me start out by describing the features I personally need for using
Wicket in a portlet environment.
I want to be able to run a Wicket application both as "plain" web application
and as a portlet at the same time (needing only one WAR file).
This means a solution which doesn't require using a portlet specific api but
one transparent and independent of the runtime context.
Furthermore, I want to be able to use as much as possible of all the Wicket
features for Ajax, header contributions and (optionally, possibly) cookies.
But especially those features are going to be difficult to support in a portal independent way as the current Portlet API 1.0 doesn't support any of those,
actually doesn't even allow using them...
The next Portlet Specification 2.0 (JSR-286) will provide much better support for these, but as it isn't available yet we'll be required to use some hacks
and/or portal specific extensions to be able to implement and use them *now*.
Finally, I need to be able to run multiple Wicket portlets on one (web) page, meaning properly isolating their execution/session environments and things like
unique markup id generation/usage across Wicket applications.
Besides these functional requirements, I think we should anticipate as much as
possible on JSR-286 portlet API 2.0.
I'm one of the Expert Group members for JSR-286 and we've doing our best to make life much easier for web framework developers. And while there still will be
limitations difficult to overcome, many of the issues I'll address further down will be "solved" natively by JSR-286.
We currently expect to complete the Portlet Specification 2.0 near the end of this summer, but after that it will still take (quite) some time before most/all
portals will be able to fully support it.
But as I don't want to wait until then I've tried to come up with a temporary/custom solutions which aligns as much as possible to what JSR-286 is going to
deliver natively through the Portlet API 2.0.
Once that happens we should then be able to "swap out"/delete only a few
extension points for proper JSR-286 alignment.
A few JSR-168/JSR-286 pointers:
- JSR-186, Portlet Specification 1.0: http://jcp.org/en/jsr/detail?id=168
- JSR-286, Portlet Specification 2.0: http://jcp.org/en/jsr/detail?id=286
- current early draft (non-official): http://ipc658.inf-swt.uni-jena.de/spec/
(latest rev. 15, d.d. May 24, 2007)
- reference implementation :
http://svn.apache.org/repos/asf/portals/pluto/branches/1.1-286-COMPATIBILITY/
I think there are basically 3 different routes a servlet web framework can take
to provide portlet support:
a) providing a separate native portlet (and therefore partly parallel) api
b) "simulate" the web/servlet environment by dispatching to a servlet or filter; wrapping the servlet context, request and response; intercept response writing
(especially urls and redirects) and rewrite and adapt the output to accommodate to the portlet requirement
c) fully abstract the servlet and portlet differences within the framework and
use separate adaptors for handling each appropriately
Each of these solutions (in their pure form) has its own typical drawbacks
though:
Solution a)
This solution potentially provides the best native support for portlet development as the developer is aware about this environment and can directly use native
portlet features like portlet preferences, window states and portlet modes.
On the other hand, keeping the portlet support functionally in sync with all the features provided for the servlet based development is cumbersome as these
really are different/parallel apis.
Furthermore, getting an application which was developed for the servlet environment running as a portlet will require code changes and possibly a loss of
(major) features if the two apis haven't been properly kept aligned.
The current portlet support in wicket-stuff is based upon this solution.
While its more or less working (albeit still very limited) for wicket 1.2, its
broken and already far behind the current 1.3 trunk.
Solution b)
This solution looks quite straightforward and is used in the Apache Portals
Struts Bridge I wrote already several years ago.
The main advantage of this solution is that it (theoretically) is the least intrusive so that you might be able to use the underlying web framework (almost)
transparently: it even doesn't have to know its running in a portlet environment.
Well, theoretically, if the framework is accommodating enough.
For Struts (1.x) I did have to "hack" into a few areas because it wasn't able to cope with the distinct portlet request phases (action and render), and Struts
(taglibs) write urls directly to the response so for those I had to provide overrides. And of course Struts 1.x didn't have provide Ajax/Web 2.0 features...
Another caveat of this solution is that it is not possible to dispatch to a servlet during the processAction phase of a portlet request, at least not using the
Portlet API 1.0.
But, as a portlet container is formally running on top of (or extending) a servlet container, the underlying servlet container is/should be accessible even if
not through the portlet api.
To solve this problem, I created a generic ServletContextProvider interface
(initially) for the Struts Portlet Bridge a few years ago.
Since then, all open-source portals (and a few commercial ones too) have provided implementations of this interface so in practice you can now use this very
reliably. See also: http://portals.apache.org/bridges
The next Portlet API 2.0 will have this limitation removed so then this
interface/extension won't be needed any more.
But besides this issue, in general if the underlying framework directly writes to the response without using some pluggable url rewriting abstraction; expects
to be sole owner of the (web) page, url and/or session state; and doesn't allow separation of request processing and rendering, it can become quite difficult to
properly "wrap" it in a portlet environment.
Although Wicket already recognizes/supports separate action and render phases, at this
moment it "breaks down" on the other issues...
Wicket really is written to run applications in a servlet environment *only*. And as result the page, url and session state management fully expects to be under
full control of the framework. Well, in a portlet environment this clearly isn't the case and "fixing" that from the outside by only "wrapping" the servlet
environment is going to be quite difficult, if even possible.
Solution c)
This is the solution taken for instance by JSF although its definitely not perfect yet, see JSR-301 (for which I'm also an Expert Group member) which tries to
fix a lot of its current "defects" for running in a portlet context.
The idea is simple: abstract the api and semantic differences of the servlet
and portlet environments in the framework and provide adaptors to handle them.
Well, in practice this isn't so simple, mostly because the servlet environment allows so much more freedom and control: providing only the common denominator
can severely limit what you can do with the framework.
Although Wicket has already abstracted away most of the servlet api for end
users/developers, under the hood it uses it very directly to the fullest extend
:)
So, which solution to choose for the portlet support?
Let me first try to list the most important issues and problems I think needs
to be addressed and/or solved.
Note: this is *my* current list. Others might consider some of these less
important or have other requirements I'm not yet or not fully addressing here.
Please chime in if you think differently or would like to bring up other
problems I might have overlooked.
* Wicket URLs
A Portlet doesn't have an url or path of its own through which it is invoked. For interaction with the user all urls have to be encoded as Portlet render or
action urls which are will be served by the *portal* application, not the Wicket (web) application. On the other hand, resource urls (e.g. for rendering images,
iframe contents etc.) can be used which are going to be served by the Wicket web application directly. But, as the portlet page is served by the portal
application, those resource urls have to be fully qualified (at least web context path relative).
Note: Portlet api 2.0 will add Portlet ResourceURLs to be handled by the
portlet directly.
All Wicket URLs are now (1.3 trunk) encoded as current request *relative* urls,
which thus won't work in the portlet environment.
Furthermore, the Wicket URLs are created and written out *directly* to the
response in implementations of IRequestCodingStrategy, e.g.
WebRequestCodingStrategy and UrlCompressingWebRequestCodingStrategy. Note: I
found a few other classes where (only Ajax?) urls are created and written out
directly too...
* Header contributions
A Portlet doesn't "own" the (web) page its defined on. A Portlet is only allowed to provide its content as a markup fragment to be embedded/aggregated on the
page by the portal. So, formally, a portlet cannot contribute anything like including (external) css or javascript in the head section of a web page. Also note
that usually more than one portlet is running within the same page all using *one* head section ...
Furthermore, the portlet spec allows for "streaming" portals, which means that in theory the head section of a page might even already have been written to the
response before a portlet is invoked to render its content fragment!
Now, in practice not many (open-source) portals are/support "streaming" and a lot of portals *do* support header contributions. But none of that is formally
supported by the portlet specs. Portlet API 2.0 will provide some support for header contributions but most likely only statically (pre)defined. I will still
try to get adding contributions dynamically supported but I don't have high hopes for that right now :(
So, if we want to support header contributions in Wicket (I do), we'll be required to use portal specific extensions or embed/load the contributions directly
from within the body section.
* portlet namespace
Because multiple portlets can run on the same web page, the portlet provides a portlet (window) namespace which is intended to be used as pre/postfix for markup
ids and javascript function & variable names.
Right now, Wicket Component generates the markupId which are only guaranteed to
be unique within the application or at least within the generated page content.
So, when you add multiple (Wicket) portlets to a portal page this might easily
result in javascript runtime errors.
Additionally, the same portlet (instance) might be added more than once to the same page (or to different pages). But the Wicket Session store is keyed off from
the application name and thus multiple portlet windows using the same application might cause Session state interferences. They really need to isolated from
each other to guarantee proper operation.
The portlet specification solves this problem by providing two different
Portlet Session scopes: PORTLET_SCOPE and APPLICATION_SCOPE.
Of course, as a portlet container still runs on top of/extends the servlet
container, there is still only one servlet session (the APPLICATION_SCOPE).
PORTLET_SCOPE attributes are simply stored/isolated in the APPLICATION_SCOPE
(servlet) session using the portlet namespace as prefix.
A simple "trick" which I used for the Apache Portals Struts Bridge to solve this is (optionally) wrapping the servlet session and only provide the PORTLET_SCOPE
attributes to the Struts Servlet. Note: Portlet API 2.0 will provide exactly the same feature as an optional portlet runtime configuration :)
* Ajax support and Wicket Resources
As you might expect already: Portlet API 1.0 doesn't support Ajax at all.
But luckily portlet API 2.0 will, to some extend through its new
serveResource/ResourceURL support.
At least, AFAIK right now probably enough for what is needed/used by Wicket.
Right now there are two different solutions possible:
1) serve the Ajax requests directly through the servlet container of the Wicket
application, not through the portal application
2) use portal specific extensions to directly access the portlet which then can
process/dispatch the Ajax call to Wicket.
Although solution 1) might look like the easiest way out and is mentioned quite often as it doesn't require any portal specific extension, its main limitation
is that it will only work for Ajax requests which don't need to write out portlet urls again (links, new form action urls, etc.).
As soon as you need to update/replace a fragment which contains (or need to
contain) portlet urls, this solution will not work.
And solution 1) has another problem with respect to the PORTLET_SCOPE namespaced portlet session. If the PORTLET_SCOPE session is propagated to the servlet
container, direct web application servlet request urls will have to encode the portlet namespace to be able to "reconnect" to the correct Wicket Session.
And not isolating the servlet session to only see the PORTLET_SCOPE session effectively means you can only use one wicket portlet *window* from the same web
application.
I personally think solution 1) restricts and complicates Ajax support far too much and thus I propose we go for solution 2), especially as Portlet API 2.0 will
be able to support that solution natively through its new serveResource/ResourceURL feature. And AFAIK a lot (if not most) of the existing portals already
provide a similar (proprietary) solution for exactly this use-case: Ajax support.
For Jetspeed-2 (for which I'm also a committer) I know how to do this (using the portlet pipeline) but I have no technical knowledge how other open-source
portals like Liferay, Gridsphere, JBoss, etc. do this. Hopefully other developers familiar with those portals can chime in here?
And I think Wicket Resource requests really should be treated likewise.
I don't know if it is common to render links etc. from Resource requests, but
if so, they *need* to be handled just as Ajax requests.
And the PORTLET_SCOPE session isolation problem applies to Wicket Resource
requests as well.
* Handling the Portlet Action and Render phase and managing the Wicket page URL
The portlet request handling is strictly divided in two phases: action
processing and content rendering.
Besides the limitation of invoking a servlet during processAction (which can be solved using the ServletContextProvider as described above), Portlet API 1.0
also doesn't allow creating portlet URLs during processAction. And *that* is a limitation not easily to hack without deep knowledge of the underlying
portal/portlet container. Note: this limitation will be gone too with Portlet API 2.0.
So, for now the current default Wicket RenderStrategy
IRequestCycleSettings.REDIRECT_BUFFER cannot be used!
For processAction requests, the RenderStrategy needs to be enforced to
RenderStrategy REDIRECT_TO_RENDER and for all other requests to ONE_PASS_RENDER.
As I described earlier, a portlet doesn't have an url or path of its own, but
of course it does know request parameters.
By encoding a WicketURL as a portlet parameter, a Wicket portlet can still
provide/simulate a page url to the Wicket framework.
Furthermore, by storing the final redirect url after processAction as a portlet render parameter, the subsequent render request(s) can also provide this page
url to Wicket. Note though, all these urls need to be made fully qualified urls again and not current page url relative.
The one thing left to handle during processAction is intercepting response.setStatus and response.sendError calls. Those normally would go directly to the
browser but for a portlet environment these need to be captured and somehow "transported" to the render phase to be displayed within the specific portlet window
only.
* Writing Cookies and other response headers
Another area not supported by the Portlet API 1.0 (again: 2.0 will provide some support for this) is writing response headers. The Portlet API 1.0 requires that
anything written to the response headers is ignored.
Now, I haven't deeply investigated yet how much Wicket depends on this (for non-Ajax based responses) so I'm not sure yet if this is a high priority feature to
support right now.
AFAIK, I don't expect to be needing it much, but maybe others do?
If we do want to support his (for non-Ajax based responses) it will require additional portal specific extensions. I know we can support this with Jetspeed-2
but have no idea if/how other (open-source) portals handle this.
For Ajax based requests this won't be a problem as we're going to have those served through direct portlet requests and as such will have full control over the
response.
I think the above list describes the most important issues which needs to be
addressed.
So how to solve these?
After reviewing the current wicket-portlet support at wicket-stuff, I think we
might want to try another (3rd now) try.
As I already mentioned in the beginning, the current portlet support is mostly
based on what I called solution a).
While I think its a very valuable solution when you only need to write native Wicket portlets I also think its going to be difficult to keep the separate
parallel apis aligned both technically and feature wise. Furthermore, for me personally, it prevents me running a Wicket application transparently both in
servlet and portlet environments.
The solution b) I described is one I'm already quite familiar with from my work for the Struts Portlet Bridge and provides the big advantage of allowing to run
a Wicket application both as servlet and portlet.
But, solution b) in its pure form (e.g. fully simulating the portlet
environment) is not very feasible, especially with the current Portlet API 1.0
limitations.
The way the Wicket framework is set up (and very much to my liking, don't misunderstand me here), it is very difficult to plug in the required wrappers at the
right place to handle the above described issues. Wicket isn't a managed framework and uses a lot of hard coded factory methods so "hooking" into the framework
transparently as it is right now is virtually impossible.
But solution c), abstracting out the differences between the servlet and portlet environments isn't perfect either and requires quite some changes under the
hood of the framework and probably will result in a lot of limitations (and frustrations) for both the servlet and portlet environment developers and users...
So, I want to propose a solution d): combining solutions b) and c) and
anticipate as much as possible the upcoming Portlet API 2.0 enhancements.
Now: who didn't see this coming :)
Dispatching from the portlet to a Wicket (servlet)filter brings the big
advantage of running/invoking Wicket natively within the servlet container.
This means that there won't be a need to factor out the servlet api itself and
thus won't require large scale (low level) code changes.
And with Portlet API 2.0, support for features like Cookies and writing response Headers
will come "automatically".
So here comes plan d):
* New org.apache.wicket.protocol.http.portlet.WicketPortlet
The WicketPortlet is configured (using an initParameter) against a specific
filter path, e.g. Wicket WebApplication.
The WicketPortlet maintains a parameter for the current Wicket page url, based
against the filter path (e.g. fully qualified to the context path).
When a request (action, render or direct resource/ajax call) is received by the WicketPortlet, it dispatches it to Wicket as a servlet request using the
provided Wicket page url parameter.
* New org.apache.wicket.protocol.http.portlet.WicketPortletFilter extending
WicketFilter
The WicketPortletFilter first checks if it is a Portlet based request or a
direct browser (servlet) request.
If the request is a direct browser request it simply delegates the request to the
WicketFilter and "normal" Wicket web application handling continues.
This will allow deploying the same Wicket application (with the same web.xml) as a normal web application too (as long as you don't use portlet specific
features within your application).
If the request is dispatched from the WicketPortlet (easily determined from request attributes), the WicketPortletFilter wraps the servlet request and response
objects with specialized portlet environment versions (I probably can copy those almost verbatim from the ones I wrote for the Struts Portlet Bridge).
Furthermore, the Servlet Session object will be wrapped to provide an isolated
PORTLET_SCOPEd session to Wicket to support multiple windows of the same
portlet.
And the RenderStrategy IRequestCycleSettings.REDIRECT_TO_RENDER will have to be
enforced when invoked from portlet processAction, otherwise ONE_PASS_RENDER.
Thereafter, the WicketPortletFilter can let the standard WicketFilter handle the request
as if it were a "normal" web based request.
* new interface org.apache.wicket.request.IRenderContext
I propose a new IRenderContext interface for handling url rewriting, (action) redirecting, providing access to the (portlet) namespace for markup Ids and
isolated session state, and writing HeaderContributions.
For url rewriting, only three methods are needed to support creating Portlet
ActionURLs, Portlet RenderURLs and Resource/Ajax URLs.
The current direct url writing to the response, primarily done in WebRequestCodingStrategy, will have to delegate writing out the final url through one of these
methods. And anywhere Ajax callback urls are written also need to do the same.
A org.apache.wicket.protocol.http.servlet.ServletRenderContext implementation
class will simply pass through these urls.
A org.apache.wicket.protocol.http.portlet.PortletRenderContext implementation class will first make the relative urls fully qualified again and then wrap them
as a parameter on a Portlet ActionURL or RenderURL. And for the Resource/Ajax urls it will require a new IPortletResourceURLFactory interface (see below). For
this interface a portal specific implementation will have to be provided for encoding a direct portlet request url.
Note: this interface and its usage will be fully "hidden" behind the IRenderContext and once Portlet API 2.0 becomes available, it can simply be removed as then
natively supported Portlet ResourceURLs can be created.
Similar, the markupId generated by Component will have to be pre- or post-fixed
by the portlet namespace provided by the PortletRenderContext.
The ServletRenderContext will return an empty string as namespace.
Finally, writing out header contributions (as done in
HtmlHeaderContainer.onComponentTag) should be delegated to this interface as
well. The
PortletRenderContext can handle writing out the contribution through a new IPortletHeaderResponse interface (see below), the ServletRenderContext will simply
write it out to the real response.
The WicketPortletFilter will instantiate (and configure) the appropriate implementation of IRenderContext depending how it is invoked (as servlet or from the
portlet).
* new org.apache.wicket.protocol.http.portlet.IWicketResourceURLFactory
interface
To allow direct portlet requests in an Portlet API 1.0 environment, a portal
specific implementation of this interface will be required.
This interface will extend nothing and depend only on the Portlet API 1.0 to
allow complete freedom for portals how to implement it.
The concrete implementation to be used will have to be loaded by the
WicketPortlet and will be passed on to the WicketPortletFilter as request
attribute.
The WicketPortletFilter can then set it on the PortletRenderContext to be used
for creating Resource/Ajax urls.
This interface will provide one method: String
createResourceURL(PortletContext, PortletRequest, PortletResponse, Map
parameters).
Although this simple factory method isn't feature wise comparable to the Portlet API ResourceURL, it probably is flexible enough for our purpose. If not, it
will be easy enough to improve it until it does.
* new org.apache.wicket.protocol.http.portlet.IPortletHeaderResponse interface
and default EmbeddedPortletHeaderResponse
To be able to support header contributions on different portals, the IPortletHeaderResponse interface will allow to abstract out how header contributions are
written to the response.
A default org.apache.wicket.protocol.http.portlet.EmbeddedPortletHeaderResponse implementation will be provided which should work on all portals and which will
use DHTML/javascript to link in external CSS and javascript libraries and attach bodyOnload handlers.
But, I'd also want to support portals which allow direct header contributions (like Jetspeed-2). For this, a custom IPortletHeaderResponse implementation will
optionally be loaded by WicketPortlet and passed on to WicketPortletFilter similar as done with the IPortletResourceURLFactory.
Note: as I said above, I regrettably expect this one feature not going to be
properly/fully supported by Portlet API 2.0 :(
So, this currently covers my plan d) proposal for Wicket portlet support.
Anyone interested, and still with me at the end of this very long mail, please
take a shot at it and shoot holes in it as much as you can :)
I'll continue with my implementation based on this proposal and will keep you
all posted about my progress!
Thanks for keeping up this far :)
Regards, Ate
