🎉 Welcome to WireBox 8.0.0 - this release focuses on WireBox, CacheBox, and LogBox updates that ship as part of the ColdBox platform. Below is a focused summary of the changes relevant to this documentation set.

🚀 Major Highlights

• WireBox - BoxLang Prime support and key binder cleanups

• CacheBox - BoxLang Prime support and provider fixes

• LogBox - BoxLang Prime support and new configuration options

📚 Documentation MCP Server

Connect AI assistants directly to these docs via the Model Context Protocol (MCP):

• https://cachebox.ortusbooks.com/~gitbook/mcp

• https://logbox.ortusbooks.com/~gitbook/mcp

• https://wirebox.ortusbooks.com/~gitbook/mcp

VSCode Connect:

🎶 Release Notes

CacheBox

New Features

BoxLang Prime

Bugs

CacheBox CFProvider Only Works with EhCache

LogBox

New Features

BoxLang Prime

Improvements

Add new LogBox configuration option to disallow serializing complex objects: serializeExtraInfo

WireBox

New Features

BoxLang prime

Tasks

getCacheBoxConfig() on WireBox Binder removed after deprecation

Binder.getProperty() `default` Argument Removed

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

WireBox Manual - Version 7.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

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

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.

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.

In all reality we could be building our objects and its dependencies, , without any configuration just plain location and implicit conventions. This is great but not very flexible for refactoring, so let's do the best practice of defining a mapping or an alias to a real object.

We do this by creating a WireBox configuration binder wirebox.system.ioc.config.Binder, which is a simple CFC that defines the way WireBox behaves and defines object mappings. This binder is then used to initialize WireBox so it has knowledge of these mappings and our settings.

WireBox also sports event-driven programming where it can announce several object life cycle events, and you can listen to them by creating listener CFCs.

Each event execution also comes with a structure of name-value pairs called data that can contain objects, variables, and all kinds of data useful for listeners. This data is sent by the event caller, and each event caller decides what this data sent is. Also, remember that WireBox can also be run with a reference to

WireBox allows you to create your own object persistence scopes so you can have full control on their lifecycle. This is easily done in the following process:

1. Create a CFC that implements wirebox.system.ioc.scopes.IScope

2. Register your custom scope in your configuration binder

You can create your own persistence scope or if you are getting funky, override the internal persistence scopes with your own logic.

WireBox allows you to create your own DSL object builders and then register them via your configuration binder. This allows you to create a namespace or override an internal namespace with your own object builder. By now we have seen our injection DSL and noticed that we have internal namespaces. With this feature we can alter it or create new ones so our annotations and injection DSLs can be customized to satisfaction. This is easily done in the following process

1. Create a CFC that implements wirebox.system.ioc.dsl.IDSLBuilder

