Ok, now that we know how to configure WireBox, let's get into the fun stuff of object mapping. How do we do this? By using our DSL mapping initiators that tell WireBox how to start the object registration process. You will then concatenate the initiators with some DSL destinations methods, DI data, etc to tell WireBox all the information it might need to construct, wire and persist the object. Here are the DSL initiators:

Gives you the ability to easily inject base ORM services or binded virtual entity services for you:

Added

• Github actions for LTS Releases

• LTS Updates

Bugs

• COLDBOX-1219 CFProvider ACF versions are Hard-Coded

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

This release was a ColdBox minor bump with no tickets affecting Wirebox

 __          ___          ____
 \ \        / (_)        |  _ \
  \ \  /\  / / _ _ __ ___| |_) | _____  __
   \ \/  \/ / | | '__/ _ \  _ < / _ \ \/ /
    \  /\  /  | | | |  __/ |_) | (_) >  <
     \/  \/   |_|_|  \___|____/ \___/_/\_\

WireBox Manual - Version 6.x

WireBox is an enterprise ColdFusion Dependency Injection and Aspect Oriented Programing (AOP) framework. WireBox's inspiration has been based on the idea of rapid workflows when building object oriented ColdFusion applications, programmatic configurations and simplicity. With that motivation we introduced dependency injection by annotations and conventions, which has been the core foundation of WireBox. We have definitely been influenced by great DI projects like Google Guice, Grails Framework, Spring and ColdSpring so we thank them for their contributions and inspiration

WireBox is standalone framework for ColdFusion (CFML) applications and it is also bundled with the ColdBox Platform.

Versioning

WireBox is maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with the following format:

<major>.<minor>.<patch>

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bumps the patch

License

The ColdBox Platform, WireBox is open source and licensed under the Apache 2 License.

• Copyright by Ortus Solutions, Corp

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

Discussion & Help

The WireBox help and discussion group can be found here: https://community.ortussolutions.com/

Reporting a Bug

We all make mistakes from time to time :) So why not let us know about it and help us out. We also love pull requests, so please star us and fork us: https://github.com/coldbox/coldbox-platform

Jira Issue Tracking

• https://ortussolutions.atlassian.net/browse/COLDBOX

• https://ortussolutions.atlassian.net/browse/WIREBOX

• https://ortussolutions.atlassian.net/browse/LOGBOX

• https://ortussolutions.atlassian.net/browse/CACHEBOX

Professional Open Source

WireBox is a professional open source library supported by Ortus Solutions. If you are interested in support please consider our Ninja Subscription Support or if you need consulting please purchase on of our Consulting Plans. Here are some areas that we can assist you with:

• Custom Development

• Professional Support & Mentoring

• Training

• Server Tuning

• Security Hardening

• Code Reviews

• Much More

Resources

• Official Site: https://www.coldbox.org

• CFCasts Video Training: http://ww.cfcasts.com

• Source Code: https://github.com/coldbox/coldbox-platform

• Bug Tracker: https://ortussolutions.atlassian.net/browse/WIREBOX

• Twitter: @coldbox

• Facebook: https://www.facebook.com/coldboxplatform

• Vimeo Channel: https://vimeo.com/channels/coldbox

HONOR GOES TO GOD ABOVE ALL

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

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

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

• Version 6.0 - August 2020

• Version 3.0 - March 2011

• Version 2.0 - April 2007

• Version 1.0 - June 2006

Here are the release notes for WireBox 6.4.0

Major Updates

WireBox Child Injectors

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

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

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

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

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

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

• getChildInjectors() - Get all the child injectors registered

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

Child Enhanced Methods

• getInstance()

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

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

    • Locally

    • Parent

    • All Children (in order of registration)

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

  1. Locally

  2. Parent

  3. Children

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

Getting Instances From Specific Child Injectors

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

Child Injector Explicit DSL

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

IInjector Interface Updates

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

Release Notes

Release Notes

WireBox 6.1.0 is a minor release with small fixes and minor updates.

Release Notes

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

Major Updates

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

WireBox Performance, Performance and More Performance

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

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

Release Notes

WireBox 6 is a major release for WireBox accompanied by the ColdBox Platform release. WireBox includes LogBox and CacheBox and you can find the appropriate release notes for those libraries as well.

Release Notes

This minor release brings in some major performance enhancements for the way WireBox maps and creates objects. We highly encourage upgrading to it.

Release Notes

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer with over 15 years of software development and systems architecture experience. He was born in San Salvador, El Salvador in the late 70’s, during a period of economical instability and civil war. He lived in El Salvador until 1995 and then moved to Miami, Florida where he completed his Bachelors of Science in Computer Engineering at Florida International University. Luis resides in The Woodlands, Texas with his beautiful wife Veronica, baby girl Alexia and baby boy Lucas!

He is the CEO of Ortus Solutions, a consulting firm specializing in web development, ColdFusion (CFML), Java development and all open source professional services under the ColdBox and ContentBox stack. He is the creator of ColdBox, ContentBox, WireBox, MockBox, LogBox and anything “BOX”, and contributes to many open source ColdFusion projects. He is also the Adobe ColdFusion user group manager for the Inland Empire. You can read his blog at www.luismajano.com

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

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

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

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

