OSID - osid.configuration.ValueRetrievalSession Service Interface Definition

Interface	osid.configuration.ValueRetrievalSession
Implements	`osid.OsidSession`
Description	This session is used to retrieve active configuration values. Two views of the configuration data are defined: federated: parameters defined in configurations that are a parent of this configuration in the configuration hierarchy are included isolated: parameters are contained to within this configuration conditional: values are filtered that do not pass any defined conditions, whether or not they are explciity passed into the lookup methods of this session unconditional: values are filtered only for the conditions that are explicity passed as parameters. Any conditions defined for the value that do not require explicit data for retrieval are ignored. This session assumes an active view. Values are not OSID objects and are obtained using a reference to a Parameter.
Method	getConfigurationId
Description	Gets the `Configuration` `Id` associated with this session.
Return	`osid.id.Id`		the `Configuration` `Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getConfiguration
Description	Gets the `Configuration` associated with this session.
Return	`osid.configuration.Configuration`		the `Configuration` associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupValues
Description	Tests if this user can perform `Value` lookups. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a `PERMISSION_DENIED.` This is intended as a hint to an application that may opt not to offer lookup operations to unauthorized users.
Return	`boolean`		`false` if lookup methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeValueView
Description	The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.
Compliance	`mandatory`		This method is must be implemented.
Method	usePlenaryValueView
Description	A complete view of the `Value` returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.
Compliance	`mandatory`		This method is must be implemented.
Method	useFederatedConfigurationView
Description	Federates the view for methods in this session. A federated view will include values from parent configurations in the configuration hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedConfigurationView
Description	Isolates the view for methods in this session. An isolated view restricts lookups to this configuration only.
Compliance	`mandatory`		This method is must be implemented.
Method	useConditionalView
Description	Returns only values that pass the defined parameter condition. Some parameter conditions do not require explicit conditional data to be passed and the `Values` returned from any method in this session are filtered on an implicit condition.
Compliance	`mandatory`		This method is must be implemented.
Method	useUnconditionalView
Description	Values that are filtered based on an implicit condition are not filtered out from methods in this session. Methods that take an explicit condition as a parameter are filtered on only those conditions that are specified.
Compliance	`mandatory`		This method is must be implemented.
Method	getValueByParameter
Description	Gets a `Value` for the given parameter `Id.` If more than one value exists for the given parameter, the most preferred value is returned. This method can be used as a convenience when only one value is expected. `getValuesByParameters()` should be used for getting all the active values.
Parameters	`osid.id.Id`	`parameterId`	the `Id` of the `Parameter` to retrieve
Return	`osid.configuration.Value`		the value
Errors	NOT_FOUND		the `parameterId` not found or no value available
	NULL_ARGUMENT		the `parameterId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getValuesByParameter
Description	Gets all the `Values` for the given parameter `Id.` In plenary mode, all values are returned in the order requested or an error results. In comparative mode, inaccessible values may be omitted or the values reordered. In conditional mode, the values are filtered through evaluation. In unconditional mode, the values are returned unfiltered.
Parameters	`osid.id.Id`	`parameterId`	the `Id` of the `Parameter` to retrieve
Return	`osid.configuration.ValueList`		the value list
Errors	NOT_FOUND		the `parameterId` not found
	NULL_ARGUMENT		the `parameterId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getValuesByParameters
Description	Gets the `Values` for the given parameter `Ids.` In plenary mode, the values for all parameters are returned in the order requested or an error results. In comparative mode, inaccessible values may be omitted or the values reordered. In conditional mode, the values are filtered through evaluation. In unconditional mode, the values are returned unfiltered.
Parameters	`osid.id.IdList`	`parameterIds`	the `Id` of the `Parameter` to retrieve
Return	`osid.configuration.ValueList`		the value list
Errors	NOT_FOUND		a parameter `Id` is not found
	NULL_ARGUMENT		`parameterIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getValueCondition
Description	Gets a value condition for the given parameter.
Parameters	`osid.id.Id`	`parameterId`	the `Id` of a `Parameter`
Return	`osid.configuration.ValueCondition`		a value condition
Errors	NULL_ARGUMENT		`parameterId` is `null`
Compliance	`mandatory`		This method must be implemented.
Method	getValueByParameterOnCondition
Description	Gets a value in this configuration based on a condition. If multiple values are available the most preferred one is returned. The condition specified is applied to any or all parameters in this configuration as applicable.
Parameters	`osid.id.Id`	`parameterId`	the `Id` of a `Parameter`
Parameters	`osid.configuration.ValueCondition`	`valueCondition`	the condition
Return	`osid.configuration.Value`		the value
Errors	NOT_FOUND		parameter `Id` is not found
	NULL_ARGUMENT		`parameterId` or `valueCondition` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`valueCondition` not of this service
Compliance	`mandatory`		This method must be implemented.
Method	getValuesByParameterOnCondition
Description	Gets all the values for a parameter based on a condition. In plenary mode, all values are returned or an error results. In comparative mode, inaccessible values may be omitted.
Parameters	`osid.id.Id`	`parameterId`	the `Id` of a `Parameter`
Parameters	`osid.configuration.ValueCondition`	`valueCondition`	the condition
Return	`osid.configuration.ValueList`		the value list
Errors	NOT_FOUND		parameter `Id` is not found
	NULL_ARGUMENT		`parameterId` or `valueCondition` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`valueCondition` is not of this service
Compliance	`mandatory`		This method must be implemented.
Method	getValuesByParametersOnCondition
Description	Gets the values for parameters based on a condition. The specified condition is applied to any or all of the parameters as applicable. In plenary mode, all values are returned or an error results. In comparative mode, inaccessible values may be omitted.
Parameters	`osid.id.IdList`	`parameterIds`	the `Id` of a `Parameter`
Parameters	`osid.configuration.ValueCondition`	`valueCondition`	the condition
Return	`osid.configuration.ValueList`		the value list
Errors	NOT_FOUND		a parameter `Id` is not found
	NULL_ARGUMENT		`parameterIds` or `valueCondition` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
	UNSUPPORTED		`valueCondition` not of this service
Compliance	`mandatory`		This method must be implemented.