2. Register your custom DSL builder in your configuration binder

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!

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( object, injector ) {
      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.

Thanks to our ColdBox Evangelist, Brad Wood, we have a feature in our Providers that you can leverage its onMissingMethod() to proxy calls into the provided object itself. So let's say our provided object has a method called sayHello(), then with an injected provider you must do this:

property name="chatter" inject="provider:Chat";

function useChatter(){
    return chatter.get().sayHello();
}

That is great, but you can proxy calls into the provider itself by removing the extra get() call and doing this:

property name="chatter" inject="provider:Chat";

function useChatter(){
    return chatter.sayHello();
}

The WireBox provider object (wirebox.system.ioc.Provider) has an onMissingMethod() function that will take all missing method calls and proxy them to the provided object. Now, this is great but be ready to lose on performance if you use this approach. That is the only caveat to this approach, is that you will be impacted by performance, not crazy, but try it.

The executor namespace is both available in ColdBox and WireBox standalone and it is used to get references to created asynchronous executor thread pools.

property name="coldbox-tasks" inject="executor";

property name="taskExecutor" inject="executor:myTasks";

WireBox also comes packaged with our handy object populator that has been so successful in our ColdBox applications. The object populator object can populate objects with data from XML, JSON, WDDX, structures, queries and much more. So we highly encourage you to check it out as it will really help out in your applications.

The way to retrieve it is to use the getObjectPopulator() method on the injector and then call one of our populate methods on the object. You can also use the wirebox:populator injection DSL to retrieve it.

populator = injector.getObjectPopulator();

property name="populator" inject="wirebox:populator";

This is a feature where you can mark methods in your components with a special provider annotation so they can serve the objects you requested automatically for you. This is an amazing feature as it will take the original method signature and replace the method for you with one that will serve the provided objects for you automatically. How insane is that! You deserve some getting jiggy wit it (chapter 4) dancing!

public Espresso function getEspresso() provider="espresso"{}

Wow! That's it! Yep, just create an empty method signature and annotated with provider={mapping} and then WireBox will read these annotated methods and replace them for you at runtime so when you call etEspresso() it actually calls the WireBox injector and requests a new espresso instance and it returns it.

Caution Please note that the visibility of provided methods does not matter to WireBox. It can provide public, private, or packaged visibilities with no problem at all.

The source code for this book is hosted in GitHub: https://github.com/ortus-docs/wirebox-docs. You can freely contribute to it and submit pull requests. The contents of this book is copyright by Ortus Solutions, Corp 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 Children’s Home () is one of the ministries that is 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 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.

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:

Hola amigo! I'm excited that you are interested in contributing to ColdBox, CacheBox, LogBox, and/or WireBox. Before submitting your contribution, please make sure to take a moment and read through the following guidelines:

Code Of Conduct

This project is open source, and as such, the maintainers give their free time to build and maintain the source code held within. They make the code freely available in the hope that it will be of use to other developers and/or businesses. Please be considerate towards maintainers when raising issues or presenting pull requests. We all follow the Golden Rule: Do to others as you want them to do to you.

• As contributors and maintainers of this project, we pledge to respect all people who contribute through reporting issues, posting feature requests, updating documentation, submitting pull requests or patches, and other activities.

• Participants will be tolerant of opposing views.

• Examples of unacceptable behavior by participants include the use of sexual language or imagery, derogatory comments or personal attacks, trolling, public or private harassment, insults, or other unprofessional conduct.

Bug Reporting

Each of the main standalone frameworks in ColdBox has separate locations for submitting bug reports. Please also ensure that if you submit a pull request, you link it to the appropriate issue.

• ColdBox Core:

• CacheBox :

• LogBox :

If you file a bug report, your issue should contain a title, a clear description of the issue, a way to replicate the issue, and any support files we might need to replicate your issue. The goal of a bug report is to make it easy for yourself - and others - to replicate the bug and develop a fix for it. All issues that do not contain a way to replicate will not be addressed.

Support Questions

If you have questions about usage, professional support, or just ideas to bounce off the maintainers, please do not create an issue. Leverage our support channels first.

• Ortus Community Discourse:

• Box Slack Team:

• Professional Support:

Pull Request Guidelines

• The master branch is just a snapshot of the latest stable release. All development should be done in dedicated branches. Do not submit PRs against the master branch. They will be closed.

• All pull requests should be sent against the development branch or the LTS version branch releases/v{version}

Security Vulnerabilities

If you discover a security vulnerability, please email the development team at and make sure you report it to the #security channel in our Box Team Slack Channel. All security vulnerabilities will be promptly addressed.

Development Setup

We have added all the necessary information to develop on ColdBox in our area and our so you can set up the database to test against.

Language Compatibility

Please make sure your code runs on the following Supported CFML Engines:

• Lucee 5+

• Adobe ColdFusion 2018+

Coding Styles & Formatting

We are big on coding styles and have included a .cfformat.json in the root of the project so that you can run the formatting tools and CommandBox scripts:

We recommend that anytime you hack on the core, you start the format watcher (box run-script format:watch). This will monitor your changes and auto-format your code for you.

You can also see the Ortus Coding Standards you must follow here: https://github.com/Ortus-Solutions/coding-standards.

CFC Docs With DocBox

All CFCs are self-documenting, and we leverage to document the entire software. All functions must be properly documented using the DocBox syntax: https://docbox.ortusbooks.com/getting-started/annotating-your-code

Financial Contributions

You can support ColdBox and all of our Open Source initiatives at Ortus Solutions by becoming a Patreon. You can also get lots of goodies and services depending on the level of contributions.

Contributors

Thank you to all the people who have already contributed to ColdBox! We: heart: : heart: : heart: love you!

Made with

Versioning Schema

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

And constructed with the following guidelines:

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

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

• Bug fixes and misc changes bump the patch

LTS - Support Policy

Updates are provided for 12 months for all releases, and security fixes are provided for two years after the next major release.

Releases

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 8.0 - October 2025

In our previous section, we have seen all the events WireBox announces, but how do we listen? There are two ways to build WireBox listeners because there are two modes of operation, but the core is the same.

1. Listeners are simple CFCs who must create methods that match the name of the event they want to listen to.

2. If you are running WireBox within a ColdBox application, listeners are Interceptors and you declare them and register them the same way you do with normal interceptors.

These methods can take up to two parameters depending on your mode of operation (standalone or ColdBox). The one main difference between pure Wirebox listeners and ColdBox interceptors is that the configure method for the standalone WireBox is different.

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)

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.

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.

