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

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

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

    // The WireBox configuration structure DSL
    wireBox = {

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

        // CacheBox
        cacheBox = { enabled = true },

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

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

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

        // Package scan locations
        scanLocations = [],

        // Stop Recursions
        stopRecursions = [],

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

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

    // Map Bindings below
}

logBoxConfig

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

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

cachebox

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

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

scopeRegistration

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

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

customDSL

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

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

customScopes

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

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

scanLocations

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

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

stopRecursions

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

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

parentInjector

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

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

listeners

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

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

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

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

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

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

this.TYPES

• CFC : Construction of a CFC

• JAVA : Construction of a Java class

• WEBSERVICE : Construction of a webservice object

• RSS : Construction of an RSS feed

• DSL : Construction by DSL string

• CONSTANT : A constant value

• FACTORY : Construction by factory method

this.SCOPES

• NOSCOPE : Transient objects

• PROTOTYPE : Transient objects

• SINGLETON : Objects constructed only once and stored in the injector

• SESSION : ColdFusion session scoped based objects

• APPLICATION : ColdFusion application scope based objects

• REQUEST : ColdFusion request scope based objects

• SERVER : ColdFusion server scope based objects

• CACHEBOX : CacheBox scoped objects

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

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

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

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

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

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

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

    function configure(){

    }

    function onLoad(){

    }

    function onShutdown(){

    }
}

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

component{

 function configure(required binder){

 }

 function onLoad(){

 }

 function onShutdown(){

 }

}

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

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

new wirebox.system.ioc.Injector( 'path.to.my.Binder' );
// or
var oBinder = createObject( 'path.to.my.Binder' );
new wirebox.system.ioc.Injector( oBinder );

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

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