In this article, we're going to discuss a bit more about the configuration library in Quino 2.0. Other entries on this topic have been the articles about Encodo’s configuration library for Quino: <a href="{www-en}/blogs.php?entry_id=412">part I</a>, <a href="{www-en}/blogs.php?entry_id=413">part II</a> and <a href="{www-en}/blogs.php?entry_id=414">part III</a>. The goal of this article is to discuss a concrete example of how we decided whether to use generic type parameters throughout the configuration part of Quino. The meat of that discussion will be in a part 2 because we're going to have to lay some groundwork about the features we want first. (Requirements!) <h>A Surfeit of Generics</h> As of <a href="{www-en}/blogs.php?entry_id=412">Quino 2.0-beta2</a>, the configuration library consisted of a central <c>IApplication</c> interface which has a reference to an IOC container and a list of startup and shutdown actions. As shown in <a href="{www-en}/blogs.php?entry_id=414">part III</a>, these actions no longer have a generic <c>TApplication</c> parameter. This makes it not only much easier to use the framework, but also easier to extend it. In this case, we were able to remove the generic parameter without sacrificing any expressiveness or type-safety. As of beta2, there were still several places where generic <c>TApplication</c> parameters were cluttering the API. Could we perhaps optimize further? Throw out even more complexity without losing anything? <h>Starting up an application</h> One of these places is the actual engine that executes the startup and shutdown actions. This code is a bit trickier than just a simple loop because Quino supports execution in debug mode---without exception-handling---and release mode---with global exception-handling and logging. As with any application that uses an <abbr title="Inversion of Control">IOC</abbr> container, there is a configuration phase, during which the container can be changed and an execution phase, during which the container produces objects but can no longer be re-configured. Until 2.0-beta2, the execution engine was encapsulated in several extension methods called <c>Run()</c>, <c>StartUp()</c> and so on. These methods were generally generic in <c>TApplication</c>. I write "generally" because there were some inconsistencies with extension methods for custom application types like Winform or Console applications. While extension methods can be really useful, this usage was not really appropriate as it violated the open/closed principle. For the final release of Quino, we wanted to move this logic into an <c>IApplicationManager</c> so that applications using Quino could (A) choose their own logic for starting an application and (B) add this startup class to a non-Quino IOC container if they wanted to. <h>Application Execution Modes</h> So far, so good. Before we discuss how to rewrite the application manager/execution engine, we should quickly revisit what exactly this engine is supposed to do. As it turns out, not only do we wnat to make an architectural change to make the design more open for extension, but the basic algorithm for starting an application changed, as well. <pullquote align="right" width="220px">What does it mean to <i>run</i> an application?</pullquote>Quino has always acknowledged and kinda/sorta supported the idea that a single application can be run in different ways. Even an execution that results in immediate failure technically counts as an execution, as a traversal of the state machine defined by the application. If we view an application for the state machine that it is, then every application has at least two terminal nodes: OK and Error. But what does OK mean for an application? In Quino, it means that all startup actions were executed without error and the <c>run()</c> action passed in by the caller was also executed without error. Anything else results in an exception and is shunted to Error. <img attachment="144986.gif" align="left">But is that true, really? Can you think of other ways in which an application could successfully execute without really having failed? For most applications, the answer is yes. Almost every application---and certainly every Quino application---supports a command line. One of the default options for the command line of a Quino application is <c>-h</c>, which shows a manual for the other command-line options. If the application is running in a console, this manual is printed to the console; for a Winform application, a dialog box is shown; and so on. This "help" mode is actually a successful execution of the application that did <i>not</i> result in the main event loop of the application being executed. Thought of in this way, any command-line option that controls application execution could divert the application to another type of terminal node in the state machine. A good example is when an application provides support for importing or exporting data via the command line. <h>"Canceled" Terminal Nodes</h> A terminal node is also not necessarily only <c>Crashed</c> or <c>Ok</c>. Almost any application will also need to have a <c>Canceled</c> mode that is a perfectly valid exit state. For example, <ul> If the application requires a login during execution (startup), but the user aborts authentication If the application supports schema migration, but the user aborts without migrating the schema </ul> These are two ways in which a standard Quino application could run to completion without crashing but without having accomplished any of its main tasks. It ran and it didn't crash, but it also didn't do anything useful. <h>Intermediate Nodes in the Application State Machine</h> This section title sounds a bit pretentious, but that's exactly what we want to discuss here. Instead of having just start and terminal nodes, the Quino startup supports cycles through intermediate nodes as well. What the hell does that mean? It means that some nodes may trigger Quino to <i>restart</i> in a different mode in order to handle a particular kind of error condition that could be <i>repaired</i>.<fn> A concrete example is desperately needed here, I think. The main use of this feature in Quino right now is to support on-the-fly schema-migration without forcing the user to restart the application. This feature has been in Quino from the very beginning and is used almost exclusively by developers during development. The use case to support is as follows: <ol> Developer is running an application Developer make change to the model (or pulls changes from the server) Developer runs the application with a schema-change Application displays migration tool; developer can easily migrate the schema and continue working </ol> This workflow minimizes the amount of trouble that a developer has when either making changes or when integrating changes from other developers. In all cases in which the application model is different from the developer's database schema, it's very quick and easy to upgrade and continue working. <h>"Rescuing" an application in Quino 2.0</h> How does this work internally in Quino 2.0? The application starts up but somehow encounters an error that indicates that a schema migration might be required. This can happen in one of two ways: <ol> The schema-verification step in the standard Quino startup detects a change in the application model vis à vis the data schema Some other part of the startup accesses the database and runs into a <c>DatabaseException</c> that is indicative of a schema-mismatch </ol> In all of these cases, the application that was running throws an <c>ApplicationRestartException</c>, that the standard <c>IApplicationManager</c> implementation knows how to handle. It handles it by shutting down the running application instance and asking the caller to create a new application, but this time one that knows how to handle the situation that caused the exception. Concretely, the exception includes an <c>IApplicationCreationSettings</c> descendant that the caller can use to decide how to customize the application to handle that situation. The manager then runs <i>this new</i> application to completion (or until a new <c>RestartApplicationException</c> is thrown), shuts it down, and asks the caller to create the original application again, to give it another go. In the example above, if the user has successfully migrated the schema, then the application will start on this second attempt. If not, then the manager enters the cycle again, attempting to repair the situation so that it can get to a terminal node. Naturally, the user can cancel the migration and the application also exits gracefully, with a <c>Canceled</c> state. A few examples of possible application execution paths: <ul> Standard => <hl>OK</hl> Standard => <span class="error">Error</span> Standard => <span class="caution">Canceled</span> Standard => Restart => Migrator => Standard => <hl>OK</hl> Standard => Restart => Migrator => <span class="caution">Canceled</span> </ul> The pattern is the same for interactive, client applications as for headless applications like test suites, which attempt migration once and abort if not successful. Applications like web servers or other services will generally only support the OK and Error states and fail when they encounter a <c>RestartApplicationException</c>. Still, it's nice to know that the pattern is there, should you need it. It fits relatively cleanly into the rest of the API without making it more complicated. The caller passes two functions to the <c>IApplicationManager</c>: one to create an application and one to run it. An example from the Quino <c>CodeGeneratorApplication</c> is shown below: <code> internal static void Main() { new ApplicationManager().Run(CreateApplication, GenerateCode); } private static IApplication CreateApplication( IApplicationCreationSettings applicationCreationSettings ) { ... } private static void GenerateCode(IApplication application) { ... } </code> We'll see in the next post what the final API looks like and how we arrived at the final version of that API in Quino 2.0. <hr> <ft>Or <i>rescued</i>, using the nomenclature from Eiffel exception-handling, which actually does something very similar. The exception handling in most languages lets you clean up and move on, but the intent isn't necessarily to re-run the code that failed. In Eiffel, this is exactly how exception-handling works: fix whatever was broken and re-run the original code. Quino now works very much like this as well.</ft>