Reply

Wicket 1.2: Control Wicket URLs with URL Mounting

At 10:28 PM on Apr 3, 2006, R.J. Lorimer wrote:

( Disclaimer: This article is one of many in a series devoted to the Java web-application framework, Wicket. If you haven't yet, please see the first article - 'A Little Bit About Wicket' for a comprehensive list of all available articles).

Overview

It seems that the concept of completely controlling the URLs that are generated and consumed by Wicket is a hot topic. I talked about it briefly in this tip (Server-Side State Revisited; Bookmarkable Links) , and that sparked a conversation in the comments about the upcoming feature in Wicket 1.2 . The topic came up again today with the announcement of the release of Wicket 1.2 Beta 3 .

The intention behind controlling the URL could be multiple things. First, being able to adapt URLs is the only way to fit into the expected URLs of a legacy system. Second, the URLs from Wicket are verbose enough that it makes it easier for someone with enough malice to attempt to manipulate the URL to produce unexpected results (although due to Wicket's server state, that is surprisingly difficult). Don't get me wrong, I'm not saying that changing the URL necessarily fills a serious security hole, but it is an extra level of indirection to help mask internal details. Finally, many systems (such as search engines) can be drastically impacted by the shape, length, and stability of URLs - after all, it's no good if changing the internal details (such as a package name for a particular Page class) causes a page of your website to completely lose rank and fall off of search engines (where previously it may have been #1!).

What's Missing in Wicket 1.1

Wicket 1.1 already has support for this type of feature in a limited capacity in the form of page aliases. Page aliases are a handy feature, but they only get you so far; so many of the details of Wicket's URLs are still off limits in Wicket 1.1. At this point (given the imminent release of Wicket 1.2) I don't think it's worth going into too much detail on page aliases.

Some Technical Jargon

Wicket 1.2 has an entire API ( IRequestCodingStrategy ) that is devoted to this new process. These strategies at a high-level basically know two things:

• How to 'decode' a request URL into something that Wicket understands
• How to 'encode' a request target (such as a page) into a request URL

As you can imagine, this interface is used to translate requests from the client into page calls, as well as for converting components (such as PageLinks ) into anchor URLs to be sent back to the client.

Now, if you wanted to, you could replace the IRequestCodingStrategy directly; however in most cases you probably don't need to (and probably wouldn't want to, anyway). If you look a bit more carefully, you'll see that the IRequestCodingStrategy extends the interface IRequestTargetMounter . This API is designed to allow you to plug in individual strategies for unique URL paths. Among other things, this interface has a mount and unmount method that take a path and, in the case of the mount method, also takes yet-another-strategy (the IRequestTargetURLCodingStrategy ) for handling requests towards this particular path.

Using This Stuff

Now that we've gone through the 'nickel' tour of the API, let's discuss practical usage a bit. The first, most straightforward activity we can try is to map a bookmarkable page to something simpler. Previously I discussed that when Wicket generated links to other pages, it did so by adding a request parameter it would use to find that page. I showed that it would produce a URL that looks something like this:

http://localhost:8080/jl/app?wicket:bookmarkablePage=:com.javalobby.tnt.wicket.aloha.AlohaPage

Note that this is actually just a little different than the URL in my older article; this is filled with Wicket-specific identifiers and markup that was added intentionally in Wicket 1.2 as part of an effort to completely isolate the Wicket parameters from the user parameters. Either way, it's fairly clear that Wicket is trying to link to the page 'AlohaPage' - and it's also fairly clear that we're using Wicket.

Mounting this page to a particular URL couldn't be much simpler. The request coding strategy methods have been propogated to the application class, so you don't have to do any complex lookups to get to request coding APIs. In fact, you don't even have to work with the target URL coding strategies in the simplest case. Let's say we wanted to map all calls to AlohaPage to "/home" - in our application 'init' method we can now add this line:

// [in AlohaApplication.init()]
mountBookmarkablePage("/home", AlohaPage.class);

The net result is that navigating to this page presents this URL:

http://localhost:8080/jl/app/home

Much prettier. Now, you may recall that our running 'aloha' example also had a second page that took a URL request parameter. When it is unmapped and we click the link to this page, we're taken to a URL that looks something like this:

http://localhost:8080/jl/app?wicket:bookmarkablePage=:com.javalobby.tnt.wicket.aloha.Page2&productId=1694969292874602935

Let's try mapping this page as well, and then just see what we get:

// [in AlohaApplication.init()]
mountBookmarkablePage("/2", Page2.class);

Here's the net result:

http://localhost:8080/jl/app/2/productId/1694969292874602935

Wow. You'll notice that not only did Wicket use our /2 mapping, but when it came time to apply the request parameter, it implemented a tiered folder structure rather than query parameters. This type of URL has become quite popular in the web world thanks to applications such as radio userland. Amazingly, we somehow managed to do this all with one line.

In reality, this mountBookmarkablePage(...) method is just a convenience method that utilizes a built-in variety of the IRequestTargetURLCodingStrategy that translates URLs into this folder format. This built-in strategy is the BookmarkablePageRequestTargetUrlCodingStrategy , and actually inherits all of the 'forward-slash parameter pathing' from the AbstractRequestTargetUrlCodingStrategy .

If your pages are organized in packages in a way that closely resembles the way you want the URLs to be mapped, and you are happy with the default class name being the leaf of the folder path (e.g. 'Page2' as opposed to '2', and 'AlohaPage' as opposed to 'home') you can use a special form of target URL strategy that works on a per-package basis, rather than a per-class basis. So, let's map the entire page package in our current example:

// [in AlohaApplication.init()]
mount("/main", PackageName.forClass(AlohaPage.class));

What we're doing here is passing a base path and a package so that Wicket knows that all pages in that package should be rooted at that path. Now our urls are now:

http://localhost:8080/jl/app/main/AlohaPage
http://localhost:8080/jl/app/main/Page2/productId/1694969292874602935

Of course, if these URL patterns aren't what you are interested in, or you need to meet some legacy API criteria, you can always implement custom coding strategies by creating your own IRequestTargetURLCodingStrategy . In the event you want to implement your own URL coding strategy, you just need to use the mount method that takes an implementation of the IRequestTargetURLCodingStrategy class. The implementation may drastically vary by what you want to achieve, of course, and can work with any number of request targets.

URL mounting is extensively used by the Wicket request system, and goes far beyond just bookmarkable pages. The extensive details go beyond what's really in scope for this tip; but all sorts of things can be managed through this API.

Until next time,

R.J. Lorimer
Contributing Editor - rj -at- javalobby.org
Author              - http://www.coffee-bytes.com
Software Consultant - http://www.numbersix.com