--[[----------------------------------------------------------------------------

WFCapabilities.lua

--------------------------------------------------------------------------------

ADOBE CONFIDENTIAL
------------------
Copyright 2013 Adobe Systems Incorporated
All Rights Reserved.

NOTICE: All information contained herein is, and remains the property of
Adobe Systems Incorporated and its suppliers, if any. The intellectual and
technical concepts contained herein are proprietary to Adobe Systems
Incorporated and its suppliers and are protected by all applicable
intellectual property laws, including trade secret and copyright laws.
Dissemination of this information or reproduction of this material is
strictly forbidden unless prior written permission is obtained from
Adobe Systems Incorporated.

----------------------------------------------------------------------------]]--

local WFArguments = require 'WFArguments'

local WFCapabilitiesImp = require 'WFCapabilitiesImp'

--==============================================================================

local WFCapabilities = {}

-- @mark WFCapabilities namespace

--[[!
	\class WFCapabilities
	\brief 	WFCapabilities provides a way to customize the behavior of WichitaFoundation.
	WFCapabilities on their own provides nothing but a simple runtime key/value store, and a
	mechanism for registering filters to run in response to events.  It is not a persistence
	mechanism (consult KSPrefs for a persistence mechanism that includes notification).
	
	Other classes that are intended to take on custom behavior will consult WFCapabilities
	for parameters a client may have set via setCapability, and alter their behavior
	accordingly.  For example, a client may set the IMS client ID via this mechanism.
	
	Additionally, clients may alter results produced internally if an API provides
	a selector for doing so via the filtering API.  This would allow a client to, for example,
	add an additional index to the index store, or modify an index that WF produces without
	needing to modify WF code.
--]]

--------------------------------------------------------------------------------

--[[!
	\brief Globally set a capability selector to the specified value.  Refer
	to the documentation for the selector to see what effect this may have
	on the behavior of Wichita Foundation.
		
	To avoid race conditions, one should normally set all capabilities early in launch prior
	to creating additional message processors.

	\param selector (string) : The selector.
	\param value (string) : The value.
--]]
function WFCapabilities.setCapability( selector, value )
	WFArguments.check( "+string", "?+string" )
	return WFCapabilitiesImp.setCapability( selector, value )
end

--------------------------------------------------------------------------------

--[[!
	\brief Get the single global value for a  a capability selector.  You should
	document what the selector you are reading is meant to do, as well as what
	are legal values.
	
	\param selector (string) : The selector.
	\return (string) : The value stored for this selector, or nil if none has been set.
--]]
function WFCapabilities.getCapability( selector )
	WFArguments.check( "+string" )
	return WFCapabilitiesImp.getCapability( selector )
end

--------------------------------------------------------------------------------

--[[!
	\brief Add a function to run whenever a value is produced internally for
	a particular filter id.
	
	The clientId is used to allow a client to replace a filter that has been already
	registered.  Only one filter is retained for each combination of selector and clientId.
	
	The filter is provided as a string which is looked up via require.  This is done because
	a filter may run on any message processor.
	
	To avoid race conditions, one should normally register all filters early in launch prior
	to creating additional message processors.
	
	\param selector (string) : The selector.
	\param clientId (string) : A unique client id.
	\param namespaceFunc (string) : A namespace name and function as a single string containing
	a single period.  For example "MyNamespace.myFunction".  Whenever a value needs filtering,
	your function will be called.
--]]
function WFCapabilities.addFilter( selector, clientId, value )
	WFArguments.check( "+string", "+string", "?+string" )
	return WFCapabilitiesImp.addFilter( selector, clientId, value )
end

--------------------------------------------------------------------------------


--[[!
	\brief Invoke all filter functions on a set of values and return the filtered
	result.
	
	If any filter produces an error, the error is thrown.

	The result of each filter is passed as arguments to the last.  The last filter's
	results are returned.
		
	\param selector (string) : The selector.
	\param ... : params to pass to filter
	\return the result of the last filter function.
--]]
function WFCapabilities.callFilters( selector, ... )
	WFArguments.check( "+string" )
	return WFCapabilitiesImp.callFilters( selector, ... )
end

--==============================================================================

return WFCapabilities