You can then use these properties with the following methods in your Binder:

• 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 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

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

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 )

The injection DSL is a domain specific language that denotes what to inject in the current placeholder: property, argument, or method via the inject annotation. This injection DSL not only can it be used via annotations but also via our mapping DSL whenever a dsl argument can be used. This DSL is constructed by joining words separated by a : colon. The first part of this string is what we will denote as the injection DSL Namespace.

Property Annotation

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

WireBox can be installed as a standalone framework or included with the latest ColdBox Platform release, so it is unnecessary if you are within a ColdBox application.

System Requirements

• Adobe ColdFusion 2018+

This DSL namespace interacts with the loaded LogBox instance.

The following chart shows you the most common methods when dealing with the WireBox Injector. This doesn't mean there are no other methods on the Injector that are of value, so please check out the CFC Docs for more in-depth knowledge.

An upgrade from WireBox 7 should not incur any breaking changes, but you should still read through the guide to ensure you are not using any deprecated or removed features.

ColdFusion 2018-2021 Support Dropped

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

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.

Here is a small example:

Let's get funky now! We have seen how to inject objects and how to scope objects. However, we need to talk about a cool WireBox feature called object providers. We learned that when you request an object from WireBox it creates it and injects it immediately. However, sometimes we need more control like:

• Delay construction of the dependency until some point in time during your controlled execution. Maybe you don't want to construct some dependencies until some feature in your application is enabled.

• You need multiple instances of a class. Like a User service producing transient users, or our espresso machine creating espressos.

An object that is scoped into request, session, server, cachebox or application scopes and if wired into a persisted object will remain around even when this object has expired from the scope. This is called scope-widening injection and is a problem that must be addressed by NOT injecting them into persisted objects directly but by using WireBox's provider approach. This guarantees that the object's scope lifecycle will be maintained and your singleton or other persistent objects will be decoupled from the scope by accessing the target object via its provider.

For example, let's say you have a handler that wires in a user object that is scoped into session scope, but the handler itself is scoped as a singleton:

So when the handler is created and persisted as a singleton, the user object gets created, stored in session and also referenced into the lifecycle of the handler object. So now, if the user expires from session, the handler does not know about it, because all it knows it that a direct reference to that out of context object still remains. So if the user needed things in session to exist, this will now fail. This problem is much like how Hibernate and detached objects work. Objects are no longer in session, they are detached. This scope widening issue is resolved by NOT injecting the user object directly into the handler but by using a provider.

You can inject automatic object providers by using the provider injection DSL namespace. This will inject a WireBox provider class (wirebox.system.ioc.Provider) that follows our with one method on it: get() that will provide you with the requested mapped object.

The difference between custom providers here is that WireBox will create a virtual provider object for you dynamically at runtime, configure it to retrieve a specific type of mapping and then use that for you. The provider namespace will take everything after it and evaluate it as either a named mapping or a full injection DSL string.

For example, inject="provider:MyService" will inject a provider of MyService objects, so it will look for a MyService

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:

Here is an example of how to accomplish this:

WireBox fully supports (AOP) for ColdFusion (CFML) and any ColdFusion framework. Just note the different namespaces if using within the ColdBox Platform and standalone WireBox.

WireBox AOP RefCard

Our will get you up and running in no time.

You can make two CFCs blend together simulating a virtual runtime inheritance with WireBox. WireBox will grab the target CFC and blend into it all of the virtual inheritance CFC's methods and properties. It will then also create a $super reference in the target and a $superinit() reference. This is a great alternative to real inheritance and allow for runtime mixins to occur. You start off by mapping the base or source CFC and then mapping the target CFC and declaring a virtualInheritance to the base or source CFC:

This will grab all methods and properties in the BaseModel CFC and mix them into the UserService, then create a virtual $super scope which will map to an instantiated instance of the BaseModel

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:

You can also use our cool mapping DSL to create mappings that refer to provided objects by using the DSL construction type:

You can use the following mapping methods to map to virtual providers by using their dsl arguments:

