public interface KeyLookupSession extends OsidSession
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.
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.
Modifier and Type | Method and Description |
---|---|
boolean |
canLookupKeys()
Tests if this user can lookup
Keys. |
Agency |
getAgency()
Gets the
Agency associated with this session. |
Id |
getAgencyId()
Gets the
Agency Id associated with this
session. |
Key |
getKey(Id keyId)
Gets the agent key.
|
Key |
getKeyForAgent(Id agentId)
Gets the agent key.
|
KeyList |
getKeys()
Gets all
Keys. |
KeyList |
getKeysByGenusType(Type keyGenusType)
Gets a
KeyList corresponding to the given key genus
Type which does not include keys of genus types derived
from the specified Type. |
KeyList |
getKeysByIds(IdList keyIds)
Gets a
KeyList corresponding to the given agent
IdList. |
KeyList |
getKeysByParentGenusType(Type keyGenusType)
Gets a
KeyList corresponding to the given key genus
Type and include any additional keys with genus types
derived from the specified Type. |
KeyList |
getKeysByRecordType(Type keyRecordType)
Gets a list of keys corresponding to the given key record
Type. |
void |
useComparativeKeyView()
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 |
useFederatedAgencyView()
Federates the view for methods in this session.
|
void |
useIsolatedAgencyView()
Isolates the view for methods in this session.
|
void |
usePlenaryKeyView()
A complete view of the
Key returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getAgencyId()
Agency
Id
associated with this
session. Agency Id
associated with this sessionmandatory
- This method must be implemented. Agency getAgency() throws OperationFailedException, PermissionDeniedException
Agency
associated with this session. Agency
associated with this sessionOperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canLookupKeys()
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. false
if key management is not authorized,
true
otherwisemandatory
- This method must be implemented. void useComparativeKeyView()
mandatory
- This method is must be implemented. void usePlenaryKeyView()
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.mandatory
- This method is must be implemented. void useFederatedAgencyView()
mandatory
- This method is must be implemented. void useIsolatedAgencyView()
mandatory
- This method is must be implemented. Key getKey(Id keyId) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.keyId
- the Id
of the Key
NotFoundException
- keyId
is not found
or no key existsNullArgumentException
- keyId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. KeyList getKeysByIds(IdList keyIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.keyIds
- the list of Ids
to retrieve Key
listNotFoundException
- an Id was
not foundNullArgumentException
- keyIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. KeyList getKeysByGenusType(Type keyGenusType) throws OperationFailedException, PermissionDeniedException
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.keyGenusType
- a key genus type Key
listNullArgumentException
- keyGenusType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failure
occurredmandatory
- This method must be implemented. KeyList getKeysByParentGenusType(Type keyGenusType) throws OperationFailedException, PermissionDeniedException
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.keyGenusType
- a key genus type Key
listNullArgumentException
- keyGenusType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failure
occurredmandatory
- This method must be implemented. KeyList getKeysByRecordType(Type keyRecordType) throws OperationFailedException, PermissionDeniedException
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.keyRecordType
- a key record type Key
listNullArgumentException
- keyRecordType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. Key getKeyForAgent(Id agentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
agentId
- the Id
of the Agent
NotFoundException
- agentId
is not found
or no key existsNullArgumentException
- agentId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. KeyList getKeys() throws OperationFailedException, PermissionDeniedException
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. Keys
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.