In this section you will find the release notes for each version we release under this major version. If you are looking for the release notes of previous major versions use the version switcher at the top left of this documentation book. Here is a breakdown of our major version releases.

• Version 6.0 - August 2020

• Version 5.0 - July 2018

• Version 4.0 - January 2015

• Version 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

Release notes - ColdBox Platform - 6.11.0

New Feature

COLDBOX-1322 BoxLang CacheBox Provider

Improvement

COLDBOX-1321 Update all cbproxies to work with BoxLang

COLDBOX-1323 detect ORM Hibernate Version for BoxLang

Bug

COLDBOX-1320 Update all GitHub actions to make sure the builds work

COLDBOX-1325 populator discover entity name not accouting for missing entityname

Release notes - ColdBox Platform - 6.10.0

Bug

COLDBOX-1274 javacasting to long for new Java LocalDateTime instead of int, Adobe not doing type promotion

COLDBOX-1279 Render encapsulator bleed of this scope by engines

Improvement

COLDBOX-1273 Removal of deprecated CFML functions in core

COLDBOX-1275 Improved engine detection by the CFMLEngine feature class

COLDBOX-1278 Remove unsafe evaluate function usage

Added

• COLDBOX-1229 Added debug argument to ScheduleExecutor and Scheduler when creating tasks for consistency

• COLDBOX-1230 Reorganized ScheduledTasks functions within the CFC into code groups and comments

Improvements

• COLDBOX-1226 Scheduled Tasks Updates

Fixed

• COLDBOX-1145 RestHandler OnError() Exception not checking for empty `exception` blocks which would cause another exception on development ONLY

Added

• Github actions for LTS Releases

• LTS Updates

Bugs

• COLDBOX-1219 CFProvider ACF versions are Hard-Coded

• WIREBOX-132 WireBox caches Singletons even if their autowired dependencies throw exceptions.

Bug

COLDBOX-1138 Event Cache Response Has Status Code of 0 (or Null)

COLDBOX-1139 make event caching cache keys lower cased to avoid case issues when clearing keys

Release Notes

ColdBox 6.1.0 is a minor release sporting fixes and a few minor updates to make your coding life easier 😂.

The major compatibility issues will be covered as well as how to smoothly upgrade to this release from previous ColdBox versions. You can also check out the What's New guide to give you a full overview of the changes.

Lucee 4.5 Support Dropped

Lucee 4.5 support has been dropped.

ColdFusion 11 Support Dropped

ColdFusion 11 support has been dropped. Adobe doesn't support them anymore, so neither do we.

Setting Changes

The following settings have been changed and altering behavior:

• coldbox.autoMapModels is now defaulted to true

  • Which means that all your models will be MAPPED for you. If you have specific mappers in your config/WireBox.cfc make sure they override the mapping or turn this setting false.

• coldbox.onInvalidEvent has been REMOVED in preference to coldbox.invalidEventHandler

• coldbox.jsonPayloadToRC is now defaulted to true

BuildLink( linkto ) argument removed

The buildLink() method had an argument linkTo . It has now changed to to to provide simplification

SES Interceptor Removed

The SES interceptor has finally been removed. You can now remove it from your interceptor declarations. If you are relying on the SES interceptor for routing, then you will need to access the RoutingService via the following injection methods or retrieval methods:

Method Changes

getModel() Removed

This method was marked for deprecation in ColdBox 5 and now it is removed. You can use the getInstance() method instead.

WireBox Provider get() method to $get()

All WireBox providers now implement the new interface which has changed the method of get() to $get() to avoid proxying to methods that already implement a get() method. So if you are using the get() method just update it to the new $get() method.

getSetting()

The getSetting() method does NOT include a fwSetting boolean argument anymore. You can now use the getColdBoxSetting() method instead.

announceInterception( state, interceptData ) => announce( state, data )

This method has now been deprecated in favor of its shorthand announce(). This method will still work but it will be removed in the next major version. So just rename it now. Also note that the interceptData has now changed to just data

processState( state, interceptData ) => announce( state, data )

This method was used in the event manager and interceptor service and has been marked for deprecation. Please use the method announce() instead. Which is also a consistency in naming now.

setNextEvent() Removed

The method setNextEvent() has been removed in favor of relocate(). We had deprecated this method in ColdBox 5.

Interceptor Buffer Methods Removed

These methods have been deprecated since version 4 and they are now removed.

• getBufferObject()

• getBufferString()

• appendToBuffer()

• clearBuffer()

Every interception listener receives the buffer as an argument so there is no need to go to global functions for working with the buffer.

Interceptor Arguments: interceptData => data

All interceptors receive arguments when listening, we have renamed the interceptData to just data. The old approach still works but it is marked as deprecated. So just rename it to data

System Path Changes

• Default Bug Report Files are now located in /coldbox/system/exceptions/. Previously /coldbox/system/includes/

So make sure you update your CustomErrorTemplate path to this new path:

Rendering Changes

The entire rendering mechanisms in ColdBox 6 have changed. We have retained backwards compatibility but there might be some loopholes that worked before that won't work now. Basically, the renderer is a singleton and each view renders in isolation. Meaning if a view sets a variable in it's variables scope NO OTHER view will have access to it.

ColdBox provides you with a nice method for generating links between events by leveraging an object called event that is accessible in all of your layouts/views and event handlers. This event object is called behind the scenes the request context object, which models the incoming request and even contains all of your incoming FORM and URL variables in a structure called rc.

Building Links

The method in the request context that builds links is called: buildLink(). Here are some of the arguments you can use:

Edit Your View

Edit the views/virtual/hello.cfm page and wrap the content in a cfoutput and create a link to the main ColdBox event, which by convention is main.index. You can use main.index or just main (Remember that index is the default action)

This code will generate a link to the main.index event in a search engine safe manner and in SSL detection mode. Go execute the event: http://localhost:{port}/virtual/hello and click on the generated URL, you will now be navigating to the default event /main/index. This technique will also apply to FORM submissions:

URL Structure & Mappings

ColdBox allows you to manipulate the incoming URL so you can create robust URL strategies especially for RESTFul services. This is all done by convention and you can configure it via the application router: config/Router.cfc for more granular control.

We have now seen how to execute events via nice URLs. Behind the scenes, ColdBox translates the URL into an executable event string just like if you were using a normal URL string:

• /main/index -> ?event=main.index

• /virtual/hello -> ?event=virtual.hello

• /admin/users/list -> ?event=admin.users.list

• /handler/action/name/value -> ?event=handler.action&name=value

• /handler/action/name -> ?event=handler.action&name=

By convention, any name-value pairs detected after an event variable will be treated as an incoming URL variables. If there is no pair, then the value will be an empty string.

