org.osid.configuration

Interface ValueRetrievalSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

ValueLookupSession

public interface ValueRetrievalSession
extends OsidSession

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 Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupValues() Tests if this user can perform Value lookups.
Configuration	getConfiguration() Gets the Configuration associated with this session.
Id	getConfigurationId() Gets the Configuration Id associated with this session.
Value	getValueByParameter(Id parameterId) Gets a Value for the given parameter Id.
Value	getValueByParameterOnCondition(Id parameterId, ValueCondition valueCondition) Gets a value in this configuration based on a condition.
ValueCondition	getValueCondition(Id parameterId) Gets a value condition for the given parameter.
ValueList	getValuesByParameter(Id parameterId) Gets all the Values for the given parameter Id.
ValueList	getValuesByParameterOnCondition(Id parameterId, ValueCondition valueCondition) Gets all the values for a parameter based on a condition.
ValueList	getValuesByParameters(IdList parameterIds) Gets the Values for the given parameter Ids.
ValueList	getValuesByParametersOnCondition(IdList parameterIds, ValueCondition valueCondition) Gets the values for parameters based on a condition.
void	useComparativeValueView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useConditionalView() Returns only values that pass the defined parameter condition.
void	useFederatedConfigurationView() Federates the view for methods in this session.
void	useIsolatedConfigurationView() Isolates the view for methods in this session.
void	usePlenaryValueView() A complete view of the Value returns is desired.
void	useUnconditionalView() Values that are filtered based on an implicit condition are not filtered out from methods in this session.

Methods inherited from interface org.osid.OsidSession

getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions

Methods inherited from interface org.osid.binding.java.OsidSession

close

Methods inherited from interface java.io.Closeable

close

Method Detail

getConfigurationId

Id getConfigurationId()

Gets the Configuration Id associated with this session.

Returns:

the Configuration Id associated with this session

Compliance:

mandatory - This method must be implemented.

getConfiguration

Configuration getConfiguration()
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets the Configuration associated with this session.

Returns:

the Configuration associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupValues

boolean canLookupValues()

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.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeValueView

void useComparativeValueView()

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.

usePlenaryValueView

void usePlenaryValueView()

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.

useFederatedConfigurationView

void useFederatedConfigurationView()

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.

useIsolatedConfigurationView

void useIsolatedConfigurationView()

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.

useConditionalView

void useConditionalView()

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.

useUnconditionalView

void useUnconditionalView()

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.

getValueByParameter

Value getValueByParameter(Id parameterId)
                          throws NotFoundException,
                                 OperationFailedException,
                                 PermissionDeniedException

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:

parameterId - the Id of the Parameter to retrieve

Returns:

the value

Throws:

NotFoundException - the parameterId not found or no value available

NullArgumentException - the parameterId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getValuesByParameter

ValueList getValuesByParameter(Id parameterId)
                               throws NotFoundException,
                                      OperationFailedException,
                                      PermissionDeniedException

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:

parameterId - the Id of the Parameter to retrieve

Returns:

the value list

Throws:

NotFoundException - the parameterId not found

NullArgumentException - the parameterId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getValuesByParameters

ValueList getValuesByParameters(IdList parameterIds)
                                throws NotFoundException,
                                       OperationFailedException,
                                       PermissionDeniedException

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:

parameterIds - the Id of the Parameter to retrieve

Returns:

the value list

Throws:

NotFoundException - a parameter Id is not found

NullArgumentException - parameterIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getValueCondition

ValueCondition getValueCondition(Id parameterId)

Gets a value condition for the given parameter.

Parameters:

parameterId - the Id of a Parameter

Returns:

a value condition

Throws:

NullArgumentException - parameterId is null

Compliance:

mandatory - This method must be implemented.

getValueByParameterOnCondition

Value getValueByParameterOnCondition(Id parameterId,
                                   ValueCondition valueCondition)
                                     throws NotFoundException,
                                            OperationFailedException,
                                            PermissionDeniedException

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:

parameterId - the Id of a Parameter

valueCondition - the condition

Returns:

the value

Throws:

NotFoundException - parameter Id is not found

NullArgumentException - parameterId or valueCondition is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - valueCondition not of this service

Compliance:

mandatory - This method must be implemented.

getValuesByParameterOnCondition

ValueList getValuesByParameterOnCondition(Id parameterId,
                                        ValueCondition valueCondition)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

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:

parameterId - the Id of a Parameter

valueCondition - the condition

Returns:

the value list

Throws:

NotFoundException - parameter Id is not found

NullArgumentException - parameterId or valueCondition is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - valueCondition is not of this service

Compliance:

mandatory - This method must be implemented.

getValuesByParametersOnCondition

ValueList getValuesByParametersOnCondition(IdList parameterIds,
                                         ValueCondition valueCondition)
                                           throws NotFoundException,
                                                  OperationFailedException,
                                                  PermissionDeniedException

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:

parameterIds - the Id of a Parameter

valueCondition - the condition

Returns:

the value list

Throws:

NotFoundException - a parameter Id is not found

NullArgumentException - parameterIds or valueCondition is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - valueCondition not of this service

Compliance:

mandatory - This method must be implemented.