1 of 9

Injection DSL

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.

inject="{namespace}:extra:extra:extra"

Property Annotation

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

property name="service" inject="id:MyService";

property name="TYPES" inject="id:CustomTypes" scope="this";

property name="roles" inject="id:RoleService:getRoles" scope="instance";

Constructor Argument Annotation

You can also use annotated constructor arguments with the inject annotation.

<---  Via tag based annotations --->
<cffunction name="init" returntype="any" output="false">
    <cfargument name="myService" inject="UserService">
    <cfargument name="cache"      inject="cachebox:default">

</cffunction>


// Via script but alternative method as inline annotations are broken in ACF

/**
* Init
* @myService.inject UserService
* @cache.inject cachebox:default
*/
function init(required myService, required cache){
}

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.

Setter Method Annotation

You can also annotate setter methods with the inject annotation to provide injections

<---  Via tag based annotations --->
<cffunction name="setService" returntype="any" output="false" inject="UserService">
    <cfargument name="service">
</cffunction>


function setService(required service) inject="UserService"{
  variables.service = arguments.service;
}

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!

ID-Model-Empty Namespace

The default namespace is not specifying one. This namespace is used to retreive either named mappings or full component paths.

// Let's assume we have mapped a few objects called: UserService, SecurityService and RoleService

// Empty inject, use the property name, argument name or setter name
property name="userService" inject;

// Using the name of the mapping as the value of the inject
property name="security" inject="SecurityService";

// Using the full namespace
property name="userService" inject="id:UserService";
property name="userService" inject="model:UserService";

// Simple factory method
property name="roles" inject="id:RoleService:getRoles";

// Module Injection Shortcut
property name="MyService" inject="@myModule";

CFC Instantiation Order

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.

Provider Namespace

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

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

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

WireBox Namespace

Talk and get objects from the current wirebox injector

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

CacheBox Namespace

This DSL namespace is only active if using CacheBox or a ColdBox application context.

property name="cacheFactory" inject="cacheBox";
property name="cache" inject="cachebox:default";
property name="data" inject="cachebox:default:myKey";

EntityService Namespace

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:

// Generic ORM service layer
property name="genericService" inject="entityService";
// Virtual service layer based on the User entity
property name="userService" inject="entityService:User";

LogBox Namespace

This DSL namespace interacts with the loaded LogBox instance.

Java Namespace

Interact with Java directly

property name="builder" inject="java:java.lang.StringBuilder";

ColdBox Namespace

This namespace is a combination of namespaces that are only active when used within a ColdBox application:

Single Stage Injections

Two Stage Injections

Three Stage Injections

Examples

// some examples
property name="logbox" inject="logbox";
property name="rootLogger" inject="logbox:root";
property name="logger" inject="logbox:logger:model.com.UserService";
property name="moduleService" inject="coldbox:moduleService";
property name="producer" inject="coldbox:interceptor:MessageProducer";
property name="producer" inject="interceptor:MessageProducer";
property name="appPath" inject="coldbox:fwSetting:ApplicationPath";