Every time the framework renders a view, it will try to leverage the default layout which is located in layouts/Main.cfm by convention. This is an HTML file that gives format to your output and contains the location of where the view you want should be rendered.

Layout Code

This location is identified by the following code: renderView()

The call to the renderView() method with no arguments tells the framework to render the view that was set using event.setView(). This is called a rendering region. You can use as many rendering regions within layouts or even within views themselves.

Creating A Layout

Let's create a new simple layout with two rendering regions. Open up CommandBox and issue the following commands:

Open the layouts/Funky.cfm layout and let's modify it a bit by adding the footer view as a rendering region.

If you are use to using cfinclude to reuse templates, think about it the same way. renderview() is a much more powerful cfinclude.

Using The Layout

Now, let's open the handler we created before called handlers/hello.cfc and add some code to use our new layout explicitly via adding a layout argument to our setView() call.

Go execute the event now: http://localhost:{port}/hello/index and you will see the view rendered with the words funky layout and footer view at the bottom. Eureka, you have now created a layout.

Congratulations! Did you finish this guide in less than 60 minutes? If you did please leave us some great feedback below. If you didn't, then please do tell us why, we would love to improve our guides.

You can now move on to the next level in becoming a ColdBox Guru! Choose your path below:

• Learn about HMVC via ColdBox Modules

• Learn about Dependency Injection

• Learn about Caching

• Learn about Logging

• Learn about Testing

Getting Help

If you run into issues or just have questions, please jump on our ColdBox Google Group and our Slack team and ask away.

ColdBox is Professional Open Source under the Apache 2.0 license. We'd love to have your help with the product.

This is an array of interceptor definitions that you will use to register in your application. The key about this array is that ORDER matters. The interceptors will fire in the order that you register them whenever their interception points are announced, so please watch out for this caveat. Each array element is a structure that describes what interceptor to register.

//Register interceptors as an array, we need order
interceptors = [

    { 
        // The CFC instantiation path
        class="",
        // The alias to register in WireBox, if not defined it uses the name of the CFC
        name="",
        // A struct of data to configure the interceptor with.
        properties={}
    }

    { class="mypath.MyInterceptor",
      name="MyInterceptor",
      properties={useSetterInjection=false}
    }
];

Warning : Important: Order of declaration matters! Also, when declaring multiple instances of the same CFC (interceptor), make sure you use the name attribute in order to distinguish them. If not, only one will be registered (the last one declared).

This structure allows you to define a system-wide default layout and view.

//Layout Settings
layoutSettings = {
    // The default layout to use if NOT defined in a request
    defaultLayout = "Main.cfm",
    // The default view to use to render if NOT defined in a request
    defaultView   = "youForgot.cfm"
};

Hint Please remember that the default layout is Main.cfm

The logBox structure is based on the LogBox declaration DSL, see the LogBox Documentation for much more information.

