ColdBox HMVC Platform- v6.x

• Much More

It provides a set of reusable code and tools that can be used to increase your development productivity as well as a development standard for working in team environments.

Versioning

<major>.<minor>.<patch>

And constructed with the following guidelines:

• Breaking backward compatibility bumps the major (and resets the minor and patch)

• New additions without breaking backward compatibility bumps the minor (and resets the patch)

• Bug fixes and misc changes bumps the patch

License

• Copyright by Ortus Solutions, Corp

• ColdBox, CacheBox, WireBox, LogBox are registered trademarks by Ortus Solutions, Corp

Discussion & Help

Reporting a Bug

Jira Issue Tracking

Professional Open Source

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

Resources

HONOR GOES TO GOD ABOVE ALL

Because of His grace, this project exists. If you don't like this, then don't read it, it's not for you.

"Therefore being justified by faith, we have peace with God through our Lord Jesus Christ: By whom also we have access by faith into this grace wherein we stand, and rejoice in hope of the glory of God." Romans 5:5

Added

• Github actions for LTS Releases

• LTS Updates

Bugs

Release notes - ColdBox Platform - 6.11.0

New Feature

Improvement

Bug

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 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

Release Notes

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

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

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

Added

Improvements

Fixed

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

6.5.1 Release Notes - July 12th, 2021

Bug

Improvement

6.5.0 Release Notes - July 9th, 2021

Release notes - ColdBox Platform - 6.10.0

Bug

Improvement

Bug

Release Notes

• The majority of code examples in this book are done in cfscript.

• All ColdFusion examples designed to run on the open source Lucee Platform or Adobe ColdFusion 11+

External Trademarks & Copyrights

Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc.

ColdBox, CommandBox, FORGEBOX, TestBox, ContentBox, Ortus Solutions are all trademarks and copyrights of Ortus Solutions, Corp.

Notice of Liability

The information in this book is distributed “as is”, without warranty. The author and Ortus Solutions, Corp shall not have any liability to any person or entity with respect to loss or damage caused or alleged to be caused directly or indirectly by the content of this training book, software and resources described in it.

Contributing

Charitable Proceeds

Shalom Children's Home

Shalom now cares for over 80 children in El Salvador, from newborns to 18 years old. They receive shelter, clothing, food, medical care, education and life skills training in a Christian environment. The home is supported by a child sponsorship program.

We have personally supported Shalom for over 6 years now; it is a place of blessing for many children in El Salvador that either have no families or have been abandoned. This is good earth to seed and plant.

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

Requirements

• Grab a cup of coffee or tea

• Get comfortable

Need Help?

Welcome to the world of ColdBox!

We are excited you are taking this development journey with us. Before we get started with ColdBox let's install CommandBox CLI, which will allow you to install/uninstall dependencies, start servers, have a REPL tool and much more.

IDE Tools

ColdBox has the following supported IDE Tools:

CommandBox CLI

Download CommandBox

1. No Java Runtime (30mb)

2. Embedded Runtime (80mb)

Starting CommandBox

Once you download and expand CommandBox you will have the box.exe or box binary, which you can place in your Windows Path or *Unix /usr/bin folder to have it available system wide. Then just open the binary and CommandBox will unpack itself your user's directory: {User}/.CommandBox. This happens only once and the next thing you know, you are in the CommandBox interactive shell!

We will be able to execute a-la-carte commands from our command line or go into the interactive shell for multiple commands. We recommend the interactive shell as it is faster and can remain open in your project root.

Installing ColdBox

To get started open the CommandBox binary or enter the shell by typing box in your terminal or console. Then let's create a new folder and install ColdBox into a directory.

mkdir 60-minute-quickstart --cd
install coldbox

Dir 0 Jan 25,2021 11:04:05 coldbox
File 112 Jan 25,2021 11:04:05 box.json

Uninstalling ColdBox

To uninstall ColdBox from this application folder just type uninstall coldbox. Try it out!

Updating ColdBox

To update ColdBox from a previous version, just type update coldbox.

• AdvancedScript (default): A script based advanced template

• rest: A RESTFul services template

• rest-hmvc: A RESTFul service built with modules

• Simple : A traditional simple template

• SuperSimple : The bare-bones template

Scaffolding Our Application

So let's create our first app using the default template skeleton AdvancedScript:

coldbox create app Quickstart

This will scaffold the application and also install ColdBox for you. The following folders/files are generated for you:

+ coldbox // The ColdBox framework library (CommandBox Tracked)
+ config // Configuration files
+ handlers // Your handlers/controllers
+ includes // static assets
+ interceptors // global interceptors
+ layouts // Your layouts
+ lib // Java Jars to load
+ models // Your Models
+ modules // CommandBox Tracked Modules
+ modules_app // Custom modules
+ tests // Test harness
+ views // Your Views
+ Application.cfc // Bootstrap
+ box.json // CommandBox package descriptor
+ index.cfm // Front controller

Now let's start a server so we can see our application running:

server start

Default Event

This command will start a server with URL rewrites enabled, open a web browser for you and execute the index.cfm which in turn executes the default event by convention in a ColdBox application: main.index. This is now our first convention!

Hooray, we have scaffolded our first application, started a server and executed the default event. Explore the application template generated, as it contains many useful information about your application.

File/Folder Conventions

Re-initializing The Application

There will be times when you make configuration or code changes that are not reflected immediately in the application due to caching. You can tell the framework to reinit or restart the application for you via the URL by leveraging the special URL variable fwreinit.

http://localhost:{port}/?fwreinit=1

You can also use CommandBox to reinit the application:

coldbox reinit

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

• 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

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

  3. Children

• 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

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

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

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

    • x-current-routed-url

    • x-current-routed-namespace

    • x-current-event

• Global Headers

  • The following headers are sent in each request

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

    • x-cached-response : If the request is cached via event caching

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" );

New Interception: onColdBoxShutdown()

We have created a new interception point that is fired before ColdBox is shutdown completely. This can come from a reinit or an application expiration. This is a great place to shutdown custom executors, or messaging queues like RabbitMQ.

function onColdBoxShutdown(){
    myRabbitMQChannel.close();
}

Routing Enhancements

We have done several enhancements to the entire routing capabilities in ColdBox apart from several bug fixes.

buildLink() Ease of Use

We have also re-arranged the arguments so you can easily build links with query strings using positional arguments instead of name-value pairs:

string function buildLink(
    to,
    queryString       = "",
    boolean translate = true,
    boolean ssl,
    baseURL     = ""
);

<a href="#event.buildLink( 'main.list', 'userid=4' )#">My Link</a>

buildLink() Named Route Support

The request context method event.buildLink() has been now added named route support. The event.route() method was introduced to do named routing with a name and params argument. Now, you can also use this approach but via the to argument in the buildLink() method by just passing a struct.

// Using the route() method
event.route( "contactUs", { id : 3 } )

// Using the buildLink() method and the to struct arg
event.buildLink( { name : "contactUs", params : { id : 3 } } )

Route Metadata

You can now add custom metadata to specific route or resourceful routes by using the meta() method or the meta argument. This is simply a struct of name value pairs you can add into the route record.

route( "/render/:format" )
	.meta( { secure : false } )
	.to( "actionRendering.index" );

// Resources
	resources(
		resource: "photos",
		meta    : { secure : true }
	);

Now, how good is adding the metadata if you can't get it. So you can get the current route's metadata via the new request context method: getCurrentRouteMeta() method:

if( event.getCurrentRouteMeta().secure ){
  // secure it.
}

Route Record

We have also added the method getCurrentRouteRecord() to the request context so you can get the struct definition of the route record of the currently routed route. Below is a sample screenshot of the record:

Dynamic Routing Redirection

The toRedirect() method has been enhanced to accept a closure as the target of relocation. This closure will received the parsed parameters, the incoming route record and the event object. You can now determine dynamically where the relocation will go.

( route, params, event ) => "/new/route" 

function( route, params, event ){ return "/new/route"; }

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

route( "/old/api/users/:id" )
    .toRedirect( ( route, params, event ) => { return "/api/v1/users/#params.id#" } )

Happy Redirecting!

Release Notes

The full release notes per library can be found below. Just click on the library tab and explore their release notes:

Event handlers are the controller layer in ColdBox and is what you will be executing via the URLor a FORMpost. All event handlers are singletons, which means they are cached for the duration of the application, so always remember to var scope your variables in your functions.

/**
 * Development environment
 */
