CommandBox : CLI, Package Manager, REPL & More
5.9.0
5.9.0
  • Introduction
  • About This Book
  • Authors
  • Overview
  • Release History
    • 5.x Versions
      • What's New in 5.9.1
      • What's New in 5.9.0
      • What's New in 5.8.0
      • What's New in 5.7.0
      • What's New in 5.6.0
      • What's New in 5.5.2
      • What's New in 5.5.1
      • What's New in 5.4.2
      • What's New in 5.4.1
      • What's New in 5.4.0
      • What's New in 5.3.1
      • What's New in 5.3.0
      • What's New in 5.2.1
      • What's New in 5.2.0
      • What's New in 5.1.1
      • What's New in 5.1.0
      • What's New in 5.0.0
    • 4.x Versions
      • What's new in 4.8.0
      • What's New in 4.7.0
      • What's New in 4.6.0
      • What's New in 4.5.0
      • What's New in 4.4.0
      • What's New in 4.3.0
      • What's New in 4.2.0
      • What's New in 4.1.0
      • What's New in 4.0.0
    • 3.x Versions
      • What's New in 3.9.0
      • What's New in 3.8.0
      • What's New in 3.7.0
      • What's New in 3.6.0
      • What's New in 3.5.0
      • What's New in 3.4.0
      • What's New in 3.3.0
      • What's New in 3.2.0
      • What's New in 3.1.1
      • What's New in 3.0.1
      • What's New in 3.0.0
    • 2.x Versions
      • What's New in 2.2.0
      • What's New in 2.1.1
      • What's New in 2.1.0
      • What's New in 2.0.0
    • 1.x Versions
      • What's in 1.0.0
  • Getting Started Guide
  • Setup
    • Requirements
    • Download
    • Installation
    • Light and Thin Binaries
    • Non-Oracle JREs
    • Upgrading
    • Common Errors
  • Usage
    • Execution
      • Recipes
      • CFML Files
        • Using a DB in CFML scripts
      • OS Binaries
      • CFML Functions
      • Exit Codes
    • Commands
    • Parameters
      • Escaping Special Characters
      • File Paths
      • Globbing Patterns
      • Piping into Commands
      • Expressions
    • Command Help
    • Environment Variables
    • System Settings
    • System Setting Expansion Namespaces
    • Ad-hoc Command Aliases
    • Default Command Parameters
    • REPL
    • Tab Completion
    • Interactive Shell Features
    • forEach Command
    • watch Command
    • jq Command
    • printTable Command
    • sql Command
    • Auto Update Checks
    • Bullet Train Prompt
    • 256 Color Support
    • A Little Fun
  • IDE Integrations
    • Sublime Text
    • Visual Studio Code
  • Config Settings
    • Module Settings
    • Proxy Settings
    • Endpoint Settings
    • Server Settings
    • JSON Settings
    • Misc Settings
    • Task Runner Settings
    • Setting Sync
    • Env Var Overrides
  • Embedded Server
    • Multi-Engine Support
    • ModCFML Support
    • Server Versions
    • Start HTML Server
    • Offline Server Starts
    • Debugging Server Starts
    • Server Processes
    • Manage Servers
    • FusionReactor
    • Server Logs
    • Server Scripts
    • Configuring Your Server
      • Security
        • Basic Authentication
        • Client Cert Authentication
      • Server Profiles
      • Server Rules
        • Baked in Rules
        • Allowed Static Files
        • Rule Language
        • Custom Predicates/Handlers
        • Rule Examples
        • Debugging Server Rules
      • Server Port and Host
      • Proxy IP
      • SSL Server Certs
        • SSL Client Certs
      • HTTPS Redirect/HSTS
      • URL Rewrites
      • Aliases
      • Custom Error Pages
      • MIME Types
      • Welcome Files
      • Custom Java Version
      • Adding Custom Libs
      • GZip Compression
      • REST Servlet
      • Performance Tuning
      • Undertow Options
      • Custom Tray Menus
      • JVM Args
      • Case Sensitivity of Web Server
      • Ad-hoc Env Vars
      • Ad-Hoc Java System Properties
      • server.json Env Var overrides
      • Server Home
      • web.xml Overrides
      • Console Log Layout
      • Adobe cfpm
      • Experimental Features
    • External Web Server
    • Starting as a Service
    • Single Server Mode
    • Server.json
      • Working with server.json
      • Packaging Your Server
      • Using Multiple server.json Files
  • Package Management
    • Installing Packages
      • Installation Path
      • Installation Options
      • Advanced Installation
      • Debug Installation
    • Private Packages
    • System Modules
    • Code Endpoints
      • ForgeBox
      • HTTP(S)
      • File
      • Folder
      • Git
      • Java
      • S3
      • CFLib
      • Jar (via HTTP)
      • Lex (via HTTP or File)
      • Gist
    • Package Scripts
    • Dependencies
    • Semantic Versioning
    • Updating Packages
    • Creating Packages
      • Editing Package Properties
      • Publishing Lucee Extensions to ForgeBox
    • Artifacts
    • Box.json
      • Basic Package Data
      • Extended Package Data
      • Package URLs
      • Installation
      • Embedded Server
      • Dependencies
      • TestBox
    • Managing Version
  • Task Runners
    • Task Anatomy
    • BaseTask Super Class
    • Task Target Dependencies
    • Passing Parameters
    • Using Parameters
    • Task Output
      • Printing tables
      • Printing Columns
      • Printing Tree
    • Lifecycle Events
    • Threading/Async
    • Task Interactivity
    • Shell Integration
    • Downloading Files
    • Running Other Commands
    • Error Handling
    • Hitting Your Database
    • Sending E-mail
    • Interactive Jobs
    • Watchers
    • Property Files
    • Running other Tasks
    • Loading Ad hoc Jars
    • Loading Ad-hoc Modules
    • Cancel Long Tasks
    • Progress Bar
    • Installing Lucee Extensions
    • Caching Task Runners
  • Helpful Commands
    • Token Replacements
    • Checksums
    • Code Quality Tools
    • ask and confirm
  • Deploying CommandBox
    • Github Actions
    • Docker
    • Heroku
    • Amazon Lightsail
  • TestBox Integration
    • Test Runner
    • Test Watcher
  • Developing For CommandBox
    • Modules
      • Installation and Locations
      • Configuration
        • Public Properties
        • Configure() Method
        • Lifecycle Methods
      • Conventions
      • User Settings
      • Linking Modules
    • Commands
      • Aliases
      • Using Parameters
        • Using File Globs
        • Dynamic Parameters
      • Command Output
      • Tab Completion & Help
      • Interactivity
      • Watchers
      • Shell integration
      • Running Other Commands
      • Error handling
      • Watchers
      • Loading Ad hoc Jars
    • Interceptors
      • Core Interception Points
        • CLI Lifecycle
        • Command Execution Lifecycle
        • Module Lifecycle
        • Server Lifecycle
        • Error Handling
        • Package Lifecycle
      • Custom Interception Points
    • Injection DSL
    • Example Project
    • FusionReactor for the CLI
  • ForgeBox Enterprise
    • Introduction
    • Storage
    • Commands
      • List
      • Register
      • Login
      • Set Default
      • Remove
    • Usage
