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
>
>
>