function development() {
    coldbox.customErrorTemplate = "/coldbox/system/exceptions/Whoops.cfm"; // interactive bug report
    coldbox.handlerCaching = false;
    coldbox.handlersIndexAutoReload = true;
    coldbox.eventCaching = false;
    coldbox.viewCaching = false;
}

Handler Code

Go open the handlers/main.cfc and let's explore the code.

component extends="coldbox.system.EventHandler" {

    /**
     * Default Action
     */
    function index( event, rc, prc ) {
        prc.welcomeMessage = "Welcome to ColdBox!";
        event.setView( "main/index" );
    }

    /**
     * Produce some restfulf data
     */
    function data( event, rc, prc ) {
        return [
            { "id" : createUUID(), name : "Luis" },
            { "id" : createUUID(), name : "JOe" },
            { "id" : createUUID(), name : "Bob" },
            { "id" : createUUID(), name : "Darth" }
        ];
    }

    /**
     * Relocation example
     */
    function doSomething( event, rc, prc ) {
        relocate( "main.index" );
    }

    /************************************** IMPLICIT ACTIONS *********************************************/

    function onAppInit( event, rc, prc ) {
    }

    function onRequestStart( event, rc, prc ) {
    }

    function onRequestEnd( event, rc, prc ) {
    }

    function onSessionStart( event, rc, prc ) {
    }

    function onSessionEnd( event, rc, prc ) {
        var sessionScope     = event.getValue( "sessionReference" );
        var applicationScope = event.getValue( "applicationReference" );
    }

    function onException( event, rc, prc ) {
        event.setHTTPHeader( statusCode = 500 );
        // Grab Exception From private request collection, placed by ColdBox Exception Handling
        var exception = prc.exception;
        // Place exception handler below:
    }

}

Let's recap: Every action in ColdBox receives three arguments:

• rc - A struct that contains both URL/FORM variables (unsafe data)

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

Setting Views - Default Layout

This line event.setView( "main/index" ) in the index action told ColdBox to render a view back to the user found in views/main/index.cfm.

ColdBox also has the concepts of layouts, which are essentially reusable views that can wrap other views or layouts. They allow you to reuse content so you can render views/layouts inside in a specific location in the CFML content. By convention, ColdBox looks for a layout called layouts/Main.cfm. This is yet another convention, the default layout. Your application can have many layouts or non layouts at all.

Executing Events

We have now seen how to add handlers via CommandBox using the coldbox create handler command and also execute them by convention by leveraging the following URL pattern:

http://localhost:{port}/folder/handler/action
http://localhost:{port}/handler/action
http://localhost:{port}/handler

Also remember, that if no action is defined in the incoming URL then the default action of index will be used.

Working With Incoming Data

Now, let's open the handler we created before called handlers/hello.cfc and add some public and private variables to it so our views can render the variables.

function index( event, rc, prc ){
    // param an incoming variable.
    event.paramValue( "name", "nobody" );
    // set a private variable
    prc.when = dateFormat( now(), "full" );
    // set the view to render
    event.setView( "hello/index" );
}

Let's open the view now: views/hello/index.cfm and change it to this:

<cfoutput>
<p>Hello #encodeForHTML( rc.name )#, today is #prc.when#</p>
</cfoutput>

If you execute the event now: http://localhost:{port}/hello/index you will see a message of Hello nobody.

Now change the incoming URL to this: http://localhost:{port}/hello/index?name=ColdBox and you will see a message of Hello ColdBox.

ColdBox 6.4.0 is more of a major than a minor release due to the amount of work we have done to bring you one of the most revolutionary features of this framework: Scheduled Tasks.

ColdBox Scheduled Tasks

Scheduled tasks have always been a point of soreness for many developers in ANY language. Especially choosing where to place them for execution: should it be cron? windows task scheduler? ColdFusion engine? Jenkins, Gitlab? and the list goes on and on.

The ColdBox Scheduled Tasks offers a fresh, programmatic and human approach to scheduling tasks on your server and multi-server application. It allows you to define your tasks in a portable Scheduler we lovingly call the Scheduler.cfc which not only can be used to define your tasks, but also monitor all of their life-cycles and metrics of tasks. Since ColdBox is also hierarchical, it allows for every single ColdBox Module to also define a Scheduler and register their own tasks as well. This is a revolutionary approach to scheduling tasks in an HMVC application.

