Environment Control Via Interceptors

One of the cool thing about interceptors, is that sooo much can be done with them. This little interceptor is very very useful when you are dealing with multiple environments and you would like different settings or aspects according to environment. Therefore, ColdBox comes with a basic environment control interceptor that you can use for your projects. Below is a quick guide to show you how to use it.

How to Configure it?

The way to configure the environment interceptor is via your configuration file. Look below for the sample:

<Interceptor class="coldbox.system.interceptors.environmentControl">
  <Property name='configFile'>config/environments.xml.cfm</Property>
  <Property name='fireOnInit'>false</Property>
</Interceptor>

Important Note: The environment control interceptor fires at the afterConfigurationLoad interception point. This way, you can override any aspect configuration before it gets configured and fired. You can also set the fireOnInit property to true, to fire on interceptor creation.

This declares that you want to use the environment control interceptor and assign a configFile property to where you environment settings xml exists. I usually place all my configuration files in my config directory. You also need to set the fireOnInit boolean flag. This flag, tells the interceptor to fire itself on creation also. This is useful, if you are declaring a chain of interceptors that also need settings as per their environments. The default value is false

That's it, this configures your application for using the interceptor, now to the fun stuff.

The Environments Configuration

In order for the interceptor to know which environments you want, where you are and what settings to override, you must fill out an xml file similar to the following:

<?xml version="1.0" encoding="ISO-8859-1"?>
<!-- Declare as many tiers as you like with a unique name -->
<environmentcontrol>
        
  <!-- give an environment a name and a comma delimmited list of url snippets to match -->
  <environment name="development" urls="localhost,dev,jfetmac">
        <!--ColdBoxSpecific Settings -->
        <Setting name="HandlerCaching"                  value="false" />
        <Setting name="HandlersIndexAutoReload" value="false" />
        <Setting name="IOCObjectCaching"                value="false" />
        <Setting name="DebugMode"                               value="false" />
        <Setting name="DebugPassword"                   value="" />
        <Setting name="ReinitPassword"                  value="" />
        <Setting name="EnableDumpVar"                   value="false" />
        <Setting name="EnableColdboxLogging"    value="false" />
        <Setting name="onInvalidEvent"                  value="" />
        
        <!--
                AppSpecific Settings: <Setting name="MySetting" value="Hello" />
        -->             
  </environment>
        
</environmentcontrol>

As you can see from the sample xml, you need to define the following:

<environment> element

This element tells the interceptor to look for this environment. You can create as many environment elements as you like and it has the following attributes:

• Attributes

Attribute	Description
name	The name of the environment
urls	The url snippets (comma-delimited) to look for in the CGI.HTTP_HOST

The interceptor grabs the urls attribute and scans the CGI.HTTP_HOST variable to see if the snippets can be found. If it is, then it will set the following in the application configuration settings:

• ENVIRONMENT = The name attribute of the environment element.

It will then read in all the Setting elements and place them in your configuration structure. You can also use complex variable declarations as defined in the Configuration Guide

Important Note: This process will override any previously defined setting.

And that is it! You now can have environment specific settings. The good thing, is that you can actually extend the environment control interceptor and modify or decorate it as you like. Maybe you have your own ways of determining environments, well, you can easily expand on it.