Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
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.
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.
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.
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
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
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.
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.
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.
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 .
Please refer to the section to find out more about custom DSLs, the following are just the way you declare them:
Please refer to the section to find out more about custom scopes, the following are just the way you declare them:
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) |
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 |
The method used to tell the injector which configuration file to use for logging operations. Ignored in an application context