You can learn all about them in our two sections:

Release Notes

Handler Scaffolding

Now let's create our first controller, which in ColdBox is called Event Handler. Let's go to CommandBox again:

coldbox create handler name="hello" actions="index"

This will generate the following files:

• A new handler called hello.cfc inside of the handlers folder

• A view called index.cfm in the views/hello folder

• An integration test at tests/specs/integration/helloTest.cfc.

Default URL Routing

Now go to your browser and enter the following URL to execute the generated event:

# With rewrites enabled
http://localhost:{port}/hello/index

You will now see a big hello.index outputted to the screen. You have now created your first handler and view combination. However, how did this work? It works as ColdBox by convention creates another agreement with you on how to execute events, default URL routing.

Your application router is located at : config/Router.cfc. It will include a few default routes for you and the following default URL route:

// Conventions based routing
route( ":handler/:action?" ).end();

This route tells ColdBox to look for the names of handlers (including directory names) and for names of the handler actions (functions). The ? on the :action portion denotes that the action might or might not exist in the URL. If it doesn't exist, then another convention is in play, the default action which is index.

Handler Code

Let's check out the handler code:

component{

    /**
     * Default Action
     */
     function index( event, rc, prc ){
        event.setView( "hello/index" );
     }


}

As you can see, a handler is a simple CFC with functions on them. Each function maps to an action that is executed via the URL. The default action in ColdBox is index()which receives three arguments:

• rc - A struct that contains both URL/FORM variables (unsafe data)

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

Executing Events

Did you detect a convention here?

The sections in the URL are the same as the name of the event handler CFC (hello.cfc) and method that was generated index(). By convention, this is how you execute events in ColdBox by leveraging the following URL pattern that matches the name of a handler and action function.

http://localhost:{port}/folder/handler/action
http://localhost:{port}/handler/action
http://localhost:{port}/handler

If no action is defined in the URL then the default action of index will be used.

All of this URL magic happens thanks to the URL mappings capabilities in ColdBox. By convention, you can write beautiful URLs that are RESTFul and by convention. You can also extend them and create more expressive URL Mappings by leveraging the config/Router.cfc which is your application router.

My First Virtual Event

Now let's create a virtual event, which is basically just a view we want to execute with no event handler controller needed. This is a great way to incorporate non-mvc files into ColdBox. Migrating from a traditional application?

coldbox create view name="virtual/hello"

Open the view now (/views/virtual/hello.cfm) and add the following:

<h1>Hello from ColdBox Land!</h1>

Then go execute the virtual event:

http://localhost:{port}/virtual/hello

You will get the Hello From ColdBox Land! displayed! This is a great way to create tests or even bring in legacy/procedural templates into an MVC framework.

Luis Fernando Majano Lainez

Luis has a passion for Jesus, tennis, golf, volleyball and anything electronic. Random Author Facts:

• He played volleyball in the Salvadorean National Team at the tender age of 17

• The Lord of the Rings and The Hobbit is something he reads every 5 years. (Geek!)

• His first ever computer was a Texas Instrument TI-86 that his parents gave him in 1986. After some time digesting his very first BASIC book, he had written his own tic-tac-toe game at the age of 9. (Extra geek!)

• He has a geek love for circuits, micro-controllers and overall embedded systems.

• He has of late (during old age) become a fan of organic gardening.

Keep Jesus number one in your life and in your heart. I did and it changed my life from desolation, defeat and failure to an abundant life full of love, thankfulness, joy and overwhelming peace. As this world breathes failure and fear upon any life, Jesus brings power, love and a sound mind to everybody!

“Trust in the LORD with all your heart, and do not lean on your own understanding.” – Proverbs 3:5

Contributors

Jorge Emilio Reyes Bendeck

Jorge started working as project manager and business developer at Ortus Solutions, Corp. in 2013, . At Ortus he fell in love with software development and now enjoys taking part on software development projects and software documentation! He is a fellow Christian who loves to play the guitar, worship and rejoice in the Lord!

Therefore, if anyone is in Christ, the new creation has come: The old has gone, the new is here! 2 Corinthians 5:17

Brad Wood

Brad's CommandBox Snake high score is 141.

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:

controller.getRoutingService()

property name="routingService" inject="coldbox:routingService"

Method Changes

getModel() Removed