Fundamentals of Themelia - FallThrough Processors
Friday, June 20, 2008
This documentation has been updated for Themelia Framework 2.0 Beta 5.
After mid processors have executed, Themelia runs an HTTP handler selection algorithm to find the best match for the specific request. If there is no handler match, a fall through processor, if set, catches the route and handles it directly. In a way, you could think of this as being similar to the "default" statement in a C# switch block. If no fall through processor is provided or if all registered fall through processors return null, Themelia defaults to passing the request back to IIS to let if figure out the route.
In the basic Themelia web site sample, there is an authentication HTTP handler which handles /authentication/ and the sample web site also rewrites /login/, /logout/, and /problem/. Now, while we know exactly what happens with these explicitly stated routes, it tells us absolutely nothing about what to do about a request to /contact/. In this scenario, if no fall through processor were set, it would be up to IIS to handle the request. If IIS doesn't have anything for it to do (i.e. there is no /contract/ folder or virtual folder), the end user may receive a 404 error. Actually, this may be exactly what you want sometimes.
A fall through processor is made by creating a class that inherits from Themelia.Web.Routing.FallThroughProcessorBase. This is an abstract class that requires you to implement the following signature. The signature should look very familiar to ASP.NET veterans as it's the same signature used in HTTP handler factories as that's functionally what a fall through processor is.
System.Web.IHttpHandler GetHandler(System.Web.HttpContext context, String requestType, String virtualPath, String path, params Object[] parameterArray);
Fall through processors may be registered in web.config like this:
<themelia.web> <webDomains> <add> <fallThroughProcessors> <add type="Themelia.Web.Routing.ForbiddenFallThroughProcessor, Themelia.Web" /> </fallThroughProcessors> </add> </webDomains> </themelia.web>
There are a few fall through processors provided with Themelia. These are WebFormFallThroughProcessor, ForbiddenFallThroughProcessor, UrlRewriteFallThroughProcessor, PassThroughFallThroughProcessor, and RedirectFallThroughProcessor. If one of these is set, all routes not handled by the Themelia handle selection algorithm will be caught by one of these fall through processors or by a custom one of your own design. Let's run through each of these to go over what value each provides.
The first of the fall through processor I would like to cover here, WebFormFallThroughProcessor, has a fairly obvious purpose: it catches routes and turns them into WebForms. You would use this fall through processor in a scenario where you have major sections (see Themelia Web Domains) of your web site that have nothing but web forms.
The next fall through processor that should be discussed is the ForbiddenFallThroughProcessor. This one essentially ties down all loose ends in your web site. The idea is that, if the HTTP selection algorithm doesn't find a good match for your route, ForbiddenFallThroughProcessor will set the active handler to BlockedHttpHandler, which does exactly what the name suggests: blocks the request. In other words, anything not explicitly stated in Themelia, will be denied. For example, in the sample Themelia web site, /contact/ would show you a big sign reading "This part of the system is not publicly accessible."
The last three fall through processors are specialized processors that have special meaning in their own context. In fact, each is described in detail in their respective sections: PageAlias, PassThrough, and Redirect.
Of course, you can make your own fall through processor as well. Perhaps you want to make something that does nothing more than sends you to you a more exciting 404 page than what people are traditionally used to. It can be anything. If you ever wanted a "catch all" for your web sites, you now have it.
One major example of a fall through processor is in Minima 3.1, which uses its own BlogFallThroughProcessor to handle all unhandled traffic. This is incredibly important since Minima lives off this ability. The BlogFallThroughProcessor will handle every request from /2008/05 to /label/aspnet to /2008/05/Minima-30-Released. Therefore, Minima obviously requires full control over the entire URL to know what information to display.
Fall through processors are also compatible with Themelia processor factories, so feel free to create aliases for each of your fall through processors. The above example, using Themelia's internal processor factory allows you to shorten the configuration to:
<themelia.web> <webDomains> <add> <fallThroughProcessors> <add type="ForbiddenFallThroughProcessor" /> </fallThroughProcessors> </add> </webDomains> </themelia.web>
Fall Through Processor Initialization Parameters
Various features in Themelia have what are called initialization parameters. The ForbiddenFallThroughProcessor, for example, is aware of these parameters and allow you to provide the processor with information it may use at a later time.
Normally, when we set the ForbiddenFallThroughProcessor all requests which hit this processor simply end there with no output. However, by using an initialization parameter we can have the processor display text instead. Here's an example of using an initialization parameter with a fall through processor:
<themelia.web> <webDomains> <add> <fallThroughProcessors> <add type="ForbiddenFallThroughProcessor"> <parameters> <add name="text" value="You do not have access to view this page." /> </parameters> </add> </fallThroughProcessors> </add> </webDomains> </themelia.web>
Initialization parameters follow the "name/value" pattern, but the name portion is often unused. In this case, name is ignored and the value is what's used to display the message.
If you are installing the fall through processor via a Themelia web component, then just set the initialization parameter using the following programmatic syntax:
//- @Register -// public override void Register(FactoryDataList factoryDataList, ProcessorDataList processorDataList, HandlerDataList handlerDataList, AliasDataList aliasDataList, RedirectDataList redirectDataList) { factoryDataList.Add(FactoryData.Create("Sample.Web.Routing.ProcessorFactory, Sample.Web")); }
As a closing note, it's important to note that a handler might not even be set after all fall through processors complete. Of course that's not the case with WebFormFallThroughProcessor and ForbiddenFallThroughProcessor, but if you were to write your own custom fall through processors, you could return null to have the request handled my IIS directly. In fact, if no fall through processor returns any handler, Themelia sets the route to use its magical PassThrough handler, which simply signals Themelia not to handle the request, but to pass it to IIS.