//LogBox DSL
logBox = {
    // The configuration file without fileextension to use for operation, instead of using this structure
    configFile = "config/LogBox", 
    // Appenders
    appenders = {
        appenderName = {
            class="class.to.appender", 
            layout="class.to.layout",
            levelMin=0,
            levelMax=4,
            properties={
                name  = value,
                prop2 = value 2
            }
    },
    // Root Logger
    root = {levelMin="FATAL", levelMax="DEBUG", appenders="*"},
    // Granualr Categories
    categories = {
        "coldbox.system" = { levelMin="FATAL", levelMax="INFO", appenders="*"},
        "model.security" = { levelMax="DEBUG", appenders="console"}
    }
    // Implicit categories
    debug  = ["coldbox.system.interceptors"],
    info   = ["model.class", "model2.class2"],
    warn   = ["model.class", "model2.class2"],
    error  = ["model.class", "model2.class2"],
    fatal  = ["model.class", "model2.class2"],
    off    = ["model.class", "model2.class2"]
};

Info : If you do not define a logBox DSL structure, the framework will look for the default configuration file config/LogBox.cfc. If it does not find it, then it will use the framework's default logging settings.

ConfigFile

You can use a configuration CFC instead of inline configuration by using this setting. The default value is config/LogBox.cfc, so by convention you can just use that location. If no values are defined or no config file exists, the default configuration file is coldbox/system/web/config/LogBox.cfc.

This structure is used to house module configurations. Please refer to each module's documentation on how to create the configuration structures. Usually the keys will match the name of the module to be configured.

component {

     function configure() {

         moduleSettings = {
             myModule = {
                someSetting = "overridden"
             }
        };
    }
}

The ColdBox Routing DSL will be used to register routes for your application, which exists in your application or module router object. Routing takes place using several methods inside the router, which are divided into the following 3 categories:

1. Initiators - Starts a URL pattern registration, but does not fully register the route until a terminator is called (target).

2. Modifiers - Modifies the pattern with extra metdata to listen to from the incoming request.

3. Terminators - Finalizes the registration process usually by telling the router what happens when the route pattern is detected. This is refered to as the target.

Initiators

The following methods are used to initiate a route registration process.

• route( pattern, [target], [name=arguments.pattern] ) - Register a new route with optional target terminators and a name

• get( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a GET http verb restriction

• post( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a POST http verb restriction

• put( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a PUT http verb restriction

• patch( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a PATCH http verb restriction

• options( pattern, [target], [name] ) - Register a new route with optional target terminators, a name and a OPTIONS http verb restriction

• group( struct options, body ) - Group routes together with options that will be applied to all routes declared in the body closure/lambda.

Modifiers

Modifiers will tell the routing service about certain restrictions, conditions or locations for the routing process. It will not register the route just yet.

• header( name, value, overwrite=true ) - attach a response header if the route matches

• headers( map, overwrite=true ) - attach multiple response headers if the route matches

• as( name ) - Register the route as a named route

• rc( name, value, overwrite=true ) - Add an RC value if the route matched

• rcAppend map, overwrite=true ) - Add multiple values to the RC collection if the route matched

• prc( name, value, overwrite=true ) - Add an PRC value if the route matched

• prcAppend map, overwrite=true ) - Add multiple values to the PRC collection if the route matched

• withHandler( handler ) - Map the route to execute a handler

• withAction( action ) - Map the route to execute a single action or a struct that represents verbs and actions

• withModule( module ) - Map the route to a module

• withNamespace( namespace ) - Map the route to a namespace

• withSSL() - Force SSL

• withCondition( condition ) - Apply a runtime closure/lambda enclosure

• withDomain( domain ) - Map the route to a domain or subdomain

• withVerbs( verbs ) - Restrict the route to listen to only these HTTP Verbs

• packageResolver( toggle ) - Turn on/off convention for packages

• valuePairTranslator( toggle ) - Turn on/off automatic name value pair translations

Terminators

Terminators finalize the routing process by registering the route in the Router.

• end() - Register the route as it exists

• toAction( action ) - Send the route to a specific action or RESTFul action struct

• toView( view, layout, noLayout=false, viewModule, layoutModule ) - Send the route to a view/layout

• toRedirect( target, statusCode=301 ) - Relocate the route to another event

• to( event ) - Execute the event if the route matches

• toHandler( handler ) - Execute the handler if the route matches

• toResponse( body, statusCode=200, statusText="ok" ) - Inline response action

• toModuleRouting( module ) - Send to the module router for evaluation

• toNamespaceRouting( namespace ) - Send to the namespace router for evaluation

Apart from routing by convention, you can also register your own expressive routes. Let's investigate the routing approaches.

Inline Terminator

The route() method allows you to register a pattern and immediately assign it to execute an event or a response via the target argument.

The first pattern registers and if matched it will execute the wiki.page event. The second pattern if matched it will execute the profile.show event from the users module and register the route with the userprofile name.

Inline Responses

You can also pass in a closure or lambda to the target argument and it will be treated as an inline action:

You can also pass just an HTML string with {rc_var} replacements for the routed variables place in the request collection

Routing to Events

If you will not use the inline terminators you can do a full expressive route definition to events using the to() method, which allows you to concatenate the route pattern with modifiers:

Routing To Handler Action Combinations

You can also route to a handler and an action using the modifiers instead of the to() method. This long-form is usually done for visibility or dynamic writing of routes. You can use the following methods:

• withHandler()

• withAction()

• toHandler()

• end()

Routing to Views

You can also route to views and view/layout combinations by using the toView() terminator:

Routing to Redirects

You can also use the toRedirect() method to re-route patterns to other patterns.

Dynamic Routing Redirection

You can also pass a closure as the target of relocation. This closure will received the parsed parameters, the incoming route record and the event object. You can determine dynamically where the relocation will go.

This is great if you need to actually parse the incoming route and do a dynamic relocation.

Happy Redirecting!

Routing to Handlers

You can also redirect a pattern to a handler using the toHandler() method. This is usually done if you have the action coming in via the URL or you are using RESTFul actions.

Routing to RESTFul Actions

You can also route a pattern to HTTP RESTFul actions. This means that you can split the routing pattern according to incoming HTTP Verb. You will use a modifier withAction() and then assign it to a handler via the toHandler() method.

Routing to Responses

The Router allows you to create inline responses via closures/lambdas or enhanced strings to incoming URL patterns. You do not need to create handler/actions, you can put the actions inline as responses.

If you use a response closure/lambda, they each accepts three arguments:

1. event - An object that models and is used to work with the current request (Request Context)

2. rc - A struct that contains both URL/FORM variables merged together (unsafe data)

3. prc - A secondary struct that is private only settable from within your application (safe data)

If the response is an HTML string, then you can do {rc_var} replacements on the strings as well:

Sub-Domain Routing

You can also register routes that will respond to sub-domains and even capture portions of the sub-domain for multi-tenant applications or SaaS applications. You will do this using the withDomain() method.

You can leverage the full routing DSL as long as you add the withDomain() call with the domain you want to bind the route to. Also note that the domain string can contain placeholders which will be translated to RC variables for you if matched.

Adding Variables to RC/PRC

You can also add variables to the RC and PRC structs on a per-route basis by leveraging the following methods:

• rc( name, value, overwrite=true ) - Add an RC value if the route matched

• rcAppend map, overwrite=true ) - Add multiple values to the RC collection if the route matched

• prc( name, value, overwrite=true ) - Add an PRC value if the route matched

• prcAppend map, overwrite=true ) - Add multiple values to the PRC collection if the route matched

This is a great way to manually set variables in the incoming structures:

Routing Conditions

You can also apply runtime conditions to a route in order for it to be matched. This means that if the route matches the URL pattern then we will execute a closure/lambda to make sure that it meets the runtime conditions. We will do this with the withCondition() method.

Let's say you only want to fire some routes if they are using Firefox, or a user is logged in, or whatever.

The base tag in HTML allows you to tell the browser what is the base URL for assets in your application. This is something that is always missed when using frameworks that enable routing.

We definitely recommend using this HTML tag reference as it will simplify your asset retrievals.

<base href="#event.getHTMLBaseURL()#">

The framework also offers you the capability to bind incoming FORM/URL/REMOTE/XML/JSON/Structure data into your model objects by convention. This is done via WireBox's object population capabilities. The easiest approach is to use our populateModel() function which will populate the object from many incoming sources:

• request collection RC

• Structure

• json

• xml

• query

This will try to match incoming variable names to setters or properties in your domain objects and then populate them for you. It can even do ORM entities with ALL of their respective relationships. Here is a snapshot of the method:

Let's do a quick example:

Person.cfc

component accessors="true"{

    property name="name";
    property name="email";

    function init(){
        setName('');
        setEmail('');
    }
}

editor.cfm

Event Handler -> person.cfc

In the dump you will see that the name and email properties have been bound.

More often you will find that certain web operations need to be restricted in terms of what HTTP verb is used to access a resource. For example, you do not want form submissions to be done via GET but via POST or PUT operations. HTTP Verb recognition is also essential when building strong RESTFul APIs when security is needed as well.

Manual Solution

You can do this manually, but why do the extra coding :)

This solution is great and works, but it is not THAT great. We can do better.

Allowed Methods Property

Another feature property on an event handler is called this.allowedMethods. It is a declarative structure that you can use to determine what the allowed HTTP methods are for any action on the event handler.

If the request action HTTP method is not found in the approved list, it will look for a onInvalidHTTPMethod() on the handler and call it if found. Otherwise ColdBox throws a 405 exception that is uniform across requests.

Allowed Methods Annotation

You can tag your event actions with a allowedMethods annotation and add a list of the allowed HTTP verbs as well. This gives you a nice directed ability right at the function level instead of a property. It is also useful when leveraging DocBox documentation as it will show up in the API Docs that are generated.

Apart from executing events from the URL/FORM or Remote interfaces, you can also execute events internally, either public or private from within your event handlers or from interceptors, other handlers, layouts or views.

RunEvent()

You do this by using the runEvent() method which is inherited from our FrameworkSuperType class. Here is the method signature:

The interesting aspect of internal executions is that all the same rules apply, so your handlers can return content like widgets, views, or even data. Also, the eventArguments enables you to pass arguments to the method just like method calls:

Executions

Declaration

Caching

As you can see from the function signature you can tell ColdBox to cache the result of the event call. All of the cached content will go into the template cache by default unless you use the cacheProvider argument. The cache keys are also based on the name of the event and the signature of the eventArguments structure. Meaning, the framework can cache multiple permutations of the same event call as long as the eventArguments are different.

A part from using runEvent() to execute events, you can also abstract it by using the runRoute() method. This method is fairly similar but with the added benefit of executing a NAMED route instead of the direct event it represents. This gives you the added flexibility of abstracting the direct event and leveraging the named route.