Powered by GitBook
On this page

Was this helpful?

Edit on GitHub
Export as PDF
  1. Task Runners

Lifecycle Events

If a task runner has methods of this name, they will be executed automatically.

  • preTask - Before any target in the task

  • postTask - After any target in the task

  • aroundTask - Wraps execution of any target in the task

  • pre<targetName> - Before a specific target (Ex: preRun)

  • post<targetName> - After a specific target (Ex: postRun)

  • around<targetName> - Wraps execution of a specific target (Ex: aroundRun)

  • onComplete - Fires regardless of exit status

  • onSuccess - Fires when task runs without failing exit code or exception

  • onFail - Fires if exit code is failing after the action is done (always fires along with onError, but does not receive an exception object). Use this to respond generally to failures of the job.

  • onError - fires only if an unhandled exception is thrown and receives exception object. Use this to respond to errors in the task. Does not fire for interrupted exceptions

  • onCancel - Fires when the task is interrupted with Ctrl-C

Every event receives the following data:

  • target - The name of the target executing

  • taskArgs - A struct containing the arguments for the target method

The onError event receives this additional data:

  • exception - The cfcatch object

The aroundTask and around<target> events receive the this additional data:

  • invokeUDF - A UDF to invoke to call the actual target method

A simple “around” event looks like this:

function aroundTask() {
  return invokeUDF();
}

A more complex one, like this:

function aroundTask( string target, struct taskArgs, any invokeUDF ) {

	print.line( 'aroundTask before #target#' );
	
	local.result = invokeUDF();
	
	print.line( 'aroundTask after #target#' );
	
	if( !isNull( local.result ) ) {
		return local.result;
	} 
	
}

It is important to return any value received from the invokeUDF() method (may return null) in case the original target returns an exit code. Otherwise, a failing exit code returned by the target will be ignored!

If you wish to modify the incoming arguments to the target, you may modify the taskArgs struct, which is passed by reference. It is not necessary to pass anything into the invokeUDF() method call.

function aroundTask( string target, struct taskArgs, any invokeUDF ) {
  // Override incoming parameter
  taskArgs.foo='bar';
  return invokeUDF();
}

Control when lifecycle method fire with these this scoped variables in the task CFC. These are all comma-delimited lists. When empty, they are ignored. When at least one target name is specified in “only”, then ONLY those targets will have the corresponding event fire. Any targets listed in the “except” settings, will not fire. These settings apply to the primary target being executed as well as any 'depends” targets.

this.preTask_only='';
this.preTask_except='';
this.postTask_only='';
this.postTask_except='';
this.aroundTask_only='';
this.aroundTask_except='';
this.onComplete_only='';
this.onComplete_except='';
this.onSuccess_only='';
this.onSuccess_except='';
this.onFail_only='';
this.onFail_except='';
this.onError_only='';
this.onError_except='';
this.onCancel_only='';
this.onCancel_except='';

When one target depends on other targets, it makes sense for pre and post events to fire, but it doesn’t make sense for onComplete, onFail, onSuccess, onError, or onCancel to fire for each one since those are “final” events. As such, the following will only fire for the top level target being executed. (Keep in mind, if a “depends” target fails, the error will bubble up to the top level.

  • onError

  • onSuccess

  • onFail

  • onComplete

  • onCancel

If an aroundTask and around<target> method are both specified, they will both execute with the task-level one (more generic) wrapped “around” the target level one (more specific).

To clarify the order of execution, here is the output from a successful task running a “run” target that has every possible method above defined.

aroundTask prior to invokeUDF()
 preTask
  aroundRun prior to invokeUDF()
   preRun
    Task execution here
   postRun
  aroundRun after invokeUDF()
 postTask

ColdBox notes: this feature is modeled after the pre/post/around features of ColdBox event handlers where a Task is analogous to a handler and a target is analogous to an action. There are some differences in how CommandBox’s pre/post/around events were implemented.

  • ColdBox does not allow an aroundhandler and around<action> at the same time, but CommandBox does allow an aroundTask and around<target> at the same time.

  • ColdBox executes pre/post before and after the around events. CommandBox wraps the pre/post code with the around code. This means, for example, exceptions raised by a preTask or postTask method can be try/caught in the aroundTask method.

  • For around methods, ColdBox passes a direct reference to the original action UDF to invoke and all the original arguments must be passed along by argumentCollection. CommandBox passes a special invoker UDF to around methods which does not require any arguments as it internally calls the original target method with the necessary arguments. This reduces boilerplate. In both cases, the return value of the UDF needs to be dealt with appropriately.

PreviousPrinting TreeNextThreading/Async

Last updated 2 years ago

Was this helpful?