Request coding strategy

As javadoc for IRequestCodingStrategy says "implementations of this interface are responsible for digesting the incoming request and creating a suitable RequestParameters object for it, as well as creating URL representations for request targets". The default implementation for IRequestCodingStrategy is WebRequestCodingStrategy. You can change it by implementing IRequestCycleProcessor and overriding AbstractRequestCycleProcessor#newRequestCodingStrategy() method.

There are two methods in the IRequestCodingStrategy interface:

RequestParameters decode(Request request);
CharSequence encode(RequestCycle requestCycle, IRequestTarget requestTarget);

The decode() method digests incoming requests and creates RequestParameters. This method is commonly used as it is shown in the diagram on the request overview page, where the method converts data from request to RequestParameters object which is used to determine which IRequestTarget to create.

The encode() method returns the URL that will point to the provided request target. This method is used at render phase by components and it is commonly called by one of the RequestCycle#urlFor(...) methods.

Though it seems from the names of decode() and encode() methods that they are "symmetric", it is not so. The encode() method is more like counterpart for IRequestCycleProcessor#resolve() method, i.e.:

• encode() converts a target into a URL (see RequestCycle#urlFor(...) methods implementation)
• resolve() converts a URL into a target (in the this case URL is presented in the form of RequestParameters).

For example, if there is a bookmarkable link on a page, it will render itself by creating a BookmarkablePageRequestTarget and passing it to encode() method. The produced URL will be shown on the web page and when user requests this URL, resolve() method will create BookmarkablePageRequestTarget.

Besides the above IRequestCodingStrategy also supports mounting (see source code for this example). There are two methods for this in IRequestCodingStrategy:

void mount(IRequestTargetUrlCodingStrategy urlCodingStrategy);
void unmount(String path);

These are methods that are eventually called by WebApplication#mount*() methods and WebApplication#unmount() method. So when you mount bookmarkable page, you actually mount BookmarkablePageRequestTargetUrlCodingStrategy. Mounting itself means that you add implementation of IRequestTargetUrlCodingStrategy (do not confuse it with IRequestCodingStrategy) to the list of strategies in IRequestTargetMounter implementation.

Implementations of IRequestTargetUrlCodingStrategy interface know how to encode and decode request targets to/from a URL. Every strategy has a mount path which can be obtained by getMountPath() method. A strategy also has methods encode() and decode() are "symmetric", i.e.:

• encode() converts a target into a URL
• decode() converts a URL into target (URL here is in the form of RequestParameters)

Both matches() methods are used before encode() and decode() to ensure this instance of IRequestTargetUrlCodingStrategy is applicable:

• for matches(String path) "applicable" generally means that requested URL is the same as the mount path;
• for matches(IRequestTarget) "applicable" generally means that the target links to the page of the same class as the mounted page.

The diagram belows shows how IRequestTargetUrlCodingStrategy is used. In the first case if WebRequestCycleProcessor cannot resolve target itself, it attempts to find IRequestTargetUrlCodingStrategy and delegate resolving to it. In the second case WebRequestCodingStrategy tries to find applicable IRequestTargetUrlCodingStrategy and delegates encoding to it.

Note also targetForRequest(), urlCodingStrategyForPath() and pathForTarget() methods from IRequestTargetMounter interface.