OSID - osid.authentication.keys.KeyLookupSession Service Interface Definition

Interface	osid.authentication.keys.KeyLookupSession
Implements	`osid.OsidSession`
Description	This session provides methods for retrieving `Key` objects. The `Key` is associated with an `Agent` and identified by the `Agent` Id. This session defines two sets of views which offer differing behaviors when retrieving multiple objects. comparative view: elements may be silently omitted or re-ordered plenary view: provides a complete and ordered result set or is an error condition isolated agency view: All key methods in this session operate, retrieve and pertain to keys defined explicitly in the current agency. Using an isolated view is useful for managing keys with the KeyAdminSession. federated agency view: All key methods in this session operate, retrieve and pertain to all keys defined in this agency and any other agents implicitly available in this agency through agency inheritence. Generally, the comparative view should be used for most applications as it permits operation even if there is data out of sync. For example, a hierarchy output can be plugged into a lookup method to retrieve all objects known to a hierarchy, but it may not be necessary to break execution if a node from the hierarchy no longer exists. However, some administrative applications may need to know whether it had retrieved an entire set of objects and may sacrifice some interoperability for the sake of precision. Keys may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the `Key.`
Method	getAgencyId
Description	Gets the `Agency` `Id` associated with this session.
Return	`osid.id.Id`		the `Agency Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getAgency
Description	Gets the `Agency` associated with this session.
Return	`osid.authentication.Agency`		the `Agency` associated with this session
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupKeys
Description	Tests if this user can lookup `Keys.` A return of true does not guarantee successful authorization. A return of false indicates that it is known getting a `Key` will result in a `PERMISSION_DENIED.` This is intended as a hint to an application that may opt to offer key management functions to unauthorized users.
Return	`boolean`		`false` if key management is not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeKeyView
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	usePlenaryKeyView
Description	A complete view of the `Key` 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	useFederatedAgencyView
Description	Federates the view for methods in this session. A federated view will include keys in agencies which are children of this agency in the agency hierarchy.
Compliance	`mandatory`		This method is must be implemented.
Method	useIsolatedAgencyView
Description	Isolates the view for methods in this session. An isolated view restricts lookups to this agency only.
Compliance	`mandatory`		This method is must be implemented.
Method	getKey
Description	Gets the agent key. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned `Agent` via the `Key` may have a different Id than requested, such as the case where a duplicate `Id` was assigned to an Agent and retained for compatibility.
Parameters	`osid.id.Id`	`keyId`	the `Id` of the `Key`
Return	`osid.authentication.keys.Key`		the key
Errors	NOT_FOUND		`keyId` is not found or no key exists
	NULL_ARGUMENT		`keyId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getKeysByIds
Description	Gets a `KeyList` corresponding to the given agent `IdList.` In plenary mode, the returned list contains all of the keys for agents specified in the `Id` list, in the order of the list, including duplicates, or an error results if an `Id` in the supplied list is not found or inaccessible. Otherwise, inaccessible `Keys` may be omitted from the list and may present the elements in any order including returning a unique set.
Parameters	`osid.id.IdList`	`keyIds`	the list of `Ids` to retrieve
Return	`osid.authentication.keys.KeyList`		the returned `Key` list
Errors	NOT_FOUND		an `Id was` not found
	NULL_ARGUMENT		`keyIds` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getKeysByGenusType
Description	Gets a `KeyList` corresponding to the given key genus `Type` which does not include keys of genus types derived from the specified `Type.` In plenary mode, the returned list contains all known keys or an error results. Otherwise, the returned list may contain only those keys that are accessible through this session.
Parameters	`osid.type.Type`	`keyGenusType`	a key genus type
Return	`osid.authentication.keys.KeyList`		the returned `Key` list
Errors	NULL_ARGUMENT		`keyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure occurred
Compliance	`mandatory`		This method must be implemented.
Method	getKeysByParentGenusType
Description	Gets a `KeyList` corresponding to the given key genus `Type` and include any additional keys with genus types derived from the specified `Type.` In plenary mode, the returned list contains all known keys or an error results. Otherwise, the returned list may contain only those keys that are accessible through this session.
Parameters	`osid.type.Type`	`keyGenusType`	a key genus type
Return	`osid.authentication.keys.KeyList`		the returned `Key` list
Errors	NULL_ARGUMENT		`keyGenusType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure occurred
Compliance	`mandatory`		This method must be implemented.
Method	getKeysByRecordType
Description	Gets a list of keys corresponding to the given key record `Type.` The set of keys implementing the given record type is returned. In plenary mode, the returned list contains all known keys or an error results. Otherwise, the returned list may contain only those keys that are accessible through this session.
Parameters	`osid.type.Type`	`keyRecordType`	a key record type
Return	`osid.authentication.keys.KeyList`		the returned `Key` list
Errors	NULL_ARGUMENT		`keyRecordType` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getKeyForAgent
Description	Gets the agent key.
Parameters	`osid.id.Id`	`agentId`	the `Id` of the `Agent`
Return	`osid.authentication.keys.Key`		the key
Errors	NOT_FOUND		`agentId` is not found or no key exists
	NULL_ARGUMENT		`agentId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	getKeys
Description	Gets all `Keys.` In plenary mode, the returned list contains all known keys or an error results. Otherwise, the returned list may contain only those keys that are accessible through this session.
Return	`osid.authentication.keys.KeyList`		a list of `Keys`
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.