• mapDSL()

Now that we have built our aspect we need to register it with WireBox so it knows about it and all DI can be performed in it. Let's open our WireBox binder and use the following DSL method:

• mapAspect(aspect,autoBinding=[true])

This tells WireBox to register a new aspect called MethodLogger that points to the CFC model.aspects.MethodLogger that I have just built. WireBox will then mark that object as an aspect, create it once the injector loads and have it ready for building.

Now I can use the ortus scope in my mappings DSL and even my annotations, isn't that cool!

Inject object providers, please refer to our provider section in this guide.

// using id
property name="timedService" inject="provider:TimedService";

// using DSL
property name="timedService" inject="provider:logbox:logger:{this}";

Now that we have activated the AOP engine, let's build a simple method logger aspect that will intercept before our method is called and after our method is called. So if you remember your AOP dictionary terms, we will create an aspect that does a before and after advice on the method. Phew! To do this we must implement a CFC that WireBox AOP gives you as a template: wirebox.system.aop.MethodInterceptor. This CFC interface looks like this:

<cfinterface hint="Our AOP Method Interceptor Interface">

    <---  invokeMethod --->
    <cffunction name="invokeMethod" output="false" access="public" returntype="any" hint="Invoke an AOP method invocation">
        <cfargument name="invocation" required="true" hint="The method invocation object: wirebox.system.ioc.aop.MethodInvocation">
    </cffunction>

</cfinterface>

This means, that we must create a CFC that implements the invokeMethod method with our own custom code. It also receives 1 argument called invocation that maps to a CFC called wirebox.system.aop.MethodInvocation that you can learn from our cool API.

Our approach to AOP is simplicity, therefore this invokeMethod implements the most powerful advice called around advice, so you will always do an around advice, but it will be up to your custom code to decide what it does before (beforeAdvice), around (aroundAdvice) and after (afterAdvice) the method call.

The other advantage of WireBox AOP aspects is that once they are registered with WireBox they act just like normal DI objects in WireBox, therefore you can apply any type of dependency injection to them.

The scope interface can be found here: coldbox.system.ioc.scopes.IScope.

/**
 * Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp
 * www.ortussolutions.com
 * ---
 * The main interface to produce WireBox storage scopes
 **/
interface {

	/**
	 * Configure the scope for operation and returns itself
	 *
	 * @injector             The linked WireBox injector
	 * @injector.doc_generic coldbox.system.ioc.Injector
	 *
	 * @return coldbox.system.ioc.scopes.IScope
	 */
	function init( required injector );

	/**
	 * Retrieve an object from scope or create it if not found in scope
	 *
	 * @mapping             The linked WireBox injector
	 * @mapping.doc_generic coldbox.system.ioc.config.Mapping
	 * @initArguments       The constructor struct of arguments to passthrough to initialization
	 */
	function getFromScope( required mapping, struct initArguments );


	/**
	 * Indicates whether an object exists in scope
	 *
	 * @mapping             The linked WireBox injector
	 * @mapping.doc_generic coldbox.system.ioc.config.Mapping
	 *
	 * @return coldbox.system.ioc.scopes.IScope
	 */
	boolean function exists( required mapping );

}

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

Explicit Binder Configuration

Explicit Creation

Scan Locations Binder Configuration

Set Locations Creation

Luis Fernando Majano Lainez

Luis Majano is a Computer Engineer, published author, founder, and CEO of Ortus Solutions, Corp (www.ortussolutions.com), a consulting firm specializing in open-sourcing tooling, web development, architecture, and professional open-source.

He has been designing and working with software architecture and technologies since the year 2000. 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.

He is the creator of ColdBox HMVC, ContentBox Modular CMS, TestBox BDD, CommandBox CLI, and over 200 open-source projects. He speaks regularly at several international conferences, and you can read his blog at .

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

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

• His first computer was a Texas Instrument TI-99/4A 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!)

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 , Mexico, he went back to his home country, where he worked as the COO of. 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 a 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 in 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 (Olathe, KS). Today he lives in Kansas City with his wife and three girls, where he still disassembles most of his belongings (including automobiles) with a slightly higher success rate of putting them back together again.) Brad enjoys church, 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 () and likes to work on solder-at-home digital and analog circuits with his daughter and build projects with Arduino-based microcontrollers.

Brad's CommandBox Snake high score is 141.