All the same feature of runEvent() apply to runRoute()

RunRoute()

Just like you can create links based on named routes and params, you can execute named routes and params as well internally via runRoute()

Parameters

The params argument you pass to the runRoute() method will be translated into event arguments. Therefore they will be passed as arguments to the event the route represents:

// Execute
runRoute( "userData", { id=4 } )

In the example above, the userData named route points to the user.data event.

Module Routes

If you want to execute module routes, no problem! Just use our @ or : notation to tell the controller from which module's router we should pick the route from.

ColdBox Core MVC does not have validation built-in but it is implemented via the official core cbValidation module. You can easily install the module in your application via:

box install cbvalidation

You can find much more information about this module in the following resources:

• Source: https://github.com/coldbox/cbox-validation

• Documentation: https://github.com/coldbox-modules/cbox-validation/wiki

• ForgeBox : http://forgebox.io/view/cbvalidation

So what if I want to render a view outside of my application without using the setting explained above? Well, you use the externalView() method.

<cfoutput>#externalView(view='/myViewsMapping/tags/footer')#</cfoutput>

Major Updates

Here is a listing of all the major updates and improvements in this version.

Event Caching HTTP Response Codes

Event caching has been updated to allow the caching of the set http response code from your handler code via event.setHTTPHeader() or event.renderData() . This is essential from a developer's perspective as it will respect whatever response code you respond with. This is also imperative for RESTFul services.

function data( event, rc, prc ) cache=true cacheTimeout=5{
    
    event.setHTTPHeader( statusCode = 404 );

}

WireBox Performance, Performance and More Performance

This release brings in a complete re-architecture of the creation, inspection and wiring of objects in WireBox in order to increase performance. Every single line of code was optimized and analyzed in order to bring the creation, inspection and wiring of objects to its maximum speed. This will be noted more on the creation of transient (non-persisted) objects more than in singleton objects. So if you are asking WireBox for transient objects, you will see and feel the difference.

In some of our performance testing we had about 4000 object instantiations running between 500ms-1,100 ms depending on CPU load. While with simple createObject() and no wiring, they click around 400-700 ms. Previously, we had the same instantiations clocking at 900-3,500 ms. So we can definitely see a major improvement in this area.

New ColdBox Testing Virtual App

This release sports the creation of the encapsulated virtual ColdBox App: coldbox.system.testing.VirtualApp. Previously, the only way to create virtual apps was to do it manually just like the BaseTestCase object did when doing integration testing and that's about it. In this release, we provide a clean interface for starting, restarting, checking and shutting down virtual applications that can be used for testing, proxying, etc. It also allows a faster and eager approach to starting the virtual application before your runner and tests. This will allow any ORM bridges to be respected and best of all the ability to execute anything in the framework before your runners, suites or specs. Database migrations anyone?

Test Harness

All application templates have been updated to use the new Virtual App in the tests/Application.cfc. This will allow for a virtual application to be started once your runner or specs are executed and shutdown at the end of the request. Here are the two methods in charge of doing this in the Application.cfc

public boolean function onRequestStart( targetPage ){
	// Set a high timeout for long running tests
	setting requestTimeout="9999";
	// New ColdBox Virtual Application Starter
	request.coldBoxVirtualApp = new coldbox.system.testing.VirtualApp( appMapping = "/root" );

	// If hitting the runner or specs, prep our virtual app
	if ( getBaseTemplatePath().replace( expandPath( "/tests" ), "" ).reFindNoCase( "(runner|specs)" ) ) {
		request.coldBoxVirtualApp.startup();
	}

	// ORM Reload for fresh results
	if( structKeyExists( url, "fwreinit" ) ){
		if( structKeyExists( server, "lucee" ) ){
			pagePoolClear();
		}
		// ormReload();
		request.coldBoxVirtualApp.restart();
	}

	return true;
}

public void function onRequestEnd( required targetPage ) {
	request.coldBoxVirtualApp.shutdown();
}

Your integration tests and unit tests remain the same. The only difference is that internally they all use this object to create the virtual applications.

Scheduled Tasks Exception Handling

All scheduled tasks have automatic exception handling now. Before, whenever you had exceptions and you did NOT implement any of the exception handling listeners, your code would be swallowed up and never to be seen! Now, we avoid this and log them to standard error so you can debug your code.

Also, in the previous version, if you had an exception your afterAnyTask() or the after() life cycle methods would never be called. Now they are!! Hooray!!

ColdBox Schedulers Automatic Injection

All ColdBox enabled schedulers will have the following automatic injections so you can have ease of use for leveraging objects and contexts during your task declarations and executables.

All module schedulers will have the following extra automatic injections:

Scheduled Tasks Start and End Dates

All scheduled tasks now support the ability to seed in the start and end dates via our DSL:

• startOn( date, time = "00:00" )

• endOn( data, time = "00:00" )

