coldbox.system.web

Class Controller

lucee.Component
    extended by coldbox.system.web.Controller
Direct Known Subclasses:
MockController , ControllerDecorator

Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp www.ortussolutions.com --- Manages a ColdBox application, dispatches events and acts as an overall front controller.

Class Attributes:
  • synchronized : false
    •  
  • accessors : true
    •  
  • persistent : false
    •  
  • serializable : false
    •  
    Property Summary
    type property default serializable required
    any CFMLEngine
          The CFML engine helper.

    • access = public
    • returntype = any
    		 true false
    any appHash
          ColdBox application unique hash key.

    • access = public
    • returntype = any
    		 true false
    any appKey
          ColdBox application key that tracks the controller in the `application` scope.

    • access = public
    • returntype = any
    		 true false
    any appName
          The ColdFusion application name as per the application scope.

    • access = public
    • returntype = any
    		 true false
    any appRootPath
          ColdBox application root path.

    • access = public
    • returntype = any
    		 true false
    any asyncManager
          The Application's AsyncManager.

    • access = public
    • returntype = any
    		 true false
    any cachebox
          The reference to CacheBox.

    • access = public
    • returntype = any
    		 true false
    boolean coldboxInitiated
          ColdBox initiation flag.

    • access = public
    • returntype = any
    		 true false
    struct coldboxSettings
          The internal ColdBox settings structure.

    • access = public
    • returntype = any
    		 true false
    struct configSettings
          The application configuration settings structure.

    • access = public
    • returntype = any
    		 true false
    any log
          The controller logger object.

    • access = public
    • returntype = any
    		 true false
    any logbox
          The reference to LogBox.

    • access = public
    • returntype = any
    		 true false
    any renderer
          The view/layout renderer singleton.

    • access = public
    • returntype = any
    		 true false
    any services
          Container for all internal services (ordered struct).

    • access = public
    • returntype = any
    		 true false
    any util
          The system utility object.

    • access = public
    • returntype = any
    		 true false
    any wirebox
          The reference to WireBox.

    • access = public
    • returntype = any
    		 true false
    Constructor Summary
    init(any appRootPath, [any appKey='cbController'])
          Constructor.
    Method Summary
    private any _runEvent([any event=''], [boolean prePostExempt='false'], [boolean private='false'], [boolean defaultEvent='false'], [struct eventArguments='[runtime expression]'])
         Executes events with full life-cycle methods and returns the event results if any were returned.
    string getAppHash()
    string getAppKey()
    string getAppName()
    string getAppRootPath()
    string getAsyncManager()
    string getCFMLEngine()
    any getCache(any cacheName='default')
         Get a Cache provider from CacheBox.
    string getCachebox()
    any getColdBoxSetting(any name, [any defaultValue])
         Get a ColdBox setting.
    string getColdboxInitiated()
    string getColdboxSettings()
    string getConfigSettings()
    any getDataMarshaller()
         Get the system data marshaller, you can also retrieve it from wirebox via dataMarshaller@coldbox.
    any getHandlerService()
         Get the handler service.
    any getInterceptorService()
         Get the interceptor service.
    any getLoaderService()
         Get the loader service.
    string getLog()
    string getLogbox()
    any getMemento()
         Get controller memento, used only by decorator only.
    any getModuleService()
         Get the module service.
    any getRenderer()
         Get the system web renderer, you can also retrieve it from wirebox via renderer@coldbox.
    any getRequestService()
         Get the request service.
    any getRoutingService()
         Get the routing service.
    any getSchedulerService()
         Get the scheduling service.
    string getServices()
    any getSetting(any name, [any defaultValue])
         Get a setting from the application.
    string getUserSessionIdentifier()
         This method will return the unique user's request tracking identifier according to our discovery algoritm:.
    string getUtil()
    string getWirebox()
    private any invoker(any target, any method, [struct argCollection='[runtime expression]'], [boolean private='false'])
         Invoke private/public event handler methods.
    private any loadColdBoxSettings()
         Load the internal ColdBox settings.
    any locateDirectoryPath(any pathToCheck)
         Locate the real path location of a directory in a coldbox application.
    any locateFilePath(any pathToCheck)
         Locate the real path location of a file in a coldbox application.
    private any persistVariables([any persist=''], [struct persistStruct='[runtime expression]'])
         Internal helper to flash persist elements.
    any relocate([any event='[runtime expression]'], [any queryString=''], [boolean addToken='false'], [any persist=''], [struct persistStruct='[runtime expression]'], [any baseURL=''], [boolean postProcessExempt='false'], [any URL], [any URI], [numeric statusCode='302'])
         Relocate user browser requests to other events, URLs, or URIs.
    any runEvent([any event=''], [boolean prePostExempt='false'], [boolean private='false'], [boolean defaultEvent='false'], [struct eventArguments='[runtime expression]'], [boolean cache='false'], [any cacheTimeout=''], [any cacheLastAccessTimeout=''], [any cacheSuffix=''], [any cacheProvider='template'])
         Executes events with full life-cycle methods and returns the event results if any were returned.
    any runRoute(any name, [struct params='[runtime expression]'], [boolean cache='false'], [any cacheTimeout=''], [any cacheLastAccessTimeout=''], [any cacheSuffix=''], [any cacheProvider='template'], [boolean prePostExempt='false'])
         Executes internal named routes with or without parameters.
    private any sendRelocation(any URL, [boolean addToken='false'], [any statusCode='302'])
         Encapsulate a cf relocation tag.
    any setAppHash(any appHash)
    any setAppKey(any appKey)
    any setAppName(any appName)
    any setAppRootPath(any appRootPath)
    any setAsyncManager(any asyncManager)
    any setCFMLEngine(any CFMLEngine)
    any setCachebox(any cachebox)
    any setColdboxInitiated(boolean coldboxInitiated)
    any setColdboxSettings(struct coldboxSettings)
    any setConfigSettings(struct configSettings)
    any setLog(any log)
    any setLogbox(any logbox)
    any setRenderer(any renderer)
    any setServices(any services)
    Controller setSetting(any name, any value)
         Set a value in the application configuration settings.
    any setUtil(any util)
    any setWirebox(any wirebox)
    boolean settingExists(any name)
         Check if the setting exists in the application.
    private string updateSSL(any inURL, any ssl)
         Update SSL or not on a request string.
    private boolean validateAction(any action, [any inclusion=''], [any exclusion=''])
         Checks if an action can be executed according to inclusion/exclusion lists.
     
    Methods inherited from class lucee.Component
    None
    Constructor Detail

    init

    public init(any appRootPath, [any appKey='cbController'])

    Constructor

    Parameters:
    appRootPath - The application root path
    appKey - The application registered application key, default is cbController
    Property Detail

    CFMLEngine

    property any CFMLEngine

    The CFML engine helper

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

    appHash

    property any appHash

    ColdBox application unique hash key

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

    appKey

    property any appKey

    ColdBox application key that tracks the controller in the `application` scope

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

    appName

    property any appName

    The ColdFusion application name as per the application scope

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

    appRootPath

    property any appRootPath

    ColdBox application root path

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

    asyncManager

    property any asyncManager

    The Application's AsyncManager

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

    cachebox

    property any cachebox

    The reference to CacheBox

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

    coldboxInitiated

    property boolean coldboxInitiated

    ColdBox initiation flag

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

    coldboxSettings

    property struct coldboxSettings

    The internal ColdBox settings structure

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

    configSettings

    property struct configSettings

    The application configuration settings structure

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

    log

    property any log

    The controller logger object

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

    logbox

    property any logbox

    The reference to LogBox

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

    renderer

    property any renderer

    The view/layout renderer singleton

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

    services

    property any services

    Container for all internal services (ordered struct)

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

    util

    property any util

    The system utility object

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

    wirebox

    property any wirebox

    The reference to WireBox

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

    _runEvent

    private any _runEvent([any event=''], [boolean prePostExempt='false'], [boolean private='false'], [boolean defaultEvent='false'], [struct eventArguments='[runtime expression]'])

    Executes events with full life-cycle methods and returns the event results if any were returned

    Parameters:
    event - The event string to execute, if nothing is passed we will execute the application's default event.
    prePostExempt - If true, pre/post handlers will not be fired. Defaults to false
    private - Execute a private event if set, else defaults to public events
    defaultEvent - The flag that let's this service now if it is the default event running or not. USED BY THE FRAMEWORK ONLY
    eventArguments - A collection of arguments to passthrough to the calling event handler method
    Returns:
    struct { data:event handler returned data (null), ehBean:event handler bean representation that was fired }
    Throws:
    InvalidHTTPMethod

    getAppHash

    public string getAppHash()

    getAppKey

    public string getAppKey()

    getAppName

    public string getAppName()

    getAppRootPath

    public string getAppRootPath()

    getAsyncManager

    public string getAsyncManager()

    getCFMLEngine

    public string getCFMLEngine()

    getCache

    public any getCache(any cacheName='default')

    Get a Cache provider from CacheBox

    Parameters:
    cacheName - The name of the cache to retrieve, or it defaults to the 'default' cache.
    Returns:
    coldbox.system.cache.providers.IColdBoxProvider

    getCachebox

    public string getCachebox()

    getColdBoxSetting

    public any getColdBoxSetting(any name, [any defaultValue])

    Get a ColdBox setting

    Parameters:
    name - The key to get
    defaultValue - The default value if it doesn't exist
    Returns:
    The framework setting value
    Throws:
    SettingNotFoundException

    getColdboxInitiated

    public string getColdboxInitiated()

    getColdboxSettings

    public string getColdboxSettings()

    getConfigSettings

    public string getConfigSettings()

    getDataMarshaller

    public any getDataMarshaller()

    Get the system data marshaller, you can also retrieve it from wirebox via dataMarshaller@coldbox

    Returns:
    coldbox.system.core.conversion.DataMarhsaller

    getHandlerService

    public any getHandlerService()

    Get the handler service

    getInterceptorService

    public any getInterceptorService()

    Get the interceptor service

    getLoaderService

    public any getLoaderService()

    Get the loader service

    getLog

    public string getLog()

    getLogbox

    public string getLogbox()

    getMemento

    public any getMemento()

    Get controller memento, used only by decorator only.

    getModuleService

    public any getModuleService()

    Get the module service

    getRenderer

    public any getRenderer()

    Get the system web renderer, you can also retrieve it from wirebox via renderer@coldbox

    Returns:
    coldbox.system.web.Renderer

    getRequestService

    public any getRequestService()

    Get the request service

    getRoutingService

    public any getRoutingService()

    Get the routing service

    getSchedulerService

    public any getSchedulerService()

    Get the scheduling service

    getServices

    public string getServices()

    getSetting

    public any getSetting(any name, [any defaultValue])

    Get a setting from the application

    Parameters:
    name - The name of the setting
    defaultValue - The default value to use if setting does not exist
    Returns:
    The application setting value
    Throws:
    SettingNotFoundException

    getUserSessionIdentifier

    public string getUserSessionIdentifier()

    This method will return the unique user's request tracking identifier according to our discovery algoritm: 1. If we have an identifierProvider closure/lambda/udf, then call it and use it 2. If we have session enabled, use the jessionId or session URL Token 3. If we have cookies enabled, use the cfid/cftoken 4. If we have in the URL the cfid/cftoken 5. Create a request based tracking identifier: cbUserTrackingId

    getUtil

    public string getUtil()

    getWirebox

    public string getWirebox()

    invoker

    private any invoker(any target, any method, [struct argCollection='[runtime expression]'], [boolean private='false'])

    Invoke private/public event handler methods

    Parameters:
    target
    method
    argCollection
    private

    loadColdBoxSettings

    private any loadColdBoxSettings()

    Load the internal ColdBox settings

    Returns:
    The struct of settings

    locateDirectoryPath

    public any locateDirectoryPath(any pathToCheck)

    Locate the real path location of a directory in a coldbox application. 3 checks: 1) inside of coldbox app, 2) expand the path, 3) Absolute location. If path not found, it returns an empty path

    Parameters:
    pathToCheck - The relative or absolute directory path to verify and locate

    locateFilePath

    public any locateFilePath(any pathToCheck)

    Locate the real path location of a file in a coldbox application. 3 checks: 1) inside of coldbox app, 2) expand the path, 3) Absolute location. If path not found, it returns an empty path

    Parameters:
    pathToCheck - The relative or absolute file path to verify and locate

    persistVariables

    private any persistVariables([any persist=''], [struct persistStruct='[runtime expression]'])

    Internal helper to flash persist elements

    Parameters:
    persist
    persistStruct
    Returns:
    Controller

    relocate

    public any relocate([any event='[runtime expression]'], [any queryString=''], [boolean addToken='false'], [any persist=''], [struct persistStruct='[runtime expression]'], [any baseURL=''], [boolean postProcessExempt='false'], [any URL], [any URI], [numeric statusCode='302'])

    Relocate user browser requests to other events, URLs, or URIs.

    Parameters:
    event - The name of the event to relocate to, if not passed, then it will use the default event found in your configuration file.
    queryString - The query string or a struct to append, if needed. If in SES mode it will be translated to convention name value pairs
    addToken - Wether to add the tokens or not to the relocation. Default is false
    persist - What request collection keys to persist in flash RAM automatically for you
    persistStruct - A structure of key-value pairs to persist in flash RAM automatically for you
    baseURL - Use this baseURL instead of the index.cfm that is used by default. You can use this for SSL or any full base url you would like to use. Ex: https://mysite.com/index.cfm
    postProcessExempt - Do not fire the postProcess interceptors, by default it does
    URL - The full URL you would like to relocate to instead of an event: ex: URL='http://www.google.com'
    URI - The relative URI you would like to relocate to instead of an event: ex: URI='/mypath/awesome/here'
    statusCode - The status code to use in the relocation
    Returns:
    Controller

    runEvent

    public any runEvent([any event=''], [boolean prePostExempt='false'], [boolean private='false'], [boolean defaultEvent='false'], [struct eventArguments='[runtime expression]'], [boolean cache='false'], [any cacheTimeout=''], [any cacheLastAccessTimeout=''], [any cacheSuffix=''], [any cacheProvider='template'])

    Executes events with full life-cycle methods and returns the event results if any were returned.

    Parameters:
    event - The event string to execute, if nothing is passed we will execute the application's default event.
    prePostExempt - If true, pre/post handlers will not be fired. Defaults to false
    private - Execute a private event if set, else defaults to public events
    defaultEvent - The flag that let's this service now if it is the default event running or not. USED BY THE FRAMEWORK ONLY
    eventArguments - A collection of arguments to passthrough to the calling event handler method
    cache - Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.
    cacheTimeout - The time in minutes to cache the results
    cacheLastAccessTimeout - The time in minutes the results will be removed from cache if idle or requested
    cacheSuffix - The suffix to add into the cache entry for this event rendering
    cacheProvider - The provider to cache this event rendering in, defaults to 'template'
    Returns:
    null or any

    runRoute

    public any runRoute(any name, [struct params='[runtime expression]'], [boolean cache='false'], [any cacheTimeout=''], [any cacheLastAccessTimeout=''], [any cacheSuffix=''], [any cacheProvider='template'], [boolean prePostExempt='false'])

    Executes internal named routes with or without parameters. If the named route is not found or the route has no event to execute then this method will throw an `InvalidArgumentException`. If you need a route from a module then append the module address: `@moduleName` or prefix it like in run event calls `moduleName:routeName` in order to find the right route. The route params will be passed to events as action arguments much how eventArguments work.

    Parameters:
    name - The name of the route
    params - The parameters of the route to replace
    cache - Cached the output of the runnable execution, defaults to false. A unique key will be created according to event string + arguments.
    cacheTimeout - The time in minutes to cache the results
    cacheLastAccessTimeout - The time in minutes the results will be removed from cache if idle or requested
    cacheSuffix - The suffix to add into the cache entry for this event rendering
    cacheProvider - The provider to cache this event rendering in, defaults to 'template'
    prePostExempt - If true, pre/post handlers will not be fired. Defaults to false
    Throws:
    InvalidArgumentException

    sendRelocation

    private any sendRelocation(any URL, [boolean addToken='false'], [any statusCode='302'])

    Encapsulate a cf relocation tag. Encapsulated so we can mock it.

    Parameters:
    URL
    addToken
    statusCode

    setAppHash

    public any setAppHash(any appHash)

    Parameters:
    appHash

    setAppKey

    public any setAppKey(any appKey)

    Parameters:
    appKey

    setAppName

    public any setAppName(any appName)

    Parameters:
    appName

    setAppRootPath

    public any setAppRootPath(any appRootPath)

    Parameters:
    appRootPath

    setAsyncManager

    public any setAsyncManager(any asyncManager)

    Parameters:
    asyncManager

    setCFMLEngine

    public any setCFMLEngine(any CFMLEngine)

    Parameters:
    CFMLEngine

    setCachebox

    public any setCachebox(any cachebox)

    Parameters:
    cachebox

    setColdboxInitiated

    public any setColdboxInitiated(boolean coldboxInitiated)

    Parameters:
    coldboxInitiated

    setColdboxSettings

    public any setColdboxSettings(struct coldboxSettings)

    Parameters:
    coldboxSettings

    setConfigSettings

    public any setConfigSettings(struct configSettings)

    Parameters:
    configSettings

    setLog

    public any setLog(any log)

    Parameters:
    log

    setLogbox

    public any setLogbox(any logbox)

    Parameters:
    logbox

    setRenderer

    public any setRenderer(any renderer)

    Parameters:
    renderer

    setServices

    public any setServices(any services)

    Parameters:
    services

    setSetting

    public Controller setSetting(any name, any value)

    Set a value in the application configuration settings

    Parameters:
    name - The name of the setting
    value - The value to set
    Returns:
    Controller instance

    setUtil

    public any setUtil(any util)

    Parameters:
    util

    setWirebox

    public any setWirebox(any wirebox)

    Parameters:
    wirebox

    settingExists

    public boolean settingExists(any name)

    Check if the setting exists in the application

    Parameters:
    name - The name of the setting

    updateSSL

    private string updateSSL(any inURL, any ssl)

    Update SSL or not on a request string

    Parameters:
    inURL
    ssl

    validateAction

    private boolean validateAction(any action, [any inclusion=''], [any exclusion=''])

    Checks if an action can be executed according to inclusion/exclusion lists

    Parameters:
    action - The action to validate
    inclusion - The list of inclusions
    exclusion - The list of exclusions