If you need to abstract old legacy code or have funky construction processes, we would recommend you build your own provider objects. This means that you will create a component that implements wirebox.system.ioc.IProvider (one get() method) and then you can map it. Once mapped, you can use it anywhere WireBox listens for providers:

• The Injection DSL →

property name="" inject="provider:{name or injectionDSL}";

• The mapping DSL

Here is the interface you need to implement:

The CFC you build will need to be mapped so it can be retrieved by name and also so if it needs DI or any other WireBox funkiness, it can get it. So let's look at our FunkyEspressoProvider that we needed to create since we have some old legacy machines that we need to revamp:

Finally we map to the provider using the .toProvider() mapping method in the binder so anytime somebody requests an Espresso we can get it from our funky provider. Please note that I also map the provider because it also has some DI needed.

Cool! That's it, anytime you request an Espresso, WireBox will direct its construction to the provider you registered it with.

In computing, aspect-oriented programming (AOP) is a programming paradigm which aims to increase modularity by allowing the separation of cross-cutting concerns. AOP forms a basis for aspect-oriented software development.

I won't go into incredible software theory but pragmatic examples. What is the value of AOP? What does it solve? Well, how many times have we needed to do things like this:

component name="UserService"{

    function save(){

      log.info("method save() called with arguments: #serializeJSON(arguments)#");

      transaction {
         // do some work here
      }

      log.info("Save completed successfully!");
    }
}

As you can see from the example above, my real business logic is in the //do some work here comment, but our code is littered with logging and transactions. What if I have 10 methods that are very familiarly the same? Do I repeat this same littered code (cross-cutting concerns)? The answer for most of us has always been "YES! Of Course! How else do I do this?".

Well, you don't have to, AOP to the rescue. What AOP will let you do is abstract all that logging and transaction code to another object usually called an Aspect. Then we need to apply this aspect to something right? Well, in our case it has to apply to a target object, our UserService, and to a specific method, save(), which is usually refered to as the join point.

What does applying an aspect mean? It means that we will take that aspect you write and execute it at different points in time during the execution of the method you want to apply it to. This is usually refer to as an advice, "Hey Buddy! Run it here!!!".

There are multiple types of AOP advices like before, around, after, etc. We have seen in ColdBox event handlers that you can do a preHandler, postHandler and and aroundHandler methods. These are AOP advices localized to event handlers that let you execute code before a handler event, after a handler event, or completely around the handler event. The most powerful form of advice is around, as it allows you to completely surround a method call with your own custom code. Does it ring a bell now? The transaction code for Pete's Sake! You need it to completely surround the method call! Voila! The around advice will allow you to completely take over the execution and you can even determine if you want to continue the execution or not.

So how does this magic happen? Well, our WireBox AOP engine will hijack your method (join point) and replace it with a new one, usually called an AOP proxy. This new method has all the plumbing already to allow you to apply as many aspects you like to that specific method. So as you can see from our diagram below, the save method is now decorated with our two aspects, but for all intent and purposes the outside world does not care about it, they just see the save() method.

• Aspect: A modularization of a concern that cuts across multiple objects.

• Target Object : The object that will be applied with Aspects across certain methods or join points.

• Join Point : A point of execution in a target object that will be applied a specific aspect to it. This is usually the execution of a method.

• Advice : An action taken at a particular join point. Usually, before, after or around it.

• AOP Proxy : An object or method representation for the original join point or method.

WireBox has an amazing that can help you modify, listen and do all kinds of magic during object creation, wiring, etc. Our AOP implementation is just a listener that will transform objects once they are finalized with dependency injection. This means, our AOP engine is completely decoupled from the interals of the DI engine and is incredibly fast and light weight. So let's activate it in our WireBox binder configuration:

That's it! That tells WireBox to register the AOP engine once it loads. This listener also has some properties that you can tweak:

To register a custom namespace in WireBox, place the following configuration in the wirebox struct defined within the configure() method of your WireBox binder CFC. in a ColdBox app, this is /config/WireBox.cfc. Alternatively, you can use the mapDSL() call in the configure() method.

component extends="coldbox.system.ioc.config.Binder" {

    function configure(){
        wirebox = {
            // DSL Namespace registrations
            customDSL = {
                ortus = "path.model.dsl.MyDSL"
            }
        };

        // Or here...        
        mapDSL("ortus","path.model.dsl.MyDSL");        
    }
}

If you want to register a custom DSL namespace from a module, you can make the same call via the binder reference that is provided to your ModuleConfig.cfc.