This means that you can tell the scheduler when the task will become active on a specific data and time (using the scheduler's timezone), and when the task will become disabled.

task( "restricted-task" )
  .call( () => ... )
  .everyHour()
  .startOn( "2022-01-01", "00:00" )
  .endOn( "2022-04-01" )

xTask() - Easy Disabling of Tasks

Thanks to the inspiration of TestBox where you can mark a spec or test to be skipped from execution by prefixing it with the letter x you can now do the same for any task declaration. If they are prefixed with the letter x they will be registered but disabled automatically for you.

function configure(){

	xtask( "Disabled Task" )
		.call ( function(){
			writeDump( var="Disabled", output="console" );
		})
		.every( 1, "second" );

	task( "Scope Test" )
		.call( function(){
			writeDump( var="****************************************************************************", output="console" );
			writeDump( var="Scope Test (application) -> #getThreadName()# #application.keyList()#", output="console" );
			writeDump( var="Scope Test (server) -> #getThreadName()# #server.keyList()#", output="console" );
			writeDump( var="Scope Test (cgi) -> #getThreadName()# #cgi.keyList()#", output="console" );
			writeDump( var="Scope Test (url) -> #getThreadName()# #url.keyList()#", output="console" );
			writeDump( var="Scope Test (form) -> #getThreadName()# #form.keyList()#", output="console" );
			writeDump( var="Scope Test (request) -> #getThreadName()# #request.keyList()#", output="console" );
			writeDump( var="Scope Test (variables) -> #getThreadName()# #variables.keyList()#", output="console" );
			writeDump( var="****************************************************************************", output="console" );
		} )
		.every( 60, "seconds" )
		.onFailure( function( task, exception ){
			writeDump( var='====> Scope test failed (#getThreadName()#)!! #exception.message# #exception.stacktrace.left( 500 )#', output="console" );
		} );
		
}

Scheduled Tasks Singular Time Units

Every time unit can now be used as plural or singular, so it can allow you to create beautiful scheduled task DSLs:

// Before
task( "my-task" )
	.call( () => {} )
	.every( 1, 'hours' );

// Which sounds weird when you read it. So now you can use singular

task( "my-task" )
	.call( () => {} )
	.every( 1, 'hour' );

Available Time Units

• Nanosecond(s)

• Microsecond(s)

• Millisecond(s)

• Second(s)

• Minute(s)

• Hour(s)

• Day(s)

Safe Shutdown of Executors and Schedulers

All executors and schedulers can now be shutdown more gracefully by passing a timeout argument to the async manager and automatically by the framework. This will allow the executor to shutdown and gracefully yell at it's tasks to shutdown in a default period of 30 seconds. It will wait and then try again, if not, then well, you can't directly kill anything anymore, so you will be notified so you can do harsher punishments to these tasks.

The only exception this is NOT the case in a normal ColdBox app is when a reinit happens or when integration testing is being executed. Then we revert to the previous behavior of nuking the executors and schedulers.

AsyncManager

• shutdownAllExecutors( force, timeout )

• shutdownExecutor( name, force, timeout)

The timeout ONLY works when the force argument is false. If force is true, then it's NOT gracefully shutdown. This usually happens on ColdBox reinits or integration testing.

Schedulers

All schedulers have a shutdownTimeout property that defaults to 30 seconds. When you configure your schedulers you can change this value to whatever you see fit.

function configure(){
    
    // Set shutdown timeout to 60 seconds
    setShutdownTimeout( 60 );

}

Executors - shutdown and wait...

All executors now have a new method: shutdownAndAwaitTermination( numeric timeout = 30 ) which is used to do just that. It places the executor in shutdown mode and waits the timeout for all the tasks to complete. If they don't complete then it issues a forced shutdown.

forAttribute() - Integrate with JS Frameworks Easily

All handlers/layouts and views get a new function called forAttribute( data )which will allow you to serialize simple or complex data so it can be used within HTML attributes. This will take care of serialize the data and encoding it correctly so it can be bound to the HTML attribute so the JavaScript framework can use it as native JSON.

<div>
    <User :data="#forAttribute( prc.user.getMemento() )#">
</div>

This technique will allow you to bridge your CFML apps with your JS apps natively.

Async Interceptors Data

Finally in this version of ColdBox asynchronous interceptors will work with any complex data without any thread contingency or duplication. You can even use them for ORM events and it will work accordingly. So go for it, asynchronize your interception calls!

threadData = announce(
    state           = "onPageCreate", 
    data            = { page= local.page }, 
    asyncAll        = true,
    asyncPriority   = "high"
);

ORM Event Handling

This was a rough regression due to the way Hibernate is loaded by the CFML engines. We have moved to a lazy load first strategy on the entire architecture of the framework. So anything using the ColdBox proxy, like the ORM event handling, will now work in any loading situation.

Release Notes

Release Notes

Major Updates

API Resourceful Routes

We have created a shortcut approach to creating RESTFul API resources in your ColdBox Routers via the new method apiResources(). This method will create all the routes for your API service with no HTML views.

apiResources( "users" );
apiResources( "photos" );

Module Enhancements

We have made several enhancements with modules:

• Performance optimizations when registering and activating modules

• Modules now track their own registration and activation load times (Which are now visible in cbdebugger)

• Better logging of modules when they activate and register

Experimental New App Structure

We have been working on a new directory structure for ColdBox applications where the web root is not just dumped with everything on it. We have made several internal tickets to allow for this to work and we have a very early alpha available in github:

Scheduler and Task Updates

There are so many tickets that helped resolved issues with the ColdBox schedulers and scheduled tasks. We have also solidifying our Adobe scope issues and brought many new helpers for developers when building task objects.

Integration Testing of Subdomain/Domain Routing

If you are building multi-tenant applications with ColdBox and are leveraging domain and subdomain routing, then you can easily use the domain argument in all of our request(), execute() and HTTP Verb methods to simulate the domain in play for THAT specific spec execution.

describe( "subdomain routing", function(){
	beforeEach( function(){
		setup();
	} );
	
	it( "can match on a specific domain", function(){
		var event = execute( route: "/", domain: "subdomain-routing.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.index" );
	} );
	
	it( "skips if the domain is not matched", function(){
		var event = execute( route: "/", domain: "not-the-correct-domain.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "main.index" );
	} );
	
	it( "can match on a domain with wildcards", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "event" );
		expect( rc.event ).toBe( "subdomain.show" );
	} );
	
	it( "provides any matched values in the domain in the rc", function(){
		var event = execute( route: "/", domain: "luis.forgebox.dev" );
		var rc    = event.getCollection();
		expect( rc ).toHaveKey( "username" );
		expect( rc.username ).toBe( "luis" );
	} );
} );

Custom Session Identifiers

ColdBox has always had its internal way of figuring out what identifier to use for each user's request based on the way ColdFusion works. However, now you can influence and provide your own approach instead of relying on the core CFML approach. You will do this by adding a coldbox.identifierProvider closure/lambda into your config/Coldbox.cfc.

coldbox : {
    identifierProvider : function(){
        if( isNull( cookie.mytracker ) ){
            cookie.myTracker = createUUID();
        }
        return cookie.myTracker;
    }
}

WireBox Child Injectors

Welcome to the world of hierarchical dependency injection. We had the ability before to add a parent injector to WireBox, but now you can not only add a parent, but also many children to the hierarchy.

Every injector has the capability to store an ordered collection (ordered struct) of child injectors via the childInjectors property. Child injectors are used internally in many instances to provide a hierarchical approach to DI where instances can be searched for locally, in the parent and in the children. Here are some of the new methods to assist with child injectors:

• hasChildInjector( name ) - Verify if a child injector has been registered

• registerChildInjector( name, child ) - Register a child injector by name

• removeChildInjector( name ) - Remove a child injector by name

• getChildInjector( name ) - Get a child injector by name

• getChildInjectors() - Get all the child injectors registered

• getChildInjectorNames() - Get an array of all the registered child injectors

Child Enhanced Methods

• getInstance()

  • The getInstance()method now has an injector argument so you can EXPLICITLY request an instance from a child injector by name getInstance( name : "service", injector : "childInjector" )

  • Apart from the explicit lookup it can also do implicit hierarchical lookups using the following order:

    • Locally

    • Parent

    • All Children (in order of registration)

• containsInstance( name ) - This method now also searches in the child collection for the specific name instance. The lookup searches in the following order:

  1. Locally

  2. Parent
• shutdown() - The shutdown method has been enhanced to issue shutdown method calls to all child injectors registered.

Getting Instances From Specific Child Injectors

