[[Dashboard|<< Back to Dashboard]]
[[Category:compatibility]]

{| align="right"
| __TOC__
|}

= 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 [[WhatsNew:3.0.0 | 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

<source lang="xml">
<Setting name="PluginsExternalLocation" value="" />
</source>

=== ''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:

<source lang="xml">
<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>
</source>

=== Logging Settings ===

All the logging settings have been deprecated in favor of configuring logging via [[LogBox | 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.'''

{| cellpadding="5", class="tablelisting", width="600"
! '''old name''' !! '''new name'''
|-
| coldbox.cfc || Coldbox.cfc
|-
| coldbox.cfm || Coldbox.cfm
|-
| eventhandler.cfc || EventHandler.cfc
|-
| frameworkSupertype.cfc || FrameworkSupertype.cfc
|-
| interceptor.cfc || Interceptor.cfc
|-
| plugin.cfc || Plugin.cfc
|}

'''coldbox.system.plugins.'''

{| cellpadding="5", class="tablelisting", width="600"
! '''old name''' !! '''new name'''
|-
|| applicationstorage.cfc || ApplicationStorage.cfc
|-
|| beanFactory.cfc || BeanFactory.cfc
|-
|| cfcViewer.cfc || CFCViewer.cfc
|-
|| clientstorage.cfc || ClientStorage.cfc
|-
|| cookiestorage.cfc || CookieStorage.cfc
|-
|| feedGenerator.cfc || FeedGenerator.cfc
|-
|| feedReader.cfc || FeedReader.cfc
|-
|| ioc.cfc || IOC.cfc
|-
|| json.cfc || JSON.cfc
|-
|| logger.cfc || Logger.cfc
|-
|| messagebox.cfc || MessageBox.cfc
|-
|| methodInjector.cfc || MethodInjector.cfc
|-
|| queryHelper.cfc || QueryHelper.cfc
|-
|| renderer.cfc || Renderer.cfc
|-
|| resourceBundle.cfc || ResourceBundle.cfc
|-
|| sessionstorage.cfc || SessionStorage.cfc
|-
|| timer.cfc || Timer.cfc
|-
|| webservices.cfc || Webservices.cfc
|-
|| zip.cfc || Zip.cfc
|}

'''coldbox.system.interceptors.'''

{| cellpadding="5", class="tablelisting", width="600"
! '''old name''' !! '''new name'''
|-
|| autowire.cfc || Autowire.cfc
|-
|| coldboxSideBar.cfc || ColdBoxSideBar.cfc
|-
|| deploy.cfc || Deploy.cfc
|-
|| environmentControl.cfc || EnvironmentControl.cfc
|-
|| executionTracer.cfc || ExecutionTracer.cfc
|-
|| security.cfc || Security.cfc
|-
|| ses.cfc || SES.cfc
|}

=== Camel Casing: New Location ===
The following files have been camel cased and moved to new locations:

{| cellpadding="5", class="tablelisting", width="650"
! '''old location-name''' !! '''new location-name'''
|-
|| coldbox.system.testController.cfc || coldbox.system.testing.mock.web.TestController.cfc
|-
|| coldbox.system.extras.testing.baseMXUnitTest.cfc || coldbox.system.testing.BaseTestCase.cfc
|-
|| coldbox.system.extras.testing.baseTest.cfc || REMOVED
|-
|| coldbox.system.beans.requestContext.cfc || coldbox.system.web.context.RequestContext.cfc
|-
|| coldbox.system.beans.requestContextDecorator.cfc || coldbox.system.web.context.RequestContextDecorator.cfc
|-
|| coldbox.system.controller.cfc || coldbox.system.web.Controller.cfc
|}

<div class="mynotes">
'''Note:''' cfcUnit support has been completely dropped.
</div>

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

{| cellpadding="5", class="tablelisting", width="600"
! '''old location''' !! '''new location'''
|-
|| debuggerConfig.cfc || coldbox.system.web.config.DebuggerConfig.cfc
|-
|| configBean.cfc || coldbox.system.core.collections.ConfigBean.cfC
|-
|| datasourceBean.cfc || coldbox.system.core.db.DatasourceBean.cfc
|-
|| eventhandlerBean.cfc || coldbox.system.web.context.EventHandlerBean.cfc
|-
|| exceptionBean.cfc || coldbox.system.web.context.ExceptionBean.cfc
|-
|| interceptorState.cfc || coldbox.system.web.context.InterceptorState.cfc
|-
|| mailSettingsBean.cfc || coldbox.system.core.mail.MailSettingsBean.cfc
|}

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

{| cellpadding="5", class="tablelisting", width="650"
! '''old location-name''' !! '''new location-name'''
|-
|| coldbox.system.extras.ColdBoxProxy.cfc || coldbox.system.remote.ColdBoxProxy.cfc
|-
|| coldbox.system.extras.ColdBoxFactory.cfc || coldbox.system.ioc.ColdBoxFactory.cfc
|-
|| coldbox.system.extras.transfer.* || coldbox.system.orm.transfer.*
|}


== 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'''.

<source lang="coldfusion">
-- DO THIS --
property name="UserService" inject;
property name="UserService" inject="Model";

-- NOT THIS --
property name="UserService" type="model";
</source>

== 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.

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

== 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. [[plugins:FeedReader | 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. [[plugins:FeedGenerator | 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:

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

<div class="mynotes">
'''Important''' : You must also remove your ''modelMappings.cfm'' and update to your the [[WireBox]] configuration binder instead.
</div>