Fusebox Execution Mode Parameters

Fusebox 4.1 has the concept of loading, parsing and executing as part of a request. It loads the XML files (fusebox.xml and circuit.xml). It parses the XML and created the parsed/ fuseaction files. It executes those files. There are two standard execution modes, set as parameters in fusebox.xml:

<parameter name="mode" value="development" />

<parameter name="mode" value="production" />

Fusebox 5 further defined the process and 'mode' parameters by making available the following:

<parameter name="mode" value="development-circuit-load" />

<parameter name="mode" value="development-full-load" />

<parameter name="mode" value="production" />

With development-full-load being the equivalent to Fusebox 4's single development mode.

Development mode

Causes the framework to load the XML files, if any of them have changed since the last load operation, and parse them on-demand (i.e., generating a parsed/ fuseaction file for each request).

Development-full-load

In development-full-load mode, the core files reparses the XML files only if they have changed and re-builds all the Fusebox memory structures on every request.

Development-circuit-load

In Development-circuit-load, does not re-load the fusebox.xml file, doesn't re-build the Fusebox memory structures, does not reinitialize the framework, but does reload any circuit.xml files required by the current request.

Removes the performance hit with reinitializing the framework during development and is thread safe.

- Recommended for development which will not require fusebox.xml changes.

Production mode

Causes the framework to load the XML files just once, at application startup, and then only parse each fuseaction the first time it is requested - changes to the XML files are ignored until the framework is restarted or explicitly told to load the XML files and/or parse the fuseaction again.

You can specify URL variables that tell Fusebox to load the XML files or just re-parse the requested fuseaction. You can also tell Fusebox not to execute a request (i.e., you might tell it to re-parse a specific fuseaction but not actually execute it). Those URL variables are:

  • fusebox.load=true (or false)
  • fusebox.parse=true (or false)
  • fusebox.execute=true (or false)

You need to specify fusebox.password=thepassword when you specify any of the above. thepassword is set in fusebox.xml:

<parameter name="password" value="thepassword" />

Note that by default fusebox.password is an empty string, but this can be set in the fusebox.xml file with the "password" parameter. If you've set your own password, you'll need to specify that password in the URL when you pass the "fusebox.password". For best results if you are moving from production mode to one of the development modes, make sure to delete all your parsed files in the parsed directory as well.

Development mode is effectively equivalent to fusebox.load=true&fusebox.parse=true&fusebox.execute=true if any of the XML files have changed and fusebox.load=false&fusebox.parse=true&fusebox.execute=true if they have not changed.

Production mode is effectively equivalent to fusebox.load=false&fusebox.parse=false&fusebox.execute=true.

Fusebox 5 adds a new execution mode and two new URL variables. Just as in Fusebox 4.1, basic development mode is not thread-safe so it is hard to develop applications that make multiple concurrent requests to the framework (such as AJAX-powered user interfaces). To offset that, you can now choose this new mode:

<parameter name="mode" value="development-circuit-load" />

This new mode does not load the fusebox.xml file and does not re-initialize the framework itself, but it does reload any circuit.xml files required by the current request (if they have changed) and re-parse the requested fuseactions. This removes the performance hit involved with re-initializing the framework CFCs during regular development mode and is also thread safe.

In keeping with the more explicit name of the new development mode, the basic development mode should be specified as "development-full-load" - the old "development" mode is deprecated (Fusebox 5 still supports it but in strict mode, "development" will cause an exception).

The two new URL variables are:

  • fusebox.loadclean=true (or false)
  • fusebox.parseall=true (or false)

The former is equivalent to fusebox.load but also deletes all existing parsed/ files before reloading the framework. This is a good way to ensure that every fuseaction will get re-generated, as well as clearing out any old parsed/ files that represent fuseactions that are no longer present in the application. The latter causes every public fuseaction in your entire application to be re-parsed and all the parsed/ files re-generated - effectively a pre-compilation option. This can be useful for a production system, after a new release of your application, so that your users do not have to experience the one-off hit of parsing on as each fuseaction is requested.

Production Mode on Deployment

In Fusebox 5.5 you can set FUSEBOX_PARAMETERS.mode in Application.cfc, Application.cfm, index.cfm, or fusebox.init.cfm and this setting will override the value in fusebox.xml at startup (not per request). This can help in making your code easily deployable between development and production environments by adding the following logic:

If (ListFirst(CGI.SERVER_NAME, ".") EQ "dev"){
FUSEBOX_PARAMETERS.mode = "development-circuit-load";
}
Else {
FUSEBOX_PARAMETERS.mode = "production";
}

Additional Information

  • development -> development-full-load
  • development-no-load -> development-circuit-load

The development mode would still be supported as a deprecated alias for development-full-load. In strictMode, Fusebox 5 would throw an exception if development mode was specified (and the exception would say it was deprecated in favor of development-full-load).

The documentation would then explain the modes as follows:

  • development-full-load is useful while you are modifying fusebox.xml a lot, early in the development cycle as it reloads the entire framework on every request - but it is not thread-safe;
  • development-circuit-load is likely the most common development mode: it is thread-safe but still reloads circuit.xml files whenever they change and always regenerates the parsed/ file - it does not reload the fusebox.xml file (use fusebox.load=true for that);

To be honest, development-no-load is probably not very useful at all because development-circuit-load doesn't reload a circuit.xml file if it hasn't changed and therefore, if you aren't changing circuit files, development-circuit-load and development-no-load (-parse-only) would be exactly the same really...

Fusebox 5 Deprecated

In order to help developers migrate code away from deprecated features, Fusebox 5 introduces a new fusebox.xml parameter called strictMode. By default, this is set to false and deprecated features are silently supported. If you set this parameter to true, Fusebox 5 will detect those deprecated features and throw an exception if they are used (well, using application.fusebox.rootdirectory in strict mode will cause an exception in your code since Fusebox 5 only sets that variable when strictMode is false!):

<parameter name="strictMode" value="true" />

In addition, Fusebox 5 performs some additional validation of XML verbs and attributes since it deprecates any undocumented attributes appearing in the XML file that are not declared using an XML namespace.

It is possible (and likely) that a future release of Fusebox will change the default of strictMode to true or will simply make the deprecated features illegal.

Additional Information