• He has a geek love for circuits, microcontrollers and overall embedded systems.

• He has of late (during old age) become a fan of running and bike riding with his family.

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

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

Contributors

Jorge Emilio Reyes Bendeck

Jorge is an Industrial and Systems Engineer born in El Salvador. After finishing his Bachelor studies at the Monterrey Institute of Technology and Higher Education ITESM, Mexico, he went back to his home country where he worked as the COO of Industrias Bendek S.A.. In 2012 he left El Salvador and moved to Switzerland in pursuit of the love of his life. He married her and today he resides in Basel with his lovely wife Marta and their daughter Sofía.

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

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

Brad Wood

Brad grew up in southern Missouri where he systematically disassembled every toy he ever owned which occasionally led to unintentional shock therapy (TVs hold charge long after they've been unplugged, you know) After high school he majored in Computer Science with a music minor at MidAmerica Nazarene University (Olathe, KS). Today he lives in Kansas City with his wife and three girls where he still disassembles most of his belongings (including automobiles) just with a slightly higher success rate of putting them back together again.) Brad enjoys church, all sorts of international food, and the great outdoors.

Brad has been programming CFML for 12+ years and has used every version of CF since 4.5. He first fell in love with ColdFusion as a way to easily connect a database to his website for dynamic pages. Brad blogs at (http://www.codersrevolution.com) and likes to work on solder-at-home digital and analog circuits with his daughter as well as building projects with Arduino-based microcontrollers.

Brad's CommandBox Snake high score is 141.

Dependency injection is the art of making work come home to you. Dhanji R. Prasanna

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 and extend.

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 capabilities are all driven by our AOP listener which decouples itself from WireBox code and makes it extremely flexible.

We have also seen the value of a central location for object configuration and behavior so we created our very own WireBox Programmatic Mapping DSL (Domain Specific Language) that you can use to define object construction, relationships, AOP, etc in pure ColdFusion (No XML!). We welcome you to stick around and read our documentation so you can see the true value of WireBox in your web applications.

Dependency Injection Explained

We have released one of our chapters from our CBOX202: Dependency Injection 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: http://ortus-public.s3.amazonaws.com/cbox202-unit1-3.pdf

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

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, scale your objects and metadata

• Integrated logging via LogBox, 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

• Standalone ORM Entity Injection

WireBox RefCard

Useful Resources

• http://code.google.com/p/google-guice

• http://www.manning.com/prasanna/

• http://en.wikipedia.org/wiki/Aspect-oriented_programming

• http://en.wikipedia.org/wiki/Dependency_injection

• http://en.wikipedia.org/wiki/Inversion_of_control

• http://martinfowler.com/articles/injection.html

• http://www.theserverside.com/news/1321158/A-beginners-guide-to-Dependency-Injection

• http://www.developer.com/net/net/article.php/3636501

• http://code.google.com/p/google-guice/

A primer to WireBox usage

Dependency injection and instance construction with WireBox is easy. In its most simplest form we can just leverage annotations and be off to dancing Big Willy style! You can use our global injection annotation inject on cfproperties, setter methods or constructor arguments. This annotation tells WireBox to inject something in place of the property, argument or method; basically it is your code shouting "Hey buddy, I need your help here".

What it injects depends on the contents of this annotation that leverages our (Domain Specific Language). The simplest form of the DSL is to just tell WireBox what mapping to bring in for injection. Please note that I say mapping and not object directly, because WireBox works on the concept of an object mapping. This mapping in all reality can be a CFC, a java object, an RSS feed, a webservice, a constant value or pretty much anything you like.

If you don't like annotations because you feel they are too intrusive to your taste, don't worry, we also have a programmatic configuration binder you can use to define all your objects and their dependencies. We will discuss object mappings and our configuration binders later on, so let's look at how cool this is by checking out our Coffee Shop sample class. The CoffeeShop class below will use our three types of injections to showcase how WireBox works, please note that most likely we would build this class by picking one or the other, which in itself brings in pros and cons for each approach.

So let's break this class down. First, you can see a singleton annotation on the component declaration. This tells WireBox that this class should only be created once and then cached in its internal singleton scope of the injector. In other words, this is called object life scopes. You can refer to the persistence scopes annotations later on in the guide to learn all about how to scope your classes.

Second, we built our coffee shop class with three external dependencies: 1 by cfproperty, 1 by constructor argument and 1 by setter injection. Again, you can see later on in this guide the difference between all these injection styles and choose what you prefer. In this example, we just showcase the different injection styles. Also, as you can see from the source code the three types of injection uses the inject annotation but with different content:

If you just mark a property, argument or method with the inject annotation, WireBox will assume it is a mapping and the ID should be either the property name, the argument name or the method name. However, if you want to specify the id in the DSL string, just use the simple id:{mapping} dsl notation. That's it! Isn't that cool, you just mark out your dependencies and WireBox will build and inject them for you!

Thirdly, this class has the following method:

The method has a cool little annotation called onDIComplete that tells WireBox that after all DI dependencies have been injected, then execute the method. That is so cool, WireBox can even open the coffee shop for me so I can get my espresso fix. Not only that but you can have multiple onDIComplete methods declared and WireBox will call them for you (in discovered order). These are called object post processors that are discovered by annotations or can be configured via our configuration binder and we will learn about them later on. WireBox also fires a series of object life cycle events throughout an object's life span in which you can build listens to and actually perform some cool stuff on them. So now that we got all excited about opening the coffee shop let's get into something even more interesting, unit testing and mocking.

Another important aspect leveraging DI concepts when building our components is that we can immediately write tests for them and leverage mocking to test for actual behaviors. This is a great advantage as it allows you to rapidly test to confirm your component is working without worrying about building or assembling objects in your tests. You have eliminated all kinds of crazy creation and assembler code and just concentrated yourself on the problem at hand. You are now focused to code the greatest piece of software you have ever imagined, thanks to WireBox!

Now we can run our tests and verify that our coffee shop is operational and producing sweet sweet espresso!

The source code for this book is hosted in GitHub: . You can freely contribute to it and submit pull requests. The contents of this book is copyright by and cannot be altered or reproduced without 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 -

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

External Trademarks & Copyrights

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

Notice of Liability

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

Contributing

We highly encourage contribution to this book and our open source software. The source code for this book can be found in our where you can submit pull requests.

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 2 months.

Shalom Children's Home

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

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

Another aspect of our objects is when are they created? Good question!

By default all objects are created ONLY when they are requested, in other words they are lazy created. But what if you are spoiled and you want your stuff NOW NOW NOW! Well, you can, cry if you want to! Just tell WireBox that you want your objects to be eagerly created via the mapping DSL asEagerInit() function or a eagerInit annotation on the component.

WireBox can be downloaded as a standalone framework or it is included with the latest ColdBox Platform release, so no need to install it if you are within a ColdBox application.

System Requirements

• Adobe ColdFusion 2016 (Deprecated)

• Adobe ColdFusion 2018+

• Lucee 5+

CommandBox Installation

You can leverage CommandBox to install the standalone version of WireBox with a simple command:

# Latest Version
box install wirebox

# Bleeding Edge
box install wirebox@be

This will install WireBox as a dependency in your application into a folder called wirebox. You can then leverage the standalone namespace within your application: wirebox.system.ioc.

Manual Download

You can download the latest version of WireBox from https://www.forgebox.io/view/wirebox. Place in your webroot or create a /wirebox mapping in your system.

Namespaces

Standalone Namespace

wirebox.system.ioc

ColdBox Namespace

coldbox.system.ioc

We have now coded our classes and unit tests with some cool annotations in record time, so what do we do next? Well, WireBox works on the idea of three ways to discover and create your classes:

So let's do examples for each where our classes we just built are placed in a directory called model of the root directory.

Implicit Creation

injector = new wirebox.system.ioc.Injector();
espresso = injector.getInstance( "model.CoffeeShop" ).makeEspresso();

Explicit Binder Configuration

map("CoolShop").to("model.CoffeeShop");

Explicit Creation

injector = new wirebox.system.ioc.Injector();
espresso = injector.getInstance("CoolShop").makeEspresso();

Scan Locations Binder Configuration

wirebox.scanLocations = ["model"];

Set Locations Creation

injector = new wirebox.system.ioc.Injector();
espresso = injector.getInstance("CoffeeShop").makeEspresso();

We touched briefly on singleton and no scope objects in this section, so let's delve a little into what scoping is. WireBox's default behavior is to create a new instance of an object each time you request it via creation or injection (Transient/Prototype objects), this is the NO SCOPE scope.

Scopes allow you to customize the object's life span and duration. The singleton scope allows for the creation of only one instance of an object that will live for the entire life span of the injector. WireBox ships with several different life span scopes but you can also create your own custom scopes (). You can also tell WireBox in what scope to place the instance into by annotations or via the configuration binder. We have an entire section dedicated to discovering all the WireBox annotations, but let's get a sneak peek at them and also how to do it via our mapping DSL.

Scope Annotations

• You can tag a cfcomponent tag or component declaration with a scope={named scope} annotation that tells WireBox what scope to use

• You can have nothing on the cfcomponent tag or component declaration which denotes the NO SCOPE

• You can tag a cfcomponent tag or component declaration with a singleton annotation

Scope Configuration Binder

Internal Scopes

Here are the internal scopes that ship with WireBox:

This is cool! We can now have full control of how objects are persisted via the WireBox injector, we are not constricted to one type of persistence anymore.

Whether you use WireBox standalone or within a ColdBox context a Binder gets a structure of configuration properties so it can use them whenever you are configuring it or declaring mappings. If you are in standalone mode, the Injector can be constructed with a properties structure that will be passed to the binder for usage. If you are in a ColdBox application the ColdBox application configuration structure is passed for you. You can then use these properties with the following methods:

• getProperty(name,[default]) : Get a specific property

• getProperties() : Get all the properties structure

• propertyExists(name) : Check if a property exists

• setProperty(name,value) : Dynamically add properties to the structure

Most of the time we believe our DI engines should be black boxes, but we try to think otherwise. We encourage developers to know what is going on so they can debug easily and not hit their foreheads against their keyboards. Believe me, I have done so before. That is why WireBox is tightly integrated with LogBox to provide incredible debugging information to ANY appender you desire so you can know what is going on. Another aspect of knowing what the DI engine does is how dependencies are resolved. Here is a typical flow of injection:

Instance Creation

1. Object is requested by name and the Injector tries to check if the mapping exists for that name. If no mapping is found then it tries to locate the object by using the internal scan locations to try to find it. If it cannot find it and there is a parent injector defined, then the request is funneled to the parent injector and we start our process again. If no parent injector is declared and no localization, then we throw a not located exception.

2. If the object was found via the scan locations, then we register a new mapping according to its location and discover all the metadata out of the object in preparation for construction and DI

3. We now have a guaranteed mapping so we retrieve it and we verify if the mapping's metadata has been processed or not. If the mapping is marked with no autowiring then we skip to the next step. If not, we process the mapping's metadata and prepare it for DI

4. We verify that the scope define for the mapping exists, else we throw an invalid scope exception

5. We ask the scope to produce the mapping object for us. The scope is in charge of persistence, locking, etc.

6. The scope builds the instance by asking the injector to build a new instance with the correct constructor and constructor arguments and stores it in its scope once the injector builds it. The builder decides what type of construction is needed for the mapping as it can be a CFC, java object, webservice, RSS feed, factory method call, etc. Each constructor argument is processed for dependency resolution.

7. The scope then sends the instance for DI wiring and process back to the injector

8. The injector returns the instance

Dependency Resolution

1. Arrive at the desired injection point and get the injection DSL. If the DSL is empty, then it defaults to the id/model namespace. For this injection DSL Namespace we try to find a valid DSL builder for it. If none is found an exception is thrown. If we have a match, then the DSL builder is called with the DSL string to retrieve.

2. The DSL builder then tries to parse and process the DSL string for object retrieval. If the DSL is a WireBox mapping then we try to retrieve the instance by name (Refer back to Instance Creation).

3. If the builder could not produce an instance, it is logged and DI is skipped on it.

ColdSpring was the first dependency injection framework for ColdFusion in the good 'ol days. It was inspired by Java Spring and it rocked during its tenure. As a matter of fact, there is still quite a large number of applications leveraging it, even though the framework itself is completely legacy, unsupported and might not even work on some versions of Adobe 2018+ as well. If you are in this technical debt boat and want a quick win and recover some ground in the technical debt war, then this document is for you.

If you have an application that leveraged ColdSpring for your dependency injection, you can easily port it to WireBox. The first step is converting the ColdSpring XML file to a WireBox Binder. This will translate 1-1 the bean configurations to WireBox configurations.

Then it will be up to you to test your objects and get up and running really quickly.

WireBox

WireBox is an enterprise ColdFusion Dependency Injection and Aspect Oriented Programing (AOP) framework. WireBox's inspiration has been based on the idea of rapid workflows when building object oriented ColdFusion applications, programmatic configurations and simplicity. With that motivation we introduced dependency injection by annotations and conventions, which has been the core foundation of WireBox.

WireBox is standalone framework for ColdFusion (CFML) applications and it is also bundled with the ColdBox Platform.

What's even more important its that WireBox is:

• Modern

• Professionally Supported

• Actively Maintained

• Widely Used

CommandBox

Make sure you have CommandBox CLI installed as we will be using it to install WireBox and convert our XML file to WireBox DSL.

ColdSpring XML to WireBox DSL

Now it's time to install our module that converts ColdSpring XML to WireBox DSL:

box install commandbox-coldspring-to-wirebox

This will install the coldspring-to-wirebox command into your CLI. You can get help by issuing a coldspring-to-wirebox --help command. However, it's very easy to use, so let's convert that XML file:

# Produces a WireBox.cfc where you run the command
coldspring-to-wirebox tests/coldspring.xml.cfm

# Stores the WireBox.cfc in the same location as the file above
coldspring-to-wirebox tests/coldspring.xml.cfm tests/WireBox.cfc

That's it! This will convert all your definitions and you are ready to roll!

Test Your Binder

We can now instantiate a new instance of WireBox with this Binder and use it!

new wirebox.system.ioc.Injector( "tests/WireBox" );

// Get an instance!
application.wirebox.getInstance( "MyOldBean" );

Right now would be a great time to create some canary integration tests using TestBox which can verify that your objects can be created and wired up correctly. This will be a huge help to get you started on the road to better test coverage and migrating your legacy elephant to modern times:

component extends="testbox.system.BaseSpec"{

     // executes before all suites
     function beforeAll(){
          wirebox = new wirebox.system.ioc.Injector( "path.to.Binder" );
     }

     // executes after all suites
     function afterAll(){
          structDelete( application, "wirebox" );
     }

     // All suites go in here
     function run( testResults, testBox ){
          describe( "UserService", () => {

               it( "can be created and wired", () => {
                    var target = wirebox.getInstance( "UserService" );
                    expect( target ).toBeComponent();
                    expect( target.getUserDAO() ).toBeComponent();
               } );

          } );
     }

}

The mapping destinations tell WireBox what type of object you are mapping to. You will usually use these methods by concatenating map() or with() initiator calls:

Here are some examples:

// CFC
map("FunkyObject").to("myapp.model.service.FunkyService");
mapPath("myapp.model.service.FunkyService");
mapDirectory("myapp.model");
// Java
map("buffer").toJava("java.lang.StringBuffer");
// RSS feed
map("googleNews").toRSS("http://news.google.com/news?output=rss");
// Webservice
map("myWS").toWebservice("http://myapp.com/app.cfc?wsdl");
// Provider
map("Espresso").toProvider("FunkyEspressoProvider");
// DSL
map("Logger").toDSL("logbox:root");

// factory methods
map("ColdboxFactory").to("coldbox.system.extras.ColdboxFactory");
map("ColdBoxController").toFactoryMethod(factory="ColdBoxFactory",method="getColdBox");
map("BeanInjector")
    .toFactoryMethod(factory="ColdBoxFactory",method="getPlugin")
    .methodArg(name="plugin",value="BeanFactory")

// Mixin a new method in my object that dispenses users
mapPath("UserService")
    .providerMethod("getUser","User");

When using WireBox inside of ColdBox, the binder CFC is located by convention in /config/WireBox.cfc. When using WireBox outside of ColdBox, you can create a binder CFC anywhere with any name using one of these two methods:

1. Create a configuration CFC that extends the WireBox configuration object: coldbox.system.ioc.config.Binder and has a configure() method.

2. Or create a simple configuration CFC that has a configure( binder ) method that accepts a WireBox configuration binder object

From the configure() method you will be able to interact with the Binder methods or creating implicit DSL structures in order to configure WireBox for operation and also to create object mappings. From the onLoad() method you can also use it for mappings with main distinction that the WireBox machinery is now online (logging, events, caching, etc). This is necessary for leveraging mapDirectory() calls.

When you instantiate the Wirebox injector, pass either the CFC path to your binder CFC or an instance of the CFC.

Each configuration binder has two public properties accessible in the this scope:

1. this.TYPES : A reference to wirebox.system.ioc.Types used to declare what type of object you are registering for construction or wiring

2. this.SCOPES : A reference to wirebox.system.ioc.Scopes used to declare in what life cycle scope the object will be stored under

These two classes contain static public members in the this scope that facilitate the declaration of persistence scopes and construction types for object mappings. Below are the valid enumerations for these two classes:

this.TYPES

• CFC : Construction of a CFC

• JAVA : Construction of a Java class

• WEBSERVICE : Construction of a webservice object

• RSS : Construction of an RSS feed

• DSL : Construction by DSL string

• CONSTANT : A constant value

• FACTORY : Construction by factory method

this.SCOPES

• 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

If you are using your configuration binder within a ColdBox application you will have some extra goodies in the Binder that come in very handy:

• getColdBox() : Retrieve the instance of the running ColdBox application

• getAppMapping() : Get the current AppMapping, the location of the application on th server, setting for the running ColdBox application

// map the model folder
mapDirectory( getAppMapping() & ".model" );

The WireBox binder will also be injected with 3 methods that will allow you to talk to your system environment or Java system properties. This will help you with container based applications or applications that rely on environment settings/secrets.

• getEnv( key, [defaultValue] ) - Get a Java system environment value

• getSystemProperty( key, [defaultValue] ) - Get a Java system property value

• getSystemSetting( key, [defaultValue] ) - This method will retrieve a key from the Java system properties and if it does not exist, then it checks the system environment.

A part from using the configuration binder, you can also leverage component annotations to dictate behavior on the object.

Instead of declaring data structures you can use the methods in the binder to configure WireBox for operation. All methods return an instance of the binder so you can concatenate methods.

logBoxConfig( "config.LogBox" )
    .scanLocations( getAppMapping() & ".includes.models" )
    .stopRecursions( "model.BaseService,model.BaseModel" )
    .mapScope( "Ortus", "model.scopes.Ortus" );

Now that we have constructed our injector let's discuss a little about injection idioms or styles WireBox offers before we go all cowboy and start configuring and using this puppy. The styles shown below are written in execution order.

Constructor (1)

Motivation: Mandatory dependencies for object creation

Each constructor argument receives a inject annotation with its required injection DSL. Be careful when dealing with object circular dependencies as they will fail via constructor injection due to its chicken and the egg nature

Object Properties (2)

Motivation: Great documentable approach to variable mixins to reduce getter/setter verbosity

Leverages the greatest aspect of ColdFusion, the dynamic language, to mixin variables at runtime by using the cfproperty annotations. Great for documentation and visualizing object dependencies and safe for circular dependencies.

Cons is that you can not use the dependencies in an object's constructor method-- instead use onDIComplete().

Setter Methods (3)

Motivation: Legacy classes

The inject annotation MUST exist on the setter method if the object is not mapped. Mapping must be done if you do not have access to the source or you do not want to touch the source.

Cons is that you can not use the dependencies in an object's constructor method-- instead use onDIComplete().

Summary

These are the three injection styles that WireBox supports and which style you choose depends on your requirements and also your personal taste. The setter method approach is linked to the way Spring and ColdSpring approach it which is the traditional JavaBean style of setXXX where XXX is the name of the mapping or object to pass into the setter method for injection.

The mapping DSL is the way to configure object mappings in WireBox that will represent objects, factories or providers. All mappings DSL methods return back an instance of the binder so you can concatenate methods to create readable execution chains.

The chains are divided into three types:

1. Initiators - Start the mapping DSL process

2. Modifiers - Can modify a mapping with metadata and behavior

3. Destinations - Tells the binder to what object or behavior we should map to.

In the configure() method you can create a structure called wirebox in the variables scope that will hold the configuration data for WireBox. You can configure WireBox for operation using these structures or via programmatic method calls.

/**
* Configure WireBox
*/
function configure(){

    // The WireBox configuration structure DSL
    wireBox = {

        // LogBox Config: instantiation path
        logBoxConfig = "wirebox.system.ioc.config.LogBox",

        // CacheBox
        cacheBox = { enabled = true },

        // Scope registration, automatically register a wirebox injector instance on any CF scope
        // By default it registeres itself on application scope
        scopeRegistration = {
            enabled = true,
            scope   = "application", // server, cluster, session, application
            key        = "wireBox"
        },

        // DSL Namespace registrations
        customDSL = {
            // namespace = "mapping name"
        },

        // Custom Storage Scopes
        customScopes = {
            // annotationName = "mapping name"
        },

        // Package scan locations
        scanLocations = [],

        // Stop Recursions
        stopRecursions = [],

        // Parent Injector to assign to the configured injector, this must be an object reference
        parentInjector = "",

        // Register all event listeners here, they are created in the specified order
        listeners = [
            // { class="", name="", properties={} }
        ]
    };

    // Map Bindings below
}

logBoxConfig

The path to the LogBox Configuration object to use. By default it uses the one displayed below. If you are using WireBox within a ColdBox application, the LogBox configuration is taken from the ColdBox application.

wirebox.logBoxConfig = "wirebox.system.ioc.config.LogBox";

cachebox

If you are using WireBox within a ColdBox application this setting is ignored and it will use the ColdBox application's CacheBox configuration. The following are the keys for this configuration structure:

wirebox.cacheBox = {
    // Activate the CacheBox DSL and caching
    enabled = false,
    // An optional configuration file to use for loading CacheBox
    configFile = "coldbox.system.ioc.config.CacheBox",
    // A reference to an already instantiated CacheBox CacheFactory, instead of building one
    cacheFactory = "",
    //A class path namespace to use to create CacheBox: Default=coldbox.system.cache or wirebox.system.cache
    classNamespace = ""
};

scopeRegistration

This structure tells WireBox how to leach itself into any ColdFusion scope when initialized instead of you placing it in the scope.

wirebox.scopeRegistration = {
    // activate scope registration
    enabled = true,
    // The CF scope to place the WireBox injector on
    scope   = "application",
    // The key used to store it in the scope
    key        = "wireBox"
};

customDSL

Please refer to the Custom DSL section to find out more about custom DSLs, the following are just the way you declare them:

wirebox.customDSL = {
    // The value of the DSL Namespace is the instantiation path
    // of the DSL Namespace builder that implements wirebox.system.ioc.DSL.IDSLBuilder
    cool = "my.path.CoolDSLBuilder",
    funkyBox = "my.funky.DSLBuilder"
};

customScopes

Please refer to the Custom scopes section to find out more about custom scopes, the following are just the way you declare them:

wirebox.customScopes = {
    // The value of the instantiation path of the custom scope
    // that implements coldbox.system.ioc.scopes.IScope.
    // The name of the scope will be used when registered
    // the scope annotation.
    CoolSingletons = "my.path.SingletonScope",
    FunkyTransaction = "my.funky.Transaction"
};

scanLocations

The instantiation paths that this Injector will have registered to do object locations in order. So if you request an object called Service and no mapping has been configured for it, then WireBox will search all these scan locations for a Service.cfc in the specified order. The last lookup is the no namespace lookup which basically represents a createObject("component","Service") call. If you are using WireBox within a ColdBox application, ColdBox will register the models convention folder for you.

wirebox.scanLocations = ["models","com","org.majano"];

stopRecursions

This is an array of class path's that WireBox will use to stop recursion on any object graph that has inheritance when looking for dependencies.

wirebox.stopRecursions = [ "transfer.com.TransferDecorator", "coldbox.system.EventHandler" ];

parentInjector

This setting is actually a reference to another parent injector you would like this injector to set as its parent injector. Now say this sentence 10 times without hiccuping.

wirebox.parentInjector = application.coolInjector;
// or
wirebox.parentInjector = new coldbox.system.ioc.Injector( "old.legacy.binder" );

listeners

This section only shows you how to register WireBox listeners, so please refer to the object life cycle events section for more information. This setting is an array of listener structure definitions that WireBox's event manager will use when broadcasting object life cycle events.

wirebox.listeners = [
    {
        // The path to the listener
        class="path.to.CFC",
        // A unique name for the listener
        name="UniqueName",
        // A structure of name-value pairs for configuring this interceptor
        properties = {}
    }
    {class="my.AOPTracker"},
    {class="annotationTransactioner",properties={target='*'} },
    {class="Timer", name="CoolTimer"}
];

Talk and get objects from the current WireBox injector.

1st Level DSL

2nd Level DSL

3rd Level DSL

property name="beanFactory" inject="wirebox";
property name="settings" inject="wirebox:properties";
property name="singletonCache" inject="wirebox:scope:singleton";
property name="populator" inject="wirebox:populator";
property name="binder" inject="wirebox:binder";

// Child Injectors
property name="categoryService" inject="wirebox:child:childInjector"

4th Level DSL

property name="categoryService" inject="wirebox:child:childInjector:CategoryService"
property name="categoryService" inject="wirebox:child:childInjector:{DSL}"

You can use our mapping DSL to register influence closures or lambdas on a per mapping basis. This will allow a developer to influence the requested instance of any object/data element and decorate objects or even return different objects.

This is similar to object providers but instead of overriding the ENTIRE creation process of the object like a provider does, the user might want to simply influence the creation of a normal mapping with some additional flair. This is accomplished via the withInfluence mapping DSL function. It receives a closure as an argument and the closure has the following signature:

/**
* Influence an instance of an object
* @injector The WireBox injector reference
* @object The object to influence
*/
function( injector, object ){}

Here is an example of adding some nice pizzazz to an object:

map( 'myObject' )
   .toPath( 'com.foo.bar' )
   .withInfluence( function( injector, object ) {
      object.customSettings( true );
      object.pizzazz = 'Oh, yes!';
      return object;
});

In this instance, the instance is already built and then passed into the closure for additional influence. Please note, that the object is returned from the closure. You can make this optional, but if something IS returned, it will override the instance which will allow a developer to replace or decorate the instance as they see fit.

The mapDirectory() allows you to leverage closures or lambdas to influence and filter mappings. The arguments are filter to add a filter that MUST return boolean in order to process the mapping and influence that can influence the created mapping with any custom bindings.

// influence only certain components to be singleton
mapDirectory(packagePath="coldbox.testing.testModel.ioc", influence=function(binder, path){
    if( findNoCase( "simple", arguments.path) ){
        arguments.binder.asSingleton();
    }
});

// filter some components from registration
mapDirectory(packagePath="coldbox.testing.testModel.ioc", filter=function(path){
    return ( findNoCase( "simple", arguments.path ) ? false : true );
});

You can store a-la-carte attributes in a specific mapping so it can be retrieved at a later time by either an AOP aspect or Events. This is a great way to store custom metadata about an object so it can be read later for some meaningful purpose. Let's say you want to tag a mapping with a custom type that is not so easily determined from the object instance itself. You don't want to do all kinds of introspection in order to know what object you received in an aspect or an event.

map("MyHandler")
    .to("handlers.MyHandler")
    .extraAttributes({
        handlerPath = handlerLocation,
        module         = arguments.module
    });

This mapping declares that an object has some extra attributes that will be stored in the mapping, such as the location and if it belongs to a module. This is then incredibly useful when you have an attached listener to WireBox:

function afterInstanceAutowire(event, interceptData){
    var attribs = interceptData.mapping.getExtraAttributes();
    var iData     = {};

    // listen to plugins only
    if( structKeyExists(attribs, "handlerPath") ){
        //Fill-up Intercepted MetaData
        iData.handlerPath = attribs.handlerPath;
        iData.module       = attribs.module;
        iData.oHandler    = interceptData.target;

        //Fire My Own Custom Interception
        instance.interceptorService.processState("afterHandlerCreation",iData);
    }
}

As you can see from this sample, the extra attributes are incredibly essential, as the listener just sends the target object. It would take lots of introspection and metadata inspections in order to determine certain metadata about an object. However, with the extra attributes, it is just a snap!

The mapping destination toProvider() can also take a closure that will be executed whenever that mapping is requested. This allows you to add your own custom provider construction code inline without creating a standalone provider object that implements our provider interface. By leveraging closures you can really get funky and more concise in your coding. This closure will have the following signature and it must return the instance requested:

/**
* Create an instance of an object
* @injector The WireBox injector reference
*
* @return Any instance object
*/
function( injector ){}

Here is an example of how to accomplish this:

map("MyEspresso").toProvider( function( injector ){
    var espresso = new Espresso( sugar=2, cream = true );
    arguments.injector.autowire( espresso );
    return espresso;
} );

The dependencies DSL methods are mostly used to define dependencies and also to activate advanced features on target objects, such as runtime mixins, virtual inheritance, etc.

Note Please note that you can concatenate more than one of these methods calls to dictate multiple constructor arguments, setter methods, cf properties, and more.

The next step in our mapping DSL excursion is to learn about how WireBox will persist these object mappings into WireBox scopes. By default (as we have seen), all object mappings are transient objects and they belong to a scope type called NOSCOPE.

However, we need to specifically tell WireBox into what scope the declared mapped objects should be placed on in order for us to leverage caching, the singleton pattern, etc. This is accomplished by leveraging our persistence component annotations or the following methods if you prefer a non-annotation approach:

Note Please note that all WireBox configuration binders have two public properties:

this.TYPES - Enum class (coldbox.system.ioc.Types)
this.SCOPES - Enum class (coldbox.system.ioc.Scopes)

These classes have on themselves several public properties that are a cool shorthand way to link to construction types or persistence scopes

So just remember that these persistence DSL methods are not mandatory. If you are an annotations kinda developer, then you can easily add these persistence annotations to your classes.

// CFC
map("FunkyObject")
    .to("myapp.model.service.FunkyService")
    .asSingleton();
mapPath("myapp.model.service.FunkyService")
    .into(this.SCOPES.REQUEST);
// Java as NO SCOPE
map("buffer").toJava("java.lang.StringBuffer");
// RSS feed
map("googleNews")
    .toRSS("http://news.google.com/news?output=rss")
    .inCacheBox(timeout=60,lastAccessTimeout=15);
// Webservice
map("myWS")
    .toWebservice("http://myapp.com/app.cfc?wsdl")
    .into(this.SCOPES.APPLICATION);

The following annotations can be placed in the component declaration to tell the WireBox injector where to persist the constructed object. If no scope annotations are found on the component or mappings then the object is treated as NO SCOPE or a prototype/transient object; one that gets constructed and discarded every time.

• singleton - A singleton object that persists for the entire life-time of the application

• scope="registered_scope" : Persist in a registered scope: session, request, singleton, custom, etc.

component singleton{}

component scope="singleton"{}

component scope="request"{}

component singleton threadsafe{}

Thanks to Phill Nacelli, you can reuse object definitions in your binder or via annotations. This means that you can declare an object with its dependencies and then create other definitions that use all of this parent object's definitions. This saves tons of time in declarations and provides you with great reusability.

// Binder method
parent(alias);

// Parent Annotation
component parent="alias"{}

Here is a small example:

// PARENT Mappings
map("AbstractService").to("model.AbstractService");
    .property(name:"someAlphaDAO", ref:"someAlphaDAO")
    .property(name:"someBravoDAO", ref:"someBravoDAO");

// Concrete service with parent and also some added dpendencies of its own
map("ConcreteService").to("#myPath#.parent.SomeConcreteService")
    .parent("AbstractService")
    .property(name:"someCharlieDAO", ref:"someCharlieDAO")
    .property(name:"someDeltaDAO", ref:"someDeltaDAO");;

If you would like to use CacheBox for persistence for you objects you will need to mark your CFC with the following annotation(s)

• cachebox="[provider]" - The default provider is called 'default', so this annotation can be empty or a named cache provider

• cache - Cache into the default provider, shorthand annotation, no value needed

This annotation has two sub annotations that you can also leverage for granular control of your CacheBox integration:

• cacheTimeout - The timeout in minutes (optional)

• cacheLastAccessTimeout - The last access or idle timeout in minutes (optional)

// cache into the default provider
component cache{}
// cache into the default provider
component cachebox{}

// cache into the ehcache provider
component cachebox="ehcache"{}

// cache into the ehcache provider with settings
component cachebox="ehcache" cacheTimeout="20"{}

// cache with settings
component cache cacheTimeout="60" cacheLastAccessTimeout="10"{}

Caution When storing objects in volatile scopes like cache, session, request, etc. You must be careful of not injecting them directly into singletons or other volatile objects as you could have memory leaks via a side effect called Scope Widening Injection. We recommend combining them via WireBox Providers to avoid this side effect.

Since version 5.5.0 all mappings in WireBox will only be processed when they are requested for the very first time. This is to enhance performance and increase startup times. Processing means that the object's and its inheritance trail are inspected for metadata, which can be a very time consuming process.

process()

However, you can explicitly process a mapping right after mapping it via the binder's process() method.

mapPath( "com.app.Service" ).process();

That's it! If you call the process() method right after a mapping, it will be automatically processed. This means all annotations will be inspected.

mapDirectory( process=true )

If you are mapping using mapDirectory() then you can pass the process argument to true and all mappings in that directory scan will be processed automatically.

mapDirectory( packagePath="models.services", process=true );
// or
mapDirectory( "models.services" ).process();

WireBox bases itself on the idea of creating object injectors (wirebox.system.ioc.Injector) that in turn will produce and wire all your objects. You can create as many injector instances as you like in your applications, each with configurable differences or be linked hierarchically by setting each other as parent injectors.

Each injector can be configured with a configuration binder or none at all. If you are a purely annotations based kind of developer and don't mind requesting pathed components by convention, then you can use the no-configuration approach and not even have a single configuration file, all using autowiring and discovery of conventions. However, if you would like to alter the behavior of the injector and also create object mappings, you will need a configuration binder. The next section explains the way to create this configuration binder, below is how to startup or bootstrap the injector in different manners:

No Configuration Binder:

myObject = new coldbox.system.ioc.Injector().getInstance("my.object");

With a Configuration Binder:

myObject = new coldbox.system.ioc.Injector("myBinderPath").getInstance("CoolObject");

The WireBox injector class is the pivotal class that orchestrates DI, instance events and so much more. We really encourage you to study its API Docs to learn more about its construction and usage methods.

IDSLBuilder

The scope interface can be found here: coldbox.system.ioc.dsl.IDSLBuilder.

Your DSL Builder

Here is a sample DSL builder:

Registration

In your configuration binder you can then register the DSL component you created

This will register a new injection DSL namespace called ortus that maps to that instantiation component path.model.dsl.OrtusBuilder.

As you can see from the sample, creating your own DSL builder is fairly easy. The benefits of a custom DSL builder is that you can very easily create and extend the injection DSL language to your own benefit and if you are funky enough, override the behavior of the internal DSL Namespaces.