The getInstance() has been modified to have an injector argument that you can use to specifically ask for an instance from that child injector. If the child injector has not been registered you will get a InvalidChildInjector Exception.

getInstance( name: "CategoryService", injector : "ChildInjector" )

Child Injector Explicit DSL

The following is the DSL you can use to explicitly target a child injector for a dependency. You will prefix it with wirebox:child:{name} and the name of the injector:

// Use the property name as the instance name
property name="categoryService" inject="wirebox:child:childInjector"
// Use a specific instance name
property name="categoryService" inject="wirebox:child:childInjector:CategoryService"
// Use any DSL
property name="categoryService" inject="wirebox:child:childInjector:{DSL}"

IInjector Interface Updates

The coldbox.system.ioc.IInjector interface's getInstance() method has been modified to include support for child injector retrievals:

/**
 * Locates, Creates, Injects and Configures an object model instance
 *
 * @name The mapping name or CFC instance path to try to build up
 * @initArguments The constructor structure of arguments to passthrough when initializing the instance
 * @dsl The dsl string to use to retrieve the instance model object, mutually exclusive with 'name'
 * @targetObject The object requesting the dependency, usually only used by DSL lookups
 * @injector The child injector name to use when retrieving the instance
 */
function getInstance(
	name,
	struct initArguments,
	dsl,
	targetObject = "",
	injector
);

Release Notes

Compatibility Notes

Please note that the following ticket corrects behavior in ColdBox that MIGHT affect interceptors that have injected dependencies that have the same name as application helper methods from other modules.

Example:

component 
{

    // inject cbauth so we can use it in our interceptor
    property name="auth" inject="provider:authenticationService@cbauth";

    function preProcess( event ) {

        writeDump( auth.isLoggedIn() );

    }

}

The interceptor above has a dependency of auth from the cbauth module. However, the cbauth module also has an application helper called auth. So at runtime, this will throw an exception:

Routines cannot be declared more than once.
The routine auth has been declared twice in different templates.

ColdFusion cannot determine the line of the template that caused this error. This is often caused by an error in the exception handling subsystem.

This is because now we can't inject the cbauth mixin because we already have a cbauth dependency injected. The resolution, is to RENAME the injection variables so they don't collide with module application helpers.

6.5.2 Release Notes - July 14, 2021

Regression

• COLDBOX-1024 Module helpers no longer injected/mixed into interceptors

6.5.1 Release Notes - July 12th, 2021

Bug

• COLDBOX-1024 Module helpers no longer injected/mixed into interceptors

Improvement

• COLDBOX-1026 Update BeanPopulator for Hibernate 5 detection in Lucee new extension

• COLDBOX-1025 Added back the finally block, just to make sure cleanup are done in bootstrap reinits

6.5.0 Release Notes - July 9th, 2021

ColdBox 6.3.0 is a minor release that squashes lots of bugs and does tons of improvements for performance!

ColdBox 6.2.0 is a minor release with some major improvements in many areas like:

• Async programming

• Logging

• Object creations

• WireBox Mappings and Binders

WireBox Binder & Mapping Objects Rewritten

This is a major change in the core as we have finally rewritten the WireBox Binder and object Mapping objects to script. This resulted in a 45-50% code reduction for those objects and an impressive 30% speed improvements when creating and processing mappings with the new binder processing optimizations. We analyzed every single line of code on these two objects and we are incredibly satisfied with the initial results.

That's right, we have some async goodness prepared for future versions when dealing with multiple directory mappings and much more.

Async Package Performance Upgrades

We have done more runtime analysis on our asynchronous package and we have optimized the heck out of it using the amazing FusionReactor Profilers! Especially the applyAll() and collection based parallel computing. We reached a point where all of our tests cases where running faster than even native Lucee/Adobe 2021 parallel constructs. Below you can see a snapshot of our test bed creating 1000 transient objects with dependency injections and object populations using async constructs.

You can find our test bed here: https://github.com/ColdBox/coldbox-platform/blob/development/tests/suites/async/performance-parallel-tests.cfm

Just a reminder that the ColdBox async capabilities are all powered by the Java concurrency packages leveraging Completable Futures, Executors and Scheduled Tasks. It is not only true to the Java API but we have made tons of enhancements especially for ColdFusion and its dynamic nature. Check out our docs!

It is also available to ANY ColdFusion application that is NOT running ColdBox. This is achieved by using either of our standalone libraries: WireBox, CacheBox and LogBox.

Test Dependency Injection

This version introduces the capability for you to tag your integration tests with an autowire annotation on the component tag. By adding this annotation, your test object will be inspected and wired with dependencies just like any other WireBox object.

component extends="coldbox.system.testing.BaseTestCase" autowire {

    // DI
    property name="securityService" inject="provider:securityService";
    property name="jwt"             inject="provider:JWTService@cbsecurity";
    property name="cbsecure"        inject="provider:CBSecurity@cbsecurity";
    property name="qb"              inject="provider:QueryBuilder@qb";

    /*********************************** BDD SUITES ***********************************/
    function run(){
        describe( "Authentication Specs", function(){
            beforeEach( function( currentSpec ){
                // Setup as a new ColdBox request for this suite, VERY IMPORTANT. ELSE EVERYTHING LOOKS LIKE THE SAME REQUEST.
                setup();
                // Make sure nothing is logged in to start our calls
                securityService.logout();
                jwt.getTokenStorage().clearAll();
            } );

            story( "I want to authenticate a user via username/password and receive a JWT token", function(){
                given( "a valid username and password", function(){
                    then( "I will be authenticated and will receive the JWT token", function(){
                        // Use a user in the seeded db
                        var event = this.post(
                            "/api/v1/login",
                            {
                                username : variables.testEmployeeEmail,
                                password : variables.testPassword
                            }
                        );
                        var response = event.getPrivateValue( "Response" );
                        expect( response.getError() ).toBeFalse( response.getMessagesString() );
                        expect( response.getData() ).toHaveKey( "token,user" );
                        // debug( response.getData() );
                        var decoded = jwt.decode( response.getData().token );
                        expect( decoded.sub ).toBe( variables.testEmployeeId );
                        expect( decoded.exp ).toBeGTE( dateAdd( "h", 1, decoded.iat ) );
                        expect( response.getData().user.userId ).toBe( variables.testEmployeeId );
                    } );
                } );
                given( "invalid username and password", function(){
                    then( "I will receive a 401 invalid credentials exception ", function(){
                        var event = this.post(
                            "/api/v1/login",
                            { username : "invalid", password : "invalid" }
                        );
                        var response = event.getPrivateValue( "Response" );
                        expect( response.getError() ).toBeTrue();
                        expect( response.getStatusCode() ).toBe( 401 );
                    } );
                } );
            } );

        } );
    }

}

ColdBox Test Matchers

