wirebox.system.ioc

Class Injector

lucee.Component
    extended by wirebox.system.ioc.Injector

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.ortussolutions.com --- The WireBox injector is the pivotal class in WireBox that performs dependency injection. It can be used standalone or it can be used in conjunction of a ColdBox application context. It can also be configured with a mapping configuration file called a binder, that can provide object/mappings and configuration data. A WireBox Injector: Builds the graphs of objects that make up your application. All injectors implement: wirebox.system.ioc.IInjector Easy Startup: 

injector = new wirebox.system.ioc.Injector();
Inline Config: 
injector = new wirebox.system.ioc.Injector( { scopeRegistration : { enabled : false } } );
Binder Startup 
injector = new wirebox.system.ioc.Injector(new MyBinder());
Binder Path Startup 
injector = new wirebox.system.ioc.Injector( "config.MyBinder" );

Class Attributes:
  • synchronized : false
    •  
  • see : wirebox.system.ioc.IInjector
    •  
  • accessors : true
    •  
  • persistent : false
    •  
  • serializable : false
    •  
    Property Summary
    type property default serializable required
    any asyncManager
          The Global AsyncManager.

    • access = public
    • returntype = any
    • see = wirebox.system.async.AsyncManager
    		 true false
    any binder
          The Configuration Binder object.

    • access = public
    • returntype = any
    		 true false
    any cacheBox
          CacheBox Link.

    • access = public
    • returntype = any
    		 true false
    struct childInjectors
          An injector can have children injectors referenced by a unique name.

    • access = public
    • returntype = any
    		 true false
    any coldbox
          ColdBox Application Link.

    • access = public
    • returntype = any
    		 true false
    any eventManager
          Event Manager Link.

    • access = public
    • returntype = any
    		 true false
    array eventStates
          Configured Event States.

    • access = public
    • returntype = any
    		 true false
    any injectorID
          The injector Unique ID.

    • access = public
    • returntype = any
    		 true false
    any log
          Log Reference.

    • access = public
    • returntype = any
    		 true false
    any logBox
          LogBox and Class Logger.

    • access = public
    • returntype = any
    		 true false
    string name
          The name of the injector.

    • access = public
    • returntype = any
    		 true false
    any objectBuilder
          The object builder for this injector.

    • access = public
    • returntype = any
    		 true false
    any parent
          Parent Injector.

    • access = public
    • returntype = any
    		 true false
    any root
          Root Injector instance.

    • access = public
    • returntype = any
    		 true false
    any scopeStorage
          Scope Storages Utility.

    • access = public
    • returntype = any
    		 true false
    any scopes
          LifeCycle Scopes.

    • access = public
    • returntype = any
    		 true false
    any taskScheduler
          The logBox task scheduler executor.

    • access = public
    • returntype = any
    • see = wirebox.system.async.executors.ScheduledExecutor
    		 true false
    any utility
          ColdBox Utility class.

    • access = public
    • returntype = any
    		 true false
    any version
          WireBox Version.

    • access = public
    • returntype = any
    		 true false
    Constructor Summary
    init([any binder='wirebox.system.ioc.config.DefaultBinder'], [struct properties='[runtime expression]'], [any<wirebox.system.web.Controller> coldbox=''], [any name='root'])
          WireBox can be constructed with no parameters and it will use the default binder: `wirebox.
    Method Summary
    any autowire(any target, [any<Mapping> mapping], [any targetID=''], [boolean annotationCheck='false'])
         I wire up target objects with dependencies either by mappings or a-la-carte autowires.
    private any buildBinder(any binder, any properties)
         Load a configuration binder object according to passed in type.
    any buildInstance(any<Mapping> mapping, [struct initArguments='[runtime expression]'])
         Build an instance, this is called from registered scopes only as they provide locking and transactions.
    Injector clearSingletons()
         Clear the singleton cache.
    Injector configure(any binder, struct properties)
         Configure this injector for operation, called by the init().
    private Injector configureCacheBox(struct config)
         Configure a standalone version of cacheBox for persistence.
    private Injector configureEventManager()
         Configure a standalone version of a WireBox Event Manager.
    private Injector configureLogBox(any configPath)
         Configure a standalone version of logBox for logging.
    boolean containsInstance(any name)
         Checks if this injector can locate a model instance or not.
    private Injector doScopeRegistration([any scopeInfo='[runtime expression]'])
         Register this injector on a user specified scope.
    string getAsyncManager()
    string getBinder()
    string getCacheBox()
    Injector getChildInjector(any name)
         Get a child injector from this injector.
    array getChildInjectorNames()
         Get an array of all the registered child injectors in this injector.
    string getChildInjectors()
    string getColdbox()
    string getEventManager()
    string getEventStates()
    string getInjectorID()
    Injector getInjectorReference(any name)
         Get an injector reference by unique name.
    array getInjectorReferenceNames()
         Get an array of registered injector references.
    any getInstance([any name], [struct initArguments='[runtime expression]'], [any dsl], [any targetObject=''], [any injector])
         Locates, Creates, Injects and Configures an object model instance.
    string getLog()
    string getLogBox()
    string getName()
    string getObjectBuilder()
    any getObjectPopulator()
         Get an object populator useful for populating objects from JSON,XML, etc.
    any<Injector> getParent()
         Get a reference to the parent injector instance, else an empty simple string meaning nothing is set.
    string getRoot()
    any getScope(any scope)
         Get a registered scope in this injector by name.
    struct getScopeRegistration()
         Get the structure of scope registration information.
    string getScopeStorage()
    string getScopes()
    string getTaskScheduler()
    string getUtility()
    string getVersion()
    boolean hasChildInjector(any name)
         Verify if a child injector has been registered by name.
    boolean hasParent()
         Has a parent injector.
    boolean hasRoot()
         Has a root injector.
    private Injector injectTarget(any target, any propertyName, any propertyObject, any scope, any argName)
         Inject a model object with dependencies via setters or property injections.
    boolean isCacheBoxLinked()
         Checks if CacheBox is linked.
    boolean isColdBoxLinked()
         Checks if Coldbox application context is linked.
    any locateInstance(any name)
         Tries to locate a specific instance by scanning all scan locations and returning the instantiation path.
    any<Injector> locateScopedSelf()
         Return a self reference using the scoped registration, mostly used by providers or scope widening objects.
    private Injector processAfterCompleteDI(any targetObject, any DICompleteMethods)
         Process after DI completion routines.
    private any processDelegation(any target, string targetID, any delegate, any DIData)
         Process a target object dependency delegation.
    private Injector processInjection(any targetObject, array DIData, string targetID, any mapping)
         Process property and setter injections.
    private Injector processLazyProperties(any targetObject, any mapping)
         Process lazy properties on the target object.
    private Injector processMixins(any targetObject, any mapping)
         Process mixins on the selected target.
    private Injector processObservedProperties(any targetObject, any mapping)
         Process observed properties on the target object.
    private Injector processProviderMethods(any targetObject, any mapping)
         Process provider methods on the selected target.
    Injector registerChildInjector(any name, any child)
         Register a child injector instance with this injector and set this injector as a parent of the child.
    Injector registerDSL(any namespace, any path)
         A direct way of registering custom DSL namespaces.
    Injector registerInjectorReference(any injector)
         Register an injector to be tracked in the lookup reference map.
    Injector registerListener(any listener)
         Register all the configured listeners in the configuration file.
    private Injector registerListeners()
         Register all the configured listeners in the configuration file.
    any registerNewInstance(any name, any instancePath)
         Register a new requested mapping object instance thread safely and returns the mapping configured for this instance.
    private Injector registerScopes()
         Register all internal and configured WireBox Scopes.
    boolean removeChildInjector(any name)
         Remove a child injector from this injector.
    Injector removeFromScope()
         Remove the Injector from scope registration if enabled, else does nothing.
    any setAsyncManager(any asyncManager)
    any setBinder(any binder)
    any setCacheBox(any cacheBox)
    any setChildInjectors(struct childInjectors)
    any setColdbox(any coldbox)
    any setEventManager(any eventManager)
    any setEventStates(array eventStates)
    any setInjectorID(any injectorID)
    any setLog(any log)
    any setLogBox(any logBox)
    any setName(string name)
    any setObjectBuilder(any objectBuilder)
    any setParent(any<Injector> injector)
         Link a parent Injector with this injector.
    any setRoot(any root)
    any setScopeStorage(any scopeStorage)
    any setScopes(any scopes)
    any setTaskScheduler(any taskScheduler)
    any setUtility(any utility)
    any setVersion(any version)
    any shutdown()
         Shutdown the injector gracefully by calling the shutdown events internally.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init([any binder='wirebox.system.ioc.config.DefaultBinder'], [struct properties='[runtime expression]'], [any<wirebox.system.web.Controller> coldbox=''], [any name='root'])

    WireBox can be constructed with no parameters and it will use the default binder: `wirebox.system.ioc.config.DefaultBinder` for configuration and place the instance in `application.wirebox` scope for easy access. However you can also instantiate Wirebox with: - A binder instance - A binder path - A WireBox configuration DSL structure

    Parameters:
    binder - A binder instance, path, or DSL structure to configure WireBox with
    properties - A structure of binding properties to passthrough to the Binder Configuration CFC
    coldbox - A coldbox application context that this instance of WireBox can be linked to, if not using it, we just ignore it.
    name - The internal name of the injector, defaults to 'root' if not passed
    Property Detail

    asyncManager

    property any asyncManager

    The Global AsyncManager

    Attributes:
    access - public
    required - false
    returntype - any
    see - wirebox.system.async.AsyncManager
    serializable - true

    binder

    property any binder

    The Configuration Binder object

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    cacheBox

    property any cacheBox

    CacheBox Link

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    childInjectors

    property struct childInjectors

    An injector can have children injectors referenced by a unique name

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    coldbox

    property any coldbox

    ColdBox Application Link

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    eventManager

    property any eventManager

    Event Manager Link

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    eventStates

    property array eventStates

    Configured Event States

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    injectorID

    property any injectorID

    The injector Unique ID

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    log

    property any log

    Log Reference

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    logBox

    property any logBox

    LogBox and Class Logger

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    name

    property string name

    The name of the injector

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    objectBuilder

    property any objectBuilder

    The object builder for this injector

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    parent

    property any parent

    Parent Injector

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    root

    property any root

    Root Injector instance

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    scopeStorage

    property any scopeStorage

    Scope Storages Utility

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    scopes

    property any scopes

    LifeCycle Scopes

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    taskScheduler

    property any taskScheduler

    The logBox task scheduler executor

    Attributes:
    access - public
    required - false
    returntype - any
    see - wirebox.system.async.executors.ScheduledExecutor
    serializable - true

    utility

    property any utility

    ColdBox Utility class

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true

    version

    property any version

    WireBox Version

    Attributes:
    access - public
    required - false
    returntype - any
    serializable - true
    Method Detail

    autowire

    public any autowire(any target, [any<Mapping> mapping], [any targetID=''], [boolean annotationCheck='false'])

    I wire up target objects with dependencies either by mappings or a-la-carte autowires

    Parameters:
    target - The target object to wire up
    mapping - The object mapping with all the necessary wiring metadata. Usually passed by scopes and not a-la-carte autowires
    targetID - A unique identifier for this target to wire up. Usually a class path or file path should do. If none is passed we will get the id from the passed target via introspection but it will slow down the wiring
    annotationCheck - This value determines if we check if the target contains an autowire annotation in the cfcomponent tag: autowire=true|false, it will only autowire if that metadata attribute is set to true. The default is false, which will autowire anything automatically.

    buildBinder

    private any buildBinder(any binder, any properties)

    Load a configuration binder object according to passed in type

    Parameters:
    binder - The data CFC configuration instance, instantiation path or programmatic binder object to configure this injector with
    properties - A map of binding properties to passthrough to the Configuration CFC

    buildInstance

    public any buildInstance(any<Mapping> mapping, [struct initArguments='[runtime expression]'])

    Build an instance, this is called from registered scopes only as they provide locking and transactions

    Parameters:
    mapping - The mapping to construct
    initArguments - The constructor structure of arguments to passthrough when initializing the instance

    clearSingletons

    public Injector clearSingletons()

    Clear the singleton cache

    configure

    public Injector configure(any binder, struct properties)

    Configure this injector for operation, called by the init(). You can also re-configure this injector programmatically, but it is not recommended.

    Parameters:
    binder - The configuration binder object or path or dsl structure to configure this Injector instance with
    properties - A structure of binding properties to passthrough to the Configuration CFC

    configureCacheBox

    private Injector configureCacheBox(struct config)

    Configure a standalone version of cacheBox for persistence

    Parameters:
    config - The cacheBox configuration data structure

    configureEventManager

    private Injector configureEventManager()

    Configure a standalone version of a WireBox Event Manager

    configureLogBox

    private Injector configureLogBox(any configPath)

    Configure a standalone version of logBox for logging

    Parameters:
    configPath

    containsInstance

    public boolean containsInstance(any name)

    Checks if this injector can locate a model instance or not

    Parameters:
    name - The object name or alias to search for if this container can locate it or has knowledge of it

    doScopeRegistration

    private Injector doScopeRegistration([any scopeInfo='[runtime expression]'])

    Register this injector on a user specified scope

    Parameters:
    scopeInfo - The scope info struct: key, scope

    getAsyncManager

    public string getAsyncManager()

    getBinder

    public string getBinder()

    getCacheBox

    public string getCacheBox()

    getChildInjector

    public Injector getChildInjector(any name)

    Get a child injector from this injector

    Parameters:
    name
    Throws:
    ChildNotFoundException - If the passed child name does not exist with this injector

    getChildInjectorNames

    public array getChildInjectorNames()

    Get an array of all the registered child injectors in this injector

    getChildInjectors

    public string getChildInjectors()

    getColdbox

    public string getColdbox()

    getEventManager

    public string getEventManager()

    getEventStates

    public string getEventStates()

    getInjectorID

    public string getInjectorID()

    getInjectorReference

    public Injector getInjectorReference(any name)

    Get an injector reference by unique name

    Parameters:
    name - The unique injector reference name

    getInjectorReferenceNames

    public array getInjectorReferenceNames()

    Get an array of registered injector references

    getInstance

    public any getInstance([any name], [struct initArguments='[runtime expression]'], [any dsl], [any targetObject=''], [any injector])

    Locates, Creates, Injects and Configures an object model instance

    Parameters:
    name - The mapping name or CFC instance path to try to build up
    initArguments - The constructor structure of arguments to passthrough when initializing the instance
    dsl - The dsl string to use to retrieve the instance model object, mutually exclusive with 'name
    targetObject - The object requesting the dependency, usually only used by DSL lookups
    injector - The child injector to use when retrieving the instance
    Returns:
    The requested instance
    Throws:
    InvalidChildInjector - When you request an instance from an invalid child injector name

    getLog

    public string getLog()

    getLogBox

    public string getLogBox()

    getName

    public string getName()

    getObjectBuilder

    public string getObjectBuilder()

    getObjectPopulator

    public any getObjectPopulator()

    Get an object populator useful for populating objects from JSON,XML, etc.

    Returns:
    wirebox.system.core.dynamic.ObjectPopulator

    getParent

    public any<Injector> getParent()

    Get a reference to the parent injector instance, else an empty simple string meaning nothing is set

    getRoot

    public string getRoot()

    getScope

    public any getScope(any scope)

    Get a registered scope in this injector by name

    Parameters:
    scope - The scope name
    Throws:
    InvalidScopeException - When the scope requested has not been registered in this Injector

    getScopeRegistration

    public struct getScopeRegistration()

    Get the structure of scope registration information

    getScopeStorage

    public string getScopeStorage()

    getScopes

    public string getScopes()

    getTaskScheduler

    public string getTaskScheduler()

    getUtility

    public string getUtility()

    getVersion

    public string getVersion()

    hasChildInjector

    public boolean hasChildInjector(any name)

    Verify if a child injector has been registered by name

    Parameters:
    name - The name of the child injector to check

    hasParent

    public boolean hasParent()

    Has a parent injector

    hasRoot

    public boolean hasRoot()

    Has a root injector

    injectTarget

    private Injector injectTarget(any target, any propertyName, any propertyObject, any scope, any argName)

    Inject a model object with dependencies via setters or property injections

    Parameters:
    target - The target that will be injected with dependencies
    propertyName - The name of the property to inject
    propertyObject - The object to inject
    scope - The scope to inject a property into, if any else empty means it is a setter call
    argName - The name of the argument to send if setter injection

    isCacheBoxLinked

    public boolean isCacheBoxLinked()

    Checks if CacheBox is linked

    isColdBoxLinked

    public boolean isColdBoxLinked()

    Checks if Coldbox application context is linked

    locateInstance

    public any locateInstance(any name)

    Tries to locate a specific instance by scanning all scan locations and returning the instantiation path. If model not found then the returned instantiation path will be empty

    Parameters:
    name - The model instance name to locate

    locateScopedSelf

    public any<Injector> locateScopedSelf()

    Return a self reference using the scoped registration, mostly used by providers or scope widening objects

    processAfterCompleteDI

    private Injector processAfterCompleteDI(any targetObject, any DICompleteMethods)

    Process after DI completion routines

    Parameters:
    targetObject - The target object to do some goodness on
    DICompleteMethods - The array of DI completion methods to call

    processDelegation

    private any processDelegation(any target, string targetID, any delegate, any DIData)

    Process a target object dependency delegation

    Parameters:
    target - The target object being injected with dependencies/delegations
    targetID - The target ID to process injections
    delegate - The delegation object that was injected
    DIData - The DI information about the delegation/injection

    processInjection

    private Injector processInjection(any targetObject, array DIData, string targetID, any mapping)

    Process property and setter injections

    Parameters:
    targetObject - The target object to do some goodness on, usually a CFC
    DIData - The DI data array to use for injection
    targetID - The target Identifier of the target object
    mapping - The mapping of the target object

    processLazyProperties

    private Injector processLazyProperties(any targetObject, any mapping)

    Process lazy properties on the target object

    Parameters:
    targetObject - The target object to do some goodness on
    mapping - The target mapping

    processMixins

    private Injector processMixins(any targetObject, any mapping)

    Process mixins on the selected target

    Parameters:
    targetObject - The target object to do some goodness on
    mapping - The target mapping

    processObservedProperties

    private Injector processObservedProperties(any targetObject, any mapping)

    Process observed properties on the target object

    Parameters:
    targetObject - The target object to do some goodness on
    mapping - The target mapping

    processProviderMethods

    private Injector processProviderMethods(any targetObject, any mapping)

    Process provider methods on the selected target

    Parameters:
    targetObject - The target object to do some goodness on
    mapping - The target mapping

    registerChildInjector

    public Injector registerChildInjector(any name, any child)

    Register a child injector instance with this injector and set this injector as a parent of the child.

    Parameters:
    name - The unique name to register the child with
    child - The child Injector instance to register

    registerDSL

    public Injector registerDSL(any namespace, any path)

    A direct way of registering custom DSL namespaces

    Parameters:
    namespace - The namespace you would like to register
    path - The instantiation path to the CFC that implements this scope, it must have an init() method and implement: wirebox.system.ioc.dsl.IDSLBuilder

    registerInjectorReference

    public Injector registerInjectorReference(any injector)

    Register an injector to be tracked in the lookup reference map. Used for providers mostly.

    Parameters:
    injector - The injector to track

    registerListener

    public Injector registerListener(any listener)

    Register all the configured listeners in the configuration file

    Parameters:
    listener - The listener to register

    registerListeners

    private Injector registerListeners()

    Register all the configured listeners in the configuration file

    registerNewInstance

    public any registerNewInstance(any name, any instancePath)

    Register a new requested mapping object instance thread safely and returns the mapping configured for this instance

    Parameters:
    name - The name of the mapping to register
    instancePath - The path of the mapping to register

    registerScopes

    private Injector registerScopes()

    Register all internal and configured WireBox Scopes

    removeChildInjector

    public boolean removeChildInjector(any name)

    Remove a child injector from this injector

    Parameters:
    name - The unique name of the child injector to remove
    Returns:
    Boolean indicator if the injector was found and removed (true) or not found and not removed (false)

    removeFromScope

    public Injector removeFromScope()

    Remove the Injector from scope registration if enabled, else does nothing

    setAsyncManager

    public any setAsyncManager(any asyncManager)

    Parameters:
    asyncManager

    setBinder

    public any setBinder(any binder)

    Parameters:
    binder

    setCacheBox

    public any setCacheBox(any cacheBox)

    Parameters:
    cacheBox

    setChildInjectors

    public any setChildInjectors(struct childInjectors)

    Parameters:
    childInjectors

    setColdbox

    public any setColdbox(any coldbox)

    Parameters:
    coldbox

    setEventManager

    public any setEventManager(any eventManager)

    Parameters:
    eventManager

    setEventStates

    public any setEventStates(array eventStates)

    Parameters:
    eventStates

    setInjectorID

    public any setInjectorID(any injectorID)

    Parameters:
    injectorID

    setLog

    public any setLog(any log)

    Parameters:
    log

    setLogBox

    public any setLogBox(any logBox)

    Parameters:
    logBox

    setName

    public any setName(string name)

    Parameters:
    name

    setObjectBuilder

    public any setObjectBuilder(any objectBuilder)

    Parameters:
    objectBuilder

    setParent

    public any setParent(any<Injector> injector)

    Link a parent Injector with this injector

    Parameters:
    injector - A WireBox Injector to assign as a parent to this Injector
    Returns:
    Injector

    setRoot

    public any setRoot(any root)

    Parameters:
    root

    setScopeStorage

    public any setScopeStorage(any scopeStorage)

    Parameters:
    scopeStorage

    setScopes

    public any setScopes(any scopes)

    Parameters:
    scopes

    setTaskScheduler

    public any setTaskScheduler(any taskScheduler)

    Parameters:
    taskScheduler

    setUtility

    public any setUtility(any utility)

    Parameters:
    utility

    setVersion

    public any setVersion(any version)

    Parameters:
    version

    shutdown

    public any shutdown()

    Shutdown the injector gracefully by calling the shutdown events internally.