# Introduction Learn Modern ColdFusion \ in 100+ Minutes.

cfml.rocks

Welcome to the wonderful world of dynamic programming with ColdFusion \. The purpose of this book is to jump-start developers into the ColdFusion \ programming language from a **MODERN** perspective and a focus on best practices, object orientation, and tooling. ColdFusion is not the same as it was 20 years ago; yes it's more than 20 years old! It's dynamic, vibrant, modern, fluent, and functional! Let's begin our adventure into the world of **MODERN** ColdFusion \. ## Support Open Source This book is available free of charge [online](https://modern-cfml.ortusbooks.com) and commercially as a [downloadable or printed book](https://www.ortussolutions.com/learn/coldfusion). Your support goes a long way to help the development of this book, future book endeavors, and all the open-source projects we work on. To support us, please consider becoming our patron at [patreon.com/ortussolutions](https://patreon.com/ortussolutions) for as little as $10/month. ## Ortus Solutions, Corp ![](/files/-LA-Uonn6zwzUcHtVri8) This book was written and maintained by [Luis Majano](https://www.luismajano.com) and the [Ortus Solutions](https://www.ortussolutions.com) Development Team. > Ortus Solutions is a company that focuses on building professional open source tools, custom applications and great websites! We're the team behind ColdBox, the de-facto enterprise CFML HMVC Platform, TestBox, the CFML Testing and Behavior Driven Development (BDD) Framework, ContentBox, a highly modular and scalable Content Management System, CommandBox, the ColdFusion \ CLI, package manager, etc, and many more - # Welcome CFML is vibrant, modern and strong! Welcome to the wonderful world of dynamic programming with ColdFusion (CFML). This book aims to jump-start developers into the ColdFusion (CFML) programming language from a modern perspective and focus on best practices, object orientation, and tooling. ColdFusion is not the same as it was 20 years ago; yes, it's more than 20 years old! It's dynamic, vibrant, modern, fluent, and functional! Let's begin our adventure into the world of MODERN ColdFusion (CFML). {% hint style="info" %} This book is inspired by the original [Ruby in 100 minutes](http://tutorials.jumpstartlab.com/projects/ruby_in_100_minutes.html), [Mike Henke's work on CFML in 100 minutes](https://github.com/mhenke/CFML-in-100-minutes/wiki), and [Learn CF in a week series](http://www.learncfinaweek.com/). {% endhint %} ## ColdFusion vs. CFML Let's get this ambiguity out of the way. **ColdFusion** is the server product, and **CFML** is the language, short for **C**old**F**usion **M**arkup **L**anguage. In turn, ColdFusion is actually the platform or framework in which CFML scripts are executed. It is similar to the relationship between HTML and a web browser like IE, Firefox, or Safari. More information at: CFML will execute in a ColdFusion engine. # Author Information about the author ## Luis Fernando Majano Lainez
Luis Majano is a Computer Engineer who has been developing and designing software systems since 2000. He was born in [San Salvador, El Salvador](http://en.wikipedia.org/wiki/El_Salvador), in the late 70s, during a period of economic instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida, where he completed his Bachelor of Science in Computer Engineering at [Florida International University](http://fiu.edu). He is the CEO of [Ortus Solutions](http://www.ortussolutions.com), a consulting firm specializing in web development, ColdFusion (CFML), Java development, and open-source professional services. He is the creator of ColdBox, ContentBox, CommandBox, WireBox, TestBox, LogBox, and anything "Box," and he contributes to over 250 open-source projects. He has a passion for learning and mentoring developers so they can succeed with sustainable software practices and the usage and development of open-source software. You can read his blog at [www.luismajano.com](http://www.luismajano.com) Luis is passionate about Jesus, tennis, golf, volleyball, and anything electronic. Random Author Facts: * He played volleyball in the Salvadorean National Team at the tender age of 17 * His favorite books are the Lord of the Rings and The Hobbit (Geek!) * His first ever computer was a Texas Instruments 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, microcontrollers, 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 # About This Book The source code for this book is hosted on GitHub: . You can freely contribute to it and submit pull requests. The contents of this book are copyrighted by [Ortus Solutions, Corp](http://www.ortussolutions.com/) and cannot be altered or reproduced without the author's consent. All content is provided *"As-Is"* and can be freely distributed.‌ * The majority of code examples in this book are done in `cfscript`. * The majority of code generation and running of examples are done via **CommandBox**: The ColdFusion (CFML) CLI, Package Manager, REPL - ​ ## ‌External Trademarks & Copyrights‌ Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems ## 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 concerning 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. ## Charitable Proceeds‌ 10% of the proceeds of this book will go to charity to support orphaned kids in El Salvador - . So please donate and purchase the printed version of this book; every book sold can help a child for almost two months.‌ ## Shalom Children's Home

Shalom Children's Party!

The Shalom Children's Home () is one of the ministries that are dear to our hearts located in El Salvador. During the 12-year civil war that ended in 1990, many children were left orphaned or abandoned by parents who fled El Salvador. The Benners saw the need to help these children and received 13 children in 1982. Little by little, more children came on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded. 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 supported Shalom since 2010; it is a place of blessings for many children in El Salvador who either have no families or have been abandoned. This is a good earth to seed and plant. ![Shalom Orphanage](https://raw.githubusercontent.com/ortus-docs/logbox-docs/master/images/shalom.jpg) # What is ColdFusion (CFML) ColdFusion Markup Language \ is a dynamic web programming language. ColdFusion Markup Language \ is a dynamic web programming language, which is especially suited for new developers as it was written to make a programmer's job easy and not care if the computer's job is hard. CFMLs primary goal is to be a rapid application development scripting language and middleware. It integrates with many technologies to provide an out-of-the-box language that makes things **easy**. This brief introduction will look at key language features you need to get started. ## Going Deep ![Lucee Server](/files/-LA-UpTKym2XHaKe_L6x) ColdFusion (CFML) is an interpreted and [dynamic ECMA Script like language](https://en.wikipedia.org/wiki/Dynamic_programming_language) that compiles to [Java Bytecode](https://en.wikipedia.org/wiki/Java_bytecode) directly, thus running in the Java Virtual Machine (JVM) and in almost every operating system. Implementations of the language are mostly done by two parties: [Adobe ColdFusion](http://www.adobe.com/products/coldfusion-family.html) (Commercial) and [Lucee Server](http://lucee.org/) (Free & Open Source), and they saw their beginnings in 1995. It is a mature and modern language and development platform. You can discover all the versions here: ![Adobe ColdFusion](/files/-LA-UpTUVJSCwTP4h35D) ## Developing with CFML All examples in this book will leverage CommandBox as the de-facto standard for ColdFusion (CFML) development. [CommandBox](https://www.ortussolutions.com/products/commandbox) is a standalone, native tool for Windows, Mac, and Linux that will provide you with a Command Line Interface (CLI) for developer productivity, tool interaction, package management, REPL, embedded ColdFusion/Java server, application scaffolding, and some sweet ASCII art. ## Docs Reference The best way to discover the CFML language's methods, tags, and functionality is to leverage [cfdocs.org](https://cfdocs.org/). Make sure you open it and bookmark it. {% embed url="" %} ## IDE - Editors There are many flavors of IDE's but here are our recommendations, which all support CFML * [Visual Studio Code](https://code.visualstudio.com/) *(Our Preference for both CFML and Java)* * Open-source packages * Adobe Package * [Sublime](https://www.sublimetext.com/3) * [Adobe ColdFusion Builder](http://www.adobe.com/products/coldfusion-builder.html) * Deprecated in favor of VSCode by Adobe * [IntelliJ](https://www.jetbrains.com/idea/) ### **Sublime Packages** Use [package control](https://packagecontrol.io/) in sublime to install the following packages which we use in our developer setups: * ColdBox Sublime * CommandBox Sublime * Alignment * CFML * CFMLDocPlugin * ColdFusion Docs Launcher * DockBlockr * Emmet * Enhanced HTML and CFML * SideBarEnhancements * Terminal {% hint style="success" %} You can find the sublime package manager link here: {% endhint %} ### **VSCode Packages** * Kamasamk CFML - * ColdBox Support - * CommandBox Support - * TestBox Support - * Adobe ColdFusion Builder - * CFLSP - ColdFusion syntax error checker : * CFLint - Linting Support - * LuceeDebug - A barebones debugger - * Align * Auto Alignment * Auto CLose Tag * Auto Rename Tag * AutoFileName * Better Comments * CFGoto * Code Outline * Document This * DotENV * EditorConfig * ESLint * File Utils * Git Graph * Hibernate Log Analyser {% hint style="info" %} You can find the VSCode marketplace link here: {% endhint %} # CommandBox CLI CommandBox is the de facto standard for CFML development and execution ![CommandBox CLI](/files/gmqw0pfZsckE7qaG5nL9) CommandBox is an amalgamation of many different tools and borrows concepts from NPM, Grunt/Gulp, Maven, ANT, Node, and much more. Features include: * True Command Line for ColdFusion (CFML) * Operation System integration for executing commands * Ability to create and execute commands built using ColdFusion (CFML) * ForgeBox integration for cloud package management and installations * ColdBox Platform, TestBox, and ContentBox CMS Integrations * Integrated servlet server with rewrite capabilities * Ability to create command recipes and execution * REPL (Read-Evaluate-Print-Loop) console for immediate ColdFusion (CFML) interaction * Ability to interact with users via CLI and create workflows and installers * Ability to execute workflows and tasks * Built-in Help system ## Installation CommandBox is a Java-based executable that will run on the most recent desktop operating systems (Linux, Mac OS X, Windows). Since it is a command line tool that uses a shell interface, it does not require an operating system using a GUI. Below is a simple guideline to get you up and running, but an [in-depth guide](https://commandbox.ortusbooks.com/getting-started-guide) can be found here: ### Requirements * 256MB+ RAM * 250MB+ free hard drive space * Multi-core CPU recommended * JRE/JDK 8+ ### Download If you already have a Java JRE installed level 8 or higher (and set in your environment variables), you can [download](http://www.ortussolutions.com/products/commandbox#download) the non-JRE version for your Operating System. If you don't have a JRE installed or aren't sure, we recommend downloading the version with a JRE included. Regardless of where you place the **box** binary, the first time you execute it, a `.CommandBox` folder will be created in your user's home directory, and CommandBox will be extracted into that location. If you delete this directory, it will be replaced the next time the CommandBox executable is run.

Box Shell

#### Windows Unzip the executable **box.exe** and double-click on it to open the shell. When you are finished running commands, you can close the window or type `exit`. {% hint style="info" %} **Hint:** You can make the `box.exe` available in any Windows terminal by adding its location to the `PATH` system environment variable. See {% endhint %} #### Homebrew (Mac) [Homebrew](http://brew.sh) is a great Mac package manager; it can easily install and keep your CommandBox installation up to date (even binary releases); just run the following for stable releases: ```bash brew install commandbox ``` To stay with current bleeding edge releases, use the following: ```bash brew tap ortus-solutions/boxtap brew tap-pin ortus-solutions/boxtap brew install --devel commandbox ``` Then run the `box` binary to begin the one-time unpacking process. Versions will be installed in `/usr/local/Cellar/commandbox`. To switch between versions, use `brew switch commandbox [version number]` #### Manual Linux/Mac Unzip the binary **box** and double-click on it to open the shell terminal. When you are finished running commands, you can close the window or type `exit`. {% hint style="info" %} **Hint** You can place the binary in your `/usr/bin` or `/usr/local/bin` directory so it can be available system-wide via the box command in any terminal window. {% endhint %} #### Linux apt-get Run the following commands to add the Ortus signing key, register our Debian repo, and install CommandBox. ```bash curl -fsSl https://downloads.ortussolutions.com/debs/gpg | sudo apt-key add - echo "deb https://downloads.ortussolutions.com/debs/noarch /" | sudo tee -a /etc/apt/sources.list.d/commandbox.list sudo apt-get update && sudo apt-get install commandbox ``` #### Linux yum Add the following to: `/etc/yum.repos.d/commandbox.repo` ```bash [CommandBox] name=CommandBox $releasever - $basearch failovermethod=priority baseurl=http://downloads.ortussolutions.com/RPMS/noarch enabled=1 metadata_expire=7d gpgcheck=0 ``` Then run a `sudo yum install commandbox` and be up and running ## Getting Started We have created a small [getting started guide](https://commandbox.ortusbooks.com/getting-started-guide) that will give you enough skills to move forward with any CommandBox development. You can find it here: [https://commandbox.ortusbooks.com/content/getting\_started\_guide.html](https://commandbox.ortusbooks.com/getting-started-guide) # Instructions & Interpreters CFML is a dynamic language that runs on the JVM ## Dynamic Language CFML is a **compiled** programming language that can’t run on your processor directly; it has to be fed into a middleman called the Java Virtual Machine in the form of [Java Bytecode](https://en.wikipedia.org/wiki/Java_bytecode). It is also a **dynamic language (**[**https://en.wikipedia.org/wiki/Dynamic\_programming\_language**](https://en.wikipedia.org/wiki/Dynamic_programming_language)**)**, meaning you do not have the **typed** restrictions a compile-time language like Java has. This means you have greater flexibility as the engine **infers** your types. It allows you to do runtime manipulations like method injections, removals, metadata programming, etc., that a typical typed language would not allow. It also allows us to not be in the dreaded compile, build, deploy cycle since the CFML scripts will be evaluated, compiled, and executed all at runtime. No need for re-deploying or annoying restarts.
### Runtime Exceptions However, with much power comes greater responsibility. There is a lot more potential for runtime exceptions because these exceptions cannot be caught by a compiler at compilation time, as compilation occurs simultaneously with execution. Thus, unit and integration testing become a real asset when building applications under a dynamic language. Wouldn't you know it? We also have a great tool for test-driven and behavior-driven development for ColdFusion: [**TestBox**](https://testbox.ortusbooks.com/) () ![TestBox Testing Framework](/files/-LKm9JkHwOlWWkqJlPfd) {% hint style="info" %} **TestBox** is a next-generation testing framework for ColdFusion (CFML) that is based on BDD (Behavior Driven Development) for providing a clean, obvious syntax for writing tests. It contains a testing framework, runner, assertions, and expectations library and ships with a mocking and stubbing library. {% endhint %} ### Code Portability The ColdFusion engine will convert your CFML markup into byte code and feed it into the Virtual Machine (VM) to execute it. The benefit of this approach is that you can write ColdFusion code once and, typically, execute it on many different operating systems and hardware platforms. You can run any CFML script in any Adobe or Lucee server or in the command line with CommandBox. {% hint style="info" %} Running via CommandBox in the command line will leverage the Lucee 5x CFML engine by default. Still, it can be configured easily to run Adobe Coldfusion (ACF), or different versions of either Lucee or ACF. {% endhint %} ## Java Integration CFML is a dynamic language for the JVM. Thus it runs in a full JDK/JRE context. It also provides you with hooks into the Java virtual machine. Meaning you can create and use Java objects natively in CFML. You can even create dynamic proxies and implement Java interfaces natively. Almost **Any** Java library or program can be class loaded and executed in CFML. For further reading, check out the [Java Integration Guide](https://cfdocs.org/java): ```java currentFile = createObject( "java", "java.io.File" ).init( getCurrentTemplatePath() ); writeOutput( currentFile.lastModified() ); createDynamicProxy( new cbproxies.models.Consumer( arguments.consumer ), [ "java.util.function.Consumer" ] ) ``` {% hint style="info" %} Adobe and Lucee have the added benefit of being written modularly using [OSGI](https://www.osgi.org/developer/architecture/). This will allow you to build your own Java OSGI bundles and deploy them as well. {% endhint %} ## Running CFML from the Command Line This is a durable way to write CFML code because you save your instructions into a file. That file can then be backed up, transferred, added to source control, etc. ### An Example CFML File We might create a file named `hello.cfm` like this: ```markup Hello from CFML Land! ``` Then we could run the program like this `box hello.cfm` and get the following result: ``` Hello from CFML Land! ``` {% hint style="warning" %} When you run `box hello.cfm` you’re actually loading the CFML instruction set engine (Lucee) and executing the code. Please note there is **NO** web server here. It is a pure command-line execution. {% endhint %} ## CommandBox REPL CommandBox sports a CFML **R**ead **E**val **P**rint **L**oop interface or most commonly known as **REPL**. The REPL is like a programming calculator, input in, output out. It will execute CFML instructions and give you feedback on syntax and results. To start a REPL, we must go into the CommandBox shell by typing just `box` or opening the `box` binary. Once in the CommandBox prompt, type `repl` and you will be placed in REPL mode: ![CommandBox](/files/-LA-Uqgy8av2UqgIfYcn) Please note that the REPL in CommandBox opens in **script** mode, not **tag** mode. This means that we must type in instructions that adhere to the ColdFusion scripting or ECMA script-like syntax instead of the tag-based syntax. We will discover more about syntax in the next chapter. For now, let's type the equivalent in Script syntax: ```javascript writeOutput( "Hello from CFML Land!" ) ``` ![CommandBox](/files/-LA-UqhLCOAt5OhVRzJ4) Boom! We get a magical hello from the CommandBox REPL. {% hint style="success" %} **Tip**: Our REPL supports not only one-line commands but also multi-line commands. Go ahead, try it! {% endhint %} ```javascript if( true ){ writeoutput( "hello" ) } echo( "hello" ) ``` ### Producing Output In this book, we will primarily be using the REPL or CommandBox for execution. We will use several functions to produce output during our exercises and code examples. Here is a list of what we will use to produce output to either the console, the output stream, or a log file.
FunctionLuceeAdobeDescription
echo()truefalseWhile writeOutput writes to the page-output stream, this function writes to the main response buffer.
https://cfdocs.org/echo
systemOutput()truefalseWrites the given object to the output stream
https://cfdocs.org/systemoutput
writeOutput()truetrueAppends text to the page-output stream.
https://cfdocs.org/writeoutput
writeDump()truetrueOutputs the elements, variables, and values of most CFML objects. Useful for debugging. You can display the contents of simple and complex variables, objects, components, user-defined functions, and other elements.
https://cfdocs.org/writedump
writeLog()truetrueWrites a message to a log file.
https://cfdocs.org/writelog
{% hint style="success" %} `writeDump()` is helpful in the console to visualize complex objects\ `writedump( var=variable, output="console" )`\ \ `You can also pass complex objects to` systemOuput() `as well.` {% endhint %} # Syntax Script or Tags? Choose wisely! There are two ways to write CFML code: in **tags** or in **script** syntax. Modern CFML will dictate that your view or presentation layers will utilize the **tag** syntax in `cfm` files, and the model or business layers will all be done in **script** syntax in `cfc` files. (MVC comes later). There are no differences in functionality between them; it's pure syntax. * CFScript Syntax Guide - ## Syntax Files CFML includes a set of instructions you use on pages (`.cfm`) or components (classes -`cfc`). You will write one or more instructions in a file (`.cfm,.cfc`) then run the file through a CFML engine or Command Line Interpreter like CommandBox. * `cfm` - ColdFusion markup file, tag syntax is the default and used for views * `cfc` - The default is the ColdFusion Component file (Class or Object), script syntax. ## Implicit Behavior CFML also gives you a pre-set of defined [tags](https://cfdocs.org/tags) and [functions](https://cfdocs.org/functions) available to you in any file you write your code in. These tags and functions allow you to extend the typical language constructs with many modern capabilities, from database interaction to PDF generation. They are basically automatic imports. {% hint style="success" %} **Tip:** Please note that the CFML built-in functions are also **first-class functions** so that they can be passed around as arguments to other functions or closures or saved as variables. {% endhint %} ## Exploring Behavior Three CFML instructions we will use in this section are `cfset`, `cfoutput`, and `cfdump`. * `cfset` is used to create a variable and assign it a value. * `cfoutput` displays a variable's value to the output stream. * `cfdump` is used to display the contents of simple and complex variables, objects, components, user-defined functions, and other elements to the output stream. We might have a file named *myprogram.cfm* and *Sample.cfc* like this: ### Tag Syntax {% tabs %} {% tab title="myprogram.cfm" %} ```markup #s.hello()# ``` {% endtab %} {% endtabs %} ### Script Syntax {% tabs %} {% tab title="myprogram.cfm" %} ```java s = new Sample(); writeOutput( s.hello() ); ``` {% endtab %} {% endtabs %} {% hint style="success" %} **Tip:** Please note that if you want to write in script in a tag-based file, you must use an opening and closing `` tag. {% endhint %} {% tabs %} {% tab title="Sample.cfc" %} ```javascript component{ function hello(){ return "Hello, World!"; } } ``` {% endtab %} {% endtabs %} Please note that no types and not even any visibility scopes you might be used to are present. CFML can also infer variable types on more distinct variables like dates, booleans, or numbers. However, please note that you can fully leverage types if you like: {% tabs %} {% tab title="Sample.cfc" %} ```javascript component{ public string function hello(){ return "Hello, World!"; } } ``` {% endtab %} {% endtabs %} {% hint style="success" %} By default, the return type of every function and/or argument is **any**. Thus, it can be determined at runtime as a dynamic variable. {% endhint %} ### Semi-Colons Please note that semi-colons are used to demarcate line endings in CFML `;`. However, the Lucee Server engine and Adobe ColdFusion 2018+ treat semi-colons as optional, while Adobe ColdFusion 2016 or below does not. Also, note the CommandBox REPL does NOT require semi-colons. ### Tags In Script Lucee and Adobe ColdFusion 11+ will allow you to write your CFML tags in script syntax. You basically eliminate the starting `<` and ending `>` enclosures and create a block by using the `{` and `}` mustaches. ```javascript cfhttp(method="GET", charset="utf-8", url="https://www.google.com/", result="result") { cfhttpparam(name="q", type="formfield", value="cfml"); } ``` ## Polyglot References As we now live in a world of polyglot developers, we have added references below to other languages to see the differences and similarities between CFML and other major languages in usage today. Please note that this section is merely academic and to help developers from other language backgrounds to understand the intricacies of the ColdFusion (CFML) syntax. ### PHP Syntax {% tabs %} {% tab title="myprogram.php" %} ```php hello(); ?> ``` {% endtab %} {% endtabs %} {% tabs %} {% tab title="Sample.php" %} ```php ``` {% endtab %} {% endtabs %} ### Ruby Syntax {% tabs %} {% tab title="myprogram.rb" %} ```ruby class Sample def hello "Hello, World!" end end s = Sample.new puts s.hello ``` {% endtab %} {% endtabs %} ### Java Syntax {% tabs %} {% tab title="MyProgram.java" %} ```java public class MyProgram { public String hello(){ return "Hello, world!"; } public static void main(String[] args) { System.out.println( new MyProgram().hello() ); } } ``` {% endtab %} {% endtabs %} ## Coding Standards At [Ortus Solutions](https://www.ortussolutions.com), we have developed a set of development standards for many languages. You can find our standards here: . # Comments You shall comment ALL your code! Comments are necessary and essential for any programming language. CFML is no different with helping you add code comments in both script and tag syntax. ## Tag Comments You can use the `` Syntax to comment within a CFML template (`.cfm`). This is very similar to HTML comments but adding an extra `-` to demarcate it as a CFML comment. ```markup HTML Comment ColdFusion Comment ``` ## Script Comments If you are within a CFC or in a `` block you can use an alternate style for comments. You can leverage `//` for single line comments and the following for multi-line comments: ```java /** * Multi-line Javadoc style comment * * @COLDBOX_CONFIG_FILE The override location of the config file * @COLDBOX_APP_ROOT_PATH The location of the app on disk * @COLDBOX_APP_KEY The key used in application scope for this application * @COLDBOX_APP_MAPPING The application mapping override, only used for Flex/SOAP apps, this is auto-calculated * @COLDBOX_FAIL_FAST By default if an app is reiniting and a request hits it, we will fail fast with a message. This can be a boolean indicator or a closure. */ /* Multi Line Comments are great! */ // Single line comment ``` ## Script "Javadoc" style comments A multi-line block can affect the metadata of a `component` or `function` if the opening line contains 2 asterisks. Also, for readability, some people will start each line of the comment with an asterisk. The CF engines will parse out those starting asterisks and they will not appear in the component or the function metadata. ```javascript /** * This is the hint for the function * * @param1 This is the hint for the param */ function myFunc( string param1 ){ } ``` ## CFCDoc Style Comments In the CFML world, you can write [JavaDoc](http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html) comments in what we call **CFCDoc** comments. We leverage the [DocBox](https://github.com/Ortus-Solutions/DocBox) library to generate documentation according to object metadata and comments. Please check out the [annotating your code ](https://docbox.ortusbooks.com/getting-started/annotating-your-code)section in the DocBox documentation to get a feel for how to document your code: {% code title="MyAwesome.cfc" %} ```java /** * This is my component * * @author Luis Majano */ component extends="Base" implements="IHello" singleton{ /** * The Settings */ property name="settings"; /** * Constructor * * @wirebox The Injector * @wirebox.inject wirebox * @vars The vars I need * @vars.generic Array * * @return MyComponent * @throws SomethingException */ function init( required wirebox, required vars ){ variables.wirebox = arguments.wirebox; return this; } } ``` {% endcode %} {% embed url="" %} Read about DocBox {% endembed %} You can see some examples of advanced CFC documentation here: {% hint style="success" %} **Tip**: VSCode has some great plugins for generating this type of documentation on your CFCs. We recommend the following extensions: * **Align** - Helps align everything * **AutoCloseTag** - Helps close comment and well all tags * **DocumentThis** - Automatically generates detailed JSDoc, CFCDoc comments in TypeScript and JavaScript files. {% endhint %} # Variables name = "Amazing Programmer" In CFML, variables are just pointers to a piece of data. They can hold **any** value you like and even change their value or **type** at runtime. In some languages, you need to specify the type of data you want your variable to hold at compile-time. You do not need to assign one in CFML, as everything is dynamic or inferred. The Lucee and Adobe 2021 servers infer types according to the initial value you assign to your variable. ```javascript a = "string"; // string b = now(); // datetime c = 123; // integer d = 1.34; // float f = false; // boolean, or a string for Adobe :) ``` {% hint style="danger" %} Please note that assignments are evaluated from right to left instead of traditional reading from left to right. {% endhint %} Open up the CommandBox Shell and go into CommandBox **REPL** mode by typing `repl`. Every time you assign a value to a variable, the CommandBox REPL will output or echo the variable for you. Please note that in REPL mode, the termination for a line of code is omitted. A line terminator in ColdFusion is the `;`. ![](/files/-MfYAFLjhP43rmuHUEk4) As you can see, we can create [strings](/cfml-language/strings), [numerics](/cfml-language/numbers), [arrays](/cfml-language/arrays), [structs](/cfml-language/structures), and so much more. No need for types or special assignments. The ColdFusion engine will determine or infer it and use it accordingly, thus a dynamic language. {% hint style="success" %} The CommandBox REPL is based on a Lucee 5 server, which is why semi-colons are optional, and the default syntax is script and not tags. {% endhint %} ## Case Insensitive **CFML is a case-insensitive language** as well. Meaning if you create a variable `a` and reference it as `A` they are the same. This can be a big gotcha for developers from languages like Java or JavaScript. However, as best practice, we would recommend **ALWAYS** using the same case as when you define the variable: **Don't do this** ```javascript a = "Hola Luis"; writeOutput( A ); ``` **Do this** ```javascript a = "Hola Luis"; writeOutput( a ); ``` ## Naming Requirements Most CFML variables have a few requirements imposed by the Virtual Machine (VM) * It must begin with a letter, underscore, or Unicode currency symbol. * It can contain letters, numbers, underscore characters, and Unicode currency symbols. * NO SPACES! * Not case-sensitive #### Reserved Words As with any programming language, there are specific names you just can't use, and some you can use, but they can be very confusing for developers or the engine. Here is a list of some of those: * The name of any of the internal ColdFusion engine scopes: `form, session, cgi, client, url, application, function` * Technically you can create the variable by long scoping (`local.form`), but it is confusing and error-prone. So please be careful.
Reserved WordLuceeAdobe
abstract√
and√
break√
case√
catch√
continue√
contains√
default√
do√
else√
eq√
eqv√
false√√
finally√
final√
for√
function√
gt√
gte√
import√
imp√
in√
is√
if√
interface√
lt√
lte√
local (within a function)√
neq√
not√
null (If null support is on)√√
pageenconding√
or√
returnv
switch√
true√√
try√
while√
xor√
## Flexible Typing You can also create a variable with one type and then switch it to another dynamically: ![](/files/-MfYAFLlf4CVbQP8tz5S) As you can see, the last equality wins! In this case, `a` is now an array. ## Types As we are now seeing, CFML is a typeless language, but internal types always exist. CFML will automatically cast so you can do flexible typing assignments when evaluating expressions. It does all the tedious and hard job for you. If we were to categorize CFML variables into categories, these would be: | Category | Description | | ----------- | ------------------------------------------------------------------------------------------------------------------- | | **Binary** | Raw data from files such as images, pdfs, etc | | **Complex** | A data container that represents more than one value: structures, arrays, queries, XML document objects, etc. | | **Objects** | Complex constructs representing data and functional operations. ColdFusion Components or Java Objects. | | **Simple** | One value and used directly in expressions. These include numbers, strings, floats, booleans, and date-time values. | CFML also includes many validation functions available to you to test for the type of variable you are working with. You can also use the `getmetdata()` function to get the metadata about the variable as well. ```javascript qData = getMetadata( query ) a = now() writedump( a.getMetadata() ) ``` * `isArray()` * `isBinary()` * `isBoolean()` * `isCustomFunction()` * `isClosure()` * `isDate()` * `isDateObject()` * `isDDX()` * `isJSON()` * `isNumeric()` * `isNumericDate()` * `isObject()` * `isNull()` * `isPDFFile()` * `isPDFObject()` * `isQuery()` * `isSimpleValue()` * `isSpreadsheetFile()` * `isSpreadsheetObject()` * `isStruct()` * `isWDDX()` * `isXML()` * `isXmlDoc()` ### Conversions You can also in CFML convert variables from one type to another. Here are some functions that will assist you in conversions: * `arrayToList()` * `binaryDecode()` * `binaryEncode()` * `charsetDecode()` * `charsetEncode()` * `deserializeJSON()` * `entityToQuery()` * `hash()` * `hmac()` * `HTMLParse()` * `lcase()` * `listToArray()` * `parseNumber()` * `serializeJSON()` * `toBase64()` * `toBinary()` * `toScript()` * `toString()` * `URLDecode()` * `URLEncode()` * `URLEncodedFormat()` * `val()` * `XMLFormat()` * `XMLParse()` * `XMLTransform()` {% hint style="info" %} Please note that some of them can be used as member functions directly on a specific object type. {% endhint %} ## Outputting Variables (Interpolation) You can also output or evaluate variables by using the `#` operators and using the variable name. This is referred to as interpolation in some languages: ```javascript a = "Hola Luis" writeoutput( "Welcome to CFML: #a#" ) // Echo is the same as writeOutput but LUCEE only echo( "Welcome" ) ``` Also, note that using the `#` hashes for output on assignments can be redundant if you do NOT use string interpolation but just variable assignments. **Don't do this** ```javascript a = "hello luis"; b = #a#; or b = "#a#"; ``` **Do this** ```javascript a = "hello luis"; b = a; ``` ## Debugging Variables CFML offers one of the most used functions/tags ever: `, writeDump()` and `, abort;`. These are used to dump the entire contents of a variable to the browser, console, or even a file. You can then leverage the `abort` construct to abort the request and see the output of your dumped variables. This will work with both simple and complex variables. However, be very careful when using it with Nested ORM objects, as you can potentially dump your entire database and crash the server. Leverage the `top` argument to limit dumping. ```javascript writeDump( complex );abort; writeDump( var=arrayOfORM, top=5 );abort; ``` ### Server Debugging Templates CFML Engines also allow you to turn on/off a debugging template that shows up at the bottom of requests when running in server mode. You can activate this debugging by logging in to the appropriate engine administrator and looking for the **debugging** section. Turn it on and debug like a champ. {% hint style="danger" %} **Important:** Adobe Engines have a very evil setting called *Report Execution Times*, make sure it is always turned **OFF**. If you use it with any application that leverages Components, it will slow down your application tremendously. {% endhint %} ## Paraming Variables CFML allows you to set default values for variables in case you use a variable that doesn't exist. You can use the `` tag or the `param` construct: ```markup ``` or ```javascript param myVariable = "luis"; ``` {% hint style="success" %} You can even assign types to parameterize variables and much more. Check out the docs for it: {% endhint %} ## Checking For Existence You can verify if variables exist in many different ways. The following section showcases how variables are stored in visibility and persistence scopes which are all structures or hash maps in Java terms. Meaning you can leverage structure operations for checking for existence and much more. Below are several ways to verify variable existence: * `isDefined()` - Evaluates a string value to determine whether the variable named in it exists. * `isNull()` - Returns `true` if the specified object is null, else `false`. * `structKeyExists( key, value )` - Verifies if the specified key variable exists in a structure. ```javascript // Notice the variable name is in quotes if( isDefined( "myVariable" ) ){ writeOutput( myVariable ); } else { writeOutput( "Not Defined!" ); } // Notice that the variable is NOT in quotes if( isNull( myVariable ) ){ writeOutput( "Not Defined!" ); } else { writeOutput( myVariable ); } // What is this variables scopes??? if( structKeyExists( variables, "myVariable" ) ){ writeOutput( myVariable ); } else { writeOutput( "Not Defined!" ); } ``` ## Java Integration As we have discussed, CFML is a dynamic language built on Java. Thus each variable internally is represented by a native Java data type: `String, Int, Float, Array, Vector, HashMap, etc`. This is important because each variable you create has member functions available to you that delegate or reflect its native Java class. ```javascript a = "hello"; writeOutput( a.getClass().getName() ); ``` If you run the script above in the REPL tool, you will see the output as `java.lang.String`. Therefore, the variable is typed as a `String` and can call on any method that `java.lang.String` implements. You can try this for the many types in CFML, like structs, arrays, objects, etc. ## Member Functions Besides the native Java member functions available to you, CFML also allows you to call on each variable's data type functions and chain them to create friendly language DSLs. This way, you do not have to pass variables into functions but treat the variables as objects. You can see all the member functions available according to data type here: Here are some examples: ```javascript // Function passing var myArray = []; ArrayAppend( myArray, "objec_new" ); ArraySort( myArray, "ASC" ); // Member Functions myArray.append( "objec_new" ); myArray.sort( "ASC" ); // Java Functions + CFML Functions var myProductObject = createObject( "java", "myJavaclass" ); myjavaList = myProductObject.getProductList(); myjavaList.add( "newProduct" ); // Java API myjavaList.append( "newProduct" ); // CF API myjavaList.sort( "ASC" ); // DSL Chaining s="the"; s = s.listAppend("quick brown fox", " ") .listAppend("jumps over the lazy dog", " ") .ucase() .reverse(); ``` #### Member functions for the following data types are supported: * Array * String * List * Struct * Date * Spreadsheet * XML * Query * Image Please see for further information on member functions. ## Naming Coding Standards At [Ortus Solutions](https://www.ortussolutions.com), we have developed a set of development standards for many languages. You can find our ColdFusion standards here: # Variable Scopes They gotta exist somewhere! In the CFML language, there are many persistence and visibility scopes that exist for variables to be placed in. These are differentiated by context: in a CFC, in a function, tag, thread or in a template. All CFML scopes are implemented as structures or hash maps of key-value name pairs. The default scope for variable storage is called `variables`. Thus you can refer variables like this in either CFC or Template context: ```javascript a = "hello"; writeOutput( a ); or writeOutput( variables.a ); ``` ## Persistence Scopes Can be used in any context, used for persisting variables for a period of time. * `session` - stored in server RAM or external storages tracked by unique web visitor * `client` - stored in cookies, databases, or external storages (simple values only) * `application` - stored in server RAM or external storage tracked by the running ColdFusion application * `cookie` - stored in a visitor's browser * `server` - stored in server RAM for ANY application for that CFML instance * `request` - stored in RAM for a specific user request ONLY * `cgi` - read only scope provided by the servlet container and CFML * `form` - Variables submitted via HTTP posts * `URL` - Variables incoming via HTTP GET operations or the incoming URL ## Template Scopes (CFM) * `variables` - The default or implicit scope to which all variables are assigned. ## Component Scopes (CFC) * `variables` - Private scope, visible internally to the CFC only * `this` - Public scope, visible from the outside world * `static` - No need for a CFC instance; available as a CFC representation (Lucee only) ## Function Scopes * `variables` - Has access to private variables within a Component or Page * `this` - Has access to public variables within a Component or Page * `local` - Function-scoped variables **only** exist within the function execution. Referred to as `var` scoping * `arguments` - Incoming variables to a function ## Tag Scopes * `attributes` - Incoming tag attributes * `variables` - The default scope for variable assignments * `caller` - Used within a custom tag to set or read variables within the template that called it. ## Thread Scopes * `attributes` - Passed variables via a thread * `thread` - A thread-specific scope that can be used for storage and retrieval * `local` - Variables local to the thread context ## **Evaluating Unscoped Variables** If you use a variable name **without** a scope prefix, ColdFusion checks the scopes in the following order to find the variable: 1. Local (function-local, UDFs, and CFCs only) 2. Arguments 3. Thread local (inside threads only) 4. Query (not a true scope; variables in query loops) 5. Thread 6. Variables 7. CGI 8. CFFILE 9. URL 10. Form 11. Cookie 12. Client {% hint style="danger" %} **IMPORTANT**: Because ColdFusion must search for variables when you do not specify the scope, you can improve performance by specifying the scope for all variables. It can also help you avoid nasty lookups or unexpected results. {% endhint %} # Operators Operate all things++--==!^%/\\ **Operators** are the foundation of **any** programming language. Operators are symbols that help a programmer to perform specific mathematical, structuring, destructuring, and logical computations on operands (variables or expressions). We can categorize the CFML operators into the following categories: 1. Arithmetic/Mathematical 2. Assignment 3. Logical 4. Comparison 5. Ternary 6. Elvis (Null Coalescing) 7. Function 8. Collections {% hint style="info" %} You will see that CFML does not have native [bitwise](https://en.wikipedia.org/wiki/Bitwise_operation) operators, but it does implement bitwise operations via functions since functions can also be operators in CFML: `bitAnd, bitMaskClear, bitMaskRead, bitMaskSet, bitNot, bitOr, bitSHLN, bitSHRN, bitXOR` . You can find much more information here: [https://cfdocs.org/math%2Dfunctions](https://cfdocs.org/math-functions) {% endhint %} {% hint style="success" %} For more information about bitwise operations, you can read more here: {% endhint %} {% hint style="danger" %} CFML does not offer the capability to overload operators like other languages. {% endhint %} ## Operator Precedence The order of precedence exists in CFML, just like in mathematics. You can also control the order of precedence by using the grouping operator `()` like in mathematics, the magical ordering parenthesis. {% code lineNumbers="true" %} ```javascript ^ *, / \ MOD +, - & EQ, NEQ, LT, LTE, GT, GTE, CONTAINS, DOES NOT CONTAIN, ==, !=, >, >=, <, <= NOT, ! AND, && OR, || XOR EQV IMP ``` {% endcode %} {% hint style="success" %} Remember that using parenthesis `(Grouping Operator)` is very important to denote precedence. {% endhint %} ## Arithmetic Operators These operators are used to perform arithmetic/mathematical operations on operands. | Operator | Name | Description | | -------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `+` | Add | `a = 1 + 4` | | `-` | Subtract | `a = 4 - 2` | | `*` | Multiply | `a = 4 * b` | | `/` | Divide | `a = 4 / myVariable` | | `^` | Exponentiate | `a = 2^2 // 4` | | `%, MOD` | Modulus / Remainder | `5 % 2 = 1` or `5 mod 2` | | `\` | Integer Divide | `a = 7 \ 3` is 2. Please note it does not round off the integer. | | `++` | Increment |

a = b++ assign b to a and THEN increment b
a = ++b increment b and THEN assign to a

| | `--` | Decrement |

a = b-- assign b to a and THEN decrement b
a = --b decrement b and THEN assign to a

| | `-` | Negate | `a = -b` Negate the value of b | | `+` | Positive | `a = +b` Make the value of b a positive number | | `()` | Grouping |

The grouping operator is used just like in mathematics, to give precedence to operations.
result = 3 \* (2+3) which is not the same as
result = 3 \* 2 + 3

| ## Assignment Operators These operators are usually used for compound evaluations and assignments. | Operator | Name | Description | | -------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `=` | Assignment |

a = 5 The way to assign a value to a variable. You can also assign them to multiple variables by chaining them:
a=b=c=5 which is the same as saying:
a=5;b=5;c=5

| | `+=` | Compound Add | `a += b` is equivalent to `a = a + b` | | `-=` | Compound Subtract | `a -= b` is equivalent to `a = a - b` | | `*=` | Compound Multiply | `a *= b` is equivalent to `a = a * b` | | `/=` | Compound Divide | `a /= b` is equivalent to `a = a / b` | | `%=` | Compound Modulus | `a %= b` is equivalent to `a = a % b` | | `&=` | Compound Concatenation |

A way to concatenate strings together
a = "hello "
a &= "luis" The result will be hello luis

| | `&` | Concatenation | Concatenates two strings: `"Hola" & space & "Luis"` | ### ## Logical Operators Logical operators perform logic between values or values, usually denoting a `boolean` result. | Operator | Name | Description | | ---------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `!,NOT` | Negation | `!true = false` or `a = not true` | | `&&,AND` | And |

Returns true if both operands are true.
a = b && c

| | `\|\|, OR` | Or |

Returns true if either operand is true.
a = b

| | `XOR` | Exclusive Or |

Returns true when either of the operands is true (one is true, and the other is false), but both are not true, and both are not false.
true XOR true = false
true XOR false = true
false XOR false = false

| | `EQV` | Equivalence |

The exact opposite of an exclusive or. Meaning that it will return true when both operands are either true or false.
true EQV true = true
true EQV false = false
false EQV false = true

| | `IMP` | Implication | A implies B is equivalent to `if a then b`. A imp b is false ONLY if a is true and b is false; else, it returns true always. | ### ## Comparison Operators Comparison operators are used when comparing two values, expressions, or variables. The return of a comparison is either `true` or `false`. | Operator | Name | Description | | --------------------------------------------------------------- | -------------------- | -------------------------------------------------------------------------------------------------------------------------------------- | | `eq,==` | Equality | True if `a eq b` or `a == b` | |

neq,
!=,
<>

| Not Equal | The opposite of equality: `a neq b, a != b, a <> b` | | `===` | Identity |

Returns true if the operands are equal in value and in type.
2 === "2" // false
2 === 2 // true

| | `!==` | Negated Identity | Same as the identity operator but negating the result. | | `gt,>` | Greater than | If the left operand is greater in value than the right operand | | `gte, >=` | Greater than o equal | If the left operand is greater than or equal in value than the right operand | | `lt, <` | Less than | If the left operand is less than in value than the right operand | | `lte, <=` | Less than or equal | If the left operand is less than or equal in value than the right operand | | `contains,ct` | Contains |

Returns true if the left operand contains the right one.
'hello' contains 'lo'

| | `does not contain, nct` | Negated contains |

Returns true if the left operand does NOT contain the right one.
'hello' does not contain 'pio'

| ## Ternary Operator The ternary operator is a conditional operator that works just like an `if-then-else` statement but in shorthand syntax. It has three operands: ``` condition ? value1 if true : value2 if false ``` The `condition` must evaluate to a `Boolean` value. If `true` then the `value1` will be used, or else `value2` will be used. You can combine this operator with parenthesis, Elvis operators, etc., to build rich expressions. ```javascript result = ( 10 > 0 ) ? true : false result = animal eq 'dog' ? 'bark' : 'not a dog' // More complex approach result = creditScore > 800 ? "Excellent" : ( creditScore > 700 ) ? "Good" : ( creditScore > 600 ) ? "Average" : "Bad" ``` ## Elvis Operator (Null Coalescing) The Elvis operator is usually referred to as the [null coalescing operator](https://en.wikipedia.org/wiki/Null_coalescing_operator). Its name comes from the symbol it represents, which looks like Elivs hair turned sideways: `?:`. If the expression to the operator's left is `null` , then the expression on the right will be evaluated as the result of the expression. ``` expression ?: defaultValueOrExpression ``` Here is a simple example: ```javascript function process( result ){ writeOutput( result ?: "nothing passed" ) } process() // produces 'nothing passed' process( "hello" ) // produces 'hello' displayName = rc.name ?: 'Anonymous' event .getResponse() .setError( true ) .setData( rc.id ?: "" ) ``` {% hint style="danger" %} Please note that we have seen inconsistencies in both Adobe and Lucee engines regarding the implementation of this operator. I would avoid using it in Adobe 2018 as it is broken in several cases. {% endhint %} ## Function Operators In CFML, functions can act as operators as well, as you can use the results of the function call as the operands. **Function arguments can also act as expressions, and you can even pass more functions into functions as arguments or even return functions from functions. Now that's a fun tongue twister.** ```javascript results = ucase( "this is text " ) & toString( 12 + 50 ) // I can also pass lambdas or anonymous functions as arguments results = listener( 2 * 3, (result) => result + 1 ) ``` ## Collections Operators Many operators can work on collection objects like arrays, structs, and queries. So let's start investigating them. ### Safe Navigation Operator The [Safe Navigation operator](https://en.wikipedia.org/wiki/Safe_navigation_operator) avoids accessing a key in a structure or a value in an object that does `null` or doesn't exist. Typically when you have a reference to an object, you might need to verify that it exists before accessing the methods or properties of the object. To avoid this, the safe navigation operator will return `null` instead of throwing an exception, like so: ```javascript var user = userService.findById( id ) // If user is not found, then this will still work but no exception is thrown. echo( user?.getSalary() ) s = { name : "luis" } echo( s.name ) echo( s?.name ) ``` ### Spread Operator The spread operator allows an iterable object to expand and merge in certain declarations in code. These objects in CFML are mostly arrays and structures. This operator can quickly merge all or parts of an existing array or object into another array or object. This operator is used by leveraging three dots `...` in specific expressions. ```javascript // Spread var variableName = [ ...myArray ] // Traditional var variableName = [].append( myArray ) // Spread var mergedObject = { ...obj1, ...obj2 } // Traditional mergedObject.append( obj1 ).append( obj2 ) ``` You can accomplish the result of the spread operator with the `append()` member function or traditional function in a very elegant and user-friendly syntax. It also allows you NOT to do chaining but inline expressions. The Spread syntax also allows an iterable such as an array expression or string, to be expanded in places where zero or more arguments (for function calls) are expected. Here are some examples to help you understand this operator: #### Function Calls ```javascript numbers = [ 1, 2, 3 ] function sum( x, y, z ){ return x + y + z; } // Call the function using the spread operator results = sum( ...numbers ) // 6 // Ignore the others numbers = [ 1, 2, 3, 4, 5 ] results = sum( ...numbers ) // 6 ``` #### Array Definitions ```javascript numbers = [ 1, 2, 3 ] myArray = [ 3, 4, ...numbers ] myArray2 = [ ...numbers ] myArray2 = [ ...numbers, 4, 66 ] ``` #### Struct Definitions ```javascript var mergedObject = { ...obj1, ...obj2 } user1 = { name : "luis", age: 15 } user2 = { name : "joe", location : "miami" } mergedUsers = { ...user1, ...user2 } // What will the output be? writeDump( mergedUsers ) // { name : "joe" , age : 15, location : "miami" } ``` ### Rest Operator {% hint style="danger" %} Only available in ACF 2021+ and for function arguments {% endhint %} The Rest function operator is similar to Spread Operator but behaves oppositely. The spread syntax expands the iterable constructs into individual elements, and the Rest syntax collects and condenses them into a single construct, usually an array. Please note that this operator only works on function arguments as of now. Imagine I need to create a function that takes in an unlimited number of Identifiers, so I can return all items that have that ID: ```javascript function findById( ...ids ){ } findById( 1 ) // ids is a single value of 1 findById( 1, 23, 34, 456 ) // ids is an array of values ``` You can also combine them in functions with other arguments: ```java function findById( entityName, ...ids ){ } findById( "User", 1 ) // ids is a single value of 1 findById( "Car", 1, 23, 34, 456 ) // ids is an array of values ``` # Null & Nothingness null does mean something! What is nothingness? Is there nothingness only in outer space? If a tree falls in the forest and nobody listens, does it make a sound? Starting to see the point? Does nothing really mean nothing? To be or not to be? OK, I think we are going on a philosophical tangent, so let's get back to our geekiness: `null` is Java's way to refer to "nothingness.", something that does not exist and has no value. Support for the`null`keyword itself was introduced as an option in ColdFusion 2018 (as discussed in [this blog post](https://coldfusion.adobe.com/2018/07/null-support-in-coldfusion-2018/)) and has existed as an option in Lucee (as discussed in [this guide](https://docs.lucee.org/guides/cookbooks/NullSupport.html)). ## Full-Null Support Please note that full null support is **NOT** the default in the CFML engines. Meaning you will not be able to use the `null` keyword until it is activated or get real `null` values from databases or external services. In reality, you still could simulate `null` without full null support in both engines, and sometimes you get an empty string, sometimes a full Java `null`. So basically, the nonfull null support is a partial null support, which makes it hard for developers. **So as a rule of thumb, we always recommend checking for nullness no matter WHAT!** Eventually, this flag should default to true, in our opinion, and offer full-null support out of the box. Ok, back to activating full-null support. You can do this in the admin or programmatically via the `Application.cfc` file, which can be used when building web applications. You can learn more [about it here](/beyond-the-100/applicationcfc) {% code title="Application.cfc" %} ```java component{ this.enableNullSupport = true; } ``` {% endcode %} ## Checking For Nullness Use the `isNull()` or `isDefined()` methods to evaluate for nothingness. ```javascript r = getMaybeData() if( isNull( r ) ){ // do something because r doesn't exist } if( isDefined( "r" ) ){ } ``` Also, remember that you can use the [Elvis operator](/cfml-language/operators#elvis-operator-null-coalescing) to test for null and an operator and expression. ```javascript results = getMaybeData() ?: "default value" ``` {% hint style="info" %} We would recommend that you use `isNull()` as it expresses coherently its purpose. Since `isDefined()` can also evaluate expressions. {% endhint %} ## Creating Nulls You can create nulls in different ways in CFML. Let's explore these:
ApproachFull NullDescription
null keywordtruer = null
Non returning function callfalseIf a function returns nothing, its assignment will produce a null.
function getNull(){}
r = getNull()
nullValue()falseLucee only function.
r = nullValue()
javaCast( "null", "" )false

Available in all engines

r = javaCast( "null", "" )

## In Practice If you have three eggs, and eat three eggs, then you might think you have "nothing," but in terms of eggs you have "0". Zero is something, it’s a number, and it’s not nothing. If you’re working with words and have a string like "hello" then delete the "h", "e", "l"s, and "o" you might think you’d end up with nothing, but you really have "" which is an empty string. It’s still something. Null in CFML is usually encountered when you ask for something that doesn’t exist. When looking at arrays, for instance, we created a list with five elements then asked CFML to give us the sixth element of that list. There is no sixth element, so CFML gave us null. It isn’t that there’s a blank in that sixth spot (""), it’s not a number 0, it’s nothingness – null. **Examples** ```java function getData( filter ){ if( isNull( arguments.filter ) ){ // then do this } else { // use the filter } } function returnsNull(){ if( key.exists( "invalid" ) ){ return key[ "invalid" ]; } } results = returnsNull(); writeOutput( isNull( results ) ); ``` Also note that if a function returns **nothing** it will be the same as returning `null`. # Strings Strings in CFML/Java are immutable! Remember that well! In CFML, strings are a type of variable that is used to store collections of letters and numbers. Usually defined within single or double quotes ( `'` or `"` ). Some simple strings would be `"hello"` or `"This sentence is a string!"`. Strings can be anything from `""`, the empty string, to long sets of text. The underlying type for a string in CFML is the Java [String](https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/lang/String.html), which is immutable, meaning it can never change. Thus, a new string object is always created when concatenating strings together. This is a warning that if you do many string concatenations, you will have to use a Java data type to accelerate the concatenations ([String Builders](https://www.baeldung.com/java-string-builder-string-buffer)). {% hint style="info" %} More on String Builders: {% endhint %} ## Character Extractions In Adobe 2021+ and Lucee server, you can reference characters in a string stream via their position in the string using array syntax: `varname[ position ]`. Please note that string and array positions in CFML start at 1 and not 0. ```javascript name = "luis"; writeoutput( name[ 1 ] ) => will produce l ``` Adobe has taken this further, and you can use negative indices to get characters from the end backward: ```javascript name = "luis"; writeoutput( name[ -1 ] ) => will produce s ``` ## Character Extractions by Range Adobe 2018+ also supports extraction as ranges using the following array syntax: ```javascript array[ start:stop:step ] ``` Which is extremely useful for doing character extractions in ranges ```javascript data = "Hello CFML. You Rock!"; writeOutput( data[ 1 ] ) // Returns H writeOutput( data[ -3 ] ) // Returns c writeOutput( data[ 4:10:2 ] ) // Returns l FL writeOutput( data[ 4:12 ] ) // Returns lo CFML writeOutput( data[ -10:-4:2]) // Returns o o ``` ## Common String Functions You can find all the available string functions here: . Below are some common ones that are handy to memorize: ### Len Call `len()` on a string to get back the number of characters in the string. For instance `Len( "Hello ")` would give you back **6** (notice the trailing space is counted). You can also use member functions: `a.len()`. ```javascript message = "Hola Luis" writeOutput( message.len() ) if( len( message ) ){ } ``` ### Trim, LTrim, RTrim The`Trim` function removes leading and trailing spaces and controls characters from a string. You can also use the `ltrim()` to do left trimming and `rtrim()` to do right trimming. For instance, `Trim("Hello ")` would give you back `Hello` (notice the trailing space is removed). Combine this with `Len` for example `Len( Trim( "Hello ") )` and you would get back `5`. You can also use member functions: ```javascript a.trim().len() ``` ### Replace, ReplaceNoCase, REReplace, REReplaceNoCase The `Replace` instruction replaces occurrences of **substring1** in a string with **substring2**, in a specified scope. The search is case-sensitive and the scoped default is one. If you would like the searches to be case-insensitive just use the `noCase()` suffix. For instance, `Replace("Hello", "l", "")` would give you back **Helo** after replacing the *first occurrence of l*, or `Replace("Good Morning!", "o", "e", "All")` would give you **Geed Merning!** `REReplace(), REReplaceNoCase()` are the same functions but using regular expressions: ```javascript reReplace( "test 123!", "[^a-z0-9]", "", "ALL" ) reReplace( "123abc456", "[0-9]+([a-z]+)[0-9]+", "\1" ) ``` ### RemoveChars `RemoveChars` will remove characters from a string. For instance, `RemoveChars("hello bob", 2, 5)` would give you back **hbob**. ### Mid The `mid` function extracts a substring from a string. For instance, I could call `Mid("Welcome to CFML Jumpstart", 4, 12)` and it would give you back: **come to CFML**. ```javascript s = "20001122" writedump( mid( s, 5, 2 ) ) // You can also use character extraction writedump( s[ 5:6 ] ) ``` ### ListToArray Another great function is `listToArray()` which can take any string and convert it to an array according to a delimiter, empty fields, and even multi-character delimiters. The default delimiter is a comma `,`, but you can use any one or a combination of characters. ```javascript a = "luis,majano,lucas,alexia,veronica"; myArray = a.listToArray(); // Multi-character delimiter list = "coldfusion,php,|test,java,|sql"; getArray = listToArray(list,",|",false,true); someJSON = serializeJSON(getArray); writeOutput(someJSON); ``` ## Combining Strings Combining and interpolating strings is part of any programming language and an integral part. We can do both by building upon some language [operators](/cfml-language/operators). If you have two or more strings, you can concatenate them by using the `&` operator: ```javascript name = "Luis"; a = "Hello " & name & " how are you today?"; ``` You can also concatenate and assign using the `&=` operator. Please [check out the operators](/cfml-language/operators#assignment-operators) section for more on string assignment operators. ## Interpolating Strings Interpolating is where we stick a string within another string. In CFML, we use the `#` hashes to output a variable to the stream in context. This means we can interpolate into any string: ```javascript name = "luis"; welcome = "Good morning #name#, how are you today?"; writeoutput( welcome ); ``` That's it! If you surround any **simple** variable with hashes, CFML will interpret the variable. Now try this with a complex variable and see what happens: ```javascript complex = [1,2,3]; welcome = "Good morning #complex#, how are you today (#now()#)?"; writeoutput( welcome ); ``` {% hint style="success" %} Please note that anything between hashes is interpreted as an expression in CFML. {% endhint %} ## Casting CFML also will try to automatically infer and auto-cast strings for you. However, there is a built-in function called `toString()` which can be used to try to convert any value to a string. ```javascript s = { "a": "1", "b":"2" }; writeOutput( toString(s) ) writeOutput( s.toString() ) number = 42222.222 writedump( number.toString() ) ``` # JSON JSON all things! CFML supports native JSON support via several key functions and some member functions. ## Serialize CFML gives us the `serializeJSON()` function to convert any piece of data to its JSON representation () ```javascript serializeJson( var [, serializeQueryByColumns = false ] [, useSecureJSONPrefix = false ] [, useCustomSerializer = false ] ) ``` Pass in any complex or simple variable to the `var` argument and JSON will be produced: ```javascript person = { name = "Luis Majano", company = "Ortus Solutions", year = 2006}; writeOutput( serializeJSON( person ) ); ``` If you are in Lucee, you can even use the `toJSON()` member function: ```javascript person = { name = "Luis Majano", company = "Ortus Solutions", year = 2006}; writeOutput( person.toJSON() ); ``` ### Key Casing By default CFML will convert the keys in a struct to uppercase in the result JSON document: ```javascript person = { name = "Luis Majano", company = "Ortus Solutions", year = 2006}; writeOutput( serializeJSON( person ) ); // Will become { "NAME" : "Luis Majano", "COMPANY" : "Ortus Solutions", "YEAR" : 2006 } ``` If you want to preserve the key casing then wrap them in double/single quotes and define the case: ```javascript person = { 'Name' = "Luis Majano", 'company' = "Ortus Solutions", 'year' = 2006 }; // Will become { "Name" : "Luis Majano", "company" : "Ortus Solutions", "year" : 2006 } ``` ### Possible Casting Issues Adobe ColdFusion may incorrectly serialize some strings if they can be automatically converted into other types, like numbers or booleans. One workaround is to use a CFC with [cfproperty](https://cfdocs.org/cfproperty) to specify types. Another workaround is to prepend `Chr(2)` to the value and it will be forced to a string, however, that is an unofficial/undocumented workaround. A more formal workaround is to call `setMetadata()` as a member function on a `struct` to force a type: ```javascript myStruct = { "zip"="00123" }; myStruct.setMetadata( { "zip": "string" } ); writeOutput( serializeJSON(myStruct) ); ``` ## Deserialize The inverse of serialization is deserialization (). CFML gives you the `deserializeJSON()` function that will take a JSON document and produce native CFML data structures for you. ```javascript deserializeJSON( json [, strictMapping = true ] [, useCustomSerializer = false ] ) ``` Just pass a JSON document, and off we go with native structs/arrays/dates/strings and booleans. ```java if( isJson( mydata ) ){ return deserializeJSON( data ); } person = deserializeJSON( '{"company":"Ortus","name":"Mr OrtusMan"}' ); writeOutput( person.company ); ``` This function can also be used as a member function in any string literal: ```java var deserializedData = myjsonString.deserializeJson(); var data = '[]'.deserializeJson(); ``` ## Is this JSON? CFML has a function to test if the incoming string is valid JSON () or not: `isJSON()` ```javascript isJSON( "[ 1, 2, 3 ]" ) ``` # Numbers Integers and floats to rule the world! There are two basic kinds of numbers in CFML: **integers** (whole numbers) and **floats** (have a decimal point). Internally, each CFML engine treats them uniquely and backs up each numerical value as a Java class: `java.lang.Double` or `java.lang.Integer`.
TypeSize (bits)Min ValueMax Value
Integer32-2,147,483,648 (-231)2,147,483,647 (231 - 1)
TypeSize (bits)Significant BitsExponent BitsDecimal Digits
Double64531115-16
{% hint style="danger" %} Lucee stores all numerical values as Doubles {% endhint %} {% hint style="danger" %} Adobe stores integers as Integer and floats as Doubles {% endhint %} {% hint style="success" %} **Tip:** If you are dealing with currency or tracking precision, please read about `precisionEvaluate()` to represent big numbers and precision results: {% endhint %} ```javascript a = 1; b = 50.1; writeOutput( a * b ); ``` Also, note that CFML will do the auto-casting for you when converting between integers and doubles. ## Numeric Type Once we start looking at functions/closures and lambdas, you will see that you can also type the incoming arguments and results of functions. You also won't need to type it with integer or float, just as `numeric:` ```javascript numeric function add( numeric a, numeric b ){ return a + b; } ``` ## Operators & Functions CFML offers tons of mathematical [operators](/cfml-language/operators#arithmetic-operators) and functions: | abs | aCos | arrayAvg | | ----------------- | -------------- | -------------- | | arraySum | aSin | atn | | bitAnd | bitMaskClear | bitMaskRead | | bitMaskSet | bitNot | bitOr | | bitSHLN | bitSHRN | bitXor | | ceiling | cos | decrementValue | | expt | fix | floor | | formatBaseN | incrementValue | inputBaseN | | int | log | log10 | | max | min | pi | | precisionEvaluate | rand | randomize | | randRange | round | sgn | | sin | sqr | tan | ## Casting/Parsing CFML also has a `toNumeric()` function that you can use to cast a value to a number using different [radixes](https://en.wikipedia.org/wiki/Radix). ```java toNumeric( "29.5" ) toNumeric( "FF0011", "hex" ) toNumeric( "1010", "bin" ) ``` The `parseNumber()` is also used to convert a string number into a numeral system () {% hint style="info" %} In a [positional numeral system](https://en.wikipedia.org/wiki/Positional_numeral_system), the radix or base is the number of unique [digits](https://en.wikipedia.org/wiki/Numerical_digit), including the digit zero, used to represent numbers. For example, for the [decimal system](https://en.wikipedia.org/wiki/Decimal) (the most common system in use today) the radix is ten, because it uses the ten digits from 0 through 9. {% endhint %} ## Is it a number? CFML provides the `isNumeric()` function to determine if the passed value can be converted to a numeric value. ```java isNumeric( 23 ) // yes isNumeric( "twenty" ) // no isNumeric( 5e2 ) // yes ``` ## Repeating Instructions Number variables can be used to repeat instructions. Like in many other languages, CFML supports the `for`, `while` and `loop` constructs: ```javascript for( var i = 0; i <= 10; i++ ){ writeOutput( "Showing day " & i ); } i =1; while( i <= 10 ){ writeOutput( "Showing day " & i++ ); } ``` {% hint style="info" %} Please note that the syntax varies from tag to script, so refer to the docs for subtle differences. Please also note that you can iterate over structures, arrays, queries, and objects in CFML; we will see this in later sections. See , for more information {% endhint %} # Arrays An array is a data structure consisting of a collection of elements. Almost every programming language allows you to represent different types of collections. In CFML, we have three types of collections: arrays, [structures](/cfml-language/structures), and [queries](/cfml-language/queries). An array is a number-indexed list. Imagine you had a blank piece of paper and drew a set of three small boxes in a line: ``` --- --- --- | || || | --- --- --- ``` You could number each one by its position from left to right: ``` --- --- --- | || || | --- --- --- 1 2 3 ``` Then put strings in each box: ``` ------------- --------- ---------- | "Breakfast" || "Lunch" || "Dinner" | ------------- --------- ---------- 1 2 3 ``` We have a three-element Array. CFML arrays can grow and shrink dynamically at runtime, just like Array Lists or Vectors in Java, so if we added an element, it’d usually go on the end or be appended at the end. ``` ------------- --------- ---------- ----------- | "Breakfast" || "Lunch" || "Dinner" || "Dessert" | ------------- --------- ---------- ----------- 1 2 3 4 ``` If you asked the array for the element in position two, you’d get back `Lunch`. Ask for the last element, and you’d get back: `Dessert`. ## The Story of One Now, have you detected something funny with the ordering of the elements? Come on, look closer....... They start with `1` and not `0`, now isn't that funny. CFML is one of the few languages where array indexes start at `1` and not `0`. So if you have a PHP, Ruby, or Java background, remember that `1` is where you start. Is this good or bad? Well, we will refrain from pointing fingers for now. {% hint style="info" %} All CFML arrays in Adobe ColdFusion are passed by values, while in Lucee, they are **passed by reference**. Please remember this when working with arrays and passing them to functions. There is also the `passby=reference|value` attribute to function arguments where you can decide whether to pass by reference or value. {% endhint %} ## Arrays in Code Let's go ahead and model some code in CFML using our fancy REPL tool CommandBox: ![](/files/-LA-UoqWcqEVkZYuctRY) Check it out: * The array was created by putting pieces of data between square brackets (`[]`) and separated by commas * We added an element to the array using the member function `append()` * We fetched the element at a specific position by using square brackets (`[ x ]`) and replaced `x` with the index, we wanted * We retrieved the size of the array by using the member function `len()` * We searched the contents of the array using the member function `findNoCase()` , and it gave us the index position of the element in the array. Please note that all member functions can also be used as traditional [array functions](https://cfdocs.org/array-functions). However, [member functions](https://cfdocs.org/member) do look so much better for readability. {% hint style="success" %} **Tip:** You can use the `toString()` call on any array to get a string representation of its values: `grid.toString()` {% endhint %} ## Multi-Dimensional Arrays To create grids or matrix constructs, you must create two-dimensional arrays. Basically, giving you an **x** and **y** axis of data. You will do so using the `arrayNew( dimensions = max 3 )` method: ```javascript grid = arrayNew( 2 ); grid[ 1 ][ 1 ] = 'Hammer'; grid[ 1 ][ 2 ] = 'Nail'; grid[ 2 ][ 1 ] = 'Screwdriver'; grid[ 1 ][ 2 ] = 'Screw'; ``` {% hint style="success" %} **Tip:** CFML only supports two and three-dimensional arrays, so you can easily represent x, y and z axis. {% endhint %} ## Common Methods The best way to learn about using arrays is to check out the available [member functions](https://cfdocs.org/member) and [array functions](https://cfdocs.org/array-functions). ```javascript // Sort an array meals.sort( "textnocase" ); // Clear the array meals.clear(); // Go on a diet meals.delete( "Dessert" ); meals.deleteAt( 4 ); // Iterate meals.each( function( element, index) { systemOutput( element & " " & index ); } ); // Filter an array meals.filter( function( item ){ return item.findNoCase( "unch" ) gt 0 ? true : false; } ); // Convert to a list meals.toList(); // Map/ Reduce complexData = [ {a: 4}, {a: 18}, {a: 51} ]; newArray = arrayMap( complexData, function(item){ return item.a; }); writeDump(newArray); complexData = [ {a: 4}, {a: 18}, {a: 51} ]; sum = arrayReduce( complexData, function(prev, element) { return prev + element.a; }, 0 ); writeDump(sum); ``` ## Typed Arrays CFML engines also allow you to create strongly typed arrays. This is useful if you want to determine the array's contents specifically. Similar to [generics](https://www.baeldung.com/java-generic-array) in Java. This is accomplished with a new construct but ONLY on Adobe Engines: ```javascript Syntax: arrayNew[ type ]( dimensions ) ``` This syntax will allow you to define that an array is of a certain type and how many dimensions. ```javascript // array of strings stringArray = arrayNew[ "String" ]( 1 ) // array of numerics numericArray = arrayNew[ "Numeric" ]( 1 ) // array of User CFCs aUsers = arrayNew[ "User" ]( 1 ) ``` If you want to use typed arrays in Lucee, then you will have to declare it via the `ArrayNew()` method via the second argument: ```javascript ArrayNew( dimension, type, synchronized:boolean ) ``` Different syntax than Adobe Engines: ```javascript // array of strings stringArray = arraynew( 1, "String" ) // array of numerics numericArray = arraynew( 1, "Numeric" ) // array of User CFCs aUsers = arraynew( 1, "User" ) ``` {% hint style="warning" %} Please note that the CFML engines will try to cast values automatically into the type defined by the array container. {% endhint %} {% hint style="info" %} **Tip**: By default, all CFML arrays are *Unsynchronized*. That means they are not thread-safe when accessing the data from multiple threads or shared scopes. According to the CF2016 Performance whitepaper: Unsynchronized arrays are about 93% faster due to lock avoidance. So with much power comes much responsibility. {% endhint %} ### Array Types The allowed types are: * Array * Binary * Boolean * Component * CFC by Name / SubType * Date / Datetime * Function * Numeric * Query * String * Struct ### Literal Syntax Adobe engines also support a way to do a declaration of a typed array using a literal syntax: ```javascript [ type ][ elem1, elem2, .. elemN ] ``` This is a nice way to declare them literally: ```javascript stringArray = [ 'String' ][ 1, "Word1", "Word2" ] writeDump( stringArray ) ``` ## Negative Indices Adobe 2021+ and Lucee engines also support the concept of negative indices. This allows you to retrieve the elements from the end of the array backward. So you can easily count back instead of counting forwards: ```javascript numbers = [1,2,3,4,5] writedump( numbers[ -1 ] ) // 5 writedump( numbers[ -2 ] ) // 4 writedump( numbers[ -3 ] ) // 3 writedump( numbers[ -4 ] ) // 2 writedump( numbers[ -5 ] ) // 1 writedump( numbers[ -6 ] ) // EXCEPTION!!! Array index out of range ``` ## Array Slices Both CFML engines support the [slicing](https://cfdocs.org/arrayslice) of an array via the `arraySlice()` method or the `slice()` member function, respectively. However, Adobe engines also support a slicing literal syntax that is really useful and expressive. It follows this syntax: ```javascript Syntax: array[ from : to : step:1 ] ``` This allows you to get sub-arrays easily with no looping necessary. ```javascript fruits = [ "apple", "orange", "pear", "grape" ] writedump( fruits[:] ) // Dump all fruits writedump( fruits[ 1: -1 ] ) // Dump all fruits too // Dump all fruits too but in increments of two items not 1. writedump( fruits[ 1: -1 : 2 ] ) // dumps apple and pear // Items in reverse writedump( fruits[ -1:1:-1 ] ) ``` ## Looping Over Arrays You can use different constructs for looping over arrays: * `for` loops * `loop` constructs * `each()` closures ```javascript for( var thisMeal in meals ){ systemOutput( "I just had #thisMeal#" ); } for( var x = 1; x lte meals.len(); x++ ){ systemOutput( "I just had #meals[ x ]#" ); } meals.each( function( element, index ){ systemOutput( "I just had #element#" ); } ); cfloop( from=1, to=meals.len(), index=x ){ systemOutput( "I just had #meals[ x ]#" ); } ``` ### Multi-Threaded Looping Lucee and Adobe 2021 allow you to leverage the `each()` operations in a multi-threaded fashion. The `arrayEach()` or `each()` functions allow for a `parallel` and `maxThreads` arguments so the iteration can happen concurrently on as many `maxThreads` as supported by your JVM. ```java arrayEach( array, callback, parallel:boolean, maxThreads:numeric ); each( collection, callback, parallel:boolean, maxThreads:numeric ); ``` This is incredibly awesome as now your callback will be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place when accessing shared scopes and/or resources. ```java myArray.each( function( item ){ myservice.process( item ); }, true, 20 ); ``` Even though this approach to multi-threaded looping is easy, it is not performant and/or flexible. Under the hood, the engines use a single thread executor for each execution, do not allow you to deal with exceptions, and if an exception occurs in an element processor, good luck; you will never know about it. This approach can be verbose and error-prone, but it's easy. You also don't control where the processing thread runs and are at the mercy of the engine. ### ColdBox Futures Parallel Programming If you would like a functional and much more flexible approach to multi-threaded or parallel programming, consider using the ColdBox Futures approach (usable in ANY framework or non-framework code). You can use it by installing ColdBox or WireBox into any CFML application and leveraging our `async` programming constructs, which behind the scenes, leverage the entire Java Concurrency and Completable Futures frameworks. {% embed url="" %} ColdBox Futures and Async Programming {% endembed %} Here are some methods that will allow you to do parallel computations: * `all( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations. * `allApply( items, fn, executor ):array` : This function can accept an array of items or a struct of items of any type and apply a function to each of the items in parallel. The `fn` argument receives the appropriate item and must return a result. Consider this a parallel `map()` operation. * `anyOf( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like `all()`, this method will return the future that executes the fastest! Race Baby! * `withTimeout( timeout, timeUnit )` : Apply a timeout to `all()` or `allApply()` operations. The `timeUnit` can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds. ```javascript // Let's find the fastest dns server var f = asyncManager().anyOf( ()=>dns1.resolve(), ()=>dns2.resolve() ); // Let's process some data var data = [1,2, ... 100 ]; var results = asyncManager().all( data ); // Process multiple futures var f1 = asyncManager.newFuture( function(){ return "hello"; } ); var f2 = asyncManager.newFuture( function(){ return "world!"; } ); var aResults = asyncManager.newFuture() .withTimeout( 5 ) .all( f1, f2 ); // Process mementos for an array of objects function index( event, rc, prc ){ return async().allApply( orderService.findAll(), ( order ) => order.getMemento() ); } ``` ## Spread Operator Arrays also allow the usage of the spread operator syntax to quickly copy all or part of an existing array or object into another array or object. This operator is used by leveraging three dots `...` in specific expressions. The Spread syntax allows an iterable such as an array expression or string, to be expanded in places where zero or more arguments (for function calls) or elements (for array literals) are expected. Here are some examples to help you understand this operator: #### Function Calls ```javascript numbers = [ 1, 2, 3 ] function sum( x, y, z ){ return x + y + z; } // Call the function using the spread operator results = sum( ...numbers ) // 6 // Ignore the others numbers = [ 1, 2, 3, 4, 5 ] results = sum( ...numbers ) // 6 ``` #### Array Definitions ```javascript numbers = [ 1, 2, 3 ] myArray = [ 3, 4, ...numbers ] myArray2 = [ ...numbers ] myArray2 = [ ...numbers, 4, 66 ] ``` ## Rest Operator The rest operator is similar to the spread operator but behaves oppositely. Instead of expanding the literals, it contracts them into an array you designate via the `...{name}` syntax. You can use this to define endless arguments for a function, for example. In this case, I can create a dynamic `findBy` function that takes in multiple criteria name-value pairs. ```javascript function findBy( ...args ){ writeDump( args ) } findBy( 1, 2, 3, 4, 5 ) function findBy( entityName, ...args ){ writeDump( args ) } findBy( "Luis", 1, 2, 3, 4, 5 ) ``` ## Array Destructuring (ACF2021+) Array destructuring is a very unique technique that allows you to extract an array's value(s) into new variables. Let's start first with how we would accomplish this without the destructuring syntax: ```javascript kids = [ "alexia", "lucas", "matias", "isabella" ] // Assign an array's value into a new variable k1 = kids[ 1 ] k2 = kids[ 2 ] k3 = kids[ 3 ] writeDump( k1 ) writeDump( k2 ) writeDump( k3 ) ``` This is useful, but let's use the destructuring syntax to simplify this: ```javascript kids = [ "alexia", "lucas", "matias", "isabella" ] // Destructure by assignment via an array // Each item in the array is a new variable in the variables scope [ k1, k2, k3, k4 ] = kids writeDump( k1 ) writeDump( k2 ) writeDump( k3 ) writeDump( k4 ) ``` # Structures Collection of key-value pairs; a data dictionary A structure is a collection of data where each element of data is addressed by a **name or key** and it can hold a value of any type. Like a dictionary but on steroids: ```javascript // Create a struct via function myStruct = structnew() // Create a struct via literal syntax myStruct = {} ``` {% hint style="success" %} **Tip** Underneath the hood, all CFML structures are based on the `java.util.Map` interface. So if you come from a Java background, structures are untyped `HashMaps`. {% endhint %} As an analogy, think about a refrigerator. If we’re keeping track of the produce inside the fridge, we don’t really care about where the produce is in, or basically: **order doesn’t matter**. Instead, we organize things by name, which are unique, and each name can have any value. The name *grapes* might have the value 2, then the name *lemons* might have the value 1, and *eggplants* the value 6. {% hint style="info" %} All CFML structures are passed to functions as memory references, not values. Keep that in mind when working with structures. There is also the `passby=reference|value` attribute to function arguments where you can decide whether to pass by reference or value. {% endhint %} ## Key-Value Pairs A structure is an *unordered collection* where the data gets organized as a key and value pair. CFML syntax for structures follows the following syntax: ```javascript produce = { grapes = 2, lemons = 1, eggplants = 6 }; ``` {% hint style="success" %} **Tip** Please note that `=` sign and `:` are interchangeable in CFML. So you can use any to define your structures. {% endhint %} Since CFML is a case-insensitive language, the above structure will store all keys in uppercase. If you want the **exact casing** to be preserved in the structure, then surround the keys with quotes (`"`). {% hint style="info" %} The exact casing is extremely important if you will be converting these structures into JSON in the future. {% endhint %} ```javascript produce = { "grapes" = 2, "lemons" = 1, "eggplants" = 6 }; ``` ![](/files/-LA-Ur94dmX8J9bORxX2) The *key* is the address, and the *value* is the data at that address. Please note that the *value* can be ANYTHING. It can be an array, an object, a simple value, or even an embedded structure. It doesn't matter. ## Retrieving Values Retrieving values from structures can be done via dot or array notation or the `structFind()` function. Let's explore these approaches: ### Array Notation ```javascript writeOutput( "I have #produce[ "grapes" ]# grapes in my fridge!" ); writeOutput( "I have #produce[ "eggplants" ]# eggplants in my fridge!" ); ``` ### Dot Notation ```javascript writeOutput( "I have #produce.grapes# grapes in my fridge!" ); writeOutput( "I have #produce.eggplants# eggplants in my fridge!" ); ``` ### structFind( structure, key, \[defaultValue ] ) 
// Member Function
writeOutput( "I have #produce.find( "grapes" )# grapes in my fridge!" );
writeOutput( "I have #produce.find( "eggplants" )# eggplants in my fridge!" );

// Global Function
writeOutput( "I have #structFind( produce, "grapes" )# grapes in my fridge!" );
writeOutput( "I have #structFind( produce, "eggplants" ) eggplants in my fridge!" );
{% hint style="warning" %} However, please be aware that when dealing with native Java hashmaps, we recommend using array notation as the case is preserved in array notation, while in dot notation, it does not. {% endhint %} {% hint style="success" %} CFML offers also the `structGet()` function which will search for a key or a key path. If there is no structure or array present in the path, this function creates structures or arrays to make it a valid variable path. {% endhint %} ### Safe Navigation CFML also supports the concept of [safe navigation](/cfml-language/operators#safe-navigation-operator) when dealing with structures. Sometimes it can be problematic when using dot notation on nested structures since some keys might not exist or be `null`. You can avoid this pain by using the safe navigation operator `?.` instead of the traditional `.` , and combine it with the elvis operator `?:` so if null, then returning a value. ```javascript user = { age : 40 } echo( user.age ) // 40 echo( user.salary ) // throws exception echo( user?.salary ) // nothing, no exception echo( user?.salary ?: 0 ) // 0 ``` ## Setting Values I can also set new or override structure values a la carte. You can do so via array/dot notation or via the `structInsert(), structUpdate()` functions (, ) ```javascript // new key using default uppercase notation produce.apples = 3; // new key using case sensitive key produce[ "apples" ] = 3; // I just ate one grape, let's reduce it produce[ "grapes" ] = 1; // or produce.grapes--; produce.insert( "newVeggie", 2 ) produce.update( "newVeggie", 1 ) structInsert( produce, "carrots", 5 ) structUpdate( produce, "carrots", 2 ) ``` {% hint style="success" %} **Tip** You can use the `toString()` call on any structure to get a string representation of its keys+values: `produce.toString()` {% endhint %} ## Checking Contents & Size CFML also offers some useful methods when dealing with structures: | Function | Member Function | | ----------------- | --------------- | | `structIsEmpty()` | `isEmpty()` | | `structCount()` | `count()` | ## Key Values & Existence Here are some great functions that deal with getting all key names, and key values or checking for existence: | Function | Member Function | | ------------------- | --------------- | | `structKeyArray()` | `keyArray()` | | `structKeyList()` | `keyList()` | | `structKeyExists()` | `keyExists()` | ```javascript produce.keyArray() .each( (item) => echo( item ) ) writeOutput( "My shopping bag has: #produce.keyList()# " ) writeOutput( "Do you have carrots? #produce.keyExists( 'carrots' )#" ) ``` ## Structure Types In CFML, not only can you create case-insensitive unordered structures but also the following types using the `structNew()` function ()
TypeAdobe 2018Adobe 2021Lucee
casesensitivefalsetruefalse
normaltruetruetrue
ordered or linkedtruetruetrue
ordered-casesensitivefalsetruefalse
softfalsefalsetrue
synchronizedfalsefalsetrue
weakfalsefalsetrue
Here is the signature for the `structnew()` function on Adobe engines: ```javascript structNew( [type[[,sortType][,sortOrder][,localeSensitive]|[,callback]]] ) ``` Here is the signature for Lucee engines () ``` structNew( [type, [onMissingKey] ] ) ``` Now let's create some different types of structures ```javascript produce = structNew(); pickyProduce = structNew( "casesensitive" ) queue = structNew( "ordered" ) pickyQueue = structNew( "ordered-casesensitive" ) linkedList = structNew( 'ordered' ); cache = structnew( 'soft' ); ``` ### Literal Syntax You can also use literal syntax for some of these types: ```javascript // ordered struct myStruct = [:] or [=] // Case sensitive struct ACF Only myStruct = ${} // Case sensitive ordered struct ACF Only myStruct = $[=] ``` ## Common Methods Once you create structures, you can use them in many funky ways. Please check out all the [structure functions](https://cfdocs.org/struct-functions) and all the structure modern [member functions](https://cfdocs.org/member) that are available to you. ![](/files/-LA-UrDELNzOehtFU3eI) As you can see, there are many cool methods for detecting keys, values, lengths, counts, etc. A very cool method is `keyArray()` which gives you the listing of keys as an array: ![](/files/-LA-UrDTBpfFGIWSKjxL) ## Looping Over Structures You can use different constructs for looping over structures: * `for` loops * `loop` constructs * `each()` closures ```javascript for( var key in produce ){ systemOutput( "I just had #produce[ key ]# #key#" ); } produce.each( function( key, value ){ systemOutput( "I just had #value# #key#" ); } ); ``` ### Multi-Threaded Looping As of now, only Lucee and Adobe 2021 allows you to leverage the `each()` operations in a multi-threaded fashion. The `structEach()` or `each()` functions allow for a `parallel` and `maxThreads` arguments so the iteration can happen concurrently on as many `maxThreads` as supported by your JVM. ```java structEach( struct, callback, parallel:boolean, maxThreads:numeric ); each( collection, callback, parallel:boolean, maxThreads:numeric ); ``` This is incredibly awesome as now your callback will be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place. ```java myStruct.each( function( key, value ){ myservice.process( value ); }, true, 20 ); ``` Even though this approach to multi-threaded looping is easy, it is not performant and/or flexible. Under the hood, the engines use a single thread executor for each execution, do not allow you to deal with exceptions, and if an exception occurs in an element processor, good luck; you will never know about it. This approach can be verbose and error-prone, but it's easy. You also don't control where the processing thread runs and are at the mercy of the engine. ### ColdBox Futures Parallel Programming If you would like a functional and much more flexible approach to multi-threaded or parallel programming, consider using the ColdBox Futures approach (usable in ANY framework or non-framework code). You can use it by installing ColdBox or WireBox into any CFML application and leveraging our `async` programming constructs, which behind the scenes, leverage the entire Java Concurrency and Completable Futures frameworks. {% embed url="" %} ColdBox Futures and Async Programming {% endembed %} Here are some methods that will allow you to do parallel computations: * `all( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations. * `allApply( items, fn, executor ):array` : This function can accept an array of items or a struct of items of any type and apply a function to each of the items in parallel. The `fn` argument receives the appropriate item and must return a result. Consider this a parallel `map()` operation. * `anyOf( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like `all()`, this method will return the future that executes the fastest! Race Baby! * `withTimeout( timeout, timeUnit )` : Apply a timeout to `all()` or `allApply()` operations. The `timeUnit` can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds. # Database Queries CFML provides the easiest way to query a database CFML became famous in its infancy because it was easy to query databases with a simple `cfquery` tag and no verbose ceremonious coding. There is no ceremony, just a plain datasource definition in the administrator, and we could easily query the database. In modern times, we have many more ways to query the database, and defining data sources can occur not only in the admin but in our web application's `Application.cfc` or even define it at runtime programmatically or within the query constructs themselves. {% hint style="info" %} See [Application.cfc](/beyond-the-100/applicationcfc) for more information on how to leverage it for web development. {% endhint %} ## What is a Datasource? A datasource is a **named** connection to a specific database with specified credentials. You can define an infinite amount of data sources in your CFML applications in the following locations: * Global ColdFusion Engine (Adobe or Lucee) Administrator * **Adobe** : `http://localhost:port/CFIDE/adminstrator` * **Lucee**: `http://localhost:port/lucee/admin/server.cfm` * The `Application.cfc`, which will dictate the data sources for that specific ColdFusion application * Inline in `cfquery` or `queryexecute` calls The datasource is then used to control the database's connection pool and allow the ColdFusion engine to execute JDBC calls against it. ## What is a query? A query is a request to a database representing the results' rows and columns. It returns a CFML `query` object containing a **record set** and other metadata information about the query. The query can ask for information from the database, write new data to the database, update existing information in the database, or delete records from the database. This can be done in several ways: * Using the `cfquery` tag. () * Using the `queryExecute()` function. () {% hint style="info" %} In Lucee, a query is backed by the following class: `lucee.runtime.type.QueryImpl`\ In Adobe, a query is backed by the following class: `coldfusion.sql.QueryTable` {% endhint %} ```javascript // Tag syntax SELECT QUANTITY, ITEM FROM CUPBOARD ORDER BY ITEM // script syntax qItems = queryExecute( "SELECT QUANTITY, ITEM FROM CUPBOARD ORDER BY ITEM" ); // Lucee datasource inline definition queryExecute( "SELECT * FROM Employees WHERE empid = ? AND country = ?", // sql [ 1, "USA" ], // params { // options datasource : { class : "com.microsoft.sqlserver.jdbc.SQLServerDriver", connectionString : "jdbc:sqlserver://#getSystemSetting("DB_CONNECTIONSTRING")#", username : getSystemSetting("DB_USER"), password : getSystemSetting("DB_PASSWORD") } } ) ``` {% hint style="success" %} If you are using **Lucee**, the datasource can even be defined inline. So instead of giving the name of the `datasource` it can be a `struct` definition of the datasource you want to connect to, just like the struct in `Application.cfc` {% endhint %} ## Default Datasource You can also omit the `datasource` completely from query calls, and CFML will use the one defined in `Application.cfc` as the **default** datasource connection. This is a great way to encapsulate the datasource in a single location. However, we all know that there could be some applications with multiple data sources; that's ok; at least you can have one by default. {% code title="Application.cfc" %} ```java component{ this.name = "myApp"; // Default Datasource Name this.datasource = "pantry"; } ``` {% endcode %} ## Defining Datasources If you want to use the ColdFusion Engine's administrators for registering data sources, you must visit each administrator's interfaces and follow their wizards. ### ColdFusion Engine Administrator {% embed url="" %} {% embed url="" %} ### `Application.cfc` You can also define the datasources in the `Application.cfc`, which is sometimes our preferred approach as the connections are versioned controlled and more visible than in the admin. You will do this by defining a struct called `this.datasources`. Each **key** will be the name of the datasource to register and the **value** of each key a struct of configuration information for the datasource. However, we recommend that you setup environment variables in order to NOT store your passwords in plain-text in your source code. {% code title="Application.cfc" %} ```java component{ this.datasources = { // Adobe Driver Approach mysql = { database : "mysql", host : "localhost", port : "3306", driver : "MySQL", username : "root", password : "mysql", options : value }, // Adobe url approach mysql2 = { driver : "mysql", url : "jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true", username : "", password : "" }, // Shorthand Lucee Approach myLuceeDNS = { class : "com.mysql.jdbc.Driver", connectionString : "jdbc:mysql://localhost:3306/test?useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true", username : "", password : "" }, // Long Lucee Approach myLuceeDNS = { type : "mysql", database : "mysql", host : "localhost", port : "3306", username : "", password : "" } }; } ``` {% endcode %} {% hint style="success" %} For the inline approach, you will use the struct definition, as you see in the `Application.cfc` above and pass it into the `cfquery` or `queryexecute` call. {% endhint %} ### Portable Datasources You can also make your data sources portable from application to application or CFML engine to engine by using our [CFConfig](https://cfconfig.ortusbooks.com/) project. CFConfig allows you to manage almost every setting that shows up in the web administrator, but instead of logging into a web interface, you can manage it from the command line by hand or as part of a scripted server setup. You can seamlessly transfer config for all the following: * CF Mappings * Data sources * Mail servers * Request, session, or application timeouts * Licensing information (for Adobe) * Passwords -Template caching settings -Basically any settings in the web based administrator You can easily place a `.cfconfig.json` in the web root of your project, and if you start up a CommandBox server on any CFML engine, CFConfig will transfer the configuration to the engine's innards: {% code title=".cfconfig.json" %} ```java { "requestTimeoutEnabled":true, "whitespaceManagement":"white-space-pref", "requestTimeout":"0,0,5,0", "cacheDefaultObject":"coldbox", "caches":{ "coldbox":{ "storage":"true", "type":"RAM", "custom":{ "timeToIdleSeconds":"1800", "timeToLiveSeconds":"3600" }, "class":"lucee.runtime.cache.ram.RamCache", "readOnly":"false" } }, "datasources" : { "coldbox":{ "host":"${DB_HOST}", "dbdriver":"${DB_DRIVER}", "database":"${DB_DATABASE}", "dsn":"jdbc:mysql://{host}:{port}/{database}", "custom":"useUnicode=true&characterEncoding=UTF-8&useLegacyDatetimeCode=true&autoReconnect=true", "port":"${DB_PORT}", "class":"${DB_CLASS}", "username":"${DB_USER}", "password":"${DB_PASSWORD}", "connectionLimit":"100", "connectionTimeout":"1" } } } ``` {% endcode %} {% embed url="" %} ## Displaying Results The query object can be iterated on like a normal collection through a `for, cfloop or cfoutput` , `each()` constructs. {% embed url="" %} {% embed url="" %} **In a CFM Template** ```xml There are #qItems.Quantity# #qItems.Item# in the pantry
 ``` You leverage the `cfoutput` tag by passing the `query` to it. Then in the block of the tag you use dot/array notation and interpolation to output the column you want. CFML will iterate over all rows in the query for you. ```xml There are #qItems[ 'quantity' ]# #qItems[ 'item' ]# in the pantry
 ``` {% hint style="info" %} By specifying `encodefor="html"` each variable is encoded using the `encodeForHTML` function before it is output. {% endhint %} **Using Loops** ```java for( var row in qItems ){ systemOutput( "There are #row.quantity# #row.item# in the pantry" ); } qItems.each( function( row, index ){ systemOutput( "There are #row.quantity# #row.item# in the pantry" ); } ); for( var i = 1; i lte qItems.recordCount; i++ ){ systemOutput( "There are #qItems.quantity[ i ]# #qItems.item[ i ]# in the pantry" ); } ``` As you can see, many ways to iterate over the query exist. Choose the approach that suits your needs. ### Multi-Threaded Looping Lucee and Adobe 2021+ allow you to leverage the `each()` operations in a multi-threaded fashion. The `queryEach()` or `each()` functions allow for a `parallel` and `maxThreads` arguments so the iteration can happen concurrently on as many `maxThreads` as supported by your JVM. ```java queryEach( array, callback, parallel:boolean, maxThreads:numeric ); each( collection, callback, parallel:boolean, maxThreads:numeric ); ``` This is incredibly awesome, as now your callback will be called concurrently! However, please note that once you enter concurrency land, you should shiver and tremble. Thread concurrency will be of the utmost importance, and you must ensure that var scoping is done correctly and that appropriate locking strategies are in place. ```java myquery.each( function( row ){ myservice.process( row ); }, true, 20 ); ``` Even though this approach to multi-threaded looping is easy, it is not performant and/or flexible. Under the hood, the engines use a single thread executor for each execution, do not allow you to deal with exceptions, and if an exception occurs in an element processor, good luck; you will never know about it. This approach can be verbose and error-prone, but it's easy. You also don't control where the processing thread runs and are at the mercy of the engine. ### ColdBox Futures Parallel Programming If you would like a functional and much more flexible approach to multi-threaded or parallel programming, consider using the ColdBox Futures approach (usable in ANY framework or non-framework code). You can use it by installing ColdBox or WireBox into any CFML application and leveraging our `async` programming constructs, which behind the scenes, leverage the entire Java Concurrency and Completable Futures frameworks. {% embed url="" %} ColdBox Futures and Async Programming {% endembed %} Here are some methods that will allow you to do parallel computations: * `all( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures to execute them in parallel. When you call on it, it will return a future that will retrieve an array of the results of all the operations. * `allApply( items, fn, executor ):array` : This function can accept an array of items or a struct of items of any type and apply a function to each of the items in parallel. The `fn` argument receives the appropriate item and must return a result. Consider this a parallel `map()` operation. * `anyOf( a1, a2, ... ):Future` : This method accepts an infinite amount of future objects, closures, or an array of closures/futures and will execute them in parallel. However, instead of returning all of the results in an array like `all()`, this method will return the future that executes the fastest! Race Baby! * `withTimeout( timeout, timeUnit )` : Apply a timeout to `all()` or `allApply()` operations. The `timeUnit` can be days, hours, microseconds, milliseconds, minutes, nanoseconds, and seconds. The default is milliseconds. ## Using Input We usually won't have the luxury of simple queries; we will need user input to construct our queries. Here is where you need to be extra careful not to allow for [SQL injection.](https://owasp.org/www-community/attacks/SQL_Injection) CFML has several ways to help you prevent SQL Injection, whether using tags or script calls. Leverage the `cfqueryparam` construct/tag () and always sanitize your input via the `encode` functions in CFML. ```java // Named variable holder // automatic parameterization via inline struct definitions queryExecute( "select quantity, item from cupboard where item_id = :itemID" { itemID = { value=arguments.itemID, cfsqltype="numeric" } } ); // Positional placeholder queryExecute( "select quantity, item from cupboard where item_id = ?" [ { value=arguments.itemID, cfsqltype="varchar" } ] ); ``` You can use the `:varname` notation in your SQL construct to denote a **variable** placeholder or `?` to denote a **positional** placeholder. The `cfqueryparam` tag or the inline `cfsqltype` construct will bind the value to a specific database type to avoid SQL injection and to further the database explain plan via types. The available SQL binding types are: * `bigint` * `bit` * `char` * `blob` * `clob` * `nclob` * `date` * `decimal` * `double` * `float` * `idstamp` * `integer` * `longvarchar` * `longnvarchar` * `money` * `money4` * `nchar` * `nvarchar` * `numeric` * `real` * `refcursor` * `smallint` * `sqlxml` * `time` * `timestamp` * `tinyint` * `varchar` {% hint style="warning" %} Please note that the types can be prefixed with `cf_sql_{type}` or just used as `{type}`. {% endhint %} ## Query Methods Several query methods are available in CFML that can help you manage queries and create them on the fly (). Please note that you can also use chaining and member functions as well. * `queryNew()` * `queryAddRow()` * `queryAddColumn()` * `queryColumnArray()` * `queryColumnCount()` * `queryColumnData()` * `queryColumnExists()` * `queryColumnList()` * `queryCurrentRow()` * `queryDeleteColumn()` * `queryDeleteRow()` * `queryEach()` * `queryEvery()` * `queryFilter()` * `queryGetCell()` * `queryGetResult()` * `queryGetRow()` * `queryMap()` * `queryRecordCount()` * `queryReduce()` * `queryRowData()` * `querySetCell()` * `querySlice()` * `querySome()` * `querySort()` * `quotedValueList()` * `valueList()` ## Building Queries You can use a combination of the methods above to create your own queries: ```java news = queryNew("id,title", "integer,varchar"); queryAddRow(news); querySetCell(news, "id", "1"); querySetCell(news, "title", "Dewey defeats Truman"); queryAddRow(news); querySetCell(news, "id", "2"); querySetCell(news, "title", "Men walk on Moon"); writeDump(news); users = queryNew( "firstname", "varchar", [{"firstname":"Han"}] ); subUsers = queryExecute( "select * from users", {}, { dbtype="query" } ); writedump( subUsers ); news = queryNew("id,title", "integer,varchar", [ {"id":1,"title":"Dewey defeats Truman"}, {"id":2,"title":"Man walks on Moon"} ]); writeDump(news); news = queryNew("id,title", "integer,varchar", {"id":1,"title":"Dewey defeats Truman"}); writeDump(news); ``` ## Query of Queries Query a local database variable without going through your database is another great way to query an already queried query. Too many queries? ```java users = queryNew( "firstname", "varchar", [{"firstname":"Han"}] ); subUsers = queryExecute( "select * from users", {}, { dbtype="query" } ); writedump( subUsers ); ``` Please note that using a query of queries can be quite slow sometimes, not all the time. An alternative approach is to use modern `queryFilter()` operations to actually filter out the necessary data from a query or `querySort()`, etc. ## Returning Arrays of Structs or Struct of Structs In Lucee and Adobe 2021+, you can also determine the return type of database queries as something other than the CFML query object. You can choose an array of structs or a struct of structs. This is fantastic for modern applications that rely on rich JavaScript frameworks and produce JSON. This is achieved by passing the `returntype` attribute within the query options or just an attribute of the `cfquery` tag () ```java users = queryNew( "firstname", "varchar", [{"firstname":"Han"}] ); subUsers = queryExecute( "select * from users", {}, { dbtype="query", returntype="array" } ); writedump( subUsers ); users = queryNew( "id, firstname", "integer, varchar", [{"id":1, "firstname":"Han"}] ); subUsers = queryExecute( "select * from users", {}, { dbtype="query", returntype="struct", columnkey="id" } ); writedump( subUsers ); ``` ## QB = Query Builder We have created a fantastic module to deal with queries in a fluent and elegant manner. We call it **QB** short for **q**uery **b**uilder (). You can install it using CommandBox into your application by just saying: ```bash box install qb ``` Using qb, you can: * Quickly scaffold simple queries * Make complex, out-of-order queries possible * Abstract away differences between database engines ```java // qb query = wirebox.getInstance( 'Builder@qb' ); q = query.from( 'posts' ) .whereNotNull( 'published_at' ) .whereIn( 'author_id', [5, 10, 27] ) .get(); ``` You can find all the documentation in our Ortus Books docs: # Conditionals ## Operators Conditional statements evaluate to **true** or **false** only. The most common conditional operators are `==` (equal), `!=` (not equal), `>` (greater than), `>=` (greater than or equal to), `<` (less than), and `<=` (less than or equal to). You can also define the operators as abbreviations: `EQ, NEQ, GT, GTE, LT, and LTE`. ```java a = 1; if( a == 1 ) if( a > 2 ) if( a < 2 ) if( a != 2 ) if( a >= 1 ) if( a <= 1 ) ``` Some instructions return a `true` or `false`, so they're used in conditional statements, for example, `IsArray` which is `true` only when the variable is an "array". Structures have an instruction named `structKeyExists()` or `keyExists()` which returns `true` if a key is present in a structure. Strings can also be used for conditional operations by checking the `.length()` member function. ```java a = [1,3]; if( isArray( a ) ){ // work on the array } produce = { grapes = 2, lemons = 1, eggplants = 6 }; if( produce.keyExists( "grapes" ) ){ // eat a grape produce.grapes--; } ``` Also integers can be evaluated as **true** or **false**. In ColdFusion, **0 (zero)** is **false** and any other integers are **true**. ``` I am true so will show I am true so will show I am false so will not show ``` ## If, Else If, & Else Why do we have conditional statements? Most often it's to control conditional instructions, especially `if` / `else if` / `else` expressions. Let's write an example by adding a method to our `PersonalChef.cfc` class: ```java component accessors=true{ property name="status"; function init(){ status = "The water is not boiling yet."; return this; } function water_boiling( numeric minutes ){ if( arguments.minutes < 7 ){ status = "The water is not boiling yet."; } else if ( arguments.minutes == 7 ){ status = "It's just barely boiling."; } else if ( arguments.minutes == 8 ){ status = "It's boiling!"; } else { status = "Hot! Hot! Hot!"; } return this; } } ``` Try this example using 5, 7, 8 and 9 for the values of minutes. ```java chef = new PersonalChef(); for( i in [ 5, 7, 8, 9 ] ){ chef.water_boiling( i ); systemOutput( chef.getStatus() ); } ``` * When the minutes is 5, here is how the execution goes: Is it true that 5 is less than 7? Yes, it is, so print out the line `The water is not boiling yet.`. * When the minutes is 7, it goes like this: Is it true that 7 is less than 7? No. Next, is it true that 7 is equal to 7? Yes, it is, so print out the line `It's just barely boiling`. * When the minutes is 8, it goes like this: Is it true that 8 is less than 7? No. Next, is it true that 8 is equal to 7? No. Next, is it true that 8 is equal to 8? Yes, it is, so print out the line `It's boiling!.` Lastly, when total is 9, it goes:" Is it "true" that 9 is less than 7? No. Next, is it true that 9 is equal to 7? No. Next, is it true that 9 is equal to 8? No. Since none of those are true, execute the else and print the line `Hot! Hot! Hot!`. An `if` block has: * One `if` statement whose instructions are executed only if the statement is **true** * Zero or more `else if` statements whose instructions are executed only if the statement is **true** * Zero or one `else` statement whose instructions are executed if no `if` nor `else if` statements were **true** Only one section of the `if / else if / else` structure can have its instructions run. If the if is **true**, for instance, CFML will never look at the `else if`. Once one block executes, that’s it. ## Ternary Operator The ternary operator is a compact way to do an `if, else, else if` expression statements. It is very common in other languages and can be used for a more fluent expressive conditional expression. ``` ( condition ) ? trueStatement : falseStatement ``` The way it works is that the `condition` is evaluated. If it is **true**, then the true statement executed; if it is **false**, then the false statement executes. Please note that you can chain the `trueStatement` and the `falseStatement` into more tenrary operations. However, don't abuse it as they will look ugly and just be very complex to debug. ```java ( 1 == 1 ) ? systemOutput( "true" ) : systemOutput( "false" ); ``` The output of the above statement will be..... `true` of course! ## Elvis Operator Before Elvis we had `isDefined(), structKeyExists()` and `IF` statements to do these kind of evaluations. They work, but not very expressive or concise. The Elvis operator is primarily used to assign the `right default` for a variable or an expression Or it is a short-hand way to do parameterization. It will allow us to set a value if the variable is `Null` or does not exist. For instance, ```java myName = userName ?: "Anonymous"; ``` If `userName` does not exist or evaluates to `null` then the default value of the `myName` will be assigned the right part of the `?:` elvis operator -> `Anonymous` {% hint style="warning" %} **Warning:** The elvis operator is incredibly flawed in Adobe ColdFusion 10-11-2016 and Lucee 4.5. Just avoid using it if you are using those versions. Unfortunate but true. {% endhint %} ## Safe Navigation Operator The safe navigation operator was introduced in Adobe ColdFusion 2016 and Lucee 5.2 and it allows for you to navigate structures by not throwing the dreaded `key not exists` exception but returning an `undefined` or `null` value. You can then combine that with the elvis operator and create nice chainable struct navigation. For example instead of doing things like: ```java result = ""; if( structKeyExists( var, "key" ) ){ if( structKeyExists( var.key, "otherkey" ){ result = var.key.otherkey; } } ``` You can do things like this: ```java result = var?.key?.otherKey ?: ""; ``` The hook operator (`?`) along with the dot operator (`.`) is known as safe navigation operator(`?.`). The safe navigation operator makes sure that if the variable used before the operator is not defined or java `null`, then instead of throwing an error, the operator returns `null` for that particular access. ## Switch, Case, & Default Another situation that involves conditional logic is when a single variable or expression that can have a variety of values and different statements or functions needed to be executed depending on what that value is. One way of handling this situation is with a `switch / case / default` block. ```java switch( expression ){ case value : [ case otherValue ] : { // operations break; } default : { // Default operations } } ``` Much like how the `if` statement marks the start of an `if` block and contains one or more `else if` statements and perhaps one (and only one) `else` statement, the `switch` statement marks the start of a `switch` block and can contain multiple `case` statements and perhaps one (and only one) `default` statement. The main difference is that `switch / case / default` can only evaluate the resulting value of a single variable or expression, while the `if / else if / else` block lets you evaluate the `true or false` result of different variables or expressions throughout the block. ```java switch( city ){ case "New York": region= "East Coast"; break; case "Los Angeles": region= "West Coast"; break; case "Phoenix": region= "Phoenix"; break; case "Cleveland" : case "Cincinnati" : { region= "Midwest"; break; } default: region="Unknown"; } ``` Please note that you can create a body for the `case` statements with curly braces. As best practice, do so for all `case` and/or `default` blocks ## While Loops The `while( conditional )` expression allows you to execute a code block as many times as the `conditional` expression evaluates to **true**. This is a great way to work with queues, stacks or just simple evaluations. ```cfscript testCondition = true; count = 0; while( testCondition ){ count++; if( count == 5) { testCondition = false; } } systemOutput( count ); ``` ## The `==` and `=` Common Mistake The #1 mistake people encounter when writing conditional statements is the difference between `=` and `==`. * `=` is an assignment. It means "take what's on the right side and stick it into whatever is on the left side" (or its telling not asking.) * `==` is a question. It means "is the thing on the right equal to the thing on the left" (or its asking not telling.) # Exception Management ## Try/Catch/Finally The CFML language also provides you with a traditional approach to deal with error handling at the code block level. This is usually a trio of constructs: * `try`: The try block allows you to demarcate the code to test if it fails or passes () * `catch` : The catch block is executed when the try block fails () * `finally` : The finally block executes no matter if the try fails or passes. It is guaranteed to always execute. () Basically, a try and catch statement attempts some code. If the code fails, CFML will do whatever is in the exception to try to handle it without breaking. Of course, many different types of exceptions can occur, which should sometimes be handled in a different manner than the others. ```java try{ // code to try to execute } catch( any e ) { // the any type catches ALL errors from the try above } catch( myType e ){ // Catch the `myType` only type of exception } finally { // this code executes no matter what } ``` ## Catch Types The catch construct can take an `any` or a custom exception type declared by the CFML engine, Java code or custom exceptions within your code. This is a great way to be able to intercept for specific exception types and address them differently. ```java try{ } catch( database e ){ } catch( template e ){ } ``` ### Native Exception Types Some of the exception types found in CFML are the following * `application`: catches application exceptions * `database`: catches database exceptions * `template`: catches ColdFusion page exceptions * `security`: catches security exceptions * `object`: catches object exceptions * `missingInclude`: catches missing include file exceptions * `expression`: catches expression exceptions * `lock`: catches lock exceptions * `custom_type`: catches the specified custom exception type that is defined in a [cfthrow](https://cfdocs.org/cfthrow) tag * `java.lang.Exception`: catches Java object exceptions * `searchengine`: catches Verity search engine exceptions * `any`: catches all exception types ### Custom Exception Types Custom exception types are defined by you the programmer and they can also be intercepted via their defined name. Let's say that the exception type is "`InvalidInteger`" then you can listen to it like this: ```java try{ throw( type="invalidInteger" ); } catch ( "InvalidInteger" e ){ } ``` ## Throwing Exceptions Now that you have seen how to listen to exceptions, let's discover the `throw` or `cfthrow` constructs used to throw a developer-specific exception. () The `throw()` function or tag has several attributes: * **Type** : A custom or CFML core type * **Message** : Describes the exception event * **Detail** : A detailed description of the event * **errorCode** : A custom error code * **extendedInfo** : Custom extended information to send in the exception, can be anything * **object** : Mutually exclusive with the other attributes, usually another exception object or a raw Java exception type. ```java try { throw( message="Oops", detail="xyz", errorCode=12 ); } catch (any e) { writeOutput( "Error: " & e.message); } finally { writeOutput( "I run even if no error" ); } ``` ## Rethrowing Exceptions The `rethrow` or `cfrethrow` construct allows you to well, `rethrow` the active exception by preserving all of the exception information and types. Usually you use `rethrow` within a catch block after you have done some type of operations on the incoming exception. () ```java try{ runAroundEachClosures( arguments.suite, arguments.spec ); } catch( any e ){ rethrow; } finally { runAfterEachClosures( arguments.suite, arguments.spec ); } // Mix In Stub try{ // include it arguments.targetObject.$include = variables.$include; arguments.targetObject.$include( instance.mockBox.getGenerationPath() & tmpFile ); structDelete( arguments.targetObject, "$include" ); // Remove Stub removeStub( genPath & tmpFile ); } catch( any e ) { // Remove Stub removeStub( genPath & tmpFile); rethrow; } ``` # Components **ColdFusion (CFML) is object-oriented, period!** CFML is an Object-Oriented programming language which means that all the things we interact with inside the virtual machine are objects, which in our case we will call Components (CFCs). Objects can hold data, called **properties**, and they can perform actions, called **methods** or **functions,** they can inherit from other objects, they can implement interfaces, they can contain metadata, and even act as RESTFul webservices. {% hint style="info" %} Remember that objects are not only data but data + behavior. {% endhint %} For an example of an object, think about **you** as a human being. You have properties/attributes like height, weight, and eye color. You have functions/methods like walk, run, wash dishes, and daydream. Different kinds of objects have different properties and functions. Some might even just be a collection of functions (utility/static/service objects) or what are referred to as stateless objects, there is no instance data that they represent. CFML supports not only the traditional avenues for object orientation but many unique constructs and dynamic runtime additions. Enjoy! ## Classes and Instances In Object-Oriented programming we define **classes** which are abstract descriptions of a category or type of thing; a blueprint. In our case, we will call them components and it defines what properties and functions all objects (instances) of that type have. You can consider them to be a blueprint of your object representation. They should have a distinct job and a **single** responsibility (if possible), try to avoid creating God objects. > In object-oriented programming, a God object is an object that knows too much or does too much. The God object is an example of an anti-pattern. A common programming technique is to separate a large problem into several smaller problems (a divide and conquer strategy) and create solutions for each of them. - Let's check out an example of a simple Component, `User.cfc` ```java /** * I represent a user in the system * @author Luis Majano */ component accessors="true"{ /** * The name of the user */ property name="name"; /** * The age of the user */ property name="age" type="numeric"; /** * Constructor */ function init( required name ){ variables.name = arguments.name; return this; } function run(){ // run baby, run! } } ``` Please check out the following articles: * * * * * * * ### Notes of Interest The attribute `accessors` in the component definition denotes that automatic **getters (**[**accessors**](https://en.wikipedia.org/wiki/Mutator_method)**)** and **setters (**[**mutators**](https://en.wikipedia.org/wiki/Mutator_method)**)** will be created for all defined properties in the object. Also notice that the component and each property can be documented using `/** **/` notation, which is great for automatic documentation generators like [DocBox](https://www.forgebox.io/view/docbox). {% hint style="success" %} Get into the habit of inline documentation, it can go a long way for automatic generators and make you look like you can document like a machine! {% endhint %} ### Creating Instances The *User.cfc* component above is a representation of *any* user or the *idea* of a user. In order to bring it to life we will create an [**instance**](https://en.wikipedia.org/wiki/Instance_\(computer_science\)) of it, populate it with instance data and then use it. An instance, is a copy of that blueprint that you are bringing to life that will be stored in memory and used by the language during a set of executions. Usually via a `new` or `createObject()` keyword operation from another file, which can be a template or yet another component. ```java // Create a new instance of the User class user = new User( name="luis" ); // execute a function within it user.run(); ``` * See and Please note that the `new` keyword will automatically call an object's constructor: the `init()` method. The `createObject()` will not, you will have to call the constructor manually: ```java user = createObject( "component", "User" ).init(); ``` In later chapters we will investigate the concept of [dependency injection](/extra-credit/dependency-injection). Please also note that the `createObject()` function can also be used to create different types of objects in CFML like: * Components * Webservices (WSDL based) * Java Objects * .NET assemblies * COM Objects * Corba ## Constructors Every object in theory should have a constructor method or a method that initializes the object to a **ready** state. Even if the constructor is empty, get into the habit of creating one. ```java function init(){ // prepare object state, cache data, start the engines return this; } ``` Note that the constructor returns the `this` scope. This is a reference of the object itself that is returned. You can also return `this` from **ANY** other function which allows for expressive or fluently chainable methods. ```java function setValue( required val ){ variables.value = arguments.val; return this; } obj .setValue( 'myvalue' ) .setValue( 'otherValue' ); ``` By default when using the `new Object()` operator, the Object's `init()` function will be called for you automatically. If you use the `createObject()` then the `init()` is NOT called automatically for you, you will call it explicitly. ```java // Implicit Constructor var obj = new Object(); // Explicit Constructor var obj = createObject( "component", "Object" ).init(); ``` ### Pseudo-Constructor The pseudo-constructor can be found in use in CFML and it's a unique beast. Any source code that exists between the `cfcomponent` declaration and the first function is considered to be the pseudo-constructor. This area of execution will be executed for you implicitly whenever the object is created, even before the implicit `init()` method call. I know confusing, but here is a simple sequence: `new()/createObject() -> pseudo-constructor -> init()` ```java component{ // Pseudo Constructor starts here this.helper = now(); static { staticVar : 2 }; // Pseudo Constructor ends here function init(){ return this; } } ``` ## Component Scopes Every component has certain visibility scopes where properties, variables and functions are attached to. * `variables` - Private scope, visible internally to the CFC only, where all `properties` are placed in by default. Public and private function references are place here as well. * `this` - Public scope, visible from the outside world (can break encapsulation) public function references are placed here. * `static` - Same as in Java, ability to staticly declare variables and functions at the blueprint level and not at the instance level. (Lucee only) ## Component Attributes The `component` construct can also have many attributes or name-value pairs that will give it some extra functionality for SOAP/REST web services and for Hibernate ORM Persistence. Each CFML engine provides different capabilities. You can find all of them here: . Below are the most common ones: * `accessors` - Enables automatic getters/setters for properties * `extends` - Provides inheritance via the path of the Component (CFC) * `implements` - Names of the interfaces it implements * `persistent` - Makes the object a Hibernate Entity which can be fine tuned through a slew of other attributes. * `serializable` - Whether the component can be serialized into a string/binary format or not. Default is `true`. ```java component accessors="true" serializable="false" extends="BaseUser"{ } component implements="cachebox.system.cache.ICacheProvider"{} ``` Please note that in CFML you can also declare these attributes via annotations in the comments section, weird, I know! ```java /** * My User * @extends BaseUser * @accessors true * @serializable true */ component{ } ``` ## # Properties Properties are a way to create attributes/fields/data for your object, which can also adhere to inheritance rules. They are almost the same as fields in Java. In CFML, they can also be used to describe further capabilities for RESTFul/SOAP web services and Hibernate ORM. If `accessors` are enabled, CFML will track those properties in the `variables` scope according to their name and create automatic getter and setter methods for those properties. () ```java property name="firstName" default=""; property name="lastName" default=""; property name="age" type="numeric" default="0"; property name="address" type="array"; ``` The `property` construct can also have different name-value pair attributes that can enhance its functionality. You can find all of them here: . Below are the most common ones: * `type` - A valid CFML type * `default` - Default value when the object is created, else defaults to `null`. * `setter` - Generate a setter method or not, defaults to true * `getter` - Generate a getter method or not, defaults to true Please note that in CFML you can also declare these attributes via annotations in the comments section, weird, I know! ```java /** * The user age * @type numeric * @default 0 */ property name="age" ``` # Functions Functions are the way to interact with objects, with no functions we have no object-oriented behaviors, no [abstractions](https://en.wikipedia.org/wiki/Abstraction) and no [encapsulation](https://en.wikipedia.org/wiki/Encapsulation_%28computer_programming%29). Functions have an automatic return type of `any` which means it can return any type of variable back to a user and an automatic visibility scope of `public`. They also can take in *ANY* amount of arguments, which don't even have to be defined in the function signature. WOWZA! Functions in CFML are also first-class object citizens. Meaning that each function can be addressed like an object. They can be even deleted, renamed or even injected at runtime. This is one of the most powerful qualities of the CFML dynamic language. You can at runtime manipulate objects and their functions. {% hint style="info" %} You can find all the different features of functions in the docs: {% endhint %} ### **Declaration** ```java /** * Hints */ {access} {modifier:static|final|abstract} {returnType} function {name}({attributes}){} ``` ### **Examples** ```java function hello(){ return "Hola"; } abstract function getFile(); public static function testStatic(){} public final function hello(){} private function saveData(){ } /** * Check for existence * * @name The key to check */ function boolean valueExists( required name ){ return variables.exists( arguments.name ); } ``` {% hint style="info" %} Please note that you can use valid JavaDoc syntax and [DocBox](https://github.com/Ortus-Solutions/DocBox) will document your functions and arguments as well. {% endhint %} ## Function Access Types and Scopes Functions can have different visibility contexts: * `public` - Available to the component and externally * `private` - Available only to the component that declares the method and any components that extend the component in which it is defined * `package` - Available only to the component that declares the method, components that extend the component, or any other components in the package * `remote` - Available to a locally or remotely executing page or component method, or a remote client through a URL, Flash, or a web service. To publish the function as a web service, this option is required. Another interesting tidbit in CFML is that the visibility determines where the function will exist within the scope of the CFC. Remember that functions in CFML are objects themselves. They can be added, removed, renamed even at runtime thanks to CFML being a dynamic language. * `public,remote` - The function reference is placed in both the `this` and `variables` scope * `private,package` - The function reference is placed in the `variables` scope Does this mean, that I can programmatically change an object at runtime by injecting (mixing) in new methods, or removing methods, or even renaming them? HECK YES SIREE BOB! This is the beauty of the dynamic language, you can manipulate object instances at runtime. ## Function Modifiers Function modifiers allows you to declare special behaviors to functions, from `static` availability to `final` and `abstract` declarations. The supported modifiers for CFML functions by CFML engine are the following: | Modifier | Lucee 5+ | Adobe 2016 | Adobe 2018 | Adobe 2021 | | ---------: | :------: | :--------: | :--------: | :--------: | | `static` | Yes | No | No | Yes | | `final` | Yes | No | Yes | Yes | | `abstract` | Yes | No | Yes | Yes | We have created a section for each of these types, so you can read more about the modifiers: * [Static Constructs](/cfml-language/components/static-constructs) * [Final Constructs](/cfml-language/components/final-constructs) * [Abstract Constructs](/cfml-language/components/abstract-constructs) ## Function Attributes & Metadata The `function` construct can also have many attributes or name-value pairs that will give it some extra functionality according to CFML engine (metadata). You can find all of them here: . Below are the most common ones: * `output` - Will this function send content to the output stream. Try avoiding this to `true` unless you are building libraries of some type, else you are breaking encapsulation * `description` - A short text description of the function a part from the hint * `returnFormat` - Format to return for remote callers ```java function hello() description="" returnFormat=""{ } ``` Please note that in CFML you can also declare these attributes via annotations in the comments section: ```java /** * Say Hello * * @description A nice function * @output false */ function sayHello(){ } ``` Apart from the name-value pairs of attributes the CFML language gives you, you can also add your own. These are called function annotations or custom function metadata. They can be anything you like and they don't even have to have a value. The CFML engines then gives you the ability to read the metadata out of the functions via the `getMetadata()` or `getComponentMetadata()` functions. * * ## Function Arguments Arguments tell the function how to do their operation. A function can receive zero or more arguments separated by commas in its declaration. **declaration** ```javascript function( required type name=default attribute=value, required type name=default attribute=value ){ } ``` All CFML functions are dynamic, meaning it can take any number of arguments without you even adding the signatures. You can call functions by passing arguments by position or via name-value pairs or even with a structure/array of values, which will be called an `argumentCollection`. **example** ```javascript function sayHello( target ){ return "Hi #target#! I'm #name#"; } function add( required a, required b ){ return a + b; } // Let's call add calculator.add( 1, 2 ); calculator.add( a=1, b=2 ); // struct collection values = { a = 1, b = 2 }; calculator.add( argumentCollection=values ); // array collection values = [ 1, 2 ]; calculator.add( argumentCollection=values ); ``` {% hint style="success" %} **Tip:** Please also note that you can add a-la-carte metadata or name-value pairs to each argument inline or via annotations like we have seen above. {% endhint %} **example with annotations** ```javascript /** * Constructor * * @wirebox The wirebox reference * @wirebox.inject wirebox */ function init( required wirebox ){ variables.wirebox = arguments.wirebox; return this; } ``` ## Function Returns CFML functions will use the `return` keyword to return a value from the function. A function can be marked `void` in its return type to denote that it does **not** return any value. However, if a function has no return type or `any` and you do not return explicitly a value, then the function will automatically return `null`. ```java void function nada(){ // I do stuff, but return nothing } function nada(){ // I do stuff, but also do not return anything } function add( a, b ){ return a + b; } ``` ## Function Scopes You must be getting into the habit of scopes by now. Functions also has access to all Component scopes plus a few more that are only available to the function itself. * `arguments` - Collects all the incoming arguments. If the function is called via positional, then this will be a struct with numbers as keys. If the function is called via name-value pairs, then the struct will contain the same name-value pairs. * `local` - A struct that contains all the variables that are ONLY defined in the functions via the `var` keyword. ## Function Var Scope or Local Scope Each function has a `local` scope that is ONLY available for the life-time of the execution of the function. This is where you will be defining localized variables since your object can be multi-threaded. Always Always Always plan for multi-threaded applications and make sure you var scope your variables. Why? Well, if you do not var scope a variable then your variable will end up in the implicit scope which is `variables`. ```javascript // Sum is not var scoped, so it will be placed in the variables scope, memory leak anyone? function hello(){ sum = a + b; return sum; } function hello( a, b ){ var sum = a + b; return sum; } function hello( a, b ){ local.sum = a + b; return local.sum; } ``` CFML also has a weird cascading lookup for variables, so if you do not explicitly specify the scope it is in, CFML will look for it for you. If you use a variable name without a scope prefix, CFML checks the scopes in the following order to find the variable: * Local (function-local, UDFs and CFCs only) * Arguments * Thread local (inside threads only) * Query (not a true scope; variables in query loops) * Thread * Variables * CGI * Cffile * URL * Form * Cookie * Client Because CFML must search for variables when you do not specify the scope, you can improve performance by specifying the scope for all variables. ## Executing Functions You can execute functions once you have an instance or reference of a component. If the function has arguments, you can pass them in three ways: positional, name-value pairs, or using a collection (array,struct) via the `argumentCollection` attribute. ```java user = new User( name="luis" ); writeoutput( user.getName() ); hello = user.sayHello( "bob" ); hello = user.sayHello( target="bob" ); results = calculator.add( 1, 2 ); results = calculator.add( a=1, b=2 ); vals = [ 1, 2 ]; results = calculator.add( argumentCollection=vals ); vals = { a = 1, b = 2 }; results = calculator.add( argumentCollection=vals ); ``` # Static Constructs {% hint style="danger" %} Adobe 2018 does not support static constructors. Lucee 5+, and Adobe 2021+ supports it. {% endhint %} ### What is static? In CFML, a static variable is a variable of a component that isn’t associated with an **instance** of a component. Instead, the variable belongs to the component definition itself. As a result, you can access the static variable without first creating the component instance. ### Why use static? This allows you to create pure utility objects or stateless services that require no instance or holds no instance data. It can also accelerate the retrieval of such variables or methods since no instance has to be ever instantiated in order to be used. ### Where can I apply it? In CFML, the `static` keyword can be applied in the pseudo-constructor in order to initialize static variables in a component. This is called the **static constructor**. The keyword can also be applied to functions within a Component in order to declare static functions. ## Static Constructor The static constructor is execute once before the component is loaded for the first time, so every component of the same type will share the same **static** scope. This construct is placed inside the pseudo-constructor of the component. ```java component MyFunkyCalculator{ // Static Constructor static { CACHE_KEY = "luis"; multiplier = 4; } } ``` ## Static Methods Static methods can be used without an instance of the component and can also access static variables declared in the static constructor by using the `static` scope from within the same component. ```java component MyFunkyCalculator{ // Static Constructor static { CACHE_KEY = "luis"; multiplier = 4; } public static function calculate( a ){ return static.multiplier * a; }; public static function getGlobalCacheKey(){ return static.CACHE_KEY; } } ``` ## Accessing Static Constructs We have seen how to declare the static constructor and static methods, but how in the world do we acces them from outside the component? We leverage the `::` double colon syntax. ```java // Refer to the CFC by path, then use the :: and call a function or variable MyFunkyCalculator::CACHE_KEY; MyFunkyCalculator::calculate( 1 ); ``` # Final Constructs Both Adobe 2018 and Lucee Engines support the usage of `final` constructs for three contexts: * Components * Methods * Variables (Constants) Final modifiers disallow the modifications to the source code to maintain stricter programming constructs. This would be used when you do not want to allow code to override your component or function or variable. This can be a great asset if you are building libraries, frameworks or APIs that require fine granular control of how they can be extended or used. ## Final Components Components can be declared as final, meaning they cannot be extended (inheritance) by other components. This is the ultimate code reuse blocker! However, a final component CAN extend other components. {% hint style="success" %} Final components can be used to prevent inheritance where it is not allowed. Great for APIs, frameworks, and libraries where the author wants to be strict about the usage of such code templates. {% endhint %} ```java final component{} final component extends="MyService"{} ``` {% hint style="info" %} Unlike `abstract` a function can be `final` even if the component is not `final`. {% endhint %} ## Final Functions Functions within a component can also be declared as `final`. Final methods cannot be overridden by sub-components. Final methods can be used to limit the extent to which sub-components redefine the behavior of the parent classes. ```java component BaseUtil{ final function getFile(){ return getCurrentTemplatePath(); } } // Throws exception due to final method being overriden. component extends="BaseUtil"{ function getFile(){ return "hijacked"; } } ``` {% hint style="success" %} This may be useful when frameworks/base components are being developed, to ensure the same implementation is being followed in all derived classes. {% endhint %} ## Final Variables Variables declared as final are ensured to be constants for the rest of the execution process. The value of that final variable cannot be modified post-construction of the component. Usually these constructs are used in variables defined in the pseudo-constructor. ```java component{ final static CACHE_KEY = "cb_"; final NAME = "John Majano" NAME = "Lui Majano" // Throws a final variable exception final DETAILS = { "age" : 1 } DETAILS[ "nickname" ] = "Johnny Bravo" // Allowed DETAILS = {} // Disallowed } ``` Usually, final variables should be in uppercase to denote them as contstants as per Java conventions and best practices. {% hint style="danger" %} **Important**: The variables that contain references to other objects cannot be re-bound to reference news or other objects. i.e., If a `final` variable holds a reference to an array, the reference may not be updated to a new array – but the contents of the original array itself may be updated. The same should apply to structures. {% endhint %} # Abstract Constructs The abstract constructs can be both used in Lucee and Adobe 2018. The main goal of abstraction is to handle complexities by hiding/encapsulating unnecessary details from other users. Abstraction is implemented in most languages by defining a class that has methods, properties & constructors. Abstract will allow you to define two contexts of operation: 1. Components 2. Functions ![](/files/-Lld6RR_t-EfkkqYWtmt) ## Abstract Components An abstract component allows you to make a template or blueprint for a component that will be eventually inherited from, so the inheriting class doesn't have to implement all of the methods. Therefore, abstract classes cannot be instantiated but only extended. Abstract classes can have both abstract and concrete methods defined within it. Abstract methods have no body, they are just declared, much like interfaces. Usually, you would do this to satisfy an interface declaration. In my years of experience, abstract classes usually go hand in hand with interfaces and usually implement [strategy patterns](https://en.wikipedia.org/wiki/Strategy_pattern). We would suggest that if you define abstract components that you add the prefix `Abstract` to the component name as best practice: `AbstractAnimal, AbstractLogger, AbstractPerson`. This goes a long way to help with readability and standards. {% hint style="info" %} In an inheritance hierarchy the first non-abstract class should implement **all** the abstract methods. {% endhint %} {% code title="AbstractAnimal.cfc" %} ```java /** * An abstract animal class */ abstract component implements="IAnimal"{ property animalSize; property animalType; function init( animalSize, animalType ){ variables.animalSize = arguments.animalSize; variables.animalType = arguments.animalType; return this; } /** * Shortcut for getting the animal size */ function getSize(){ return variables.animalSize; } abstract function eat( any prey="" ) abstract function makeNoise() abstract function poop() } ``` {% endcode %} ## Abstract Functions As you can see from the example above, abstract functions can be defined ONLY in an abstract component. These functions are demarcated as abstract so inherited components can implement them. You can have many abstract functions in your abstract component and you can also have many concrete functions as well: {% code title="AbstractLogger.cfc" %} ```java abstract component implements="ILogger"{ /** * Min logging level */ property name="levelMin" type="numeric"; /** * Max logging level */ property name="levelMax" type="numeric"; /** * Appender properties */ property name="properties" type="struct"; /** * Write an entry into the appender. You must implement this method yourself. * * @logEvent The logging event to log */ abstract function logMessage( required coldbox.system.logging.LogEvent logEvent ) /** * Setter for level min * * @throws AbstractAppender.InvalidLogLevelException */ AbstractAppender function setLevelMin( required levelMin ){ // Verify level if( this.logLevels.isLevelValid( arguments.levelMin ) AND arguments.levelMin lte getLevelMax() ){ variables.levelMin = arguments.levelMin; return this; } else { throw( message = "Invalid Log Level", detail = "The log level #arguments.levelMin# is invalid or greater than the levelMax (#getLevelMax()#). Valid log levels are from 0 to 5", type = "AbstractAppender.InvalidLogLevelException" ); } } /** * Utiliy to send to output to console. * * @message Message to send * @addNewLine Add a line break or not, default is yes */ private function out( required message, boolean addNewLine=true ){ if( arguments.addNewLine ){ arguments.message &= chr( 13 ) & chr( 10 ); } createObject( "java", "java.lang.System" ).out.println( arguments.message ); } } ``` {% endcode %} {% hint style="info" %} Only **abstract** components can contain **abstract** functions. {% endhint %} # Interfaces Interfaces are a type of component that have a set of signatures for specific functions and in some of the latest versions of Lucee and Adobe ColdFusion it can even have some implemented functions. You can basically call an interface a signature map for the type of components you want to create. In statically typed languages, they make a lot of sense since they can allow you to add/modify behavior of classes that the compiler can understand on how to link and compile. In a dynamic language, where functions can mutate or even be removed or injected at runtime, interfaces don't make soooo much sense. However, interfaces are a great way to provide documented signatures for developers to follow. ![](/files/-Lld64SOtd84odKmPPVg) If you are developing frameworks, libraries or structured domain models where implementations can be done at a later point of time, or different strategies adapted; interfaces are king. ![](/files/-Lld6LFvsOF-8E6LZBmd) ## Declaration Interfaces are defined in a file template with a `.cfc` extension. For best practice you can start the name of the interface with a capital `I,` example: `IAnimal.cfc, ILogger.cfc, IAdapter.cfc` ```java interface extends="other_interfaces"{ any function returnAny( required numeric obj, boolean why=false ) function sayHello() ILogger function logEvent( required logEvent ) // If in Adobe2018 or Lucee, you can implement default behavior function getCacheKey(){ return "default_key"; } } ``` ## Implementation Interfaces can extend other interfaces and components that implement them can also implement many interfaces: ```java component implements="ILogger,IAdapter"{ any function returnAny( required numeric obj, boolean why=false ){ // implementation here. } function sayHello(){ return "Hola"; } ILogger function logEvent( required logEvent ){ // log this... return this; } } ``` # Closures > A closure is the combination of a function and the lexical environment within which that function was declared. Remember that functions (UDFs) in CFML are objects, and closures are objects. So, are closures and functions the same? The answer is yes and no. The main difference between a UDF and a closure is that closures have access to the lexical environment in which they are declared. Both functions and closures can be manipulated at runtime and passed around to other functions and closures or returned from other functions and closures. Phew! A closure can be used in any of the following ways: * Defined inline without giving a name. * They can be assigned to a variable, array item, struct, and variable scope. * It can be returned directly from a function. ## Assigned Closures ```java function hello(){ var name = "luis"; var display = function(){ systemOutput( name ); }; display(); } hello(); ``` If we execute this template via CommandBox, our output will be **luis**. This means the `display` closure has access to its surroundings to display the `name` variable. It can manipulate it, add to it, remove from it, and more. ## Returned Closures/High-Order Functions We can also have a function return a closure that can leverage the function's variable environment. ```java function makeAdder( required x ){ return function( required y ){ return x + y; }; } add = makeAdder( 1 ); systemOutput( add( 2 ) ); ``` In this case, the `makeAdder` creates a function that will add the passed-in variable with another via a delay of execution. You can then execute the resultant closures `add` with another number to get your calculation of `3` in this case. **Funky!!** ## Passed Closures CFML also has the concept of functional programming using several modern operations, like `map(), reduce(), filter(), each(), etc` you can pass closures into other functions for operating on different data structures. ```java fruitArray = [ { fruit='apple', rating=4 }, { fruit='banana', rating=1 }, { fruit='orange', rating=5 }, { fruit='mango', rating=2 }, { fruit='kiwi', rating=3 } ]; favoriteFruits = fruitArray.filter( function( item ){ return item.rating >= 3; } ); systemOutput( favoriteFruits ); ``` Please note that you can construct your very own functional member functions on your objects and generate very functional custom DSL (Domain Specific Languages) by being creative. ## Delayed Execution Another big advantage of leveraging closures for functional programming is that closures are the blueprint of a function and are not executed until you want to. They are useful for delaying execution and great for design patterns like observers, filters, iterators, and much more. ```java var observe = function( val ){ // manipulate the val and return it return val; } describe( "A spec suite", function(){ it( "can do funky stuff", function(){ // I can do funky stuff here } ); } ); ``` ## Closure Scopes A closure retains a copy of variables visible at its creation. The global variables (like ColdFusion specific scopes) and the local variables (including declaring or outer function's local and arguments scope) are retained at the time of a closure creation. Functions are static. The following details the scope of closure based on the way they are defined:
ScenarioScope
In a CFC functionClosure argument scope, enclosing function local scope and argument scope, this scope, variable scope, and super scope
In a CFM functionClosure argument scope, enclosing function local scope and argument scope, this scope, variable scope, and super scope
As function argumentClosure argument scope, variable scope, and this scope and super scope (if defined in CFC component).
In a closure, the following is the order of search for an unscoped variable: * Closure's `local` scope * Closure's `arguments` scope * Outer function' `local` scope if available * Owner function's `local` scope if available * ColdFusion built-in scope ## isClosure() CFML has a built-in function called `isClosure()` that allows you to evaluate if a variable is a closure or not: ```java if( isClosure( arguments.body ) ){ arguments.body(); } ``` ## Lambda Expressions or Arrow Functions Supported only in Lucee and Adobe 2018+. {% hint style="danger" %} Please note that they are not REAL lambdas or pure functions. Pure functions are not supposed to interact with their environment and should have no side effects on their surroundings. However, in ColdFusion, they are just implemented using the expression syntax, not the semantic nature of pure functions. {% endhint %} Arrow functions reduce much of the syntax around creating closures. In its simplest form, you can eliminate the `function` keywords, curly braces, and `return` statements. Arrow expressions implicitly return the results of the expression body. ```java // Using a traditional closure makeSix = function(){ return 5 + 1; } // Using an arrow expression makeSix = () => 5 + 1; // returns 6 systemOutput( makeSix() ); ``` A simple arrow expression with multiple arguments: ```java // Takes two numeric values and adds them add = ( numeric x, numeric y ) => x + y; // returns 4 systemOutput( add( 1, 3 ) ); ``` A complex arrow expression with an argument: ```java // Takes a numeric value and returns a string isOdd = ( numeric n ) => { if( n % 2 == 0 ){ return 'even'; } else { return 'odd'; } }; // returns 'odd' SystemOutput( isOdd( 1 ) ); // returns 'even' SystemOutput( isOdd( 10 ) ); ``` # Code Locking Locking is an essential piece of software engineering. There are occasions where shared resources must be locked in order to write to them or read from them. This process of locking can be very simple or extremely complex. Sometimes it can lead to deadlocks and serious concurrency issues. Further to say, we will only cover basic usage of the locking constructs in CFML. {% hint style="success" %} You can find an in-depth article on locking here: You can also find great knowledge in the Java Synchronization tutorial: {% endhint %} ## cflock CFML gives you the `cflock` tag/construct which you can use to ensure the integrity of shared data and it allows you to have two types of locks: 1. **Exclusive** - Allows single-thread access to the CFML constructs in its body. The tag body can be executed by **one** request at a time. No other requests can start executing code within the tag while a request has an exclusive lock. ColdFusion issues exclusive locks on a first-come, first-served basis. 2. **ReadOnly** - Allows multiple requests to access CFML constructs within the tag body concurrently. Use a read-only lock only when shared data is read and not modified. If another request has an exclusive lock on shared data, the new request waits for the exclusive lock to be released Apart from the type of lock, you can also have two different locking strategies: 1. **Named Locking** : Where a name is used to identify the locking construct 2. **Scoped Locking**: Where you will lock access to a specific CFML scope. ```java lock type="exclusive|readOnly" timeout="15" name="mylock" scope="application|server|session|request" throwOnTimeout="true|false" { // Your code that is synchronized goes here } ``` ### Attributes Here are the attributes to the `cflock` construct
AttributeTypeDefaultDescription
AttributeTypeDefaultDescription
timeoutnumericrequiredMax length in seconds to wait to obtain the lock. If lock is obtained, tag execution continues. Otherwise, behavior depends on throwOnTimeout attribute value.
scopestringLock scope. Mutually exclusive with the name attribute. Only one request in the specified scope can execute the code within this tag (or within any other cflock tag with the same lock scope scope) at a time. Values are: application, request, server, session
namestringLock name. Mutually exclusive with the scope attribute. Only one request can execute the code within a cflock tag with a given name at a time. Cannot be an empty string.
throwOnTimeoutbooleantrueIf true and a timeout is reached an exception is thrown, else it is ignored.
typestringexclusivereadOnly: lets more than one request read shared data. exclusive: lets one request read or write shared data.
{% hint style="danger" %} **Important**: Please note that when using named locks, the name is shared across the entire ColdFusion server, no matter the `cfapplication` it is under. Please be aware of it and use unique enough names. Lock names are global to a ColdFusion server. They are shared among applications and user sessions, but not clustered servers. {% endhint %} ## Named Locking Named locking is the easiest, where access to the construct is by name. Lock names are global to a ColdFusion server. They are shared among applications and user sessions, but not clustered servers. ```java lock name="cache-population-myapp" timeout=10 type="exclusive"{ myData = myservice.getData(); cache.set( "mykey", myData ); } ``` ## Scoped Locking Scoped locking will allow you to lock access to a specific CFML scope like: `application, server, session and request.` You usually do this to synchronize access to variables placed within those scopes. In all essence, scope locking is expensive as it is a BIG lock around the entire scope access. I would suggest to stick to named locks so you can have pin-point accuracy when dealing with code synchronization. Remember that locking can be expensive. ```java lock scope="application" timeout="15"{ application.myNumber += 5; } lock scope="application" timeout="20" type="readonly"{ writeOutput( "I have #application.number# of sock(s) in my closet" ); } ``` {% hint style="danger" %} I highly discourage the use of scope locks as it throws a huge locking mechanism around the entire scope access. Tread with caution. {% endhint %} ## Deadlocks ![](/files/-LliEiijroFNlA0pAcCl) A deadlock is a state in which no request can execute the locked construct. After a deadlock occurs, neither thread can break it, because all requests to the protected section of the lock are blocked until the deadlock can be resolved by a lock time-out. The `cflock` tag/construct uses kernel level synchronization objects that are released automatically upon time out and/or the abnormal termination of the thread that owns them. Therefore, while processing a `cflock` , the server never deadlocks for an infinite period. However, large time-outs can block request threads for long periods, and radically decrease throughput. To. prevent this, always use the minimum time-out value. Another cause of blocked request threads is inconsistent **nesting** of `cflocks` and inconsistent naming of locks. If you nest locks, everyone accessing the locked variables must consistently nest `cflocks` in the same order. Otherwise, a deadlock can occur. More information can be found here: ## Race Conditions: Double Locking There will be cases where race conditions will exist and multiple threads will be waiting for access into a lock body construct. Furthermore, you will want that only ONE thread enters the body construct and does something and the rest get ignored. This is a race condition and it must be treated with a double lock approach. What this does is that it evaluated the condition of your body (business logic) and if available then enters the lock. Let's do a simple example where you only want ONE thread to ever populate the cache with data and return it from a function. Let's see how NOT to do it first: ```java function loadData(){ var myData = cache.get( "mykey" ); if( isNull( myData ) ){ lock name="cache-population-myapp" timeout=10 type="exclusive"{ myData = myservice.getData(); cache.set( "mykey", myData ); } } return myData; } ``` I am sure that you see this nice function and you are like, well yep it is correct! We check for the existence of the cached data, if null, we load it up and return it. WROOONG!!! This can lead to race conditions where if multiple threads are ALREADY waiting within the lock area, multiple threads can set and re-set the cached data. If we really ONLY want one thread to set the data, we must do a double lock approach: ```java function loadData(){ var myData = cache.get( "mykey" ); if( isNull( myData ) ){ lock name="cache-population-myapp" timeout=10 type="exclusive"{ if( !cache.exists( "mykey" ) ){ myData = myservice.getData(); cache.set( "mykey", myData ); } else { return cache.get( "mykey" ); } } } return myData; } ``` # Threading CFML allows you create asynchronous threads so you can execute a body of code in a separate thread. This is achieved via the `cfthread` tag & the `thread` construct. Threads are independent streams of execution, and multiple threads on a page can execute simultaneously and asynchronously, letting you perform asynchronous processing in CFML. CFML code within the `cfthread` tag body executes on a separate thread while the page request thread continues processing without waiting for the `cfthread` body to finish. You can allow the thread body to continue executing in the background or you can wait for it to finish. ![](/files/-LlrnLRAHaySHceVGAIv) {% hint style="danger" %} **IMPORTANT:** You cannot spawn a thread from within a thread in any of the CFML engines. {% endhint %} This approach is very very simplistic, if you want more control of your asynchronous programming aspects then we can move into leveraging CFML Future's via the `runAsync()` function or parallel Java streams using the [cbStreams](https://www.forgebox.io/view/cbStreams) project. Please see our [Asynchronous Programming ](/beyond-the-100/asynchronous-programming)section for information on advanced asynchronous programming. {% embed url="" %} {% embed url="" %} ### A Fair Warning Please note that once you get into concurrency you will start to get many headaches. Your code must be thread safe, appropriate locking must be in place and overall concurrency based programming will be needed on any shared resource. It is also very difficult to debug because you are no longer in the same thread and a `writedump() + abort` combo usually goes into ether. Logging will be your best friend and outputting logs to the console for debugging purposes. ### Thread Logging Here are some utility functions to assist with logging: * `systemOutput( obj, addNewLine:boolean, doErrorStream:boolean)` - Writes the given text or complex objects to the output or error stream. Complex objects are outputted as JSON. (Lucee-only) * `cfdump( var="text", output="console" )` - Send the variables to the output console, even complex variables. Complex objects are outputted as JSON. * `cflog( text, log, file, type ) or writeLog()` - Leverage the ColdFusion engine's logging facilities to send typed messages. ```java // Lucee Only sytemOutput( "Hello from thread land", true ); sytemOutput( myComplexObject, true ); // Dumps writedump( var="Hello from thread land", output="console" ); writedump( var=myComplexObject, output="console" ); // Cflogs writeLog( text = "Logging some info.", type = "information", application = "false", file = "myLogFile" ); // By default, with no file or log type it sends it to the application.log writeLog( text = "Logging more info.", type = "error" ); ``` ## Thread Construct Writing `thread` is extremely easy, just use the construct, give it a few attributes an boom you are in multi-threaded land. In tags you can use the `` tag. ```java thread name = "The name of the thread, must be unique" action="run, sleep, join, or terminate" duration="The number of milliseconds to suspend the thread processing" priority="high, low, or normal" timeout="Number in milliseconds the current thread waits for this thread to finish." { // Body to execute in a separate thread // All variables declared implicity will be placed in the thread's local scope // You still have access to all scopes. } ``` Examples: ```java thread action="run" name="myThread" { // do single thread stuff } // Wait for the myThread and myOtherThread to finish thread action="join" name="myThread,myOtherThread"; // A fancy one thread name="#thisThreadName#" action="run" priority="#arguments.asyncPriority#" interceptData="#arguments.interceptData#" threadName="#thisThreadName#" buffer="#arguments.buffer#" key="#key#" { // Retrieve interceptor to fire and local context var thisInterceptor = this.getInterceptors().get( attributes.key ); var event = variables.controller.getRequestService().getContext(); // Check if we can execute this Interceptor if( variables.isExecutable( thisInterceptor, event, attributes.key ) ){ // Invoke the execution point variables.invoker( interceptor = thisInterceptor, event = event, interceptData = attributes.interceptData, interceptorKey = attributes.key, buffer = attributes.buffer ); // Debug interceptions if( variables.log.canDebug() ){ variables.log.debug( "Interceptor '#getMetadata( thisInterceptor ).name#' fired in asyncAll chain: '#this.getState()#'" ); } } } // end thread ``` ## Thread Data Because multiple threads can process simultaneously within a single template request, applications must ensure that data from one thread does not pollute or affect data in another thread. CFML provides several scopes that you can use to manage thread data, and a request-level lock mechanism that you use to prevent problems caused by threads that access page-level data. CFML also provides metadata variables that contain any thread-specific output and information about the thread, such as its status, processing time and much more, which extremely useful. ### Thread Scopes * Thread `local` scope * `Thread` scope * `Attributes` scope #### Thread local Scope The thread-local scope is an implicit scope that contains variables that are available only to the thread, and exist only for the life of the thread. This exactly the same as the function `local` scope. Any variable that you define inside the `thread` body without specifying a scope name prefix is in the thread local scope and cannot be accessed or modified by other threads. ```java thread name="mythread"{ var localData = "this data"; // A thread local variable. believeItOrNot = "this goes into the local scope and not the variables scope"; } ``` #### `Thread` Scope The `Thread` scope contains thread-specific variables and metadata about the thread. Only the owning thread can **write** data to this scope, but the page thread and all other threads in a request can **read** the variable values in this scope. Thread scope data remains available until the page and all threads that started from the page finish, even if the page finishes before the threads complete processing. **So be careful with what you store in this scope or you can create memory leaks.** To write to this scope you can use the `thread` scope or actually the **name** of the thread as well, which is pretty cool. To read from this scope outside the `thread` construct you can use the name of the thread or the thread scope, but you must reference which thread scope within it using it's name: `thread.myThreadName` ```java thread name="mythread"{ // create a shared struct data variable. thread.myDataProcess = { name = "hello" }; thread.threadStartedAt = now(); // Or use the thread name mythread.myDataProcess.value = 1; } // Outside of the thread, you can use the thread scope or the named thread. cflog( thread.myThread.myDataProcess.hello ); cflog( mythread.myDataProcess.value + 1 ); ``` {% hint style="danger" %} Thread scoped variables are only available to the page that created the thread or to other threads created by that page. No other page can access the data, ever! If one page must access another page's `Thread scope` data, you must place the data in a shared location such as a shared scope or a file or database. {% endhint %} #### Thread Attributes Scope The thread body executes in isolation, but sometimes you need to be able to pass certain data that the thread body cannot access. In this case, we will pass them via the `thread` construct as a name-value pair. The CFML engine will then place those in the thread's `attributes` scope so they can be used for the life of the thread. **WARNING** **All variables passed as attributes will be duplicated by the engine (deep copy). That's right! A raw duplicate() will be executed for the passing variable. If it is an array or struct, the entire collection will be duplicated. If it is an object with an object graph, the ENTIRE object graph will be duplicated.** In some cases, that's ok, but it can be expensive and produce results that are not expected. Only pass variables to the attributes that you know and are ok with being duplicated. Copying the data ensures that the values passed to threads are thread-safe, because the attribute values cannot be changed by any other thread. If you do not want duplicate data, do not pass it to the thread as an attribute but use a shared scope instead that the thread body can access. ```java // A fancy one thread name="#thisThreadName#" action="run" priority="#arguments.asyncPriority#" // custom variables passed as attributes interceptData="#arguments.interceptData#" threadName="#thisThreadName#" buffer="#arguments.buffer#" key="#key#" { // Retrieve interceptor to fire and local context var thisInterceptor = this.getInterceptors().get( attributes.key ); var event = variables.controller.getRequestService().getContext(); // Check if we can execute this Interceptor if( variables.isExecutable( thisInterceptor, event, attributes.key ) ){ // Invoke the execution point variables.invoker( interceptor = thisInterceptor, event = event, interceptData = attributes.interceptData, interceptorKey = attributes.key, buffer = attributes.buffer ); // Debug interceptions if( variables.log.canDebug() ){ variables.log.debug( "Interceptor '#getMetadata( thisInterceptor ).name#' fired in asyncAll chain: '#this.getState()#'" ); } } } // end thread ``` That's it for threading. Such a simple but powerful construct built right into the CFML language. Like mentioned before, if you need much more granular control or advanced ways to do [asynchronous programming](/beyond-the-100/asynchronous-programming), go to our section on running async code fluently. # Includes If you've used other scripting environments such as PHP, or dynamic HTML, you would be familiar with the concept of **server side includes**. An **include** is a file that is embedded, or **included** within another file making it part of the execution; simple as that. This can be very useful when you want multiple CFML templates to share the same block of code, scopes and visibility. In modern times, you can call this a **mixin**. A typical example might be your website's header and footer, or the reuse of included functions. The ColdBox MVC framework even allows you to define mixin helper templates that can be injected at runtime in Controller objects, views, layouts and much more. ## A Stern Warning Now, even though doing includes/mixins are easy to do in CFML, let me give you a **BIG WARNING**. Includes are one of the most abused features in ANY language, that bring confusion and sustainability issues. Easy doesn't mean sustainable or maintainable. Do not go crazy with includes, there are many other design patterns like dependency injection and composition/aggregation that can solve reusability in much better approaches. Think about it not twice, but thrice! > **Mixin** : In object-oriented programming languages, a mixin is a class that contains methods for use by other classes without having to be the parent class of those other classes; No inheritance needed. - ## Implementation CFML provides the `` tag and the `include` construct for including files in script - . ```javascript // script include "template.cfm" runonce=true; ``` The `template` argument is a relative, absolute or CFML mapping path to the template to inject. ```javascript include template="path/to/libraries/mixins.cfm"; ``` # Java Integration ,CFML is compiled to [Java bytecode](https://en.wikipedia.org/wiki/Java_bytecode) and runs on the JVM. This gives CFML a unique advantage that not only can you write CFML but you can also integrate with the running JDK libraries or any Java library you tell the engine to use. This is great, because if there is something already written in Java, just drop it in and use it, well most of the time :) Unless Jar loading hell occurs. {% hint style="info" %} CommandBox even allows you to install jar's from any endpoint into your projects: ```bash install "jar:https://github.com/coldbox-modules/cbox-bcrypt/blob/master/modules/bcrypt/models/lib/jbcrypt.jar?raw=true" ``` {% endhint %} {% embed url="" %} {% embed url="" %} ## Creating Java Objects The easiest way to integrate with Java is to be able to instantiate Java objects or call Java static methods on objects. You will do this via the `createObject()` or the `new` operator approach. Here is the signatures for both approaches: ```java createObject( "java", "java.class.path" ) new java( "class.path" ); // ACF2018 ONLY ``` Examples: ```java // Create a Java JDK Object var buffer = createObject( "java", "java.lang.StringBuilder" ); // Using a constructor currentFile = createObject( "java", "java.io.File" ).init( getCurrentTemplatePath() ); writeOutput( currentFile.lastModified() ); // Invoking a static method javaSystem = new java( "java.lang.System" ); currentTime = javaSystem.currentTimeMillis(); writeOutput( currentTime ); ``` ## Java Casting You must remember that Java is a static and typed language. CFML is not! If you need to pass in arguments to Java functions that require native types you will have to cast them. We will use the fancy `JavaCast()` function built-in to the language. ```java integerObject = createObject( "java", "java.lang.Integer" ); maxInt = integerObject.max( javaCast( "int", 5 ), javaCast( "int", 6 ) ); ``` The `javaCast()` method takes in two arguments: * `type` : The type of casting * `variable` : The value to cast The available casting types are: * `boolean` * `double` * `float` * `int` * `long` * `string` * `null` * `byte` * `bigdecimal` * `char` * `short` If you need to cast the type but as an array then you can use the `[]` in the casting construct. Let's create a stream from an incoming list of values and cast them to an array of objects in Java. ```java createObject( "java", "java.util.Arrays" ) .stream( javaCast( "java.lang.Object[]", listToArray( arguments.target, "" ) ) ); ``` ### Java Nulls Ohh the dreaded day [nulls](/cfml-language/null-and-nothingness) where created. The variable that means that nothing exists. If you need to pass null into Java object calls then you have two approaches to create them: ```java // Adobe + Lucee javaCast( "null", "" ); // Lucee only nullValue(); ``` ## Loading Custom Jars/Libraries The `createObject( "java" )` method will look into the CFML engine's class loader to discover the class you request. If the class is not located an exception is thrown that the class could not be found. If you want to integrate with third-party Jar's and libraries then you will need to tell the engine where to look for those classes. There are essentially three ways to add custom libraries to the CFML engine: 1. Add the jars/libs to the CFML Lib paths. These are those obscure directories both Adobe and Lucee give you so you can drop your libraries and the engine's class loader can well, load them. Each engine has different paths, please see their docs on the matter. We won't cover this approach as it is incredibly rigid: 1. 2. 2. The `Application.cfc` allows you to declare a `this.javaSettings` struct where you can declare an array of locations of the libraries to load upon application startup with some nice modifiers. This will allow you to store and even leverage CommandBox for the management of such jars. 3. In Lucee, the `createObject( "java" )` construct allows you to pass in a third argument which can be a location or an array of locations of libraries to class load. This is also great for custom CFCs, task runners, or isolated class loading. ### this.javaSettings This `Application.cfc` structure takes in 3 keys that will allow you to class load any jar/.class libraries into the running ColdFusion application:
KeyDescription
KeyDescription
loadPathsAn array of paths to the directories that contain Java classes or JAR files.You can also provide the path to a JAR or a class. If the paths are not resolved, an error occurs.
loadColdFusionClassPathIndicates whether to load the classes from the ColdFusion lib directory. The default value is false.
reloadOnChangeIndicates whether to reload the updated classes and JARs dynamically, without restarting ColdFusion. The default value is false.
watchIntervalSpecifies the time interval in seconds after which to verify any change in the class files or JAR files. This attribute is applicable only if the reloadOnChange attribute is set to true. The default value is 60 seconds.
watchExtensionsSpecifies the extensions of the files to monitor for changes. By default, only .class and .jar files are monitored.
{% code title="Application.cfc" %} ```java component{ this.javaSettings = { loadPaths = [ "./lib", "./config/java/myjar.jar" ], reloadOnChange = false } } ``` {% endcode %} Once that is declared in your Application.cfc and you execute a `createobject()` with a class from those libraries, ColdFusion will know about them and create them. ### createObject() Lucee Class Loading The other approach is to leverage the `createObject()` call to do class loading. Please note that only Lucee supports this feature as of now. ```java // Reference createObject( "java", "path", array or jar location ) // Example variables.LIB_PATH = expandPath( "/mylib/apache.jar" ); createObject( "java", "org.apache.pdfbox.pdmodel.PDDocument", variables.LIB_PATH ); ``` ## Dynamic Proxies Both ColdFusion engines also allows you to create dynamic proxies from existing ColdFusion Components (CFCs). What this means is that a Dynamic proxy lets you pass ColdFusion components to Java objects. Java objects can work with the ColdFusion components seamlessly as if they are native Java objects by implementing the appropriate Java interfaces. You can even use them to simulate Java lambdas as ColdFusion components. ```java createDynamicProxy( cfc, interfaces ) ``` If you want to leverage a Java library that requires a certain type of Java object as an argument and instead of you creating that object in Java, you can see if that argument adheres to a certain interface and CFML will create a dynamic proxy that binds it. ```java createDynamicProxy( new proxies.Consumer( arguments.consumer ), // create a Consumer CFC [ "java.util.function.Consumer" ] // match it to this interface ) // Here is the Consumer CFC /** * Functional Interface that maps to java.util.function.Consumer * See https://docs.oracle.com/javase/8/docs/api/java/util/function/Consumer.html */ component extends="BaseProxy"{ /** * Constructor * * @f The lambda or closure to be used in the accept() method */ function init( required f ){ super.init( arguments.f ); return this; } /** * Performs this operation on the given argument. */ void function accept( t ){ loadContext(); variables.target( t ); } function andThen( after ){} } ``` Basically, your CFC must implement the appropriate methods the interface(s) tell you that it needs. After that, your CFC will be Javafyied, and it can be used like a native Java interface implementing objects! Enjoy! # Beyond The 100 We cannot possibly cover all the features of the ColdFusion Engines in this book as our focus was more on the core CFML language. However, please note that the engines offer a tremendous middle-ware capabilities that extend beyond normal language features. There are many areas that make ColdFusion one of the most (if not the most) **rapid application development (RAD)** languages around. {% hint style="success" %} Check out the [cfdocs](https://cfdocs.org/) and the engine documentation sites for all the different capabilities they can offer. {% endhint %} In our **Beyond The 100** section you will find more in-depth topics of how CFML can be used for web applications, database interactions, Java integration, RESTFul services*,* Image manipulation and much more. Here is a simple listing of going beyond with CFML: * PDF Creation * PDF Manipulation * Database Introspection * Object Relational Manager via Hibernate/JPA * Stored Procedures Support * Multiple JDBC Connectors * Job Scheduling * Server Monitoring * API Monitoring, Caching, Gateway * Exchange Support * LDAP Support * Spreadsheet Support * Open Office Support * Mathematical Functions * OSGI Bundle Support * Distributed Caching Support * Much More! {% embed url="" %} {% embed url="" %} # Application.cfc ## Introduction If you are running ColdFusion in a [web server like CommandBox](https://commandbox.ortusbooks.com/embedded-server) and a ColdFusion page (.cfm/.cfc) is requested, the engine will look for a special file called `Application.cfc` and if found, it will execute it for you **implicitly**. This file is used to define the following: 1. Application-wide settings, default variables, session/client storages, file mappings, datasources, style settings, ORM settings and so much more. These are created by placing them in the `this` scope and in the pseudo-constructor of the object. 2. Application **life-cycle** event handlers which the engine will execute for you **implicitly** by you just creating the appropriate available methods. {% hint style="info" %} Usually you will place this file in your **webroot**. Any page in the same directory or sub-directories that is requested will execute this file implicitly. {% endhint %} ### Transient File This file is created on every request, so make sure that it is optimized accordingly. The `application` scope can be leveraged for global persistence. Also note, that because it is instantiated on every request, you have the potential to change settings and events on a per-request basis if needed. Great use cases for this can be the following: * Switching datasources * Lowering session/client timeouts for scopes if a bot is requesting a page * Increased security * Stopping requests * Much More... {% hint style="warning" %} Please note that this file is execute for every request, so make sure it is optimized accordingly. The engine will also traverse your directories upwards until it finds this file. {% endhint %} ### Sample Template {% code title="Application.cfc" %} ```javascript component{ this.name = "My Awesome App"; this.applicationTimeout = createTimeSpan( 30, 0, 0, 0 ); //30 days this.sessionStorage = true; this.sessionTimeout = createTimeSpan( 0, 0, 60, 0 ); // 1 hour function onApplicationStart(){} function onApplicationEnd( struct applicationScope ) {} function onSessionStart() {} function onSessionEnd( struct sessionScope, struct applicationScope ) {} function onRequestStart( string targetPage ) {} function onRequest( string targetPage ) { include arguments.targetPage; } function onRequestEnd() {} function onCFCRequest( cfcname, method, struct args) { return; } function onError( any Exception, string EventName ) {} function onAbort( required string targetPage ) {} function onMissingTemplate( required string targetPage ) {} } ``` {% endcode %} {% hint style="info" %} You can find all the settings and event handlers defined for `Application.cfc` in cfdocs: . {% endhint %} ## Life-Cycle Events The `Application.cfc` also acts like a big event listener waiting for the ColdFusion server engine to call its methods in callback fashion. You can listen to when an error occurs to even when a missing template is requested and much more. If I am missing some here, please refer to the latest documentation for the latest updates: * **onApplicationStart**: The very first time your application is requested, the `onApplicationStart` event is broadcast. It only happens once, until your application times out, the process is restarted, or the computer is restarted. * **onSessionStart**: Whenever a NEW user requests any resource in your web application ColdFusion will assign them a unique session identifier and call this method for you. * **onRequestStart**: Executes before every requested resource and receives the targeted page in the arguments. You can decide to process the page or not by returning a boolean variable. * **onRequest**: This callback allows you to actually include the requested page or not. Consider the `onRequestStart()` as a before advice and the `onRequest` as an around advice over the request. You must `include` the requested page or the page will never be processed * **onRequestEnd**: Also receives the targetPage and executes after onRequestStart() and onRequest() have fired. * **onSessionEnd**: Once a unique session has expired this method will be called for you by the engine with the session and application scope structure as arguments. * **onApplicationEnd**: Once the application times out or is flushed you can listen to it. It also accepts the entire application scope as an incoming argument. * **onError**: Like a big try/catch statement across the application. This will fire whenever an untrapped exception is caught. You will receive the exception struct and the `eventName` that generated the exception. * **onAbort:** Runs when you execute the abort tag somewhere and you want to know where that pesky abort exists. It receives the `targetPage` that the abort came from. * **onCFCRequest**: Intercepts any HTTP or AMF calls to an application based on CFC request. * **onMissingTemplate**: Executed whenever a template is requested and it does not exist in the server. {% hint style="info" %} The [ColdBox HMVC Framework](https://www.coldbox.org) builds heavily on top of these life-cycle methods to provide you with a rich event-driven architecture for web applications. You can create an application with CommandBox just by running: `coldbox create app MyApp` {% endhint %} ## ColdFusion Web Applications ColdFusion differs from other Java web languages in the sense that there is one Java context application deployed (The CFML Engine) with many servlet definitions, but you can create many ColdFusion applications within the running context. All you need is to demarcate them with the `Application.cfc`, with a unique name which defines the separate ColdFusion applications. **Anything in that directory and sub-directories will be considered part of the application.** Your ColdFusion application is nothing more than a memory space reservation using the `this.name` property as the unique name for it. It can contain the variables scopes like `application`, `session`, and `client` which are unique per this reservation name. This way two ColdFusion applications can have different persistence variable scopes and can even be embedded between each other: ``` + webroot + admin/ + Application.cfc // Embedded admin app + Application.cfc // Root public app ``` ### Application Longevity This is why you can't really kill the `application` scopes. The application is reserved for a specific duration which is defined using the `this.applicationTimeout` property or defined in the Administrator. Once it expires, the engine will purge it from memory and recreate it fresh. {% hint style="success" %} **Tip** You can force the stopping of the Application scope by leveraging the method `applicationStop()`. Be careful though, as it stops full execution and restarts it. () {% endhint %} # File Handling CFML allows you to manipulate, read, upload, etc files via its built in methods which are great and easy to use. It can even help you manipulate zip/jar archives! We won't go into every single detail of file handling, but below you can find the majority of functions to deal with file handling. {% hint style="success" %} You can find the file system functions here: . {% endhint %} * [DirectoryCopy](https://docs.lucee.org/reference/functions/directorycopy.html) Copies the contents of a directory to a destination directory. * [DirectoryCreate](https://docs.lucee.org/reference/functions/directorycreate.html) Creates new directory for specified path * [DirectoryDelete](https://docs.lucee.org/reference/functions/directorydelete.html) Deltes directory for given path * [DirectoryExists](https://docs.lucee.org/reference/functions/directoryexists.html) Determines whether a directory exists. * [DirectoryList](https://docs.lucee.org/reference/functions/directorylist.html) Lists the directory and returns the list of files under it as array or query * [DirectoryRename](https://docs.lucee.org/reference/functions/directoryrename.html) Renames given directory * [ExpandPath](https://docs.lucee.org/reference/functions/expandpath.html) Creates an absolute, platform-appropriate path that is equivalent to the value of relative\_path, appended to the base path. This function (despite its name) can accept an absolute or relative path in the relative\_path attribute * [FileAppend](https://docs.lucee.org/reference/functions/fileappend.html) appends the entire content to the specified file. * [FileClose](https://docs.lucee.org/reference/functions/fileclose.html) Closes an file that is open. * [FileCopy](https://docs.lucee.org/reference/functions/filecopy.html) Copies the specified on-disk or in-memory source file to the specified destination file. * [FileDelete](https://docs.lucee.org/reference/functions/filedelete.html) Deletes the specified file on the server. * [FileExists](https://docs.lucee.org/reference/functions/fileexists.html) Determines whether a file exists * [FileGetMimeType](https://docs.lucee.org/reference/functions/filegetmimetype.html) Returns the mimetype of the given file * [FileInfo](https://docs.lucee.org/reference/functions/fileinfo.html) returns detailed info about the given file. * [FileIsEOF](https://docs.lucee.org/reference/functions/fileiseof.html) Determines whether Lucee has reached the end of the file while reading it. * [FileMove](https://docs.lucee.org/reference/functions/filemove.html) Moves file from source to destination * [FileOpen](https://docs.lucee.org/reference/functions/fileopen.html) Opens an file to read, write, or append. * [FileRead](https://docs.lucee.org/reference/functions/fileread.html) Reads an on-disk or in-memory text file or a file object created with the FileOpen function. * [FileReadLine](https://docs.lucee.org/reference/functions/filereadline.html) Reads a line from an file. * [FileSeek](https://docs.lucee.org/reference/functions/fileseek.html) Shifts the file pointer to the given position. The file must be opened with seekable option * [FileSetAccessMode](https://docs.lucee.org/reference/functions/filesetaccessmode.html) Sets the attributes of an on-disk file on UNIX or Linux. This function does not work with in-memory files. * [FileSetAttribute](https://docs.lucee.org/reference/functions/filesetattribute.html) For the given path, sets the file attributes. * [FileSetLastModified](https://docs.lucee.org/reference/functions/filesetlastmodified.html) For the given file, set the last modification date * [FileSkipBytes](https://docs.lucee.org/reference/functions/fileskipbytes.html) Shifts the file pointer by the given number of bytes. * [FileTouch](https://docs.lucee.org/reference/functions/filetouch.html) Touches given file, creates the file if not already exists. * [FileUpload](https://docs.lucee.org/reference/functions/fileupload.html) Uploads file to a directory on the server. * [FileUploadAll](https://docs.lucee.org/reference/functions/fileuploadall.html) Uploads file to a directory on the server. * [FileWrite](https://docs.lucee.org/reference/functions/filewrite.html) If you specify a file path, writes the entire content to the specified file. If you specify a file object, writes text or binary data to the file object. * [FileWriteLine](https://docs.lucee.org/reference/functions/filewriteline.html) Opens up the file (or uses the existing file object) and appends the given line of text * [GetFileInfo](https://docs.lucee.org/reference/functions/getfileinfo.html) Retrieves information about file. * [GetFreeSpace](https://docs.lucee.org/reference/functions/getfreespace.html) Returns the number of unallocated bytes in the partition named by this abstract path name. * [GetTempDirectory](https://docs.lucee.org/reference/functions/gettempdirectory.html) Returns the full path to the currently assigned temporary directory * [GetTempFile](https://docs.lucee.org/reference/functions/gettempfile.html) Creates a temporary file in a directory whose name starts with (at most) the first three characters of prefix. * [ImageWrite](https://docs.lucee.org/reference/functions/imagewrite.html) Writes a image to the specified filename or destination. ```java // A few examples content = fileRead( expandPath( "/config/myfile.txt" ) ); if( fileExists( "filepath.txt" ) ){ } fileDelete( "filepath.txt" ) fileWrite( getTempFile( getTempDirectory(), "tempFile"), "My Data" ); directoryList( "/my/path" ) directoryExists( "/my/path" )
if( structKeyExists( form, "fileInput" )) { try { uploadedFile = fileUpload( getTempDirectory(), "fileInput", "image/jpeg,image/pjpeg", "MakeUnique" ); // check the file extension of the uploaded file; mime types can be spoofed if (not listFindNoCase("jpg,jpeg", cffile.serverFileExt)) { throw("The uploaded file is not of type JPG."); } // do stuff with uploadedFile... } catch ( coldfusion.tagext.io.FileUtils$InvalidUploadTypeException e ) { writeOutput( "This upload form only accepts JPEG files." ); } catch (any e) { writeOutput( "An error occurred while uploading your file: #e.message#" ); } } ``` ## Dealing With Large Files If you want to read or manipulate large files we would recommend that you leverage our [cbStreams](https://forgebox.io/view/cbstreams) library or native Java file streaming. Below you can find some sample usage of reading large files with [cbStreams](https://forgebox.io/view/cbstreams) which implements the Java Streams API. ```java stream = streamBuilder.new().ofFile( absolutePath ); try{ //work on the stream of lines of files and close it in the finally block } finally{ stream.close(); } //You can even process file lines concurrently stream = streamBuilder.new() .parallel() .ofFile( absolutePath ); ``` # Image Manipulation Both CFML engines (Lucee & Adobe) have a very extensive and awesome image manipulation library that will allow you to create and manipulate images in an easy syntax. We cannot see every single detail about image manipulation, but it is necessary to understand that this functionality is easy in CFML and it exists. Apart from having core image functions all functions can be applied as member functions to an image object. Yes, CFML allows you to deal with image objects natively. ```java imgObj = imageRead("http://cfdocs.org/apple-touch-icon.png"); imgObj.resize(50,50); cfimage(action="writeToBrowser", source=imgObj); imgObj = imageRead("http://cfdocs.org/apple-touch-icon.png"); imgObj.blur(5); cfimage(action="writeToBrowser", source=imgObj); imgObj = imageRead("http://cfdocs.org/apple-touch-icon.png"); imgObj.rotate(90); cfimage(action="writeToBrowser", source=imgObj); imgObj = imageRead("http://cfdocs.org/apple-touch-icon.png"); info = imgObj.info(); writeDump(info); ``` You can find some great samples here: and a listing of all manipulation functions here: * [GetReadableImageFormats](https://docs.lucee.org/reference/functions/getreadableimageformats.html) Returns a list of image formats that Lucee can read on the operating system where Lucee is deployed. * [GetWriteableImageFormats](https://docs.lucee.org/reference/functions/getwriteableimageformats.html) Returns a list of image formats that Lucee can write on the operating system where Lucee is deployed. * [ImageAddBorder](https://docs.lucee.org/reference/functions/imageaddborder.html) Adds a rectangular border around the outside edge of a image. * [ImageBlur](https://docs.lucee.org/reference/functions/imageblur.html) Smooths image. * [ImageCaptcha](https://docs.lucee.org/reference/functions/imagecaptcha.html) Creates a captcha image * [ImageClearRect](https://docs.lucee.org/reference/functions/imageclearrect.html) Clears the specified rectangle by filling it with the background color of the current drawing surface. * [ImageCopy](https://docs.lucee.org/reference/functions/imagecopy.html) Copies a rectangular area of an image. * [ImageCrop](https://docs.lucee.org/reference/functions/imagecrop.html) Crops a image to a specified rectangular area. * [ImageDrawArc](https://docs.lucee.org/reference/functions/imagedrawarc.html) Draws a circular or elliptical arc. * [ImageDrawBeveledRect](https://docs.lucee.org/reference/functions/imagedrawbeveledrect.html) Draws a rectangle with beveled edges. * [ImageDrawCubicCurve](https://docs.lucee.org/reference/functions/imagedrawcubiccurve.html) Draws a cubic curve. * [ImageDrawImage](https://docs.lucee.org/reference/functions/imagedrawimage.html) this function is deprecated, use ImagePaste instead. Draws a image on a image with the baseline of the first character positioned at (x,y) in the image. * [ImageDrawLine](https://docs.lucee.org/reference/functions/imagedrawline.html) Draws a single line defined by two sets of x and y coordinates on a image. * [ImageDrawLines](https://docs.lucee.org/reference/functions/imagedrawlines.html) Draws a sequence of connected lines defined by arrays of x and y coordinates. * [ImageDrawOval](https://docs.lucee.org/reference/functions/imagedrawoval.html) Draws an oval. * [ImageDrawPoint](https://docs.lucee.org/reference/functions/imagedrawpoint.html) Draws a point at the specified (x,y) coordinate. * [ImageDrawQuadraticCurve](https://docs.lucee.org/reference/functions/imagedrawquadraticcurve.html) Draws a curved line. The curve is controlled by a single point. * [ImageDrawRect](https://docs.lucee.org/reference/functions/imagedrawrect.html) Draws a rectangle. * [ImageDrawRoundRect](https://docs.lucee.org/reference/functions/imagedrawroundrect.html) Draws a rectangle with rounded corners. * [ImageDrawText](https://docs.lucee.org/reference/functions/imagedrawtext.html) Draws a text string on a image with the baseline of the first character positioned at (x,y) in the image. * [ImageFilter](https://docs.lucee.org/reference/functions/imagefilter.html) the function ImageFilter allows to execute a filter against a image. * [ImageFilterColorMap](https://docs.lucee.org/reference/functions/imagefiltercolormap.html) These are passed to the function ImageFilters (see ImageFilter documentation) which convert gray values to colors. * [ImageFilterCurves](https://docs.lucee.org/reference/functions/imagefiltercurves.html) the curves for the wrap grid * [ImageFilterKernel](https://docs.lucee.org/reference/functions/imagefilterkernel.html) These are passed to the function ImageFilters * [ImageFilterWarpGrid](https://docs.lucee.org/reference/functions/imagefilterwarpgrid.html) A warp grid. These are passed to the function ImageFilters (see ImageFilter documentation). * [ImageFlip](https://docs.lucee.org/reference/functions/imageflip.html) Flips an image across an axis. * [ImageFonts](https://docs.lucee.org/reference/functions/imagefonts.html) return all available * [ImageFormats](https://docs.lucee.org/reference/functions/imageformats.html) return all available readers and writers * [ImageGetBlob](https://docs.lucee.org/reference/functions/imagegetblob.html) Retrieves the bytes of the underlying image. The bytes are in the same image format as the source image. * [ImageGetBufferedImage](https://docs.lucee.org/reference/functions/imagegetbufferedimage.html) Returns the java.awt.BufferedImage object underlying the current image. * [ImageGetEXIFMetadata](https://docs.lucee.org/reference/functions/imagegetexifmetadata.html) Retrieves the Exchangeable Image File Format (EXIF) headers in an image as a CFML structure. * [ImageGetEXIFTag](https://docs.lucee.org/reference/functions/imagegetexiftag.html) Retrieves the specified EXIF tag in an image. * [ImageGetHeight](https://docs.lucee.org/reference/functions/imagegetheight.html) Retrieves the height of the image in pixels. * [ImageGetIptcMetadata](https://docs.lucee.org/reference/functions/imagegetiptcmetadata.html) Retrieves the International Press Telecommunications Council (IPTC )headers in a image as a struct. The IPTC metadata contains text that describes the image that is stored with it. IPTC metadata includes, but is not limited to, caption, keywords, credit, copyright, object name, created date, byline, headline, and source * [ImageGetIPTCTag](https://docs.lucee.org/reference/functions/imagegetiptctag.html) Retrieves the value of the IPTC tag for a image. * [ImageGetWidth](https://docs.lucee.org/reference/functions/imagegetwidth.html) Retrieves the width of the specified image. * [ImageGrayscale](https://docs.lucee.org/reference/functions/imagegrayscale.html) Converts a image to grayscale. * [ImageInfo](https://docs.lucee.org/reference/functions/imageinfo.html) Returns a structure that contains information about the image, such as height, width, color model, size, and filename. * [ImageNegative](https://docs.lucee.org/reference/functions/imagenegative.html) Inverts the pixel values of a image. * [ImageNew](https://docs.lucee.org/reference/functions/imagenew.html) Creates a image. * [ImageOverlay](https://docs.lucee.org/reference/functions/imageoverlay.html) Reads two source images and overlays the second source image on the first source image. * [ImagePaste](https://docs.lucee.org/reference/functions/imagepaste.html) Takes two images and an (x,y) coordinate and draws the second image over the first image with the upper-left corner at coordinate (x,y). * [ImageRead](https://docs.lucee.org/reference/functions/imageread.html) Reads the source pathname or URL and creates a image. * [ImageReadBase64](https://docs.lucee.org/reference/functions/imagereadbase64.html) Creates a image from a Base64 string. * [ImageResize](https://docs.lucee.org/reference/functions/imageresize.html) Resizes a image. * [ImageRotate](https://docs.lucee.org/reference/functions/imagerotate.html) Rotates a image at a specified point by a specified angle. * [ImageRotateDrawingAxis](https://docs.lucee.org/reference/functions/imagerotatedrawingaxis.html) Rotates all subsequent drawing on a image at a specified point by a specified angle. * [ImageScaleToFit](https://docs.lucee.org/reference/functions/imagescaletofit.html) Creates a resized image with the aspect ratio maintained. * [ImageSetAntialiasing](https://docs.lucee.org/reference/functions/imagesetantialiasing.html) Switches antialiasing on or off in rendered graphics. * [ImageSetBackgroundColor](https://docs.lucee.org/reference/functions/imagesetbackgroundcolor.html) Sets the background color for the image. The background color is used for clearing a region. Setting the background color only affects the subsequent ImageClearRect calls * [ImageSetDrawingAlpha](https://docs.lucee.org/reference/functions/imagesetdrawingalpha.html) Sets the current drawing alpha for images. All subsequent graphics operations use the specified alpha. * [ImageSetDrawingColor](https://docs.lucee.org/reference/functions/imagesetdrawingcolor.html) Sets the current drawing color for images. All subsequent graphics operations use the specified color. * [ImageSetDrawingStroke](https://docs.lucee.org/reference/functions/imagesetdrawingstroke.html) Sets the drawing stroke for points and lines in subsequent images. * [ImageSetDrawingTransparency](https://docs.lucee.org/reference/functions/imagesetdrawingtransparency.html) Specifies the degree of transparency of drawing functions. * [ImageSharpen](https://docs.lucee.org/reference/functions/imagesharpen.html) Sharpens a image by using the unsharp mask filter. * [ImageShear](https://docs.lucee.org/reference/functions/imageshear.html) Shears an image either horizontally or vertically. * [ImageShearDrawingAxis](https://docs.lucee.org/reference/functions/imagesheardrawingaxis.html) Shears the drawing canvas. * [ImageTranslate](https://docs.lucee.org/reference/functions/imagetranslate.html) Copies an image to a new location on the plane. * [ImageTranslateDrawingAxis](https://docs.lucee.org/reference/functions/imagetranslatedrawingaxis.html) Translates the origin of the image context to the point (x,y) in the current coordinate system. * [ImageWrite](https://docs.lucee.org/reference/functions/imagewrite.html) Writes a image to the specified filename or destination. * [ImageWriteBase64](https://docs.lucee.org/reference/functions/imagewritebase64.html) Writes Base64 images to the specified filename and destination. * [ImageWriteToBrowser](https://docs.lucee.org/reference/functions/imagewritetobrowser.html) Writes image to browser. * [ImageXORDrawingMode](https://docs.lucee.org/reference/functions/imagexordrawingmode.html) Sets the paint mode of the image to alternate between the image's current color and the new specified color. * [IsImage](https://docs.lucee.org/reference/functions/isimage.html) Determines whether a variable returns a image. * [IsImageFile](https://docs.lucee.org/reference/functions/isimagefile.html) Verifies whether an image file is valid. # HTTP/S Calls CFML makes it really **easy** to interact with **any** HTTP/S endpoint via the `cfhttp` tag/construct (). The `cfhttp` call will generate an HTTP/S request and parse the response into a nice CFML structure. ```java cfhttp( url="https://www.google.com/", result="result" ){ cfhttpparam( name="q", type="formfield", value="cfml" ) } writeDump( result ) ``` {% hint style="info" %} You can use ANY http method in the `cfhttp` calls, the default is a `GET` operation. {% endhint %} As you can see from the example above, you can pass parameters to the HTTP request by using the child `cfhttpparam` construct. This parameter can be of many different types: `header, body, xml, cgi, file, url, formfield, cookie` depending on the requirements of the http endpoint. ## The Result Structure The result structure will contain the following keys: | Key | Description | | :--------------: | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `statusCode` | The HTTP response code and reason string. | | `fileContent` | The body of the HTTP response. Usually a string, but could also be a Byte Array. | | `responseHeader` | A structure of response headers, the keys are header names and the values are either the header value or an array of values if multiple headers with the same name exist. | | `errorDetail` | An error message if applicable. | | `mimeType` | The mime type returned in the Content-Type response header. | | `text` | A boolean indicateing if the response body is text or binary | | `charset` | The character set returned in the Content-Type header. | | `header` | All the http response headers as a single string. | ## CFHTTP Arguments This construct accepts many arguments with different features you can use when executing http/s calls, below we list just the most common ones, you can find them all here: | Argument | Type | Default | Description | | ------------- | ------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `url` | URL | | The http/s endpoint to hit | | `port` | numeric | 80/443 | The port of the endpoint to hit. 80 for http and 443 for https | | `method` | string | GET | The http method to use. | | `username` | string | | An optional server username | | `password` | string | | An optional server password | | `useragent` | string | ColdFusion | The user agent to simulate for the request | | `charset` | string | utf-8 | The encoding to use | | `resolveUrl` | boolean | false | No does not resolve URLs in the response body. As a result, any relative URL links in the response body do not work. Yes resolves URLs in the response body to absolute URLs, including the port number, so that links in a retrieved page remain functional. | | `redirect` | boolean | true | If the response header includes a [Location](https://cfdocs.org/location) field, determines whether to redirect execution to the URL specified in the field. | | `timeout` | numeric | unlimited | A value in seconds of the max time to take for the request. | | `getAsBinary` | string | auto | If **yes**, convert to CFML binary type, **No** keep as text, **auto** let CFML detect and convert as necessary | | `result` | string | cfhttp | The name of the variable you want the result structured returned into | | `multipart` | boolean | false | Tells ColdFusion to send all data specified by [cfhttpparam](https://cfdocs.org/cfhttpparam) type="formField" tags as multipart form data, with a Content-Type of multipart/form-data. | Basically, you can do any type of http/s calls and consume any type of RESTFul webservices with a nice CFML syntax! ## CFHTTPParam As mentioned before in our example we can use the `cfhttpparam` construct to pass parameters to the http/s endpoint. The parameters can be of different types as we can see in the following table. ```java cfhttpParam( type="", name="", value="", file="", encoded="", mimetype="" ); ``` ### Param Types | Type | Description | | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------- | | `header` | Specifies an HTTP header. Does not URL encode the value | | `body` | Specifies that the `value` is the body of the HTTP request. | | `xml` | Identifies the request as having a content-type of `text/xml` and specifies that the `value` attribute contains the body of the HTTP request. | | `cgi` | Same as `header` but URL encodes the `value` by default. | | `file` | Tells CFML to send the contents of the specified file. | | `url` | Specifies a URL query string name-value pair to append to the [cfhttp](https://cfdocs.org/cfhttp) url attribute. URL encodes the value. | | `formfield` | Specifies a form field to send. URL encodes the value by default. | | `cookie` | Specifies a cookie to send as an HTTP header. URL encodes the value. | ### Param Arguments The available param arguments to the cfhttpparam construct are: | Argument | Type | Default | Description | | ---------- | ------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `type` | string | | The type of data from the available types above | | `name` | string | | The variable name for the data | | `value` | string | | The value of the variable | | `file` | path | | Applies to `file` type; ignored for all other types. The absolute path to the file that is sent with the request. | | `encoded` | boolean | false | Applies to `formfield` and `cgi` types; ignored for all other types. Specifies whether to [URLEncode](https://cfdocs.org/urlencode) the form field or header. | | `mimetype` | string | | Applies to `file` type; invalid for all other types. Specifies the MIME media type of the file contents. The content type can include an identifier for the character encoding of the file; for example, text/html; charset=ISO-8859-1 indicates that the file is HTML text in the ISO Latin-1 character encoding. | Here is another example for you: ```java cfhttp( url="https://myrestapp.com/user", result="local.result", method="post" ){ cfhttpparam( name="x-api-token", type="header", value="123" ) cfhttpparam( type="body", value=serializeJson( '{ name : "luis", age : 2 }' ) ) } writeDump( result ) ``` ## Hyper : HTTP Builder Leveraging `cfhttp` is very very easy to use. However, it can be cumbersome and not necessarily fluent or object oriented. For this, we have provided a module called [Hyper](https://forgebox.io/view/hyper) which can help you build fluent and amazing HTTP Builders () Hyper was built after coding several API SDK's for various platforms — [S3SDK](https://github.com/coldbox-modules/s3sdk), [cbstripe](https://github.com/coldbox-modules/cbox-stripe), and [cbgithub](https://github.com/elpete/cbgithub), to name a few. I noticed that I spent a lot of time setting up the plumbing for the requests and a wrapper around `cfhttp`. Each implementation was mostly the same but slightly different. It was additionally frustrating because I really only needed to tweak a few values, usually just the `Authorization` header. It would be nice to create an HTTP client pre-configured for each of these SDK's. It seemed the perfect fit for a module. ### The problem it solves Hyper exists to provide a fluent builder experience for HTTP requests and responses. It also provides a powerful way to create clients, Bulider objects with pre-configured defaults like a base URL or certain headers. ### HyperBuilder The component you will most likely inject is the `HyperBuilder`. This is commonly aliased as `hyper`. ```java component { property name="hyper" inject="HyperBuilder@Hyper"; } ``` The `HyperBuilder` creates new requests. This can be done in one of two ways: 1. Calling the `new` method will create a new request with the configured defaults. 2. Calling any method on `HyperRequest` on the `HyperBuilder` instance will create a new request and forward on the method call. Using the `HyperBuilder` lets you easily create requests with defaults while also avoiding having to deal with providers directly. ### HyperRequest Though the `HyperBuilder` is the component you will most likely inject, `HyperRequest` is the component will you interact with the most. `HyperRequest` provides a fluent interface to configure your HTTP call. **Example:** ```java hyper.get( "https//api.github.com/users" ); hyper.setMethod( "PUT" ) .withHeaders( { "Authorization" = "Bearer #token#" } ) .setUrl( "https://jsonplaceholder.typicode.com/posts/1" ) .setBody( { title: "New Title" } ) .send(); ``` ### Request Defaults Hyper allows you to configure defaults for your requests. This is particularly useful for reducing boilerplate in your application. Defaults are set on the `HyperBuilder` instance. The easiest way to do this is to configure it in WireBox: ```java // config/WireBox.cfc component { function configure() { map( "StarWarsClient" ) .to( "hyper.models.HyperBuilder" ) .asSingleton() .initWith( baseUrl = "https://swapi.co/api" ); } } ``` Now, you can inject this pre-configured builder wherever you need in your application: ```java component { property name="StarWarsClient" inject="id"; function findUser( id ) { return StarWarsClient.get( "/people/#id#" ); } } ``` You can even create multiple clients using this approach: ```java // config/WireBox.cfc component { function configure() { map( "SWAPIClient" ) .to( "hyper.models.HyperBuilder" ) .asSingleton() .initWith( baseUrl = "https://swapi.co/api" ); map( "GitHubClient" ) .to( "hyper.models.HyperBuilder" ) .asSingleton() .initWith( baseUrl = "https://api.github.com", headers = { "Authorization" = getSetting( "SWAPI_TOKEN" ) } ); } } ``` You can also set or change the defaults by either passing the key / value pairs in to the `init` method or by calling the appropriate `HyperRequest` method on the `HyperBuilder.defaults` property. ```java var hyper = new Hyper.models.HyperBuilder( baseUrl = "https://api.github.com" ); hyper.defaults.withHeaders( { "Authorization" = token } ); ``` # Sending Emails CFML gives you the `cfmail` tag/construct to easily send email in text or HTML format without any ceremony. Just register your mail servers in the administrators or the `Application.cfc` and you are ready to start sending emails in a jiffy! ```java cfmail( subject="Your Order", from="myshop@ortus.com", to="whatever@gmail.com,another@gmail.com", bcc="orders@ortus.com" type="HTML" ){ // body of the email. writeOutput( 'Hi there,' ); writeOutput( 'This mail is sent to confirm that we have received your order.' ); }; ``` The `cfmail` tag/construct has tons of attributes, so check them out in the docs ### Query Binding You can even bind the mail construct with a query, and the engine will send as many emails as rows in the query for you: ```java var qData = userService.getNewUsers(); cfmail( subject="Welcome to FORGEBOX!", from="myshop@ortus.com", to="#qData.email#", query=qData ){ writeOutput( " Dear #qData.name#, Welcome to your FORGEBOX account! Play and just do it! ") }; ``` ### Sending Attachments You can also send attachments to your email destinations very easily using the `mimeattach` attribute or via the child `cfmailparam()` construct, which allows you to send multiple attachments, or headers. ```java cfmail( subject="Your Order", from="myshop@ortus.com", to="whatever@gmail.com,another@gmail.com", bcc="orders@ortus.com" mimeattach=expandPath( "/my/path/attach.pdf" ); ){ // body of the email. writeOutput( 'Hi there,' ); writeOutput( 'This mail is sent to confirm that we have received your order.' ); }; cfmail( subject="Attachments", to="you@domain.com", from="me@domain.com" ) { cfmailparam( name="Reply-To", value="me@domain.com" ); cfmailparam( file="c:\files\readme.txt" ); cfmailparam( file="c:\files\logo.gif" ); } ``` {% hint style="success" %} More in-depth information can be found here: {% endhint %} # Asynchronous Programming We already covered basic threading in our core CFML section. In this section we will cover the usage of asynchronous programming via futures and the `runAsync()` function built-in to Adobe ColdFusion 2018+ and Lucee 5.3+. > A Future is an eventual result of an asynchronous operation. {% embed url="" %} Java Future JDK (Useful Reference) {% endembed %} {% embed url="" %} Adobe Guide on RunAsync() {% endembed %} ## runAsync() This function returns a **Future** object, which is an eventual result of an asynchronous operation. Basically a representation of what the operation will produce, well, in the future. It takes in two arguments and returns a CFML Future object. * `callback:function` - Closure/Lambda function that returns a result to be resolved * `timeout:numeric` - Timeout for the asynchronous process in milliseconds ```java future = runAsync( function(){ return "Hello World!"; } ); writeOutput( future.get() ); future = runAsync(function(){ return 5; } ).then( function( input ){ return input + 2; } ); result = future.get( 3 ); // 3 is timeout(in ms) writeOutput(result); ``` ## The Future Object The return of the `runAsync()` function is a CFML Future, not a Java Future. The Future Object has the following functions available: | Function | ReturnType | Description | | ---------------------------- | ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `cancel()` | Boolean | Cancel the operation | | `complete( value )` | value | Sets a value to return from the future, usually from an empty future operation. | | `error( callback, timeout )` | Future | Register an error callback that will be called if the async operation fails or the timeout is reached | | `error( callback )` | Future | Register an error callback that will be called if the async operation fails | | `get()` | Any | The value of the async operation once it finalizes. **Caution: This operation blocks until the async operation finalizes.** | | `get( timeout )` | Any | The value of the async operation with a timeout in milliseconds. **Caution: This operation blocks until the async operation finalizes.** | | `isCancelled()` | Boolean | Verifies if the operation has been cancelled or not | | `isDone()` | Boolean | Verifies if the operation has finalized or not | | `then( callback )` | Future | Once the first callback operation has finalized, call this secondary callback with the value of the previous operation and return another Future | | `then( callback, timeout )` | Future | Once the first callback operation has finalized, call this secondary callback with the value of the previous operation and return another Future but with a timeout | {% hint style="info" %} All timeouts are in milliseconds {% endhint %} With the future you can now create fluent functional programming constructs to deal with your async operation. You can create different error listeners and even continue processing the value the async operation produced in another asyncronous operation. Much like a pipeline of never ending futures! ```java future = runAsync( function(){ return 5; }).then( function(input){ return input + 2; }).error( function(){ return "Error occurred."; }); result = future.get(); writeOutput(result); ``` You can mix and match the callback functions to create a nice asyncronous pipeline. Just note that if you call the `get()` operation immediately that will BLOCK the execution until the async operation finalizes, which kinda defeats the purpose of the async operation. If you do not want to block, then use the `then()` approach, where that callback will be called for you with the result of the async operation and then you can do your post-processing. The alternative is to sit and poll the `isDone()` or `isCancelled()` operations, and YUCK! # MVC ## Intro to MVC ![](/files/-LLFsgeo-UspSoQGGkHe) > "A developer often wishes to separate data (model) and user interface (view) concerns, so that changes to the user interface will not affect data handling, and that the data can be reorganized without changing the user interface. The model-view-controller solves this problem by decoupling data access and business logic from data presentation and user interaction, by introducing an intermediate component: the controller." [Wikipedia](http://en.wikipedia.org/wiki/Model-view-controller)​ MVC is a popular design pattern called [Model View Controller](http://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller) which seeks to promote good maintainable software design by separating your code into 3 main tiers: * **Model** - Business Logic, Data, Queries, Etc * **View** - Representation of your models, queries, data. * **Controller** - Orchestrator of client request to the appropriate models and views Let's go a little deeper. ### Model The Model is the heart of your application. Your business logic should mostly live here in the form of services, beans, entities and DAOs. A dependency injection framework becomes invaluable when dealing with object oriented model layers: [**WireBox**](https://wirebox.ortusbooks.com) (Dependency Injection Framework) is the framework of choice for dependency injection and aspect oriented programming. ### Views The Views are what the users see and interact with. They are the templates used to render your application out for the web browser. Typically this means cfm/HTML, but it can also be JSON, XML, data views, etc. In modern times, your views can even be pure HTML with a combination of a JavaScript MVC framework. The major players in the MVC front-end world that we would recommend in order of personal preference: * **VueJS** - * **Angular** - * **ReactJS** - * **EmberJS** - ### Controllers Controllers are the traffic cops of your application. They direct flow control, and interface directly without incoming parameters from FORM and URL scopes. It is the controller’s job to communicate with the appropriate models for processing, and set up either a view to display results or return serialized data like JSON, XML, PDF, etc. ## Benefits of MVC By implementing an MVC Framework to your applications you will gain several benefits that come inherent to the MVC design pattern. The most important benefit of MVC is that you will be **separating the presentation** from the model. This is a very important heuristic of software development as [**separation of concerns**](https://en.wikipedia.org/wiki/Separation_of_concerns) is applied and responsibilities are delegated upon the layers. ### Separation of Concerns The model and the view layers have different concerns about their implementations. A view layer is concerned with how to render the data, the type of browser, or remote rendering, etc. While the model is more concerned with the business rules of the application, how to store data and even database operations. You use different development approaches to each layer. ### Multiple GUI’s Due to this separation, you can easily create multiple views for the same model data without affecting how the model works or is coded. The view layers can adapt to the model by coding their own implementations. This makes it really easy to create multiple GUI’s for applications. ### Unit and Behavioral Testing Non-visual objects are easier to test than visual objects, in theory. With the introduction of Selenium, integration and visual UI testing has become rather simple. However, the key benefit here is that testing can be done separately. Frameworks like ColdBox even give you the ability to do UI and integration testing within its domain. ### Dependency The most important benefit that we can arise out of the MVC pattern, is the direction of the dependencies. A view depends on its model data and controller, but the model itself does not depend on the view or controllers. This is how you want to build your business logic, encapsulated and providing a good API. ## Evolution of MVC Architecture There are many types of MVC architectures and hopefully the following diagrams can help you in the progression from spaghetti hell to the most complex MVC architecture using an [`ORM`](https://en.wikipedia.org/wiki/Object-relational_mapping) or Object Relational Mapper. ### Spaghetti Hell ![Spaghetti Hell](/files/-LLFwoPuQaSbRv6nGYjH) \ As you can see from the spaghetti hell diagram above, everything is linear and can become extremely convoluted. Tracking bugs are difficult, maintenance suffers and reusability is not efficient. Everything is in the same bowl of soup. \--- ### MVC ![](/files/-LLFx8QnCOoITiTOxayI) With the introduction of MVC we can hack away our spaghetti hell and at least have three distinct and separate layers of logic. Ahh much better. However, we can get even more complex. \--- ### MVC Plus ![MVC Plus](/files/-LLFxKz_BZHOeRB-DZeZ) MVC Plus shows us how you can further partition your model layer into more layers. We can identify now a layer of service CFCs and data access object CFCs. The main transportation of data between these layers by default is implied to be ColdFusion Query objects. \--- ### MVC Plus Objects ![MVC Plus Objects](/files/-LLFxocpS5dWNTAY6ZIb) \ In this architecture approach, we have replaced (mostly) queries as our data structure of preference and converted to the usage of business objects. We are approaching a more object oriented architectural style. Remember that data is just data, objects are data plus behavior. We can encapsulate more features and abstract more behavior into actual objects now, which we could not do with queries. \--- ### MVC Plus ORM ![MVC Plus ORM](/files/-LLFyAIqhSQ3wYh5xrO7) \ In this architecture approach we have replaced business objects for ORM entities and replaced our data access layer to be controlled now by the ORM. This takes us very deep into object oriented land where the majority of our model is now modeled vi relational objects. {% hint style="danger" %} **Stern Warning:** ORMs are NOT silver bullets. They are an incredible tool that must be used for the right reasons and at the right time. Do not be confused in that you must ONLY use the ORM. No, you can still use DAOs and queries for certain things that matter. You do not need to retrieve entire object graph collections if NOT needed. We have even build a companion package for ColdBox called [**cborm**](https://github.com/coldbox-modules/cbox-cborm) that will help you build more pragmatic and enjoyable ORM applications. {% endhint %} \--- ## MVC Frameworks for ColdFusion (CFML) Here are our recommendations: * **ColdBox MVC** - * **fw/1** - * **CFWheels** - ### ColdBox MVC ![ColdBox MVC Platform](/files/-LLFwQp5Gv_MeuxHTjdp) {% hint style="info" %} ColdBox has become the defacto platform for developing modern MVC ColdFusion applications and we are partial to it because we wrote it :) {% endhint %} The ColdBox HMVC Platform is the de-facto enterprise-level HMVC framework for CFML developers. It's professionally backed, highly extensible, and productive. Getting started with ColdBox is quick and painless. The only thing you need to begin is [CommandBox](http://www.ortussolutions.com/products/commandbox), a command line tool for CFML developers. You can check out our quick learning guides below: * **Quick Start Guide:** * **60 Minute Guide:** ## More Resources * ​​ * ​​ * ​​ # Dependency Injection > Dependency injection is the art of making work come home to you.\ > Dhanji R. Prasanna **In ColdFusion, WireBox is the standard when it comes to Dependency Injection and Aspect Oriented Programming (AOP).** ![](/files/-LgIULB5RA_cLjZK7o5m) WireBox alleviates the need for custom object factories or manual object creation in your ColdFusion (CFML) applications. It provides a **standardized** approach to object **construction** and **assembling** that will make your code easier to adapt to changes, easier to [test, mock](https://testbox.ortusbooks.com) and extend. {% hint style="info" %} You can read all about WireBox here: {% endhint %} As software developers we are always challenged with maintenance and one ever occurring annoyance, **change**. Therefore, the more sustainable and maintainable our software, the more we can concentrate on real problems and make our lives more productive. WireBox leverages an array of metadata annotations to make your object assembling, storage and creation easy as pie! We have leveraged the power of event driven architecture via object listeners or interceptors so you can extend not only WireBox but the way objects are analyzed, created, wired and much more. To the extent that our [AOP ](https://wirebox.ortusbooks.com/aspect-oriented-programming/aop-intro)capabilities are all driven by our AOP listener which decouples itself from WireBox code and makes it extremely flexible. ## Dependency Injection Explained We have released one of our chapters from our [CBOX202: Dependency Injection](https://www.ortussolutions.com/learn) course that deals with getting started with Dependency Injection, the problem, the benefits and the solutions. We encourage you to download it, print it, share it, digest it and learn it: {% hint style="success" %} If you require any training please [contact us](https://www.ortussolutions.com/learn). {% endhint %} ## Advantages of a DI Framework Compared to manual Dependency Injection (DI), using WireBox can lead to the following advantages: * You will write less boilerplate code. * By giving WireBox DI responsibilities, you will stop creating objects manually or using custom object factories. * You can leverage object persistence scopes for performance and scalability. Even create time persisted objects. * You will not have any object creation or wiring code in your application, but have it abstracted via WireBox. Which will lead to more cohesive code that is not plagued with boilerplate code or factory code. * Objects will become more testable and easier to mock, which in turn can accelerate your development by using a TDD (Test Driven Development), BDD (Behavior Driven Development) approach. * Once WireBox leverages your objects you can take advantage of AOP or other event life cycle processes to really get funky with Object Orientation. ## Features at a Glance Here are a simple listing of features WireBox brings to the table: * Annotation driven dependency injection * 0 configuration mode or a programmatic binder configuration approach via ColdFusion (No XML!) * Creation and Wiring of or by: * ColdFusion Components * Java Classes * RSS Feeds * WebService objects * Constant values * DSL string building * Factory Methods * Providers * Multiple Injection Styles: Property, Setter, Method, Constructor * Automatic Package/Directory object scanning and registration * Multiple object life cycle persistence scopes: * No Scope (Transients) * Singletons * Request Scoped * Session Scoped * Application Scoped * Server Scoped * CacheBox Scoped * Integrated caching via [CacheBox](https://cachebox.ortusbooks.com), scale your objects and metadata * Integrated logging via [LogBox](https://logbox.ortusbooks.com), never try to figure out what in the world the DI engine is doing * Parent Factories * Factory Method Object Creations * Object life cycle events via WireBox Listeners/Interceptors * Customizable injection DSL * WireBox object providers to avoid scope-widening issues on time/volatile persisted objects * [Aspect Oriented Programming](https://wirebox.ortusbooks.com/aspect-oriented-programming/aop-intro) ## DI Basics ### Injection Styles There are three ways that DI frameworks can inject dependencies into object references: 1. Constructor Arguments 2. Setter Methods 3. Property Injections Each has it's own set of pros and cons. However, the important aspect of the injection types is the order it happens. Please refer back to the list above for order reference. Here is a component leveraging all three styles, what similarities do you notice in all of them? ```java component singleton{ // Property injection property name="userService" inject="UserService"; property name="log" inject="logbox:logger:{this}"; /** * Constructor Injection * * @myService.inject id:MyAwesomeService * */ function init( required myService ){ variables.myService = arguments.myService; return this; } function setMySecurityService( required service ) inject="SecurityService@api"{ varaiables.securityService = arguments.service; return this; } } ``` ### Injection Annotation All the injection styles have a marker called `inject` which can contain a value, this value is called the [Injection DSL](https://wirebox.ortusbooks.com/usage/injection-dsl). This basically tells WireBox what alias to inject into the component. The value of the injection DSL can mean different things to WireBox depending on the environment, registered custom dsl's and so much more. However, at the end of the day, it means, inject something here!! {% hint style="info" %} Please note that we have shown you the easiest approach to DI by leveraging annotations. If you do not like annotating your code and prefer a configuration approach; No Problem. WireBox offers a [configuration Binder](https://wirebox.ortusbooks.com/configuration/configuring-wirebox) where you can declare all your objects explicitly with all their dependencies and persistence. {% endhint %} Let's digest a few examples: ```groovy property name="userService" inject="UserService"; ``` The `inject="UserService"` will look for an object with that alias if it doesn't find it with the alias, it treats is like a CFC path and tries to create, inject and return that object. ```groovy property name="log" inject="logbox:logger:{this}"; ``` This inject DSL is spaced by colons (:) and tells WireBox the following: * Look for the `logbox` DSL * Ask for a `logger` * Map it to `{this}` class As you are starting to see, the injection DSL can be very powerful. ```java /** * Constructor Injection * * @myService.inject id:MyAwesomeService * */ function init( required myService ){ } ``` The `@myservice.inject` annotation for the constructor argument tells WireBox to look for the `id` of `MyAwesomeService` and pass it as the argument. Again, the colon is the separator of choice for DSLs. ### Persistence WireBox by default treats all objects it creates as transient objects. Meaning it will create it, inject it and return it. After usage it get's destroyed automatically by the JVM. If you want longer persistence for the objects you can [annotate them with a scope](https://wirebox.ortusbooks.com/configuration/component-annotations/persistence-annotations) or shortcut annotations like the `singleton` annotation. ```groovy // Transient component{} // Singleton component singleton{} // Core or Custom Scope component scope="cachebox" ``` Available scopes are: * `NOSCOPE` : Transient objects * `PROTOTYPE` : Transient objects * `SINGLETON` : Objects constructed only once and stored in the injector * `SESSION` : ColdFusion session scoped based objects * `APPLICATION` : ColdFusion application scope based objects * `REQUEST` : ColdFusion request scope based objects * `SERVER` : ColdFusion server scope based objects * `CACHEBOX` : CacheBox scoped objects ### Usage Ok, we have seen how to construct our objects according to DI principles, but how do we now use them? There are two modes of operation: * Standalone * ColdBox Application WireBox is part of the ColdBox HMVC framework, so you can leverage DI/AOP out of the box with no configuration or startup code. If you are NOT using ColdBox then you can use WireBox in standalone mode like shown below: ```groovy // Create the WireBox Main injector wirebox = new wirebox.system.ioc.Injector(); // Create it with a configuration Binder wirebox = new wirebox.system.ioc.Injector( "myBinderPath" ); // Get an object wirebox.getInstance( "MyService" ); wirebox.getInstance( "my.path.to.Service" ); ``` {% hint style="danger" %} Please note that by default the WireBox injector once initialized it will be scoped into application scope automatically for you as: `application.wirebox` {% endhint %} The main method to retrieve objects is called `getInstance()` and you can see the signature below: ```java /** * Locates, Creates, Injects and Configures an object model instance * * @name The mapping name or CFC instance path to try to build up * @dsl The dsl string to use to retrieve the instance model object, mutually exclusive with 'name * @initArguments The constructor structure of arguments to passthrough when initializing the instance * @initArguments.doc_generic struct * @targetObject The object requesting the dependency, usually only used by DSL lookups **/ function getInstance( name, dsl, struct initArguments = structNew(), targetObject="" ) ``` That's it! You can now start rolling with dependency injection in your applications. We highly encourage you to visit our [ColdBox documentation](https://coldbox.ortusbooks.com/the-basics/models) or the standalone [WireBox documentation](https://wirebox.ortusbooks.com/) for more in-depth analysis of dependency injection. We have only touched the surface. ## Useful Resources * * * * * * * * * # Security Guide Safeguarding your applications and data from attack requires addressing several important factors including server security, network security and code security. You can find all you need to know about securing your ColdFusion engines in the ColdFusion Security Guide at the most excellent [**cfdocs**](https://cfdocs.org/security) website. Please visit it, follow it, live it! * * [https://cfdocs.org/security-encryption](https://cfdocs.org/security%2Dencryption) * [https://cfdocs.org/security-obfuscation](https://cfdocs.org/security%2Dobfuscation) * [https://cfdocs.org/security-session-management](https://cfdocs.org/security%2Dsession%2Dmanagement)