We have also included a new object coldbox.system.testing.CustomMatchers which will register matchers into TestBox when doing integration tests. It will give you the nice ability to expect status codes and validation exceptions on RESTFul Requests via the ColdBox Response object.

• toHaveStatus()

• toHaveInvalidData()

var event = this.post(
    "/api/v1/login",
    { username : "invalid", password : "invalid" }
);
var response = event.getPrivateValue( "Response" );
expect( response.getError() ).toBeTrue();
expect( response.getStatusCode() ).toBe( 401 );

var event = this.post(
    "api/v1/timelogs",
    { description : "A nice unit test" }
);
expect( event.getResponse() ).toHaveStatus( 400 );
expect( event.getResponse() ).toHaveInvalidData( "project", "is required" )
expect( event.getResponse() ).toHaveInvalidData( "task", "is required" )
expect( event.getResponse() ).toHaveInvalidData( "user", "is required" )

More Rendering Improvements

Thanks to Dom Watson (@dom_watson) from PresideCMS (@presidecms) for many contributions to help clean up ColdBox view rendering! This release focuses on more performance and memory utilization updates, as well as refactoring external dependencies from pre singleton rendering approaches, which has resulted in more performance gains and lower memory usages on high rendering apps.

Whoops! Keeps Getting Better

We have had tons of updates and requests from our new exception handling experience in ColdBox: Whoops! In this release we tackle CFML core engine files so they can render appropriately, AJAX rendering for exceptions and best of all a huge performance and size boost when dealing with exceptions. Even when dealing with exceptions we want the best and the fastest experience possible for our developers.

The previous approach whoops took was to read and load all the source code of all the templates that caused the exception. You could then navigate them to discover your faults. However, each template could be loaded from 1 to up to 10 times if the stack trace followed it. In this new update we provide source template caching and dynamic runtime injection and highlighting of the source code. This has granted us the following improvements in small test cases (Your improvements could be higher)

Original Size: 218.54 KB New Size: 145.22 KB About 30-40% reduction on size depending on repetition of the templates

Original Rendering Speed: 288ms New Rendering Speed: 76ms About 74-80% rendering improvements

Release Notes

6.2.0

6.2.1

6.2.2

ColdBox 6.0.0 is a major release for the ColdBox HMVC platform. It has some dramatic new features as we keep pushing for more modern and sustainable approaches to web development. We break down the major areas of development below and you can also find the full release notes per library at the end.

Engine Support

It is also yet another source code reduction due to the dropping of support for the following CFML Engines:

• Adobe ColdFusion 11

• Lucee 4.5

The info-graphic above shows you the supported engines the 6.x platform will support.

Asynchronous Programming

We have done a tremendous amount of work to expose all the async and parallel programming constructs in ColdBox to the entire framework so developers can leverage them. There is just so much we have done on this release for concurrency, task scheduling, and parallel programming to include in one page. So visit our Async Programming section to start delving into what we are lovingly calling cbFutures!

ColdBox Executors & Tasks

Thanks to our new futures approach, all major internal libraries (WireBox, CacheBox, LogBox, MVC) will leverage them for different tasks that require asynchronicity and scheduling. You will see a noticeble difference especially in the following areas:

• Cache Reaping: All cache reaping is now done via a scheduled task running on specific frequencies

• File Appenders: It uses an async schedule to stream log data to files instead of blocking operations for sending logs. It will use a logging in-memory queue to stream the log data to the file. So you can potentially send 10000 log events and eventually they will be streamed to disk.

What are ColdBox Futures?

A ColdBox future is used for async/parallel programming where you can register a task or multiple tasks that will execute in a non-blocking approach and trigger dependent computations which could also be asynchronous. This Future object can then be used to monitor the execution of the task and create rich completion/combining pipelines upon the results of such tasks. You can still use a get() blocking operation, but that is an over simplistic approach to async programming because you are ultimately blocking to get the result.

ColdBox futures are backed by Java's CompletableFuture API, so the majority of things will apply as well; even Java developers will feel at home. It will allow you to create rich pipelines for creating multiple Futures, chaining, composing and combining results.

// Parallel Executions
async().all(
    () => hyper.post( "/somewhere" ),
    () => hyper.post( "/somewhereElse" ),
    () => hyper.post( "/another" )
).then( (results)=> logResults( results ) );

// Race Conditions, let the fastest dns resolve
var dnsServer = async().any( 
    () => dns1.resolve(),
    () => dns2.resolve()
).get();

// Process an incoming order
async().newFuture( () => orderService.getOrder() )
    .then( (order) => enrichOrder( order ) )
    .then( (order) => performPayment( order ) )
    .thenAsync( 
        (order) => dispatchOrder( order ), 
        async().getExecutor( "cpuIntensive" )
     )
    .then( (order) => sendConfirmation( order ) );

// Combine Futures
var bmi = async().newFuture( () => weightService.getWeight( rc.person ) )
    .thenCombine(
        async().newFuture( () => heightService.getHeight( rc.person ) ),
        ( weight, height ) => {
            var heightInMeters = arguments.height/100;
            return arguments.weight / (heightInMeters * heightInMeters );
        }
    )
    .get();

// Compose Futures with exceptions
async()
    .newFuture( () => userService.getOrFail( rc.id ) )
    .thenCompose( ( user ) => creditService.getCreditRating( user ) )
    .then( (creditRating) => event.getResponse().setData( creditRating ) )
    .onException( (ex) => event.getResponse().setError( true ).setMessages( ex.toString() ) );

This new approach to creating async pipelines and parallel processing, will further create extensibility and robustness in your ColdBox applications.

coldbox-tasks Global Executor

ColdBox apps by default register a coldbox-tasks fixed executor (20 threads - IO bound) that is used internally for cleanups, tasks, and schedules. However, any module or application can leverage it for scheduling tasks or workers.

asyncManager.getExecutor( "coldbox-tasks" )

CacheBox Executors

CacheBox has been refactored to leverage the async facilities in ColdBox to schedule cache reaps instead of a request initiating the reaps. This brings a lot more stability and consistency to the reaping of caches as they all execute within the new ColdBox coldbox-tasks schedule task executor.

If you are in CacheBox standalone mode, then the task scheduler will be called cachebox-tasks.

Logging Enhancements

LogBox has been entirely rewritten in script and a more fluent programming approach. It has also been revamped to leverage the scheduling executors and async programming aspects of our async package. All loggers now sport logging via an async queue and it is completely non-blocking. If you do heavy logging, the performance will be substantial.

The ModuleService and all internal ColdBox services have deeper logging constructs and more information logging to understand what happens inside of the core.

Whoops! Modern Exception Handling

Thanks to Eric Peterson, we have included Whoops as part of our core exception handling template. All the new application templates come pre-configured with whoops as part of the development custom error template.

