Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This minor release brings in some major performance enhancements for the way WireBox maps and creates objects. We highly encourage upgrading to it.
If you are using annotations for component aliases you will have to tell WireBox explicitly to process those mappings. As by default, we no longer process mappings on startup.
[WIREBOX-84] - Remove auto processing of all mappings defer to lazy loading
[WIREBOX-85] - MapDirectory
new boolean argument process
which defers to false, if true, the mappings will be auto processed
[WIREBOX-86] - New binder method: process()
if chained from a mapping, it will process the mapping's metadata automatically.
[WIREBOX-87] - AOP debug logging as serialized CFCs which clogs log files
WireBox is an enterprise ColdFusion Dependency Injection and Aspect Oriented Programing (AOP) framework. This project has been part of ColdBox since its early version 2.0 releases but it is also a standalone library that can be used in ANY ColdFusion application or 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 maintained under the Semantic Versioning guidelines as much as possible.Releases will be numbered with 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 bumps the minor (and resets the patch)
Bug fixes and misc changes bumps the patch
The ColdBox Platform, WireBox is open source and licensed under the Apache 2 License.
Copyright by Ortus Solutions, Corp
ColdBox is a registered trademark by Ortus Solutions, Corp
Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.
The WireBox help and discussion group can be found here: https://groups.google.com/forum/#!forum/coldbox
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
By Email: bugs@coldbox.org
ColdBox is a professional open source software backed by Ortus Solutions, Corp offering services like:
Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews
Much More
Official Site: https://www.coldbox.org
Source Code: https://github.com/coldbox/coldbox-platform
Bug Tracker: https://ortussolutions.atlassian.net/browse/WIREBOX
Twitter: @coldbox
Facebook: https://www.facebook.com/coldboxplatform
Google+: https://www.google.com/+ColdboxOrg
Vimeo Channel: https://vimeo.com/channels/coldbox
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
WireBox is an enterprise ColdFusion Dependency Injection and Aspect Oriented Programing (AOP) framework. This project has been part of ColdBox since its early version 2.0 releases but it is also a standalone library that can be used in ANY ColdFusion application or 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
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
Copyright by Ortus Solutions, Corp
ColdBox is a registered trademark by Ortus Solutions, Corp
Info: The ColdBox Websites, Documentation, logo and content have a separate license and they are a separate entity.
ColdBox is a professional open source software backed by Ortus Solutions, Corp offering services like:
Custom Development
Professional Support & Mentoring
Training
Server Tuning
Security Hardening
Code Reviews
Much More
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
[] - builder.toVirtualInheritance(): scoping issues
[] - When using sandbox security, and using a provider DSL the file existence checks blow up
[] - Account for leading slashes in mapDirectory()
[] - Throw a nicer DSL error if ColdBox is not linked
[] - Some improvements for the construction of transients
WireBox is maintained under the guidelines as much as possible.Releases will be numbered with the following format:
The ColdBox Platform, WireBox is open source and licensed under the License.
The WireBox help and discussion group can be found here:
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:
By Email:
By Jira:
Official Site:
Source Code:
Bug Tracker:
Twitter:
Facebook:
Google+:
Vimeo Channel:
This release is part of the ColdBox 4.2.0 update and contains the following updates:
[WIREBOX-49] - Closure-based providers don't work as documented
[WIREBOX-44] - Add a force
argument to the mapDirectory()
binder method
[WIREBOX-47] - Influence instance build via closure in the binder
[WIREBOX-3] - Add better checks for file system write permissions
[WIREBOX-45] - Update the documentation URL in box.json
[WIREBOX-50] - Pass injector
to closure-based providers
This release is part of the ColdBox 5.0.0 upgrade and it is a major release. Below you will find the major areas of improvement for WireBox and the full release notes.
We have done greats strides in consistency of error reporting during the creation of objects and their wiring. We have also added countermeasures for rogue mappings that could bring entire applications down. You will now get more consistency and better error reporting overall.
AOP now performs in over 70% faster than previous implementations. In previous versions, we would create intermediate class files that would then be loaded and injected as part of the AOP proxies. This took time and not only that, it would create 1 stub per call to a method implementation. Our strategy worked but lacked performance. In 5.0.0 we completely re-architected the way we did method injection and stub creation. We now take md5 hashes of the source code to be injected and only created the stubs 1 per-lifetime. The improvements are drastic and amazing. Enjoy AOP and don't hold back!
We have moved from an instance
scope approach to a variables
scope approach with accessors and mutators in 5.0.0 and yet again we benefit from CFML engine speed improvements. Again, thanks to the community for many pull requests.
We have completely re-engineered virtual inheritance in 5.0.0 and it behaves eerily similar to traditional inheritance at the dynamic level. Not only do we cover public methods like we used to, but also private methods and object state. You can also leverage AOP with virtual inheritance now which was a limitation in the previous version.
We have also added the capability to inherit implicit getters and setters from parent classes.
You now can register listeners on-demand with WireBox via the registerListener( listener )
method in the Injector.
onLoad(), onShutdown()
Binder CallbacksAny WireBox binder can now have two new callback methods onLoad(), onShutdown()
. The onLoad()
is called once WireBox has loaded with logging, caching, and the configure()
on the binder has been called. You can use this for leveraging mapDirectory()
calls which require the entire event system to be online or any other type of execution that leverages the entire machinery to be online.
The onShutdown()
callback is a nice way to shutdown services as you see fit.
The new WireBox Binder object is also an interceptor now. So you can create functions that listen to the entire DI/AOP process. Please see the events sections.
[WIREBOX-29] - Virtual inheritance breaks AOP on on base class methods.
[WIREBOX-52] - Virtual Inheritance doesn't inherit variables-scoped properties
[WIREBOX-63] - CFC's with same name don't get aliases picked up with mapDirectory()
[WIREBOX-64] - Illusive double id exception when race conditions
[WIREBOX-58] - Allow new listeners added to the Binder to also be registered right away, especially from modules
[WIREBOX-62] - New request context dsl injection -> coldbox:requestContext
[WIREBOX-67] - New coldbox dsl element => coldbox:router to retrieve the application's router object.
[WIREBOX-68] - Virtual Inheritance now copies over properties and private functions with generic accessors
[WIREBOX-69] - Module Injection Shortcut when the inject annotation is @moduleAdress
[WIREBOX-70] - Add a new onLoad()
method interceptor for WireBox configuration binder
[WIREBOX-72] - Make the Binder also an interceptor
[WIREBOX-73] - Add a new onShutdown()
method interceptor for WireBox configuration binder
[WIREBOX-28] - Improve errors while building depenencies
[WIREBOX-34] - Improve AOP binding by caching temp files
[WIREBOX-59] - Throw error on non-existent coldbox DSL
[WIREBOX-65] - Increase Wirebox performance by scoping variables
[WIREBOX-66] - Complete refactoring of wirebox scopes/DSL to script and direct scope usage
[WIREBOX-71] - Ability to cache metadata in CacheBox
WireBox 2.0.0 is a major release of our Dependency Injection and AOP library with some major fixes and some cool new updates.
You can find the release version information here: https://ortussolutions.atlassian.net/browse/WIREBOX/fixforversion/12300
Bugs
[WIREBOX-31] -Builder.buildDSLDependency does not use the custom DSL correctly as the default namespace kicks in
Improvements
[WIREBOX-32] -binder.mapDirectory now skips hidden dirs
[WIREBOX-35] -Remove coldbox:cacheManager DSL reference, it is no longer valid
New Features
[WIREBOX-2] -allow mapDSL to be altered at runtime by modules via new wirebox method: registerDSL()
[WIREBOX-30] -Support wiring new injection DSL = byType, which leverages the type to match to an implementation
[WIREBOX-33] -Add a force argument to the map functions so you can override if a mapping already exists
[WIREBOX-36] -New coldbox dsl to get a renderer reference: coldbox:renderer
The ColdBox injection DSL has had major updates to get to the ColdBox 4 standards.
All ocm injections have been removed in preference to
cachebox injection DSL
The coldbox:cachemanager DSL has been removed in preference to
cachebox injection DSL
All plugin injections have been deprecated in preference to
model/object injections
New coldbox:renderer dsl to inject the new ColdBox system
renderer
The map() function on the Configuration Binder now has a force argument which allows you to map no matter if the mapping exists or not already.
Injectors allow you to register custom DSLs at runtime by using the registerDSL() method on any injector. This feature was mostly done for modules, so they could enhance WireBox in a ColdBox context. However, this also allows you to leverage this in any non-ColdBox applications.
We have expanded our custom DSL and injectors to allow you to do injection by ColdFusion types. This feature is more in-line with features from Java or static languages were you can tell injectors to inject by argument or property type. Let's say you have a package of interfaces with subpackages of implementations:
You then want to rely on the interface type field of properties in my dependent CFCs and leveraging the byType injection DSL. You would first map the right implementation using the alias as the name of the Interface.
The majority of code examples in this book are done in cfscript
.
Flash, Flex, ColdFusion, and Adobe are registered trademarks and copyrights of Adobe Systems, Inc. Railo is a trademark and copyright of Railo Technologies, GmbH.
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.
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.
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 generation and running of examples are done via CommandBox: The ColdFusion (CFML) CLI, Package Manager, REPL -
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.
15% 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 () 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 werecame on their own, churches and the government brought children to them for care, and the Shalom Children’s Home was founded.
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 Rancho Cucamonga, California 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
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 persuit 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 Cristian 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
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
So our recommendation is to always try to create configuration binders as best practice, but your requirements might dictate something else.
Approach | Motivation | Pros | Cons |
Implicit Mappings | To replace | Very natural as you just request an object by its instantiation path. Very fast prototyping. | Refactoring is very hard as code is plagued with instantiation paths everywhere. Not DRY. |
Explicit Mappings | To replace | DRY, you can create multiple named mappings that point to the same blueprint of a class. Create multiple iterations of the same class. Very nice decoupling. | Not as fast to prototype as we need to define our mappings before hand in our configuration binder. |
Scan Locations | CFC discovery by conventions | A partial instantiation path(s) or folder(s) are mapped so you can retrieve by shorthand names. Very quick to prototype also without using full instantiation paths. Override of implementations can be easily done by discovery. | Harder concept to digest, not as straightforward as implicit and explicit locations. |
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 MockBox integration):
Now we can run our tests and verify that our coffee shop is operational and producing sweet sweet espresso!
In all reality we could be building our objects and its dependencies, object graph, 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.
The Binder is also the way you configure WireBox for operation.
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.
The best way to install WireBox is using CommandBox CLI and package manager.
Adobe ColdFusion 11+
Lucee 4.5+
You can leverage CommandBox to install the standalone version of WireBox with a simple command:
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
.
You can download the latest version of WireBox from https://www.coldbox.org/download#wirebox. Place in your webroot or create a /wirebox
mapping in your system.
wirebox.system.ioc
coldbox.system.ioc
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.
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
If you require any training please contact us.
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.
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
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.
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
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.
Caution If you use a persistence scope that expires after time like session, request, cachebox, etc, you will experience a side effect called scope widening injection. WireBox offers a solution to this side effect via WireBox Providers, which we will cover in detail.
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.
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.
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
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
We verify that the scope define for the mapping exists, else we throw an invalid scope exception
We ask the scope to produce the mapping object for us. The scope is in charge of persistence, locking, etc.
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.
The scope then sends the instance for DI wiring and process back to the injector
The injector returns the instance
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.
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).
If the builder could not produce an instance, it is logged and DI is skipped on it.
Caution Circular dependencies are supported in all injection styles within WireBox. With one caveat, if you choose constructor arguments with circular dependencies, you must use object providers.
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.
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:
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.
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
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:
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
The latter approach will be less verbose when talking to the mapping DSL the Binder object exposes. However, both are fully functional and matter of preference.
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.
Please also note that the Binder itself has a reference to the current Injector it belongs to (getInjector()
).
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:
this.TYPES
: A reference to wirebox.system.ioc.Types
used to declare what type of object you are registering for construction or wiring
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
Scope | Description |
| A prototype object that gets created every time it is requested. |
| A prototype object that gets created every time it is requested. |
| Only one instance of the object exists |
| The object will exist in the session scope |
| The object will exist in the application scope |
| The object will exist in the request scope |
| The object will exist in the server scope |
|
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
A object will be time persisted in any cache provider
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 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:
Initiators - Start the mapping DSL process
Modifiers - Can modify a mapping with metadata and behavior
Destinations - Tells the binder to what object or behavior we should map to.
If a mapping does not have a destination, then the information stored in the chain can bleed into other mappings.
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:
Caution From the methods we have seen above only the map()
and with()
methods require a DSL destination.
Method Signature
Description
cacheBox([configFile],[cacheFactory],[enabled],[classNamespace])
The method used to configure the injector's CacheBox integration. Ignored in an application context
listener</b>(class,[properties],[name])
The method used to register a new listener within the injector's event manager
logBoxConfig</b>(config)
The method used to tell the injector which LogBox configuration file to use for logging operations. Ignored in an application context
mapDSL(namespace,path)
The method used to register a new DSL annotation namespace with a DSL Builder object
mapScope(annotation,path)
The method used to register a new custom scope in this injector
parentInjector(injector)
Register a CFC reference to be the parent injector for the configuring injector
removeScanLocations(locations)
A method used to remove one or a list (array) of scan locations from the configuration binder
reset()
Reset the entire configuration binder to factory defaults
scanLocations(locations)
A method used to add one or a list (array) of scan locations to the configuration binder. If a path already exists it will not be appended again.
scopeRegistration(enabled,scope,key)
This method is used to tell the Injector if it should auto-register itself in any ColdFusion scope automatically
stopRecursions(classes)
A method used to register one or a list (array) of class paths the injector will look out for when discovering DI metadata. If these classes are found in the inheritance chain of an object, the injector will not process that inherited chain
Method Signature | Description |
| The method that starts the mapping process. You pass in a mapping name or a list of names to start registering |
| Map a CFC instantiation path. This method internally delivers a two-fold punch of doing |
| A cool method that tells WireBox to automatically register ALL the CFCs found recursively in that instantiation package path. All CFCs will be registered using their CFC names as the mapping names and WireBox will inspect all the CFCs immediately for DI metadata. The include and exclude arguments can be used for inclusions/exclusions lists via regex. The influence argument can be a UDF or closure that will affect the iterating registrations of objects. The filter argument can be a UDF or closure that will filter out or in the CFCs found, an include/exclude on steroids |
| Unmap/delete a mapping in the binder |
| This method is a utility method that retrieves the alias mapping so you can start concatenating methods for that specific mapping. Basically putting it into a workable context |
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.
Please note that it is completely optional to use the implicit structure configuration. You can use the programmatic methods instead. Each configuration key has the same method in the binder for programmatic configuration.
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.
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:
This structure tells WireBox how to leach itself into any ColdFusion scope when initialized instead of you placing it in the scope.
Caution Scope registration must be enabled in order for Providers to work.
Please refer to the Custom DSL section to find out more about custom DSLs, the following are just the way you declare them:
Please refer to the Custom scopes section to find out more about custom scopes, the following are just the way you declare them:
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.
Please note that order of declaration is the same as order of lookup, so it really matters. Also note that this setting only makes sense if you do not like to create mappings for objects and you just want WireBox to discover them for you.
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.
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.
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.
Caution Please note that order of declaration is the same as order of execution, so it really matters, just like ColdBox Interceptors. Please note that if you are using WireBox within a ColdBox application, you can also register listeners as interceptors in your ColdBox configuration file.
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:
Caution Please note that WireBox can create different types of objects for DI. However, only CFCs will be inspected for autowiring automatically unless you specifically tell WireBox that a certain mapping should not be autowired. In this case you will use the dependencies DSL to define all DI relationships.
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
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.
Caution Please note that by leveraging scopes that can expire such as cachebox,request,session,applications,etc you must take into account the way they are injected into other objects. They can experience a DI side effect called scope widening injection that can link an object reference that expires into another object reference that does not expire (like singleton). This causes nasty side effects and issues, so please refer to the WireBox Providers section to find out how you can avoid this nasty pitfall by using WireBox providers.
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.
Method Signature
Description
to(path)
Maps a name to a CFC instantiation path
toDSL(dsl)
Maps a name to DSL builder string. Construction is done by using this DSL string (Look at Injection DSL)
toFactoryMethod(factory,method)
Maps a name to another mapping (factory) and its method call. If you would like to pass in parameters to this factory method call you will use the methodArg()
DSL method concatenated to this method call
toJava(path)
Maps a name to a Java class that can be instantiated via createObject("java")
toProvider(provider)
Maps a name to another mapping (provider) that must implement the WireBox Provider interface (coldbox.system.ioc.IProvider
)
toRSS(path)
Maps a name to an atom or RSS URL. WireBox will then use the cffeed
tag to construct this RSS feed. It builds out into a structure with two keys: metadata : The metadata of the feed items : The items in the feed
toValue(value)
Maps a name to a constant value, which can be ANYTHING.
toWebservice(path)
Maps a name to a webservice WSDL URL. WireBox will create the webservice via createObject("webservice")
for you.
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.
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:
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!
Method Signature | Description |
asSingleton() | Maps an object to the WireBox internal Singleton scope |
into(scope) | Maps an object to a valid WireBox internal scope or any custom registered scopes by using the registered scope name. Valid internal WireBox scopes are: NOSCOPE PROTOTYPE SINGLETON SESSION APPLICATION REQUEST SERVER CACHEBOX |
inCacheBox([key='mappingName'],[timeout],[lastAccessTimeout],[provider='default']) |
asEagerInit() | Maps an object to be created immediately once the Injector is created. By default all object mappings are lazy loaded in construction. |
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.
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:
Here is an example of adding some nice pizzazz to an 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.
Maps an object to the integrated instance
Method Signature
Description
constructor(constructor)
Tells WireBox which constructor to call on the mapped object. By default if an object has an init()
method, that will be used as the constructor
noInit()
Tells WireBox that this mapped object will skip the constructor call for it. By default WireBox always calls object constructors
threadSafe()
Tells WireBox that the mapped object should be constructed and then wired with a strict concurrency lock for property injections, setter injections and onDIComplete(). Please be aware that if you use this mode of construction, circular dependencies are not allowed. The default is that property and setter injections and onDIComplete() are outside of the construction locks
notThreadSafe()
Tells WireBox to construct objects by locking only the constructor and constructor argument dependencies to allow for circular dependencies. This is the default construction mode of all persisted objects: singleton, session, server, application and cachebox scope
noAutowire()
Tells WireBox that this mapped object has its dependencies described programmatically instead of using metadata inspection to discover them
parent(alias)
Tells WireBox that this mapped object has a parent mapping with definitions it should use to base it from. This feature provides a great way to reuse object mapping definitions
initArg([name],[ref],[dsl],[value],[javaCast])
Used to define a constructor argument for the mapped object.
name
: The name of the constructor argument. Not used for Java or Webservice construction
ref
: The mapping reference id this constructor is mapped to. E.G. ref='MyFunkyEspresso'
dsl
: The construction dsl that will be used to construct this constructor argument
value
: The constant value you can use instead of a dsl or ref for this constructor argument
javaCast
: If using a java object, you can cast the value of this constructor argument
initWith()
You can pass as many arguments (named or positional) to this method to simulate the init()
call of the mapped object. WireBox will then use that argument collection to initialize the mapped object. Note, initWith()
only accepts arguments which can be evaluated at the time the binder is parsed such as static values, or binder properties. To specify mapping IDs or DSLs, use `initArg()
methodArg([name],[ref],[dsl],[value],[javaCast])
Used to define a factory method argument for the mapped object when using a factory method construction.
name
: The name of the method argument. Not used for Java or Webservice construction
ref
: The mapping reference id this method argument is mapped to. E.G. ref='MyFunkyEspresso'
dsl
: The construction dsl that will be used to construct this method argument
value
: The constant value you can use instead of a dsl or ref for this method argument
javaCast
: If using a java object, you can cast the value of this method argument
property([name],[ref],[dsl],[value],[javaCast],[scope])
Used to define a property mixin that will occur at runtime.
name
: The name of the property value to inject. Not used for Java or Webservice construction
ref
: The mapping reference id this property is mapped to. E.G. ref='MyFunkyEspresso'
dsl
: The construction dsl that will be used to construct this property argument
value
: The constant value you can use instead of a dsl or ref for this property argument
javaCast
: If using a java object, you can cast the value of this property argument
scope
: The scope inside the CFC this property will be injected too. The default scope is the variables
scope.
setter([name],[ref],[dsl],[value],[javaCast],[argName])
Used to define all the setter dependencies for a mapped object that follows the JavaBean spec: setXXX
where XXX
is the name of the mapped object.
name
: The name of the setter. Not used for Java or Webservice construction
ref
: The mapping reference id this setter is mapped to. E.G. ref='MyFunkyEspresso'
dsl
: The construction dsl that will be used to construct this setter dependency
value
: The constant value you can use instead of a dsl or ref for this setter dependency
javaCast
: If using a java object, you can cast the value of this setter dependency
argName
: The name of the argument to use, if not passed, we default it to the setter name.
mixins(udfIncludeList)
A UDF template, a list of templates or an array of templates that WireBox should use to mix-in into the target object. It will take all the methods defined in those UDF templates and mixed them into the target object at runtime.
providerMethod(method,mapping)
Will inject a new method or override a method on the target object with a new method that provides objects of the mapping you specify.
virtualInheritance(Mapping)
Create a runtime virtual inheritance from a target object into a target mapping. This approach blends the CFCs together at runtime via mixins and WireBox Funkyness!
extraAttributes(struct)
Allows the ability to store extra metadata about a mapping into WireBox that can later be retrieved via AOP invocations or WireBox events.
withInfluence( closure/UDF )
Influence the creation process of a single object. The instance is already built and then passed into the closure for additional influence. You can optionally return the object and it will override it.
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.
However, you can explicitly process a mapping right after mapping it via the binder's process()
method.
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.
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.
A part from using the configuration binder, you can also leverage component annotations to dictate behavior on the object.
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.
Annotation
Type
Description
autowire
boolean
All objects are marked as autowire=true, so if you want to disable autowiring, you can add this annotation as false. You do NOT need to add this annotation if you want to autowire it, it is redundant if you do.
alias
string
A list of aliased names you can attach to a CFC instance apart from its Component name. This is great when using the mapDirectory()
binder function.
eagerInit
none
All objects are lazy loaded unless they are marked with this annotation or marked as eager init in the binder configuration.
threadSafe
none or boolean
Determines the locking construction of the object for its wiring of dependencies. Please see our Object Persistence & Thread Safety Section.
scope
string
A valid WireBox scope or a custom registered scope. Remember that ALL components by default are placed in the NO SCOPE scope. This means they are considered transient objects.
singleton
none
Marks a component as a singleton object.
cachebox
string
Marks a component to be stored in CacheBox. The value of this annotation should be a valid registered CacheBox cache provider. The default cache provider is called default
cache
boolean
Marks a component to be cached in CacheBox in the default provider.
cacheTimeout
numeric
The timeout in minutes when the object is stored in the CacheBox provider
cacheLastAccessTimeout
numeric
The timeout in minutes when the object is stored in the CacheBox provider
mixins
list
A list of UDF templates to mixin into the object
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.
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.
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:
The injector can be constructed with three optional arguments:
If you are using WireBox within a ColdBox application, you don't even need to do any of this, we do it for you by using some configuration data in your ColdBox configuration file or conventions.
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. Below is a nice chart that showcases the WireBox injection styles, but we really encourage you to review our dependency injection section to learn the different approaches to DI, their values, and when to use them.
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.
Note Whichever injection style you use with WireBox, the target's visibility does not matter. This means that you can create private or package methods and WireBox will still inject them for you. This is absolutely great when you are an encapsulation freak and you do not want to expose public setter methods.
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:
With a Configuration Binder:
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.
The default namespace is not specifying one. This namespace is used to retreive either named mappings or full component paths.
When WireBox builds CFC instances, it is important to know the order of operations. This controls when injected dependencies are available for you to use.
Component is instantiated with createObject()
CF automatically runs the pseudo constructor (any code outside the a method declaration)
The init()
method is called (if it exists), passing any constructor args
Property (mixin) and setting injection happens
The onDIComplete()
method is called (if it exists)
Based on that order, you can see that injected dependencies (except constructor ones) are not available yet to use in the init()
and you must wait to use them in the onDIComplete()
method.
Inject object providers, please refer to our in this guide.
Argument
Type
Required
Default
Description
binder
instance or instatiation path
false
wirebox.system.ioc.config.DefaultBinder
The binder instance or instantiation path to be used to configure this WireBox injector with
properties
struct
false
structnew()
A structure of name value pairs usually used for configuration data that will be passed to the binder for usage in configuration.
coldbox
coldbox.system.web.Controller
false
null
A reference to the ColdBox application context you will be linking the Injector to.
Style
Order
Motivation
Comments
Constructor
First
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
CFProperty
Second
Great documentable approach to variable mixins to reduce getter/setter verbosity
Leverages the greatest aspect of ColdFusion, 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
Third
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.
DSL | Description |
empty | Same as saying id. Get a mapped instance with the same name as defined in the property, argument or setter method. |
id | Get a mapped instance with the same name as defined in the property, argument or setter method. |
id:{name} | Get a mapped instance by using the second part of the DSL as the mapping name. |
id:{name}:{method} | Get the {name} instance object, call the {method} and inject the results |
model | Get a mapped instance with the same name as defined in the property, argument or setter method. |
model:{name} | Get a mapped instance by using the second part of the DSL as the mapping name. |
model:{name}:{method} | Get the {name} instance object, call the {method} and inject the results |
@module | Get the object from a specific module. The name of the alias is from the property used |
DSL | Description |
provider | Build an object provider that will return the mapping according to the property, method or argument name. |
provider:{name} | Build an object provider that will return the {name} mapping. |
provider:{injectionDSL} | Build an object provider that will return the object that the {injectionDSL} refers to |
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.
Every cfproperty
can be annotated with our injection annotations:
@inject
: The injection DSL
@scope
: The visibility scope to inject the dependency into. By default it injects into variables
scope
You can also use annotated constructor arguments with the inject annotation.
Caution In full script components, annotating inline arguments is broken in Adobe ColdFusion 9. You will have to annotate them via the alternative annotation syntax in ColdFusion 9 via the javadocs style comments.
You can also annotate setter methods with the inject annotation to provide injections
WireBox offers a wide gamut of annotation namespaces you can use in your CFML applications and ColdBox applications. However, we took it a step further and allowed you to create your own custom DSL namespaces making your annotations come alive!
Talk and get objects from the current wirebox injector
In order to use this namespace you will need the cborm
module installed in your application: install cborm
Gives you the ability to easily inject base orm services or binded virtual entity services for you:
This DSL namespace is only active if using CacheBox or a ColdBox application context.
Interact with Java directly
This DSL namespace interacts with the loaded LogBox instance.
DSL
Description
wirebox
Get a reference to the current injector
wirebox:parent
Get a reference to the parent injector (if any)
wirebox:eventManager
Get a reference to injector's event manager
wirebox:binder
Get a reference to the injector's binder
wirebox:populator
Get a reference to a WireBox's Object Populator utility
wirebox:scope:{scope}
Get a direct reference to an internal or custom scope object
wirebox:properties
Get the entire properties structure the injector is initialized with. If running within a ColdBox context then it is the structure of application settings
wirebox:property:{name}
Retrieve one key of the properties structure
DSL
Description
entityService
Inject a BaseORMService object for usage as a generic service layer
entityService:{entity}
Inject a VirtualEntityService object for usage as a service layer based off the name of the entity passed in.
DSL
Description
cachebox
Get a reference to the application's CacheBox instance
cachebox:{name}
Get a reference to a named cache inside of CacheBox
cachebox:{name}:{objectKey}
Get an object from the named cache inside of CacheBox according to the objectKey
DSL | Description |
java:{class} | Get a reference or instantiate the java {class} for you. |
DSL | Description |
logbox | Get a reference to the application's LogBox instance |
logbox:root | Get a reference to the root logger |
logbox:logger:{category name} | Get a reference to a named logger by its category name |
logbox:logger:{this} | Get a reference to a named logger using the current target object's path as the category name |
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
.
Note Please see our CacheBox documentation to see all of CacheBox's events.
WireBox also sports a very nice event model that can announce several object life cycle events. You can listen to these events and interact with WireBox at runtime very easily, whether you are in standalone mode or within a ColdBox application.
Note If you are within a ColdBox application, you get the benefit of all the potential of ColdBox Interceptors and if you are in standalone mode, well, you just get the listener and that's it.
Each event execution also comes with a structure of name-value pairs called interceptData
that can contain objects, variables and all kinds of data that can be useful for listeners to use. This data is sent by the event caller and each event caller decides what this data sent is. Also, remember that WireBox also can be ran with a reference to CacheBox, which also offers lots of internal events that you can tap into. So let's start investigating first the object life cycle events.
We have already seen in our previous section all the events that are announced by WireBox, but how do we listen? There are two ways to build WireBox listeners because there are two modes of operations, but the core is the same.
Listeners are simple CFCs that must create methods that match the same name of the event they want to listen to.
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 are that the configure
method for the standalone WireBox is different.
Please note the configure()
method in the standalone listener. This is necessary when you are using Wirebox listeners outside of a ColdBox application. The configure()
method receives two parameters:
injector
: An instance reference to the calling Injector where this listener will be registered with.
properties
: A structure of properties that passes through from the configuration file.
As you can see from the examples above, each Listener component can listen to multiple events. Now you might be asking yourself, in what order are these listeners executed in? Well, they are executed in the order they are declared in either the ColdBox configuration file as interceptors or the WireBox configuration file as listeners.
Caution Order is EXTREMELY important for interceptors/listeners. So please make sure you order them in the declaration file.
So let's say that we want to listen on the beforeInjectorShutdown and on the afterInstanceCreation event in our listener.
If you are running WireBox within a ColdBox application, listeners are and you declare them and register them exactly the same way that you do with normal interceptors.
Event
Data
Description
afterInjectorConfiguration
injector : The calling injector reference
Called right after the injector has been fully configured for operation.
beforeInstanceCreation
mapping : The mapping called to be created
Called right before an object mapping is built via our internal object builders or custom scope builders.
afterInstanceInitialized
mapping : The mapping called to be created
Called after an object mapping gets constructed and initialized. The mapping has NOT been placed on a scope yet and no DI/AOP has been performed yet
afterInstanceCreation
mapping : The mapping called to be created
Called once the object has been fully created, initialized, stored, and DI/AOP performed on it. It is about to be returned to the caller via its getInstance() method.
beforeInstanceInspection
mapping : The mapping that is about to be processed.
Called whenever an object has been requested and its metadata has not been processed or discovered. In this interception point you can influence the metadata discovery.
afterInstanceInspection
mapping : The mapping that is about to be processed.
Called after an object mapping has been completely processed with its DI metadata discovery. This is your last chance to change or modify the DI data in the mapping before it is cached.
beforeInjectorShutdown
injector : The calling injector reference
Called right before the Injector instance is shutdown.
afterInjectorShutdown
injector : The calling injector reference
Called right after the Injector instance is shutdown.
beforeInstanceAutowire
injector : The calling injector reference
Called right after the instance has been created and initialized, but before DI wiring is done.
afterInstanceAutowire
injector : The calling injector reference
Called right after the instance has been created, initialized and DI has been completed on it.
DSL
Description
coldbox
Get the coldbox controller reference
DSL
Description
coldbox:configSettings
Get a reference to the application's configuration settings
coldbox:dataMarshaller
Get a reference to the application's data marshaller
coldbox:flash
Get a reference to the application's flash scope object
coldbox:fwSetting
Get a reference to the framework settings
coldbox:handlerService
Get a reference to the handler service
coldbox:interceptorService
Get a reference to the interceptor service
coldbox:loaderService
Get a reference to the loader service
coldbox:moduleService
Get a reference to the ColdBox Module Service
coldbox:requestContext
Get a reference to the current transient request context
coldbox:requestService
Get a reference to the request service
coldbox:router
Get a reference to the application router object
coldbox:routingService
Get a reference to the routing service
coldbox:renderer
Get a reference to a ColdBox renderer object
DSL
Description
coldbox:fwSetting:{setting}
Get a setting from the ColdBox settings instead of the Application settings
coldbox:setting:{setting}
Get the coldbox application {setting} setting and inject it
coldbox:setting:{setting}@{module}
Get the coldbox application {setting} from the {module} and inject it
coldbox:interceptor:{name}
Get a reference of a named interceptor {name}
coldbox:moduleSettings:{module}
Inject the entire {module} settings structure
coldbox:moduleConfig:{module}
Inject the entire {module} configurations structure
Argument | Type | Execution Mode | Description |
interceptData | struct | standalone-coldbox | The data structure passed in the event |
Argument | Type | Execution Mode | Description |
event | coldbox.system.web.context.RequestContext | coldbox | The request context of the running request |
interceptData | struct | standalone-coldbox | The data structure passed in the event |
buffer | coldbox.system.core.util.RequestBuffer | ColdBox | A request buffer object for producing elegant content in ColdBox applications |
rc | struct | coldbox | Reference to the |
prc | struct | coldbox | Reference to the |
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 →
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.
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.
You need to access scoped objects that might need reconstruction. Maybe you want to check the cache first for existence or a ColdFusion scope in order to avoid scope widening injection.
You have some old legacy funkiness for building stuff that has to remain as its own factory.
All of these areas are where WireBox Providers can really save the day. WireBox offers an automatic way to create providers for you by creating generic provider classes (wirebox.system.ioc.Provider
) that will be configured to provide the mapping you want, then injected instead of the real object requested.
This happens whenever you use the provider DSL injection namespace or annotate methods with a provider
annotation. It also gives you an interface (wirebox.system.ioc.IProvider
), which is very simple, which you can implement in order to register your own complex providers with WireBox.
You would usually do the latter if you have legacy code you need to abstract out, had funky construction processes, etc. Let's start by looking at how registering custom providers works first and then how to use the automatic WireBox providers.
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:
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
ID in the binder. However, you can also get mega funky and do this: inject="provider:logbox:logger:{this}"
and WireBox will create a provider of logbox:logger:{this}
.
Caution Remember that the value of the provider can be a simple ID or a full injection DSL.
That's it! You basically use the provider:{mapping}
injection DSL to tell a property, setter or argument that you want a provider object instead of the real deal. This will allow you to delay construction of such an object or avoid the nasty pitfall of scope widening injection.
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()
mapDSL()
property(name="",dsl="")
setter(name="",dsl="")
methodArg(name="",dsl="")
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.
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!
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.
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:
That is great, but you can proxy calls into the provider itself by removing the extra get()
call and doing this:
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.
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.
→ Scope Widening Injection Solution: Object Providers
Below is my favorite approach to solving the issue which is by using provided methods:
That's it! My getUser()
method will be replaced by WireBox with a proxy provider method that will request from the WireBox injector the user mapping instance.
While the injector can help in many ways to secure the creation of your objects, it is ultimately up to you to create code that is both thread safe and tested. It is always a great idea to design your objects without the injector in mind for threading and concurrency.
DI is not a silver bullet, but a tool to relieve object creation and not to relieve the burden of good object design. Thread safety is much more complex and can be compromised when using persistent scopes like singleton, session, server, application and cachebox, as more than one thread will be trying to access your code and dependencies.
The only guarantee the injector can provide is the constructor and constructor dependency creation to be completely locked. The following object is to be guaranteed to be locked when created and wired with dependencies:
Caution The inject annotations are done in comments as ColdFusion 9 has a bug when adding annotations on scripted arguments.
An example of a flawed object could be the following:
Why is this object flawed? It is flawed because the majority of DI engines, including WireBox, will lock for constructing the object and its constructor arguments. However, once it is constructed, it will store the object in the persistence scope of choice in order to satisfy the potential of circular dependencies in the object graph. After it is placed in the storage, the DI engines will wire up setter and property mixin injections and WireBox's onDiComplete()
method. With this normal approach, the wiring of dependencies and onDiComplete()
have the potential of mixups or missing dependencies due to concurrency. This is a normal side-effect and risk that developers take due that Java makes no guarantees that any thread other than the one that set its dependencies will see the dependencies. The memory between threads is not final or immutable so properties can enter an altered state.
"The subtle reason has to do with the way Java Virtual Machines (JVM) are designed to manage threads. Threads may keep local, cached copies of non-volatile fields that can quickly get out of sync with one another unless they are synchronized correctly." From Dependency Injection by Dhanji R. Prasanna
Note This side effect of concurrency will only occur on objects that are singletons or persisted in scopes like session, server, application, server or cachebox. It does not affect transient or request scoped objects.
WireBox, can help you lock and provide thread safety to setter and property injections by providing you with the ThreadSafe
annotation or our binder threadSafe()
tagging method. So if we wanted to make the last example thread safe for property and setter wiring then we would do the following:
Note All objects are marked as non thread safe for dependency wiring by default in order to allow for circular dependencies. Please note that if you mark an object as
threadSafe
, then it will not be able to support circular dependencies unless it uses WireBox providers. ( See Providers Section )
Our threadSafe
annotation and binder tagging property will allow for these objects to be completely locked and synchronized for object creation, wiring and onDiComplete()
. However, circular dependencies will now fail as persistence cannot be guaranteed for the setter or property dependencies. However, since WireBox is so awesome, you can still use circular dependencies by wiring instead our object providers. (Please see providers section). In conclusion, constructing and designing a CFC that is thread safe is often a very arduous process. It is also very difficult to test and recreate threading issues in your objects and applications. So don't feel bad, as even the best of us can get into some nasty wormholes when dealing with concurrency and thread safety. However, always try to design for as much concurrency as possible and test test test!
WireBox 2.0.0 supports entity injection via
ColdBox ORM Module - for use in ColdBox applications
Custom ORM Event Handler - for use in any CFML application
In order to leverage WireBox for entity injection you will have to create your own custom ORM event handler and activate event handling in the ORM at the Application.cfc
Then you can create the custom event handler with a custom postLoad()
function where you will leverage WireBox for DI.
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 AbstractModel
CFC and mix them into the UserService
, then create a virtual $super
scope which will map to an instantiated instance of the BaseModel
object.
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.
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
Key | Type | Required | Default | Description |
target | any | Yes | --- | The target to populate |
xml | any | Yes | --- | The XML string or packet |
root | string | No | The XML root element to start from |
scope | string | No | Use scope injection instead of setters population. Ex: scope=variables.instance. |
trustedSetter | boolean | No | false | If set to true, the setter method will be called even if it does not exist in the bean |
include | string | No | A list of keys to include in the population |
exclude | string | No | A list of keys to exclude in the population |
ignoreEmpty | boolean | No | false | Ignore empty values on populations, great for ORM population |
nullEmptyInclude | string | No | A list of keys to NULL when empty |
nullEmptyExclude | string | No | A list of keys to NOT NULL when empty |
composeRelationships | boolean | No | false | Automatically attempt to compose relationships from memento |
Key
Type
Required
Default
Description
target
any
Yes
---
The target to populate
qry
query
yes
---
The query to populate the bean object with
rowNumber
Numeric
No
1
The query row number to use for population
scope
string
No
Use scope injection instead of setters population. Ex: scope=variables.instance.
trustedSetter
boolean
No
false
If set to true, the setter method will be called even if it does not exist in the bean
include
string
No
A list of keys to include in the population
exclude
string
No
A list of keys to exclude in the population
ignoreEmpty
boolean
No
false
Ignore empty values on populations, great for ORM population
nullEmptyInclude
string
No
A list of keys to NULL when empty
nullEmptyExclude
string
No
A list of keys to NOT NULL when empty
composeRelationships
boolean
No
false
Automatically attempt to compose relationships from memento
Key
Type
Required
Default
Description
target
any
Yes
---
The target to populate
memento
struct
yes
---
The structure to populate the object with.
scope
string
No
Use scope injection instead of setters population. Ex: scope=variables.instance.
trustedSetter
boolean
No
false
If set to true, the setter method will be called even if it does not exist in the bean
include
string
No
A list of keys to include in the population
exclude
string
No
A list of keys to exclude in the population
ignoreEmpty
boolean
No
false
Ignore empty values on populations, great for ORM population
nullEmptyInclude
string
No
A list of keys to NULL when empty
nullEmptyExclude
string
No
A list of keys to NOT NULL when empty
composeRelationships
boolean
No
false
Automatically attempt to compose relationships from memento
Key | Type | Required | Default | Description |
target | any | Yes | --- | This can be an instantiated bean object or a bean instantiation path as a string. If you pass an instantiation path and the bean has an 'init' method. It will be executed. This method follows the bean contract (set{property_name}). Example: setUsername(), setfname() |
qry | query | yes | --- | The query to populate the bean object with |
rowNumber | Numeric | No | 1 | The query row number to use for population |
scope | string | No | Use scope injection instead of setters population. Ex: scope=variables.instance. |
trustedSetter | boolean | No | false | If set to true, the setter method will be called even if it does not exist in the bean |
include | string | No | A list of keys to include in the population |
exclude | string | No | A list of keys to exclude in the population |
prefix | string | Yes | --- | The prefix used to filter, Example: 'user_' would apply to the following columns: 'user_id' and 'user_name' but not 'address_id'. |
ignoreEmpty | boolean | No | false | Ignore empty values on populations, great for ORM population |
nullEmptyInclude | string | No | A list of keys to NULL when empty |
nullEmptyExclude | string | No | A list of keys to NOT NULL when empty |
composeRelationships | boolean | No | false | Automatically attempt to compose relationships from memento |
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.
This will register a new injection DSL namespace called ortus that maps to that instantiation component path.model.dsl.OrtusBuilder
. Here is a very simple DSL Builder:
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.
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
Create a CFC that implements wirebox.system.ioc.dsl.IDSLBuilder
Register your custom DSL builder in your configuration binder
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:
Create a CFC that implements wirebox.system.ioc.scopes.IScope
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.
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.
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
.
Now I can use the ortus
DSL Namespace in my mappings DSL and even my annotations, isn't that cool!
Injectors allow you to register custom DSLs at runtime by using the registerDSL()
method on any injector.
Key
Type
Required
Default
Description
target
any
Yes
---
The target to populate
JSONString
string
Yes
---
The JSON string to populate the object with. It has to be valid JSON and also a structure with name-key value pairs.
scope
string
No
Use scope injection instead of setters population. Ex: scope=variables.instance.
trustedSetter
boolean
No
false
If set to true, the setter method will be called even if it does not exist in the bean
include
string
No
A list of keys to include in the population
exclude
string
No
A list of keys to exclude in the population
ignoreEmpty
boolean
No
false
Ignore empty values on populations, great for ORM population
nullEmptyInclude
string
No
A list of keys to NULL when empty
nullEmptyExclude
string
No
A list of keys to NOT NULL when empty
composeRelationships
boolean
No
false
Automatically attempt to compose relationships from memento
The scoping process must be done by using some of the referenced injector's methods:
buildInstance(mapping, initArguments)
autowire()
These methods must be called sequentially in order to avoid circular reference locks. The first method buildInstance
is used to construct and initialize an object instance. The autowire method is used then to process DI and AOP on the targeted object. Let's look at my Ortus Scope:
Caution Always make sure that you use the
buildInstance
method and then store the results in the scope before wiring is done to avoid endless loops errors.
Now I can use the ortus
scope in my mappings DSL and even my annotations, isn't that cool!
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.
WireBox fully supports aspect-oriented programming (AOP) for ColdFusion (CFML) and any ColdFusion framework. Just note the different namespaces if using within the ColdBox Platform and standalone WireBox.
Our WireBox AOP RefCard will get you up and running in no time.
ColdFusion 11+
Lucee 4.5+
AND
Disk/Memory Generation
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:
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.
That's it! That tells WireBox to register the AOP engine once it loads. This listener also has some properties that you can tweak:
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 ()? The answer for most of us has always been "YES! Of Course! How else do I do this?".
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:
Property | Type | Required | Default Value | Description |
| cf include path | false |
| The location where UDF stubs will be generated to. This can be to disk or memory. |
| boolean | false | false | A cool flag to allow you to reload the class matching dictionary for development purposes only. |
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:
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.
WireBox has an amazing event driven architecture 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:
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.
Property
Type
Required
Default
Description
generationPath
cf include path
false
/wirebox/system/aop/tmp
The location where UDF stubs will be generated to. This can be to disk or memory.
classMatchReload
boolean
false
false
A cool flag to allow you to reload the class matching dictionary for development purposes only.
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.
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):
Finally, we do the after advice part which happens after the method or other aspects fire and results are returned:
That's it. I have succesfully created an aspect. What's next!
WireBox AOP supports the concept of self aspect bindings. This means that we can make things even simpler by letting the Aspect you build control what class and methods it will match against. This is great, one less thing to remember when developing the code. So let's start with the code first:
That's it! Our transaction aspect is done and it will also bind itself to ANY class and ANY method that has the transactional annotation. Then you just map it:
We are done now, by mapping the aspect WireBox detects the two annotations classMatcher
and methodMatcher
and binds it for you. WOW, but where did you get that from? Well, the component has two annotations:
How cool is that! My aspect can determine the matching for me already.
One thing to note about self binding aspects is that you can also override their matching by using the autoBind
argument in the mapAspect()
method call. So if you wanted to override the class and method matching on this aspect you would do this:
Since we have now mapped our aspect in WireBox, we now need to tell it the most important things:
To what classes or CFCs should we apply this aspect to?
To what methods or join points should we apply this aspect to?
We do this with another binder DSL method:
bindAspect(classes,methods,aspects)
What is up with that funky match()
.... stuff? Well, the classes and methods arguments of the bindAspect()
call uses our AOP funky matcher methods that exist in an object called: wirebox.system.aop.Matcher
. This matcher object is used to match classes and methods to whatever criteria you like. The binder has a convenience method called match()
that creates a new matcher object for you and returns it so you can configure it for classes and method matching. Here are the most common matching methods below:
WOW! We can really pin point anything in our system! So now that we have binded our aspect to our UserService I can rewrite it to this:
Now isn't that pretty? Much nicer and compact hugh! Plus I can reuse the method logger for ANY method in ANY class I desire (Muaaaahaaaa), that's an evil laugh by the way! But we are not done, let's keep going and do the Transactional aspect.
Method
Class Matching
Method Matching
Description
any()
true
true
Matches against any class path or method name
returns(type)
false
true
Matches against the return type of methods
annotatedWith(annotation,[value])
true
true
Matches against the finding of an annotation in a cfcomponent or cffuntion or matches against the finding AND value of the annotation.
mappings(mappings)
true
false
Matches to ONLY the named mapping(s) you pass to this method as a list or array.
instanceOf(classPath)
true
false
Matches if the target object is an instance of the classPath. This internally uses the ColdFusion isInstanceOf() method
regex(regex)
true
true
Matches against a CFC instantiation path or function name using regular expressions
methods(methods)
false
true
Matches against a list of explicit method names as a list or array
andMatch(matcher)
true
true
Does an AND evaluation with the current matcher and the one you pass in the method.
orMatch(matcher)
true
true
Does an OR evaluation with the current matcher and the one you pass in the method.