As promised a few weeks ago, I've created a separate branch,
wicket-1.3-portlet-support, and checked in a first initial version of the new
portlet support.
I also created a bunch of JIRA issues as subtasks under one main
portlet-support issue: https://issues.apache.org/jira/browse/WICKET-647.
To showcase what the portlet support is capable of (and not), I also created a
Jetspeed-2.1.1-beta1 based demo portal installer which can be downloaded from
my apache home. See: https://issues.apache.org/jira/browse/WICKET-658
I'd like to invite all developers and users interested to review this intial
version and the changes on Wicket core required for it.
Note: I've tried to isolate the changes in small commits and recorded them to
specific JIRA issues for easier reviewing.
I'm looking forward to feedback and will start discussing possible further
changes, enhancements and fixes soon on this dev list.
I *do* need your input for that as going anything further than this requires
more expertise than I currently have :)
Regards,
Ate
Ate Douma wrote:
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
