RequestContext.cfc

/**
 * Copyright Since 2005 ColdBox Framework by Luis Majano and Ortus Solutions, Corp
 * www.ortussolutions.com
 * ---
 * Models a ColdBox request, stores the incoming request collection (FORM/URL/REMOTE) and private request collection.
 * It is also used to determine metadata about a request and helps you build RESTFul responses.
 */
component serializable="false" accessors="true" {

	/**
	 * The request context which contains the URL/FORM or any incoming client data
	 */
	property name="context" type="struct";

	/**
	 * The private request context which contains safe data your application can produce
	 */
	property name="privateContext" type="struct";

	/**
	 * ColdBox Controller
	 */
	property name="controller";

	/**
	 * ColdBox System Properties
	 */
	property name="properties" type="struct";

	/**
	 * The incoming event name detection string
	 */
	property name="eventName";

	/**
	 * Execution bit determination. Used to determine if the request is executable or not
	 */
	property name="isNoExecution" type="boolean";

	/**
	 * Registered system layout ref maps
	 */
	property name="registeredLayouts" type="struct";

	/**
	 * Registered system folder layout ref maps
	 */
	property name="folderLayouts" type="struct";

	/**
	 * Registered system folder view ref maps
	 */
	property name="viewLayouts" type="struct";

	/**
	 * Default system layout
	 */
	property name="defaultLayout";

	/**
	 * Default system view
	 */
	property name="defaultView";

	/**
	 * SES Base URL used for the request
	 */
	property name="SESBaseURL";

	/**
	 * The incoming RESTFul routed struct (if any)
	 */
	property name="routedStruct" type="struct";

	/**
	 * View Rendering Regions that we will track
	 */
	property name="renderingRegions" type="struct";

	/**
	 * Response headers generated by the ColdBox application NOT the servlet
	 */
	property name="responseHeaders" type="struct";

	/**
	 * The request's timeout if set via the setRequestTimeout() method.
	 */
	property
		name   ="requestTimeout"
		type   ="numeric"
		default="0";

	/**
	 * The last status code
	 * This is used mostly for mocking and tracking multi-step responses in case repsonses are committed.
     * Defaults to 200 (OK)
	 */
	property
		name   ="statusCode"
		type   ="numeric"
		default="200";

	/**
	 * The last status text
	 *
	 * @REMOVED by Jakarta EE, remove by 8
	 */
	property
		name   ="statusText"
		type   ="string"
		default="";

	/************************************** STATIC CONSTRUCTS *********************************************/

	// HTTP VERB ALIASES
	this.METHODS = {
		"HEAD"   : "HEAD",
		"GET"    : "GET",
		"POST"   : "POST",
		"PATCH"  : "PATCH",
		"PUT"    : "PUT",
		"DELETE" : "DELETE"
	};

	// HTTP STATUS CODES
	this.STATUS = {
		"CREATED"              : 201,
		"ACCEPTED"             : 202,
		"SUCCESS"              : 200,
		"NO_CONTENT"           : 204,
		"RESET"                : 205,
		"PARTIAL_CONTENT"      : 206,
		"BAD_REQUEST"          : 400,
		"NOT_AUTHORIZED"       : 403,
		"NOT_AUTHENTICATED"    : 401,
		"NOT_FOUND"            : 404,
		"NOT_ALLOWED"          : 405,
		"NOT_ACCEPTABLE"       : 406,
		"UNPROCESSABLE_ENTITY" : 422,
		"TOO_MANY_REQUESTS"    : 429,
		"EXPECTATION_FAILED"   : 417,
		"INTERNAL_ERROR"       : 500,
		"NOT_IMPLEMENTED"      : 501
	};

	// HTTP STATUS TEXTS
	// TODO: REMOVE BY 8
	this.STATUS_TEXTS = {
		"100" : "Continue",
		"101" : "Switching Protocols",
		"102" : "Processing",
		"200" : "OK",
		"201" : "Created",
		"202" : "Accepted",
		"203" : "Non-authoritative Information",
		"204" : "No Content",
		"205" : "Reset Content",
		"206" : "Partial Content",
		"207" : "Multi-Status",
		"208" : "Already Reported",
		"226" : "IM Used",
		"300" : "Multiple Choices",
		"301" : "Moved Permanently",
		"302" : "Found",
		"303" : "See Other",
		"304" : "Not Modified",
		"305" : "Use Proxy",
		"307" : "Temporary Redirect",
		"308" : "Permanent Redirect",
		"400" : "Bad Request",
		"401" : "Unauthorized",
		"402" : "Payment Required",
		"403" : "Forbidden",
		"404" : "Not Found",
		"405" : "Method Not Allowed",
		"406" : "Not Acceptable",
		"407" : "Proxy Authentication Required",
		"408" : "Request Timeout",
		"409" : "Conflict",
		"410" : "Gone",
		"411" : "Length Required",
		"412" : "Precondition Failed",
		"413" : "Payload Too Large",
		"414" : "Request-URI Too Long",
		"415" : "Unsupported Media Type",
		"416" : "Requested Range Not Satisfiable",
		"417" : "Expectation Failed",
		"418" : "I'm a teapot",
		"421" : "Misdirected Request",
		"422" : "Unprocessable Entity",
		"423" : "Locked",
		"424" : "Failed Dependency",
		"426" : "Upgrade Required",
		"428" : "Precondition Required",
		"429" : "Too Many Requests",
		"431" : "Request Header Fields Too Large",
		"444" : "Connection Closed Without Response",
		"451" : "Unavailable For Legal Reasons",
		"499" : "Client Closed Request",
		"500" : "Internal Server Error",
		"501" : "Not Implemented",
		"502" : "Bad Gateway",
		"503" : "Service Unavailable",
		"504" : "Gateway Timeout",
		"505" : "HTTP Version Not Supported",
		"506" : "Variant Also Negotiates",
		"507" : "Insufficient Storage",
		"508" : "Loop Detected",
		"510" : "Not Extended",
		"511" : "Network Authentication Required",
		"599" : "Network Connect Timeout Error"
	};

	// Family Marker
	this.cbRequestContext = true;

	/************************************** CONSTRUCTOR *********************************************/

	/**
	 * Constructor
	 *
	 * @properties The ColdBox application settings
	 * @controller Acess to the system controller
	 */
	function init( required struct properties = {}, required any controller ){
		// Store controller;
		variables.controller        = arguments.controller;
		// Create the Collections
		variables.context           = structNew();
		variables.privateContext    = structNew();
		// flag for no event execution
		variables.isNoExecution     = false;
		// the name of the event via URL/FORM/REMOTE
		variables.eventName         = arguments.properties.eventName;
		// Registered Layouts
		variables.registeredLayouts = structNew();
		if ( structKeyExists( arguments.properties, "registeredLayouts" ) ) {
			variables.registeredLayouts = arguments.properties.registeredLayouts;
		}
		// Registered Folder Layouts
		variables.folderLayouts = structNew();
		if ( structKeyExists( arguments.properties, "folderLayouts" ) ) {
			variables.folderLayouts = arguments.properties.folderLayouts;
		}
		// Registered View Layouts
		variables.viewLayouts = structNew();
		if ( structKeyExists( arguments.properties, "viewLayouts" ) ) {
			variables.viewLayouts = arguments.properties.viewLayouts;
		}
		// Private Modules reference
		variables.modules       = arguments.properties.modules;
		// Default layout + View
		variables.defaultLayout = arguments.properties.defaultLayout;
		variables.defaultView   = arguments.properties.defaultView;
		// SES Base URL
		variables.SESBaseURL    = "";
		if ( structKeyExists( arguments.properties, "SESBaseURL" ) ) {
			variables.SESBaseURL = arguments.properties.SESBaseURL;
		}
		// routed SES structures
		variables.routedStruct      = structNew();
		// Private Flag for Invalid HTTP Method
		variables.invalidHTTPMethod = false;
		// Rendering Regions
		variables.renderingRegions  = {};
		// Response Headers
		variables.responseHeaders   = {};

		return this;
	}

	/***********************************************************************************************************/
	/************************************** COLLECTION METHODS *********************************************/
	/***********************************************************************************************************/

	/**
	 * Get a representation of this instance
	 */
	struct function getMemento(){
		// Return only non-function elements
		return variables.filter( function( key, value ){
			return ( !isCustomFunction( value ) );
		} );
	}

	/**
	 * Override the instance
	 */
	function setMemento( required struct memento ){
		structAppend( variables, arguments.memento, true );
		return this;
	}

	/**
	 * I Get a reference or deep copy of the public or private request Collection
	 *
	 * @deepCopy Default is false, gives a reference to the collection. True, creates a deep copy of the collection.
	 * @private  Use public or private request collection
	 */
	struct function getCollection( boolean deepCopy = false, boolean private = false ){
		// Private Collection
		if ( arguments.private ) {
			if ( arguments.deepCopy ) {
				return duplicate( variables.privateContext );
			}
			return variables.privateContext;
		}
		// Public Collection
		if ( arguments.deepCopy ) {
			return duplicate( variables.context );
		}
		return variables.context;
	}

	/**
	 * I get a private collection
	 *
	 * @deepCopy Default is false, gives a reference to the collection. True, creates a deep copy of the collection.
	 * @private  Use public or private request collection
	 */
	struct function getPrivateCollection( boolean deepCopy = false ){
		arguments.private = true;
		return getCollection( argumentCollection = arguments );
	}

	/**
	 * Clears the entire collection
	 *
	 * @private Use public or private request collection
	 */
	function clearCollection( boolean private = false ){
		if ( arguments.private ) {
			structClear( variables.privateContext );
		} else {
			structClear( variables.context );
		}
		return this;
	}

	/**
	 * Clears the private collection
	 */
	function clearPrivateCollection(){
		return clearCollection( private = true );
	}

	/**
	 * Append a structure to the collection, with overwrite or not. Overwrite = false by default
	 *
	 * @collection The collection to incorporate
	 * @overwrite  Overwrite elements, defaults to false
	 * @private    Private or public, defaults public.
	 */
	function collectionAppend(
		required struct collection,
		boolean overwrite = false,
		boolean private   = false
	){
		if ( arguments.private ) {
			structAppend(
				variables.privateContext,
				arguments.collection,
				arguments.overwrite
			);
		} else {
			structAppend(
				variables.context,
				arguments.collection,
				arguments.overwrite
			);
		}
		return this;
	}

	/**
	 * Append a structure to the collection, with overwrite or not. Overwrite = false by default
	 *
	 * @collection The collection to incorporate
	 * @overwrite  Overwrite elements, defaults to false
	 */
	function privateCollectionAppend( required struct collection, boolean overwrite = false ){
		arguments.private = true;
		return collectionAppend( argumentCollection = arguments );
	}

	/**
	 * Get the collection Size
	 *
	 * @private Private or public, defaults public.
	 */
	numeric function getSize( boolean private = false ){
		if ( arguments.private ) {
			return structCount( variables.privateContext );
		}
		return structCount( variables.context );
	}

	/**
	 * Get the private collection Size
	 */
	numeric function getPrivateSize(){
		return getSize( private = true );
	}

	/***********************************************************************************************************/
	/************************************** VALUE METHODS *********************************************/
	/***********************************************************************************************************/

	/**
	 * Get a value from the public or private request collection.
	 *
	 * @name         The key name
	 * @defaultValue default value
	 * @private      Private or public, defaults public.
	 */
	function getValue(
		required name,
		defaultValue,
		boolean private = false
	){
		var collection = variables.context;

		// private context switch
		if ( arguments.private ) {
			collection = variables.privateContext;
		}

		// Check if key exists
		if ( structKeyExists( collection, arguments.name ) ) {
			return collection[ arguments.name ];
		}

		// Default value
		if ( structKeyExists( arguments, "defaultValue" ) ) {
			return arguments.defaultValue;
		}

		throw(
			message = "The variable: #arguments.name# is undefined in the request collection (private=#arguments.private#)",
			detail  = "Keys Found: #structKeyList( collection )#",
			type    = "RequestContext.ValueNotFound"
		);
	}

	/**
	 * Get a value from the private request collection.
	 *
	 * @name         The key name
	 * @defaultValue default value
	 */
	function getPrivateValue( required name, defaultValue ){
		arguments.private = true;
		return getValue( argumentCollection = arguments );
	}

	/**
	 * Get a value from the request collection and if simple value, I will trim it.
	 *
	 * @name         The key name
	 * @defaultValue default value
	 * @private      Private or public, defaults public.
	 */
	function getTrimValue(
		required name,
		defaultValue,
		boolean private = false
	){
		var value = getValue( argumentCollection = arguments );

		// Verify if Simple
		if ( isSimpleValue( value ) ) {
			return trim( value );
		}

		return value;
	}

	/**
	 * Get a trim value from the private request collection.
	 *
	 * @name         The key name
	 * @defaultValue default value
	 */
	function getPrivateTrimValue( required name, defaultValue ){
		arguments.private = true;
		return getTrimValue( argumentCollection = arguments );
	}

	/**
	 * Set a value in the request collection
	 *
	 * @name    The key name
	 * @value   The value
	 * @private Private or public, defaults public.
	 *
	 * @return RequestContext
	 */
	function setValue(
		required name,
		required value,
		boolean private = false
	){
		var collection = variables.context;
		if ( arguments.private ) {
			collection = variables.privateContext;
		}

		collection[ arguments.name ] = arguments.value;
		return this;
	}

	/**
	 * Set a value in the private request collection
	 *
	 * @name  The key name
	 * @value The value
	 *
	 * @return RequestContext
	 */
	function setPrivateValue( required name, required value ){
		arguments.private = true;
		return setValue( argumentCollection = arguments );
	}

	/**
	 * remove a value in the request collection
	 *
	 * @name    The key name
	 * @private Private or public, defaults public.
	 *
	 * @return RequestContext
	 */
	function removeValue( required name, boolean private = false ){
		var collection = variables.context;
		if ( arguments.private ) {
			collection = variables.privateContext;
		}

		structDelete( collection, arguments.name );

		return this;
	}

	/**
	 * remove a value in the private request collection
	 *
	 * @name The key name
	 *
	 * @return RequestContext
	 */
	function removePrivateValue( required name, boolean private = false ){
		arguments.private = true;
		return removeValue( argumentCollection = arguments );
	}

	/**
	 * Check if a value exists in the request collection
	 *
	 * @name    The key name
	 * @private Private or public, defaults public.
	 */
	boolean function valueExists( required name, boolean private = false ){
		var collection = variables.context;
		if ( arguments.private ) {
			collection = variables.privateContext;
		}
		return structKeyExists( collection, arguments.name );
	}

	/**
	 * Check if a value exists in the private request collection
	 *
	 * @name The key name
	 */
	boolean function privateValueExists( required name ){
		arguments.private = true;
		return valueExists( argumentCollection = arguments );
	}

	/**
	 * Just like cfparam, but for the request collection
	 *
	 * @name    The key name
	 * @value   The value
	 * @private Private or public, defaults public.
	 *
	 * @return RequestContext
	 */
	function paramValue(
		required name,
		required value,
		boolean private = false
	){
		if ( not valueExists( name = arguments.name, private = arguments.private ) ) {
			setValue(
				name    = arguments.name,
				value   = arguments.value,
				private = arguments.private
			);
		}
		return this;
	}

	/**
	 * Just like cfparam, but for the private request collection
	 *
	 * @name  The key name
	 * @value The value
	 *
	 * @return RequestContext
	 */
	function paramPrivateValue( required name, required value ){
		arguments.private = true;
		return paramValue( argumentCollection = arguments );
	}

	/**
	 * Filters the collection or private collection down to only the provided keys.
	 *
	 * @keys    A list or array of keys to bring back from the collection or private collection.
	 * @private Private or public, defaults public request collection
	 */
	struct function getOnly( required keys, boolean private = false ){
		if ( isSimpleValue( arguments.keys ) ) {
			arguments.keys = listToArray( arguments.keys );
		}
		// determine target context
		var thisContext = arguments.private ? variables.privateContext : variables.context;

		var returnStruct = {};
		for ( var key in arguments.keys ) {
			if ( structKeyExists( thisContext, key ) ) {
				returnStruct[ key ] = thisContext[ key ];
			}
		}

		return returnStruct;
	}

	/**
	 * Filters the private collection down to only the provided keys.
	 *
	 * @keys A list or array of keys to bring back from the private collection.
	 */
	struct function getPrivateOnly( required keys ){
		return getOnly( keys = keys, private = true );
	}

	/**
	 * Filters the collection or private collection down to all keys except the provided keys.
	 *
	 * @keys    A list or array of keys to exclude from the results of the collection or private collection.
	 * @private Private or public, defaults public request collection
	 */
	struct function getExcept( required keys, boolean private = false ){
		if ( isSimpleValue( arguments.keys ) ) {
			arguments.keys = listToArray( arguments.keys );
		}
		// determine target context
		var thisContext = arguments.private ? variables.privateContext : variables.context;

		var returnStruct = {};
		for ( var key in thisContext ) {
			if ( !arrayContains( arguments.keys, key ) ) {
				returnStruct[ key ] = thisContext[ key ];
			}
		}

		return returnStruct;
	}

	/**
	 * Filters the private collection down to all keys except the provided keys.
	 *
	 * @keys A list or array of keys to exclude from the results of the private collection.
	 */
	struct function getPrivateExcept( required keys ){
		return getExcept( keys = keys, private = true );
	}

	/***********************************************************************************************************/
	/************************************** CURRENT CONTEXT METHODS **************************************/
	/***********************************************************************************************************/

	/**
	 * Gets the current set view the framework will try to render for this request
	 */
	string function getCurrentView(){
		return getPrivateValue( "currentView", "" );
	}

	/**
	 * Gets the current set view the framework will try to render for this request
	 */
	struct function getCurrentViewArgs(){
		return getPrivateValue( "currentViewArgs", structNew() );
	}

	/**
	 * Gets the current set views's module for rendering
	 */
	string function getCurrentViewModule(){
		return getPrivateValue( "viewModule", "" );
	}

	/**
	 * Gets the current set layout for rendering
	 */
	string function getCurrentLayout(){
		return getPrivateValue( "currentLayout", "" );
	}

	/**
	 * Gets the current set layout's module for rendering
	 */
	string function getCurrentLayoutModule(){
		return getPrivateValue( "layoutmodule", "" );
	}

	/**
	 * Get the current request's route pattern that matched
	 */
	string function getCurrentRoute(){
		return getPrivateValue( "currentRoute", "" );
	}

	/**
	 * Get the current request's routed name
	 */
	string function getCurrentRouteName(){
		return getPrivateValue( "currentRouteName", "" );
	}

	/**
	 * Get the current routed namespace that matched the route, if any
	 */
	string function getCurrentRoutedNamespace(){
		return getPrivateValue( "currentRoutedNamespace", "" );
	}

	/**
	 * Get the current routed module that matched the route, if any
	 */
	string function getCurrentRoutedModule(){
		return getPrivateValue( "currentRoutedModule", "" );
	}

	/**
	 * Get the current routed URL that matched the route pattern
	 */
	string function getCurrentRoutedURL(){
		return getPrivateValue( "currentRoutedURL", "" );
	}

	/**
	 * Get the current routed route record in all of its raw glory
	 * Returns an empty struct if no record was found.
	 */
	struct function getCurrentRouteRecord(){
		return getPrivateValue( "currentRouteRecord", {} );
	}

	/**
	 * Gets the current routed route's metadata struct, if any
	 * Returns an empty struct if no record was found.
	 */
	struct function getCurrentRouteMeta(){
		return getPrivateValue( "currentRouteMeta", {} );
	}

	/**
	 * Verify if the passed name is the same as the current route name
	 *
	 * @name The name to test against the current route
	 */
	boolean function routeIs( required name ){
		return getCurrentRouteName() == arguments.name;
	}

	/**
	 * Tests that a given path exists in the currently routed URL.
	 * If the exact flag is passed, the path must match exactly.
	 * Using the `urlMatchesExact` is preferred.
	 *
	 * @path  The path to match in the currently routed URL.
	 * @exact Flag to do an exact match instead of a partial match
	 *
	 * @return Boolean
	 */
	boolean function urlMatches( required string path, boolean exact = false ){
		// Cleanup, routed url never has a `/` in front
		arguments.path       = reReplace( arguments.path, "^/", "" );
		var currentRoutedURL = getCurrentRoutedURL();

		if ( arguments.exact ) {
			return arguments.path == currentRoutedURL;
		}

		// if the incoming path to look for is greater than the current routed url, bail out
		if ( arguments.path.len() > currentRoutedURL.len() ) {
			return false;
		}

		var replaced = replace( currentRoutedURL, arguments.path, "" );
		var sliced   = mid(
			currentRoutedURL,
			len( arguments.path ) + 1,
			len( currentRoutedURL ) - len( arguments.path )
		);
		return replaced == sliced;
	}

	/**
	 * Tests that a given path matches exactly to the currently routed URL.
	 *
	 * @path The path to match exactly to the currently routed URL.
	 *
	 * @return Boolean
	 */
	boolean function urlMatchesExact( required string path ){
		arguments.exact = true;
		return urlMatches( argumentCollection = arguments );
	}

	/**
	 * Gets the current incoming event
	 */
	string function getCurrentEvent(){
		return getValue( variables.eventName, "" );
	}

	/**
	 * Gets the current handler requested in the current event
	 */
	string function getCurrentHandler(){
		var thisEvent = getCurrentEvent();
		// If module call, clean it up
		if ( find( ":", thisEvent ) ) {
			thisEvent = getToken( thisEvent, 2, ":" );
		}
		var testHandler = reReplace( thisEvent, "\.[^.]*$", "" );
		if ( listLen( testHandler, "." ) eq 1 ) {
			return testHandler;
		}

		return listLast( testHandler, "." );
	}

	/**
	 * Gets the current action requested in the current event
	 */
	string function getCurrentAction(){
		return listLast( getCurrentEvent(), "." );
	}

	/**
	 * Gets the current module name, else returns empty string
	 */
	string function getCurrentModule(){
		var thisEvent = getCurrentEvent();
		return ( find( ":", thisEvent ) ? listFirst( thisEvent, ":" ) : "" );
	}

	/**
	 * Convenience method to get the current request's module root path. If no module, then returns empty path. You can also get this from the modules settings
	 *
	 * @module Optional name of the module you want the root for, defaults to the current running module
	 */
	string function getModuleRoot( module = "" ){
		var theModule = "";
		if ( structKeyExists( arguments, "module" ) and len( arguments.module ) ) {
			theModule = arguments.module;
		} else {
			theModule = getCurrentModule();
		}
		if ( len( theModule ) ) {
			return variables.modules[ theModule ].mapping;
		}
		return "";
	}

	/**
	 * Convenience method to get a module's inherited entry point URL, blank if not found
	 *
	 * @module Optional name of the module you want the root for, defaults to the current running module
	 */
	string function getModuleEntryPoint( module = "" ){
		var theModule = "";
		if ( structKeyExists( arguments, "module" ) and len( arguments.module ) ) {
			theModule = arguments.module;
		} else {
			theModule = getCurrentModule();
		}
		if ( len( theModule ) ) {
			return variables.modules[ theModule ].inheritedEntryPoint;
		}
		return "";
	}

	/**
	 * Are we in SSL or not? This method looks at CGI.SERVER_PORT_SECURE for indication
	 */
	boolean function isSSL(){
		if ( isBoolean( CGI.SERVER_PORT_SECURE ) AND CGI.SERVER_PORT_SECURE ) {
			return true;
		}
		// Add typical proxy headers for SSL
		if ( getHTTPHeader( "x-forwarded-proto", "http" ) eq "https" ) {
			return true;
		}
		if ( getHTTPHeader( "x-scheme", "http" ) eq "https" ) {
			return true;
		}
		// CGI.HTTPS
		if ( CGI.keyExists( "HTTPS" ) and CGI.HTTPS eq "on" ) {
			return true;
		}
		return false;
	}

	/**
	 * Check if the request was made with an invalid HTTP Method
	 */
	boolean function isInvalidHTTPMethod(){
		return variables.invalidHTTPMethod;
	}

	/**
	 * Set the invalid http method flag
	 */
	RequestContext function setIsInvalidHTTPMethod( boolean target = true ){
		variables.invalidHTTPMethod = arguments.target;
		return this;
	}

	/**
	 * Set the request timeout for the request.
	 *
	 * @seconds The number of seconds as a time limit
	 *
	 * @return RequestContext
	 */
	RequestContext function setRequestTimeout( required numeric seconds ){
		setting requesttimeout=arguments.seconds;
		return this;
	}

	/***********************************************************************************************************/
	/************************************** VIEW-LAYOUT METHODS *******************************************/
	/***********************************************************************************************************/

	/**
	 * Set the view to render in this request. Private Request Collection Name: currentView, currentLayout
	 *
	 * @view                   The name of the view to set. If a layout has been defined it will assign it, else if will assign the default layout. No extension please
	 * @args                   An optional set of arguments that will be available when the view is rendered
	 * @layout                 You can override the rendering layout of this setView() call if you want to. Else it defaults to implicit resolution or another override.
	 * @module                 The explicit module view
	 * @noLayout               Boolean flag, wether the view sent in will be using a layout or not. Default is false. Uses a pre set layout or the default layout.
	 * @cache                  True if you want to cache the rendered view.
	 * @cacheTimeout           The cache timeout in minutes
	 * @cacheLastAccessTimeout The last access timeout in minutes
	 * @cacheSuffix            Add a cache suffix to the view cache entry. Great for multi-domain caching or i18n caching.
	 * @cacheProvider          The cache provider you want to use for storing the rendered view. By default we use the 'template' cache provider
	 * @name                   This triggers a rendering region.  This will be the unique name in the request for specifying a rendering region, you can then render it by passing the unique name to the view();
	 *
	 * @return RequestContext
	 */
	function setView(
		view,
		struct args = {},
		layout,
		module                 = "",
		boolean noLayout       = false,
		boolean cache          = false,
		cacheTimeout           = "",
		cacheLastAccessTimeout = "",
		cacheSuffix            = "",
		cacheProvider          = "template",
		name
	){
		// Do we have an incoming rendering region definition? If we do, store it and return
		if ( !isNull( arguments.name ) ) {
			variables.renderingRegions[ arguments.name ] = arguments;
			return this;
		}

		// stash the view module
		variables.privateContext[ "viewModule" ] = arguments.module;

		// Direct Layout Usage
		if ( !isNull( arguments.layout ) && len( arguments.layout ) ) {
			setLayout( arguments.layout );
		}
		// else try to discover it.
		else if ( NOT arguments.noLayout AND NOT getPrivateValue( name = "layoutoverride", defaultValue = false ) ) {
			var discoveredLayout = discoverLayout( arguments.view );
			if ( discoveredLayout.len() ) {
				setPrivateValue( "currentLayout", discoveredLayout );
			}
		}

		// No Layout Rendering?
		if ( arguments.nolayout ) {
			removePrivateValue( "currentLayout" );
		}

		// Do we need to cache the view
		if ( arguments.cache ) {
			// prepare the cache keys
			var cacheEntry = {
				view              : arguments.view,
				timeout           : "",
				lastAccessTimeout : "",
				cacheSuffix       : arguments.cacheSuffix,
				cacheProvider     : arguments.cacheProvider
			};

			if ( isNumeric( arguments.cacheTimeout ) ) {
				cacheEntry.timeout = arguments.cacheTimeout;
			}

			if ( isNumeric( arguments.cacheLastAccessTimeout ) ) {
				cacheEntry.lastAccessTimeout = arguments.cacheLastAccessTimeout;
			}

			// Save the view cache entry
			setViewCacheableEntry( cacheEntry );
		}

		// Set the current view to render.
		variables.privateContext[ "currentView" ] = arguments.view;

		// Record the optional arguments
		setPrivateValue( "currentViewArgs", arguments.args, true );

		return this;
	}

	/**
	 * This function discovers implicitly the layout that accompanies the passed in view
	 * via the <pre>viewLayouts</pre> setting.
	 *
	 * @view The target view to discover the layout for.
	 *
	 * @return The layout attached to this view for rendering purposes, if none is discovered an empty string is returned.
	 */
	function discoverLayout( required string view ){
		// Verify that the view has a layout in the viewLayouts
		if ( structKeyExists( variables.viewLayouts, arguments.view ) ) {
			return variables.viewLayouts[ arguments.view ];
		}

		// Check the folders conventions now
		for ( var key in variables.folderLayouts ) {
			if ( reFindNoCase( "^#key#", arguments.view ) ) {
				return variables.folderLayouts[ key ];
			}
		}

		// If in current module, check for a module default layout
		var cModule = getCurrentModule();
		if (
			len( cModule )
			AND structKeyExists( variables.modules, cModule )
			AND len( variables.modules[ cModule ].layoutSettings.defaultLayout )
		) {
			return variables.modules[ cModule ].layoutSettings.defaultLayout;
		}

		// Fallback to application global layout
		if ( not privateValueExists( "currentLayout" ) ) {
			return variables.defaultLayout;
		}

		// Else, we have no clue what layout, set to empty
		return "";
	}

	/**
	 * Mark this request to not use a layout for rendering
	 *
	 * @return RequestContext
	 */
	function noLayout(){
		// remove layout if any
		structDelete( variables.privateContext, "currentLayout" );
		// set layout overwritten flag.
		variables.privateContext[ "layoutoverride" ] = true;
		return this;
	}

	/**
	 * Set the layout to override and render. Layouts are pre-defined in the config file. However I can override these settings if needed. Do not append a the cfm extension. Private Request Collection name
	 *
	 * @name   The name of the layout to set
	 * @module The module to use
	 */
	function setLayout( required name, module = "" ){
		// Set direct layout first.
		variables.privateContext[ "currentLayout" ] = trim( arguments.name ) & ".cfm";
		// Do an Alias Check and override if found.
		if ( structKeyExists( variables.registeredLayouts, arguments.name ) ) {
			variables.privateContext[ "currentLayout" ] = variables.registeredLayouts[ arguments.name ];
		}
		// set layout overwritten flag.
		variables.privateContext[ "layoutoverride" ] = true;
		// module layout?
		variables.privateContext[ "layoutmodule" ]   = arguments.module;

		return this;
	}

	/**
	 * Override the default layout for a request
	 *
	 * @return RequestContext
	 */
	function setDefaultLayout( required defaultLayout ){
		variables.defaultLayout = arguments.defaultLayout;
		return this;
	}

	/**
	 * Override the default view for a request
	 *
	 * @return RequestContext
	 */
	function setDefaultView( required defaultView ){
		variables.defaultView = arguments.defaultView;
		return this;
	}

	/***********************************************************************************************************/
	/************************************** EVENT METHODS **************************************************/
	/***********************************************************************************************************/

	/**
	 * Override the current event in the request collection. This method does not execute the event, it just replaces the event to be executed by the framework's RunEvent() method. This method is usually called from an onRequestStart or onApplicationStart method
	 *
	 * @event The event to override with
	 *
	 * @return RequestContext
	 */
	function overrideEvent( required event ){
		setValue( variables.eventName, arguments.event );
		// Clear out any previous caching influences
		setEventCacheableEntry( {} );
		return this;
	}

	/**
	 * Set that this is a proxy request
	 *
	 * @return RequestContext
	 */
	function setProxyRequest(){
		return setPrivateValue( "coldbox_proxyrequest", true );
	}

	/**
	 * Is this a coldbox proxy request
	 */
	boolean function isProxyRequest(){
		return getPrivateValue( "coldbox_proxyrequest", false );
	}

	/**
	 * Set the flag that tells the framework not to render, just execute
	 *
	 * @remove Remove the flag completely
	 *
	 * @return RequestContext
	 */
	function noRender( boolean remove = false ){
		if ( arguments.remove eq false ) return setPrivateValue( name = "coldbox_norender", value = true );
		else return removePrivateValue( name = "coldbox_norender" );
	}

	/**
	 * Is this a no render request
	 */
	boolean function isNoRender(){
		return getPrivateValue( name = "coldbox_norender", defaultValue = false );
	}

	/**
	 * Set that the request will not execute an incoming event. Most likely simulating a servlet call
	 *
	 * @return RequestContext
	 */
	function noExecution(){
		variables.isNoExecution = true;
		return this;
	}

	/***********************************************************************************************************/
	/************************************** URL METHODS ****************************************************/
	/***********************************************************************************************************/

	/**
	 * Setter for verifying SES mode
	 *
	 * @deprecated This will be removed in ColdBox 7
	 *
	 * @return RequestContext
	 */
	function setSESEnabled( required boolean flag ){
		return this;
	}

	/**
	 * Verify if SES is enabled or not in the request
	 *
	 * @deprecated This will be removed in ColdBox 7
	 */
	boolean function isSES(){
		return true;
	}

	/**
	 * Get the HTML base URL that is used for the HTML <base> tag. This also accounts for SSL or not.
	 */
	string function getHTMLBaseURL(){
		return reReplaceNoCase(
			buildLink( to = "", ssl = isSSL() ),
			"index.cfm\/?",
			""
		) & getContextRoot().reReplace( "^/", "" );
	}

	/**
	 * Returns the HTML base path - minus the protocol and domain
	 */
	string function getHTMLBasePath(){
		return variables.controller.getSetting( "HTMLBasePath", "" );
	}

	/**
	 * Returns the SES base path - minus the protocol and domain
	 */
	string function getSESBasePath(){
		return variables.controller.getSetting( "SESBasePath", "" );
	}

	/**
	 * Set the ses base URL for this request
	 *
	 * @return RequestContext
	 */
	function setSESBaseURL( required string sesBaseURL ){
		variables.sesBaseURL = arguments.sesBaseURL;
		return this;
	}

	/**
	 * Returns index.cfm?{eventName}=
	 */
	string function getSelf(){
		return "index.cfm?" & variables.eventName & "=";
	}

	/**
	 * Returns the full url including the protocol, host, mapping, path info, and query string.
	 * Handles SES urls gracefully.
	 *
	 * @withQuery Add the query string or not, by default it adds it
	 *
	 * @return The full url including the protocol, host, mapping, path info, and query string (maybe).
	 */
	string function getUrl( boolean withQuery = true ){
		var javaURI = createObject( "java", "java.net.URI" );
		var baseUrl = javaURI.create( getSESBaseURL() );
		var fullUrl = javaURI
			.init(
				baseUrl.getScheme(),
				baseUrl.getAuthority(),
				CGI.PATH_INFO != "" ? CGI.PATH_INFO : javacast( "null", "" ),
				javacast( "null", "" ),
				javacast( "null", "" )
			)
			.toString();

		if ( !arguments.withQuery || CGI.QUERY_STRING == "" ) {
			return fullUrl;
		}

		return fullUrl & "?" & CGI.QUERY_STRING;
	}

	/**
	 * @deprecated Use `getUrl()` instead
	 */
	string function getFullUrl(){
		return getUrl();
	}

	/**
	 * Return the relative path of the current request
	 *
	 * @withQuery Add the query string or not, by default it adds it
	 *
	 * @return the full relative path to the requested event: does not include protocol and host
	 */
	string function getPath( boolean withQuery = true ){
		return arrayToList(
			[
				variables.controller
					.getRoutingService()
					.getRouter()
					.composeRoutingPath(),
				left( CGI.PATH_INFO, 1 ) == "/" ? right( CGI.PATH_INFO, -1 ) : CGI.PATH_INFO,
				arguments.withQuery && CGI.QUERY_STRING != "" && CGI.PATH_INFO == "" ? "/" : "",
				arguments.withQuery && CGI.QUERY_STRING != "" ? "?" : "",
				arguments.withQuery ? CGI.QUERY_STRING : ""
			],
			""
		);
	}

	/**
	 * @Deprecated Use `getPath()` instead
	 */
	string function getFullPath(){
		return getPath();
	}

	/**
	 * Get all of the url path segments from the requested path
	 */
	array function getPathSegments(){
		return getPath( withQuery: false ).listToArray( "/" );
	}

	/**
	 * Get the segment from the incoming path at the specified index location
	 *
	 * @index        The index location
	 * @defaultValue If the index doesn't exist, return the default value
	 *
	 * @throws InvalidSegmentIndex - When the passed index doesn't exist
	 */
	function getPathSegment( required numeric index, defaultValue ){
		var segments = getPathSegments();
		// Verify it exists
		if ( segments.isDefined( arguments.index ) ) {
			return segments[ arguments.index ];
		}
		// Do we have a default value
		if ( !isNull( arguments.defaultValue ) ) {
			return arguments.defaultValue;
		}
		// Kick it!
		throw(
			type   : "InvalidSegmentIndex",
			message: "The segment index (#arguments.index#) does not exist in the current segments (#segments.len()#)"
		);
	}

	/**
	 * Builds links to named routes with or without parameters. If the named route is not found, 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.
	 *
	 * @name   The name of the route
	 * @params The parameters of the route to replace
	 * @ssl    Turn SSL on/off or detect it by default
	 *
	 * @throws InvalidArgumentException - If thre requested route name is not registered
	 */
	string function route( required name, struct params = {}, boolean ssl ){
		// Get routing service and default routes
		var router = variables.controller.getWirebox().getInstance( "router@coldbox" );

		// Module Route?
		var targetModule = "";
		if ( find( "@", arguments.name ) ) {
			targetModule = getToken( arguments.name, 2, "@" );
		}
		if ( find( ":", arguments.name ) ) {
			targetModule = getToken( arguments.name, 1, ":" );
		}
		// Discover route entry point
		var entryPoint = len( targetModule ) ? variables.modules[ targetmodule ].inheritedEntryPoint : "";

		// Find the named route
		var foundRoute = router.findRouteByName( arguments.name );

		// Did we find it?
		if ( !foundRoute.isEmpty() ) {
			var args = {
				to  : entryPoint & foundRoute.pattern,
				ssl : !isNull( arguments.ssl ) ? arguments.ssl : javacast( "null", "" )
			};

			// Process Params
			arguments.params.each( function( key, value ){
				args.to =
				reReplaceNoCase(
					args.to,
					":#arguments.key#-?[^/]*",
					encodeForURL( arguments.value ),
					"all"
				)
				;
			} );

			return buildLink( argumentCollection = args );
		}

		throw( type = "InvalidArgumentException", message = "The named route '#arguments.name#' does not exist" );
	}

	/**
	 * Builds links to events or URL Routes
	 *
	 * @to          The event or route path you want to create the link to
	 * @queryString The query string to append which can be a regular query string string, or a struct of name-value pairs
	 * @translate   Translate between . to / depending on the SES mode on to and queryString arguments. Defaults to true.
	 * @ssl         Turn SSl on/off on URL creation, by default is SSL is enabled, we will use it.
	 * @baseURL     If not using SES, you can use this argument to create your own base url apart from the default of index.cfm. Example: https://mysample.com/index.cfm
	 */
	string function buildLink(
		to,
		queryString       = "",
		boolean translate = true,
		boolean ssl,
		baseURL = ""
	){
		// Is this a named route?
		if ( isStruct( arguments.to ) ) {
			param arguments.to.params = {};
			param arguments.ssl       = this.isSSL();
			return this.route(
				name  : arguments.to.name,
				params: arguments.to.params,
				ssl   : arguments.ssl
			);
		}

		// Query String Struct to String
		if ( isStruct( arguments.queryString ) ) {
			arguments.queryString = arguments.queryString
				.reduce( function( result, key, value ){
					result.append( "#encodeForURL( key )#=#encodeForURL( value )#" );
					return result;
				}, [] )
				.toList( "&" );
		}

		// Cleanups
		arguments.to          = trim( arguments.to );
		arguments.baseURL     = trim( arguments.baseURL );
		arguments.queryString = trim( arguments.queryString );

		// Front Controller Base
		var frontController = "index.cfm";
		if ( len( arguments.baseURL ) neq 0 ) {
			frontController = arguments.baseURL;
		}

		// SSL ON OR TURN IT ON
		if ( isSSL() OR ( !isNull( arguments.ssl ) and arguments.ssl ) ) {
			variables.SESBaseURL = replaceNoCase( variables.SESBaseURL, "http:", "https:" );
		}

		// SSL Turn Off
		if ( !isNull( arguments.ssl ) and arguments.ssl eq false ) {
			variables.SESBaseURL = replaceNoCase( variables.SESBaseURL, "https:", "http:" );
		}

		// Translate link or plain
		if ( arguments.translate ) {
			// Convert module into proper entry point
			if ( listLen( arguments.to, ":" ) > 1 ) {
				var mConfig = controller.getSetting( "modules" );
				var module  = listFirst( arguments.to, ":" );
				if ( structKeyExists( mConfig, module ) ) {
					arguments.to = mConfig[ module ].inheritedEntryPoint & "/" & listRest( arguments.to, ":" );
				}
			}
			arguments.to = replace( arguments.to, ".", "/", "all" );

			// Conversions
			if ( len( arguments.queryString ) ) {
				if ( right( arguments.to, 1 ) neq "/" ) {
					arguments.to = arguments.to & "/";
				}
				arguments.to = arguments.to & replace( arguments.queryString, "&", "/", "all" );
				arguments.to = replace( arguments.to, "=", "/", "all" );
			}
		} else if ( len( arguments.queryString ) ) {
			arguments.to = arguments.to & "?" & arguments.queryString;
		}

		// Prepare SES Base URL Link
		if ( right( variables.SESBaseURL, 1 ) eq "/" ) {
			return variables.SESBaseURL & arguments.to;
		} else {
			return variables.SESBaseURL & "/" & arguments.to;
		}
	}

	/***********************************************************************************************************/
	/************************************** CACHING **********************************************************/
	/***********************************************************************************************************/

	/**
	 * Check wether the incoming event has been flagged for caching
	 */
	boolean function isEventCacheable(){
		return privateValueExists( name = "cbox_eventCacheableEntry" );
	}

	/**
	 * Check wether the incoming event has been flagged for caching
	 *
	 * @cacheEntry The md entry for caching
	 *
	 * @return RequestContext
	 */
	function setEventCacheableEntry( required struct cacheEntry ){
		return setPrivateValue( name = "cbox_eventCacheableEntry", value = arguments.cacheEntry );
	}

	/**
	 * Get the event cacheable entry
	 */
	struct function getEventCacheableEntry(){
		return getPrivateValue( name = "cbox_eventCacheableEntry", defaultValue = structNew() );
	}

	/**
	 * Check wether the incoming event has been flagged for caching
	 *
	 * @return RequestContext
	 */
	function removeEventCacheableEntry(){
		return removePrivateValue( name = "cbox_eventCacheableEntry" );
	}

	/**
	 * Check wether the incoming view has been flagged for caching
	 */
	boolean function isViewCacheable(){
		return privateValueExists( name = "cbox_viewCacheableEntry" );
	}

	/**
	 * Set the view cacheable entry
	 *
	 * @cacheEntry The md entry for caching
	 *
	 * @return RequestContext
	 */
	function setViewCacheableEntry( required struct cacheEntry ){
		return setPrivateValue( name = "cbox_viewCacheableEntry", value = arguments.cacheEntry );
	}

	/**
	 * Get the event cacheable entry
	 */
	struct function getViewCacheableEntry(){
		return getPrivateValue( name = "cbox_viewCacheableEntry", defaultValue = structNew() );
	}

	/***********************************************************************************************************/
	/************************************** RESTFUL **********************************************************/
	/***********************************************************************************************************/

	/**
	 * Get the response object for the current request. If there is none, then return a new one
	 * The response object lives in `prc.response`
	 *
	 * @return coldbox.system.web.context.Response
	 */
	function getResponse(){
		if ( isNull( variables.privateContext.response ) ) {
			variables.privateContext.response = new coldbox.system.web.context.Response();
		}
		return variables.privateContext.response;
	}

	/**
	 * Get the routed structure of key-value pairs. What the ses interceptor could match.
	 *
	 * @return RequestContext
	 */
	function setRoutedStruct( required struct routedStruct ){
		variables.routedStruct = arguments.routedStruct;
		return this;
	}

	/**
	 * This method will send a file to the browser or requested HTTP protocol according to arguments.
	 * CF11+ Compatibility
	 *
	 * @file        The absolute path to the file or a binary file to send
	 * @name        The name to send to the browser via content disposition header.  If not provided then the name of the file or a UUID for a binary file will be used
	 * @mimeType    A valid mime type to use.  If not passed, then we will try to use one according to file type
	 * @disposition The browser content disposition (attachment/inline) header
	 * @abortAtEnd  If true, then this method will do a hard abort, we do not recommend this, prefer the event.noRender() for a graceful abort.
	 * @extension   Only used for binary files which types are not determined.
	 * @deleteFile  Delete the file after it has been streamed to the user. Only used if file is not binary.
	 */
	function sendFile(
		file               = "",
		name               = "",
		mimeType           = "",
		disposition        = "attachment",
		boolean abortAtEnd = "false",
		extension          = "",
		boolean deleteFile = false
	){
		var fileSize = 0;

		// Binary detection settings
		if ( isBinary( arguments.file ) ) {
			if ( len( trim( arguments.name ) ) eq 0 ) {
				arguments.name = createUUID();
			}
			if ( !len( trim( arguments.extension ) ) ) {
				throw( message = "Extension missing for binary file.", type = "InvalidExtensionException" );
			}
			// Determine file size
			fileSize = len( arguments.file );
			//  Lookup mime type
			if ( !len( trim( arguments.mimetype ) ) ) {
				arguments.mimetype = getFileMimeType( extension );
			}
		}
		// Else file on disk settings
		else if ( fileExists( arguments.file ) ) {
			// Did we pass a name? Else get it from file path
			if ( !len( trim( arguments.name ) ) ) {
				arguments.name = reReplace(
					getFileFromPath( arguments.file ),
					"\.[^.]*$",
					""
				);
			}
			//  Set extension
			arguments.extension = listLast( arguments.file, "." );
			//  Set size
			fileSize            = getFileInfo( arguments.file ).size;
			//  Lookup mime type
			if ( !len( trim( arguments.mimetype ) ) ) {
				arguments.mimetype = fileGetMimeType( arguments.file );
			}
		} else {
			throw(
				message = "No file binary or file '#arguments.file#' located. Please check your path and arguments.",
				type    = "InvalidFileException"
			);
		}

		// detect if extension is already included in name argument, if not add
		if ( listLast( arguments.name, "." ) != arguments.extension ) {
			arguments.name &= ".#arguments.extension#";
		}

		//  Set content headers
		setHTTPHeader(
			name  = "content-disposition",
			value = "#arguments.disposition#; filename=#urlEncodedFormat( arguments.name )#"
		);
		setHTTPHeader( name = "content-length", value = fileSize );

		//  Send file
		if ( isBinary( arguments.file ) ) {
			cfcontent( variable = arguments.file, type = arguments.mimetype );
		} else {
			cfcontent(
				deletefile = arguments.deleteFile,
				file       = arguments.file,
				type       = arguments.mimetype
			);
		}

		//  Abort further processing?
		if ( arguments.abortAtEnd ) {
			abort;
		}
	}

	/**
	 * Use this method to tell the framework to render data for you. The framework will take care of marshalling the data for you
	 *
	 * @type             The type of data to render. Valid types are JSON, JSONP, JSONT, XML, WDDX, PLAIN/HTML, TEXT, PDF. The default is HTML or PLAIN. If an invalid type is sent in, this method will throw an error
	 * @data             The data you would like to marshall and return by the framework
	 * @contentType      The content type of the data. This will be used in the cfcontent tag: text/html, text/plain, text/xml, text/json, etc. The default value is text/html. However, if you choose JSON this method will choose application/json, if you choose WDDX or XML this method will choose text/xml for you.
	 * @encoding         The default character encoding to use.  The default encoding is utf-8
	 * @statusCode       The HTTP status code to send to the browser. Defaults to 200
	 * @statusText       Explains the HTTP status code sent to the browser.
	 * @location         Optional argument used to set the HTTP Location header
	 * @jsonCallback     Only needed when using JSONP, this is the callback to add to the JSON packet
	 * @jsonAsText       If set to false, defaults content mime-type to application/json, else will change encoding to plain/text
	 * @xmlColumnList    XML Only: Choose which columns to inspect, by default it uses all the columns in the query, if using a query
	 * @xmlUseCDATA      XML Only: Use CDATA content for ALL values. The default is false
	 * @xmlListDelimiter XML Only: The delimiter in the list. Comma by default
	 * @xmlRootName      XML Only: The name of the initial root element of the XML packet
	 * @pdfArgs          All the PDF arguments to pass along to the CFDocument tag.
	 * @formats          The formats list or array that ColdBox should respond to using the passed in data argument. You can pass any of the valid types (JSON,JSONP,JSONT,XML,WDDX,PLAIN,HTML,TEXT,PDF). For PDF and HTML we will try to render the view by convention based on the incoming event
	 * @formatsView      The view that should be used for rendering HTML/PLAIN/PDF. By default ColdBox uses the name of the event as an implicit view
	 * @formatsRedirect  The arguments that should be passed to relcoate as part of a redirect for the HTML action.  If the format is HTML and this struct is not empty, ColdBox will call relcoate with these arguments.
	 * @isBinary         Bit that determines if the data being set for rendering is binary or not.
	 */
	function renderData(
		type = "HTML",
		required data,
		contentType         = "",
		encoding            = "utf-8",
		numeric statusCode  = 200,
		statusText          = "",
		location            = "",
		jsonCallback        = "",
		boolean jsonAsText  = false,
		xmlColumnList       = "",
		boolean xmlUseCDATA = false,
		xmlListDelimiter    = ",",
		xmlRootName         = "",
		struct pdfArgs      = {},
		formats             = "",
		formatsView         = "",
		formatsRedirect     = {},
		boolean isBinary    = false
	){
		var rd = structNew();

		// With Formats?
		if ( isArray( arguments.formats ) OR len( arguments.formats ) ) {
			return renderWithFormats( argumentCollection = arguments );
		}

		// Validate rendering type
		if ( not reFindNoCase( "^(JSON|JSONP|JSONT|WDDX|XML|PLAIN|HTML|TEXT|PDF)$", arguments.type ) ) {
			throw(
				message = "Invalid rendering type",
				detail  = "The type you sent #arguments.type# is not a valid rendering type. Valid types are JSON,JSONP,JSONT,XML,WDDX,TEXT,PLAIN,PDF",
				type    = "RequestContext.InvalidRenderTypeException"
			);
		}

		// Default Values for incoming variables
		rd.type        = arguments.type;
		rd.data        = arguments.data;
		rd.encoding    = arguments.encoding;
		rd.contentType = "text/html";
		rd.isBinary    = arguments.isBinary;

		// HTTP status
		rd.statusCode = arguments.statusCode;
		rd.statusText = arguments.statusText;

		// XML Properties
		rd.xmlColumnList    = arguments.xmlColumnList;
		rd.xmluseCDATA      = arguments.xmlUseCDATA;
		rd.xmlListDelimiter = arguments.xmlListDelimiter;
		rd.xmlRootName      = arguments.xmlRootName;

		// JSON Properties
		rd.jsonCallBack = arguments.jsonCallBack;

		// PDF properties
		rd.pdfArgs = arguments.pdfArgs;

		// Automatic Content Types by marshalling type
		switch ( rd.type ) {
			case "JSON": {
				rd.contenttype = "application/json";
				if ( arguments.jsonAsText ) {
					rd.contentType = "text/plain";
				}
				break;
			}
			case "JSONP": {
				rd.contentType = "application/javascript";
				break;
			}
			case "JSONT": {
				rd.contentType = "text/plain";
				rd.type        = "JSON";
				break;
			}
			case "XML":
			case "WDDX": {
				rd.contentType = "text/xml";
				break;
			}
			case "TEXT": {
				rd.contentType = "text/plain";
				break;
			}
			case "PDF": {
				rd.contentType = "application/pdf";
				rd.isBinary    = true;
				break;
			}
		}

		// If contenttype passed, then override it?
		if ( len( trim( arguments.contentType ) ) ) {
			rd.contentType = arguments.contentType;
		}

		// HTTP Location?
		if ( len( arguments.location ) ) {
			setHTTPHeader( name = "location", value = arguments.location );
		}

		// Save Rendering data privately.
		setPrivateValue( name = "cbox_renderdata", value = rd );

		return this;
	}

	/**
	 * Get the renderData structure
	 */
	struct function getRenderData(){
		return getPrivateValue( name = "cbox_renderdata", defaultValue = structNew() );
	}

	/**
	 * Get the HTTP Request Method Type
	 */
	string function getHTTPMethod(){
		return getValue( "_method", CGI.REQUEST_METHOD );
	}

	/**
	 * Get the raw HTTP body content with conversions if needed
	 *
	 * @json Try to return the content as deserialized json
	 * @xml  Try to return the content as an XML object
	 */
	any function getHTTPContent( boolean json = false, boolean xml = false ){
		// Only read the content once
		if ( !structKeyExists( variables.privateContext, "_httpContent" ) ) {
			try {
				variables.privateContext._httpContent = getHTTPRequestData().content;
			} catch ( "java.lang.NullPointerException" e ) {
				// if an exception is thrown, it's most likely we are in a thread, default it to empty string
				variables.privateContext._httpContent = "";
			}
		}

		// leave translations NOT cached, as you could ask for different types of formats
		// during a single request.
		if ( arguments.json and isJSON( toString( variables.privateContext._httpContent ) ) ) {
			return deserializeJSON( toString( variables.privateContext._httpContent ) );
		} else if (
			arguments.xml and len( toString( variables.privateContext._httpContent ) ) and isXML(
				toString( variables.privateContext._httpContent )
			)
		) {
			return xmlParse( toString( variables.privateContext._httpContent ) );
		}

		return variables.privateContext._httpContent;
	}

	/**
	 * Get an HTTP header. If the header doesn't exist the default value of empty string is returned.
	 *
	 * @header       The header to get
	 * @defaultValue The default value, if not found
	 */
	function getHTTPHeader( required header, defaultValue = "" ){
		var headers = {};
		try {
			headers = getHTTPRequestData( false ).headers;
		} catch ( "java.lang.NullPointerException" e ) {
			// if an exception is thrown, it's most likely we are in a thread, default it to {}
			headers = {};
		}

		// ADOBE FIX YOUR ISNULL BS
		if ( headers.keyExists( arguments.header ) ) {
			return headers[ arguments.header ];
		}

		return arguments.defaultValue;
	}

	/**
	 * Set an HTTP Response Header
	 *
	 * @statusCode the status code header
	 * @statusText the status text header
	 * @name       The header name; Mutually exclusive with statusCode
	 * @value      The header value; Mutually exclusive with statusText
	 *
	 * @return RequestContext
	 *
	 * @throws RequestContext.InvalidHTTPHeaderParameters - If no name or statusCode is passed
	 */
	function setHTTPHeader( statusCode, statusText = "", name, value = "" ){
		// status code? We do not add to response headers as this is a separate marker identifier to the response
		if ( !isNull( arguments.statusCode ) ) {
			getPageContext().getResponse().setStatus( javacast( "int", arguments.statusCode ) );
			// set it locally, last one wins
			variables.statusCode = arguments.statusCode;
			variables.statusText = arguments.statusText;
		}
		// Name Exists and not already set.
		else if ( !isNull( arguments.name ) ) {
			var response = getPageContext().getResponse();

			// special exception for Set-Cookie. We always append this header, instead of overwriting
			if ( arguments.name == "Set-Cookie" ) {
				response.addHeader( javacast( "string", arguments.name ), javacast( "string", arguments.value ) );
			} else {
				response.setHeader( javacast( "string", arguments.name ), javacast( "string", arguments.value ) );
			}

			variables.responseHeaders[ arguments.name ] = arguments.value;
		} else {
			throw(
				message = "Invalid header arguments",
				detail  = "Pass in either a [statusCode] or [name] argument",
				type    = "RequestContext.InvalidHTTPHeaderParameters"
			);
		}

		return this;
	}

	/**
	 * Returns the username and password sent via HTTP basic authentication
	 */
	struct function getHTTPBasicCredentials(){
		var results = { "username" : "", "password" : "" };

		// get credentials
		var authHeader = getHTTPHeader( "Authorization", "" );

		// continue if it exists
		if ( len( authHeader ) ) {
			authHeader       = charsetEncode( binaryDecode( listLast( authHeader, " " ), "Base64" ), "utf-8" );
			results.username = getToken( authHeader, 1, ":" );
			results.password = getToken( authHeader, 2, ":" );
		}

		return results;
	}

	/**
	 * Determines if in an Ajax call or not by looking at the request headers
	 */
	boolean function isAjax(){
		return ( getHTTPHeader( "X-Requested-With", "" ) eq "XMLHttpRequest" );
	}

	/***********************************************************************************************************/
	/************************************** PRIVATE METHODS ************************************************/
	/***********************************************************************************************************/

	/**
	 * Render data with formats
	 */
	private function renderWithFormats(){
		var viewToRender = "";

		// inflate list to array if found
		if ( isSimpleValue( arguments.formats ) ) {
			arguments.formats = listToArray( arguments.formats );
		}
		// param incoming rc.format to "html"
		paramValue( "format", "html" );
		// try to match the incoming format with the ones defined, if not defined then throw an exception
		if ( arrayFindNoCase( arguments.formats, variables.context.format ) ) {
			// Cleanup of formats
			arguments.formats = "";
			// Determine view from incoming or implicit
			// viewToRender = ( len( arguments.formatsView ) ? arguments.formatsView : replace( reReplaceNoCase( getCurrentEvent() , "^([^:.]*):", "" ) , ".", "/" ) );
			if ( len( arguments.formatsView ) ) {
				viewToRender = arguments.formatsView;
			} else {
				viewToRender = replace(
					reReplaceNoCase( getCurrentEvent(), "^([^:.]*):", "" ),
					".",
					"/"
				);
			}
			// Rendering switch
			switch ( variables.context.format ) {
				case "json":
				case "jsonp":
				case "jsont":
				case "xml":
				case "text":
				case "wddx": {
					arguments.type = variables.context.format;
					return renderData( argumentCollection = arguments );
				}
				case "pdf": {
					arguments.type = "pdf";
					arguments.data = variables.controller.getRenderer().view( view = viewToRender );
					return renderData( argumentCollection = arguments );
				}
				case "html":
				case "plain": {
					if ( NOT structIsEmpty( arguments.formatsRedirect ) ) {
						variables.controller.relocate( argumentCollection = arguments.formatsRedirect );
						return this;
					}
					return setView( view = viewToRender );
				}
			}
		} else {
			throw(
				message = "The incoming format #variables.context.format# is not a valid registered format",
				detail  = "Valid incoming formats are #arguments.formats.toString()#",
				type    = "RequestContext.InvalidFormat"
			);
		}
	}

	/**
	 * Get's the file mime type for a given file extension, this is mostly used for file delivery.
	 * If not in the most common, we deliver as a binary octet-stream.
	 *
	 * @extension The extension to assume.
	 */
	private function getFileMimeType( required string extension ){
		var fileMimeType = "";
		switch ( lCase( arguments.extension ) ) {
			case "txt,js,css,cfm,cfc,html,htm,jsp,md,wiki":
				fileMimeType = "text/plain";
				break;
			case "gif":
				fileMimeType = "image/gif";
				break;
			case "jpg,jpeg":
				fileMimeType = "image/jpg";
				break;
			case "png":
				fileMimeType = "image/png";
				break;
			case "wav":
				fileMimeType = "audio/wav";
				break;
			case "mp3":
				fileMimeType = "audio/mpeg3";
				break;
			case "pdf":
				fileMimeType = "application/pdf";
				break;
			case "zip,tar,gzip":
				fileMimeType = "application/zip";
				break;
			case "ppt,pptx":
				fileMimeType = "application/vnd.ms-powerpoint";
				break;
			case "doc,docx":
				fileMimeType = "application/msword";
				break;
			case "xls,xlsx":
				fileMimeType = "application/vnd.ms-excel";
				break;
			default:
				fileMimeType = "application/octet-stream";
				break;
		}
		//  More mimeTypes: http://www.iana.org/assignments/media-types/application/
		return fileMimeType;
	}

}