component {
    function configure() {
        binder.mapDSL("ortus","path.model.dsl.MyDSL");
    }
}

Now I can use the ortus DSL Namespace in my mappings DSL and even my annotations, isn't that cool!

Dynamic Custom DSL Registration

Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector.

Here are a list of the most useful methods in this CFC

• getMethod() : Get the name of the method (join point) that we are proxying and is being executed

• getMethodMetadata() : Get the metadata structure of the current executing method. A great way to check for annotations on the method (join point)

• getArgs() : Get the argument collection of the method call

• setArgs() : Override the argument collection of the method call

• getTarget() : Get the object reference to the target object

• getTargetName() : Get the name of the target object

• getTargetMapping() : Get the object mapping of the proxied object. Great for getting metadata information about the object, extra attributes, etc.

• proceed() : This is where the magic happens, this method tells WireBox AOP to continue to execute the target method. If you do not call this in your aspect, then the proxyied method will NOT be executed.

The last method is the most important one as it tells WireBox AOP to continue executing either more aspects, the proxyed method or nothing at all.

You can use the mixins() binder method or mixins annotation to define that a mapping should be mixed in with one or more set of templates. It will then at runtime inject all the methods in those templates and mix them into the target object as public methods.

// map with mixins
map("MyService")
    .to("model.UserService")
    .mixins("/helpers/base");

// map with mixins as list
map("MyService")
    .to("model.UserService")
    .mixins("/helpers/base, /helpers/model");

// map with mixins as array
map("MyService")
    .to("model.UserService")
    .mixins( ["/helpers/base", "/helpers/model"] );


// Via annotation
component mixins="/helpers/base"{

}

This will grab all the methods in the base.cfm and model.cfm templates and inject them into the target mapping as public methods. Awesome right?

Tip The list of templates can include a .cfm extension or none at all

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.

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.

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:

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 injector can be constructed with three optional arguments:

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.

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:

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

In ColdBox, you will create to listen to any event in the application. Each of these methods that listen to events receive the following arguments:

WireBox 2.0.0 supports entity injection via

• - for use in ColdBox applications

• Custom ORM Event Handler - for use in any CFML application

Overview

Welcome to the world of hierarchical dependency injection. We had the ability before to add a parent injector to WireBox, but 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

WireBox supports the concepts of component property observers. Meaning that you can define a function that will be called for you when the setter for that property has been called and thus observe the property changes within a component.

You will accomplish this by tagging a property with an annotation called observed and created a function called: {propertyName}Observer by convention. This function will receive three arguments:

• newValue

WireBox has an amazing that can help you modify, listen and do all kinds of magic during object creation, wiring, etc. Our AOP implementation is just a listener (wirebox.system.aop.Mixer) that will transform objects once they are finalized with dependency injection. This means, our AOP engine is completely decoupled from the internals of the DI engine and is incredibly fast and light weight.

So let's activate it in our WireBox binder configuration:

That's it! That tells WireBox to register the AOP engine once it loads. This listener also has some properties that you can tweak:

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 injection DSL (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!

So let's build our unit test (Please note we use our base ColdBox testing classes for ease of use and integration):

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

We also provide an interface to create objects that adhere to our injector interface: wirebox.system.ioc.IInjector.

Then these objects can be used as parent injectors, which are great for legacy factories or creating hierarchies according to your specs. All you have to do is implement the following interface:

Once you create this CFC that implements this interface then you can call on the injector's setParent() method and you are ready to roll.

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

Populate a bean from a JSON string

Returns

• This function returns any

Arguments

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

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

In standalone mode, the listener is a simple CFC with a configure() method and any methods that match the name of the events. Each of these methods receive the following arguments:

Talk and get objects from the current WireBox injector.

1st Level DSL

WireBox's offers a wide gamut of life cycle events that are announced at certain points in execution time. Below are the current events announced by the Injector wirebox.system.ioc.Injector.

Populate a bean from a query

Returns

* This function returns Any

Here is my MethodLogger aspect that I will create:

You can see that I do some DI via annotations:

A normal constructor with one optional argument for logging results:

And our invokeMethod implementation:

As you can see, the before advice part is what happens before the execution of the real method (or more aspects) occurrs. So everything before the call to arguments.invocation.proceed():

Then we execute the real method or more aspects (we do not do anything around the method call):

Populates an Object using only specific columns from a query. Useful for performing a query with joins that needs to populate multiple objects.

Returns

• This function returns any