function development() {
    coldbox.exceptionEditor = "vscode";
    // coldbox.customErrorTemplate = "/coldbox/system/exceptions/BugReport.cfm"; // static bug reports
    coldbox.customErrorTemplate = "/coldbox/system/exceptions/Whoops.cfm"; // interactive bug report
}

This exception template will help you visualize and navigate your exceptions so you can fix those pesky bugs 🐞. You can even configure it to open the files directly into your favorite IDE using the coldbox.exceptionEditor setting:

function development() {
    coldbox.exceptionEditor = "vscode";
}

Valid Exception Editors are:

• vscode (Default)

• vscode-insiders

• sublime

• textmate

• emacs

• macvim

• idea

• atom

• espresso

RestHandler & ColdBox Response

After many years of adding a base handler and a response object to our application templates, we finally have integrated them into the core so developers can have even more support when building RESTFul services. This new rest handler will provide you with tons of utilities and approaches to make all of your RESTFul services:

• Uniform

• Consistent

• A consistent and extensible response object

• Error handling

• Invalid Route handling

• Much more

Base Class

New base class coldbox.system.RestHandler which you can inherit from or use our new restHandler annotation. This will give you access to our enhanced API utilities and the native response object via the request context's getResponse() method.

component extends="coldbox.system.RestHandler"{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }
}

component resthandler{

  function index( event, rc, prc ){
    event.getResponse()
      .setData( "Hello from restful Land" );
  }

}

You can now build all of your api’s using the native response object like the rest templates, but now from the core directly. This Rest Handler gives you the following actions out of the box:

AroundHandler in Detail

The aroundHandler() provided in the RestHandler will intercept all rest calls in order to provide consistency and uniformity to all your actions. It will try/catch for major known exceptions, time your requests, add extra output on development and much more. Here are a list of the features available to you:

• Exception Handling

  • Automatic trapping of the following exceptions: InvalidCredentials, ValidationException, EntityNotFound, RecordNotFound

  • Automatic trapping of other exceptions

  • Logging automatically the exception with extra restful metadata

  • If in a development environment it will respond with much more information necessary for debugging both in the response object and headers

• Development Responses

  • If you are in a development environment it will set the following headers for you:

    • x-current-route

• Global Headers

  • The following headers are sent in each request

    • x-response-time : The time the request took in CF

The aroundHandler() is also smart in detecting the following outputs from a handler:

• Handler return results

• Setting a view or layout to render

• Explicit renderData() calls

RequestContext Additions

• getResponse()

  • Will get you the current prc.response object, if the object doesn’t exist, it will create it and set it for you

  • The core response object can be found here: coldbox.system.web.context.Response

Extending The RestHandler

If you would like to extend or modify the behavior of the core RestHandler then you will have to create your own base handler that inherits from it. Then all of your concrete handlers will inherit from your very own handler.

// BaseHandler
component extends="coldbox.system.Resthandler"{

  // Modify it here

}

// Then make your own handlers extend from it
component extends="BaseHandler"{

}

Extending The Response Object

The response object can be found here: coldbox.system.web.context.Response and the rest handler constructs it by calling the request context’s getResponse() method. The method verifies if there is a prc.response object and if it exists it returns it, else it creates a new one. So if you would like to use your very own, then just make sure that before the request you place your own response object in the prc scope.

Here is a simple example using a preProcess() interceptor. Create a simple interceptor with commandbox e.g

coldbox create interceptor name=MyInterceptor points=preProcess

and add the following method:

function preProcess( event, interceptData, rc, prc ){
  prc.response = wirebox.getInstance( "MyResponseObject" );
}

Don't forget to register your interceptor in config/Coldbox.cfc:

		interceptors = [
			{
			class      : "interceptors.MyInterceptor",
				name       : "MyInterceptor",
				properties : {}
			}
		];

That’s it. Once that response object is in the prc scope, ColdBox will utilize it. Just make sure that your custom Response object satisfies the methods in the core one. If you want to modify the output of the response object a good place to do that would be in the getDataPacket() method of your own MyResponseObject. Just make sure this method will return a struct.

Functional If's using when()

Our super type now includes a new when() method that will allow you to build functional statements within your handlers. Here is the signature of this functional helper:

/**
 * Functional construct for if statements
 *
 * @target The boolean evaluator, this can be a boolean value
 * @success The closure/lambda to execute if the boolean value is true
 * @failure The closure/lambda to execute if the boolean value is false
 *
 * @return Returns the super type for chaining
 */
function when( required boolean target, required success, failure )

The target is a boolean and can be an expression that evaluates to a boolean. If the target is true, then the success closure will be executed for you, if not, the failure closure will be executed.

function save( event, rc, prc ){
    var oUser = populateModel( "User" );
    
    when( hasAccess(), () => oUser.setRole( rc.role ) );

}

ColdBox Renderer Becomes a Singleton

The entire rendering mechanisms have changed in ColdBox 6 and we now support a singleton based approach to view rendering. It still allows for variable safety, but the way renderings in ColdBox 6 are done are orders of magnitude faster than pre ColdBox 6 days. If you are using applications like ContentBox or Preside CMS or applications with tons of renderView() calls, your applications will fly now!

Custom ReinitKey

Thanks to a community pull request you now have the ability to chose the reinit key instead of the default of fwReinit. This is useful for security purposes.

coldbox.reinitKey = "cbReinit";

Then you can use it in the request: http://localhost/index.cfm?cbReinit=true

LogBox Config Path Init

If you are using LogBox in standalone mode, you can now construct it by passing the path to your LogBox configuration file or no path at all and we will construct LogBox with our new default config file to stream logs to the console.

application.logbox = new LogBox();

application.logbox = new LogBox( "config.MyLogBox" );

AnnounceInterception(), processState() Deprecated

These methods have been deprecated in favor of our new announce() method. We have also deprecated the argument interceptData in favor of just data.

// New consistent method
announce( state, data );

// Usage
announce( "myCustomEvent", { data = this } );

New listen() method to register one-off closures

Have you ever wanted to dynamically listen to events but not create CFC to enclose the method? Well, now you can use the new listen() method which accepts a closure/udf so you can listen to ColdBox interceptions. Here is the method signature:

/**
 * Register a closure listener as an interceptor on a specific point
 *
 * @target The closure/lambda to register
 * @point The interception point to register the listener to
 */
void function listen( required target, required point )

This allows you to easily register dynamic closures/udfs whenever you like so they can listen to events:

// Within a handler/interceptor/layouts/view
listen( function(){
    log.info( "executing from closure listener");
}, "preProcess" );

listen( () => log.info( "executing from closure listener"), "preProcess" );

// Within models (Injecting the interceptor service or controller)
controller
    .getInterceptorService()
    .listen( function(){
        log.info( "executing from closure listener");
    }, "preProcess" );