Mach II Development Guide - Concepts & Core Files

Release 1.2.1 (4/14/2005)

Contents | Application Structure & Design »

Printable Version

Concepts & Core Files

This section explains the concepts in the framework and describes how to access the core files. Much of this information is taken from my Mach II Concepts page.

MVC - Model-View-Controller

The first concept is MVC - Model-View-Controller - where the presentation (View) is completely separated from your business logic (Model) and interactions between the two are handled by Mach II itself (Controller). The Views are simply .cfm files that render HTML - presentation code - and can make use of request scope variables and an event object (set by Mach II - more below). The Model is a set of ColdFusion Components (CFCs) that represent all the logic of your application, from the database interaction to the business rules and decisions. The Controller is, essentially, Mach II itself and the parameters of the Controller are defined by the mach-ii.xml file.

Mach II has a slight grey area between the Model and the Controller. The framework has the concept of "listeners" which are CFCs that extend the framework and provide the glue between the core Controller and the core Model. These listener CFCs can be considered part of the Model or part of the Controller depending on how you like to structure your applications but best practice suggests you should keep your Model independent of the framework (so that it is easier to reuse for Web Services, Flash Remoting or even within another framework). The section on Designing Models has more information about this.

Implicit Invocation Architecture

The second concept is the Implicit Invocation Architecture on which Mach II is based. You can read more about this on the Mach II website (Ben Edwards has a great paper on this). The basic premise is that events are generated (by the user or by the application) and they are handled by, well, event handlers. The event handlers respond to the events by performing business logic and sometimes generating more events. Mach II keeps track of the active events and processes them, invoking listeners as necessary and rendering views until each each request is fully processed.

Design Patterns

These guidelines mention several design patterns (e.g., Session Façade, Memento, Transfer Object). Here are some good references on design patterns:

• Sun's Core J2EE Patterns Catalog (includes Composite View, Session Façade, Transfer Object)
• Martin Fowler's Catalog of Patterns of Enterprise Application Architecture (including Model-View-Controller, Gateway)
• Portland Pattern Repository's Wiki - Pattern Index (including Memento and many others)

Mach II Core Files

The framework is a collection of ColdFusion Components under the MachII directory. That directory can be installed under your ColdFusion document root or on a Custom Tag Path defined in the ColdFusion Administrator. At Macromedia, the MachII directory is under CVS at:

{cfmxroot}/extensions/components/MachII/

Your application index.cfm file (under {cfmxroot}/wwwroot/{appname}/) simply includes the mach-ii.cfm core file (using a mapping to the MachII directory, if Mach II is installed outside the web root):

<cfinclude template="/MachII/mach-ii.cfm" />

Prior to including the mach-ii.cfm file, you can set your own values for MACHII_CONFIG_MODE, MACHII_CONFIG_PATH and, if needed, MACHII_APP_KEY. By default, the mach-ii.cfm core file uses the directory in which the request originated ({appname} in our example) as a key into application scope to store that application's instance of the framework objects. That can be overridden by setting MACHII_APP_KEY in index.cfm (but is not generally recommended).

The mach-ii.cfm core file by default looks for ./config/mach-ii.xml (relative to the {appname} directory), which it uses to initialize the framework for that application. That path can be overridden by setting MACHII_CONFIG_PATH in index.cfm. For security purposes, it is recommended that you place your mach-ii.xml file outside your document root so that it cannot be accessed through a web browser. At Macromedia, we override MACHII_CONFIG_PATH as follows:

<cfset MACHII_CONFIG_PATH = expandPath("/environment/{appname}/mach-ii.xml") />

Remember that /environment is a mapping to {cfmxroot}/config/target/ - a directory created by our build system - so the actual configuration file, under CVS, is {cfmxroot}/config/development/{appname}/mach-ii.xml and can be overridden for staging, integration and production if necessary although this is not recommended (we have better mechanisms for handling environment-specific variables).

Note: For CFMX 6.1, expandPath() with a mapping works on Unix (Solaris and Mac OS X) but does not work on Windows - expandPath() does not process the mapping. This has been fixed in CFMX 7.

MACHII_CONFIG_MODE is set to 0 (dynamic) by default in the core files (since release 1.0.8). This causes Mach II to dynamically reload the framework only if mach-ii.xml changes. This is good for development but it can also be useful to add the following code to index.cfm:

<cfif not request.productionMode and
	structKeyExists(URL,"reloadApp")>
	<cfset MACHII_CONFIG_MODE = 1 />
</cfif> 

This allows you to force a reload easily during development by adding ?reloadApp to the URL. In production, you'd normally set MACHII_CONFIG_MODE to -1 (never). Here's a quick summary of the impact of each of the three modes:

• always (1) - Pro: changes to listeners are picked up immediately. Con: slow (because the framework is reloaded each time), can hide subtle bugs (because if your listener stores data in variables scope it will behave like data in request scope - since the listener is recreated for each request).
• dynamic (0) - Pro: listener instance data behaves correctly (persisting from request to request), easy to force a reload by changing the mach-ii.xml configuration file. Con: changes to listeners are not automatically picked up (you have to change the XML file to pick up listener changes).
• never (-1) - Pro: creates a stable production environment (you can run builds to production servers without changing the application behavior, so you can control when the changes are activated - by restarting the server). Con: you have to restart the server to pick up any changes.

At Macromedia, we set a default for MACHII_CONFIG_MODE in sitewideconstants.cfm to dynamic for development and QA environments and to never for production environments. The standard mach-ii.cfm file uses this default (request.MachIIConfigModel) if it is defined and you have not already overridden MACHII_CONFIG_MODE in your index.cfm file.

Contents | Application Structure & Design »

Comments

Add Comment

isaac dealey said on Dec 19, 2003 at 9:28 AM :

I was wondering why expandpath() is used at all... Wouldn't the system be able to find the config file if you just gave it the path starting with the mapping instead?

I.e. <cffile action="read" source="/environment/{appname}/mach-ii.xml">

instead of

<cffile action="read" source="#expandPath('/environment/{appname}/mach-ii.xml')#"> ?

SeanCorfield said on Dec 19, 2003 at 10:48 AM :

In the index.cfm file, you can set MACHII_CONFIG_PATH to an absolute path if you want
instead of using expandPath() but <cffile> requires either a full absoluet pathname or a
relative path (relative to ColdFusion's temporary directory) so you can't just use a
mapping I'm afraid (without using expandPath()).

newaite said on Feb 1, 2004 at 5:07 PM :

I am running windows and cfmx. Do you have a suggestion on how to move the config file behind the root.

Everything I have tried has resulted in error.

SeanCorfield said on Feb 1, 2004 at 5:25 PM :

You could specify a full file system path for MACHII_CONFIG_PATH:

<cfset MACHII_CONFIG_PATH = "c:\appname\config\mach-ii.xml" />

paulswan said on Sep 21, 2004 at 1:33 AM :

This may not be strictly cosher by it works:

<cfset variables.factory = CreateObject("java", "coldfusion.server.ServiceFactory") />
<cfset MACHII_CONFIG_PATH = variables.factory.runtimeservice.mappings["/mappingName"] & "\" & MACHII_APP_KEY & "\config\mach-ii.xml" />

RSS feed | Send me an e-mail when comments are added to this page | Comment Report

Current page: http://livedocs.adobe.com/wtg/public/machiidevguide/concepts.html

Add Comment