...

The new way in Wicket 1.5

org.apache.wicket.request.target.coding.IRequestTargetUrlCodingStrategy interface and all its implementations are replaced with the org.apache.wicket.request.IRequestMapper and its respective implementations.

To add a mapper into the list of mappers which Wicket will use to process a request use org.apache.wicket.Application.getRootRequestMapperAsCompound().add(mapperInstance).
When a request comes Wicket will ask all registered mappers whether they are able to process the request. Mappers with bigger org.apache.wicket.request.IRequestMapper.getCompatibilityScore(Request) are asked first. So Wicket calls org.apache.wicket.request.IRequestMapper.mapRequest(Request) for each mapper and if it returns non-null IRequestHandler then this is the handler which will be used to process the current request. In #mapRequest #mapRequest(Request) the mapper have to check request's segments (this is similar to httpServletRequest#getPath()) and request's parameters (get GET and postPOST) and decide whether they match to the mapper's functionality. For example org.apache.wicket.request.mapper.HomePageMapper is the mapper used to process the requests for all requests without any segments, i.e. requests to '/' with or without any query parameters.
The actual processing of the request is being done with org.apache.wicket.request.IRequestHandler.respond(IRequestCycle). During the processing Wicket will ask asks the mappers to create a org.apache.wicket.request.Url objects for each callback handler (e.g. link, form, ....) via org.apache.wicket.request.IRequestMapper.mapHandler(IRequestHandler).

Sometimes you may want a specific IRequestMapper to be process all incoming requests. To do this you should use org.apache.wicket.Application.setRootRequestMapper(IRequestMapper). This mapper may manipulate the Request's Url and then pass it for further processing to the registered non-root mappers. For examples of this idea see the source code of org.apache.wicket.request.mapper.CryptoMapper and org.apache.wicket.protocol.https.HttpsMapper

Default mapper implementations

...

public void init() {
	super.init();

	getRootRequestMapperAsCompound().add(new MountedMapper("/mount/point", MyPage.class));
	mountPage("/mount/point", MyPage.class); // convenient method doing the same as above
}

This mapper is a combination of all IRequestTargetUrlCodingStrategy implementations from Wicket 1.4. It supports:

1. Indexed parameters:
   mountPage("/page", MyPage.class);
   Now a request to "/page/a/b/c" will be handled by MyPage and the parameters can be get with PageParameters.get(int) (e.g. parameters.get(2) will return "c")

1. Named parameters:
   mountPage("/page/${named1}/${named2}", MyPage.class);
   Now a request to "/page/a/b" will be handled by MyPage and the parameters can be get with PageParameters.get(String) (e.g. parameters.get("named1") will return "a")

1. Optional named parameters:
   mountPage("/page/${named1}/#{named2}", MyPage.class);
   This means the second parameter is optional. Requests to "/page/a/b" and "/page/a" will be handled by MyPage and the parameters can be get with PageParameters.get(String) (e.g. parameters.get("named2") will return "b" for the first case and null for the second).
   The mapper is smart enough to handle optional named parameters in any segment, not just the last one.

1. Query parameters:
   mountPage("/page", MyPage.class);
   Now a request to "/page?a=a1&b=b1" will be handled by MyPage and the parameters can be get with PageParameters.get(String) (e.g. parameters.get("a") will return "a1")

The mapper can handle a mix of the supported parameters - indexed + named + query.

PackageMapper

This mapper can mount a whole package. That is you mount a single page with a mount path prefix and then the mapper knows how to map all Page implementations in that package.

...