<< Back to Dashboard

Compatibility Guide for ColdBox 3.0.0

This guide is a review of the major changes starting in ColdBox 3.0.0. The major compatibility issues will be covered and also how to smoothly upgrade to this release from previous ColdBox versions. You can also check out the What's New with 3.0.0 guide to give you an in-depth overview.

Configuration File Updates

The layout of the 3.0.0 configuration file has drastically changed. Please refer to the application template's configuration file or you can use our latest schema documentation: http://coldbox.org/documents/SchemaDocs/3.0.0/

Deprecated Settings

• MessageboxStyleOverride : This setting has been removed in order to make it a custom setting as this is part of a plugin. The new setting should be placed in your settings as messagebox_style_override

<DevEnvironments> Deprecated

Please update your coldbox.xml files as the <DevEnvironments> element has now been deprecated.

Setting: MyPluginsLocation Renamed

Old name renamed to PluginsExternalLocation. Please update your setting to this new name

<Setting name="PluginsExternalLocation" value="" />

DevURL attribute deprecated from webservices

The DevURL attribute will no longer be needed, since you can override all settings via the environment control interceptor, this was used when declaring webservices metadata in the configuration file:

<webservices>
    <-- <DevURL now deprecated DO NOT USE -->
	<webservice name="myAlias" URL="full WDSL URL" DevURL="" />
	<-- <DO THIS -->
	<webservice name="myAlias" URL="full WDSL URL"/>
</webservices>

Logging Settings

All the logging settings have been deprecated in favor of configuring logging via LogBox.

Flash RAM updates

The entire flash RAM machinery has been updated and revamped. So if you use the flash scope object to flash variables, please note that all variables are flashed and kept in queue until the request relocates via a setNextEvent() call. We do this in order to flash/serialize variables to flash storage one time instead of every time you flash a variable. If you want flashed variables to be persisted immediately you will have to use the saveNow arguments on all the flash object calls.

Name Refactoring

We have updated almost all the naming of our components as they where in old non-standard format. This step can potentially affect case-sensitive OS's. So please take note of the following new namings. We are also including a ColdBox 3.0.0 upgrader tool that you will find in the install folder. This tool will help you do the renaming and refactoring of your pre 3.0.0 ColdBox applications.

Camel Casing: Same Location

The following files have only been camel cased but not moved from their original locations:

coldbox.system.

coldbox.system.plugins.

coldbox.system.interceptors.

Camel Casing: New Location

The following files have been camel cased and moved to new locations:

coldbox.system.beans. This entire package has been refactored.

New Locations

The following files have just been moved to new package locations:

New Autowire Annotation

• The old autowire annotation for arguments has been _wireme, this is now standardized to the annotation inject.
• The autowire annotation used for cfproperty was type, this is now standardized to the annotation inject.

-- DO THIS --
property name="UserService" inject;
property name="UserService" inject="Model";

-- NOT THIS --
property name="UserService" type="model";

cfcUnit support Deprecated

We are basing all of our unit testing on MXUnit and dropping cfcUnit support.

SES Update: addCourse() renamed to addRoute()

The ses interceptor gets some cleanup. The addCourse() method has been renamed to addRoute() and will be deprecated in version 3.1. The method addCourse() will still delegate into addRoute() so it stays compatible, but our preference is for you to upgrade your code to use the new method addRoute()

createArray() and createStruct() deprecated

• The createArray() method in the Utilities plugin has been deprecated
• The createStruct() method in the Utilities plugin has been deprecated

Autowire Interceptor Setter Injection Changes

The autowire interceptor's default value for setter injection is now false. If you are using setter injection on your handlers, plugins and interceptors then you must explicitly enable the interceptor to continue using setter injection. Our preference is to do runtime injections.

<Interceptor class="coldbox.system.interceptors.Autowire">
  <Property name="enableSetterInjection">true</Property>
</Interceptor>

Feed Reader rewrite

The FeedReader plug-in has been written from scratch and now generates a different output to the FeedReader plug-in found in ColdBox 2.63 and earlier. A number of the outputted structure keys and query column names have been renamed, and this could possibly break applications expecting the earlier labels. Please read the documentation to find the new labels in use.

Feed Generator rewrite

The FeedGenerator plug-in has been written from scratch and will certainly be incompatible with any code used to generate feeds in ColdBox 2.63 and earlier. Please read the FeedGenerator documentation for the new usage.

setNextEvent() updates

The setNextRoute() and relocate() methods are now using internally the setNextEvent() method with its new arguments. In future 3.X versions we will deprecate the setNextRoute and relocate methods in favor of our standardized setNextEvent() method.

varStruct deprecated

The usage of the varStruct argument in the setNextEvent() and the persistVariables() methods has been deprecated in favor of the new argument called persistStruct.

Utilities Plugin Refactored

The Utilities plugin has been refactored into many individual more comprehensive plugins:

• FileUtils
• JVMUtils
• DateUtils
• Utilities
• Validator

So please check that you are not using a method that does not exist anymore on the Utilities plugin.

Upgrading to CacheBox

• The CacheManager.set() method has renamed the argument myObject to object.
• If you declare a cacheEngine structure in your configuration then you will use our compatibility engine that will be deprecated by 3.1. If you would like to use CacheBox, then you must use the CacheBox configuration DSL or a CacheBox configuration object.

Upgrading to WireBox

By default your application will continue to use our CF7 compatible WireBox factory unless you specifically TELL ColdBox to use WireBox. This will be deprecated by 3.1 as CF7 support will also be deprecated. So we highly encourage you to update your apps to use WireBox instead of the old model integration features.

To activate wirebox you must create a wirebox configuration structure:

wirebox = {
	enabled = true,
	binder = "config.WireBox", // by convention this is the default
	singletonReload = true  // reload the singleton scope on each request, great for dev.
};