public interface MapLookupSession extends OsidSession
This session provides methods for retrieving Map
objects. The Map
represents a collection of locations.
This session defines views that 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 that cannot be accessed. For
example, a browsing application may only need to examine the Maps
it can access, without breaking execution. However, an assessment
may only be useful if all Maps
referenced by it are
available, and a test-taking application may sacrifice some
interoperability for the sake of precision.
Modifier and Type | Method and Description |
---|---|
boolean |
canLookupMaps()
Tests if this user can perform
Map lookups. |
Map |
getMap(Id mapId)
Gets the
Map specified by its Id. |
MapList |
getMaps()
Gets all
Maps. |
MapList |
getMapsByGenusType(Type mapGenusType)
Gets a
MapList corresponding to the given map genus
Type which does not include maps of types derived from
the specified Type. |
MapList |
getMapsByIds(IdList mapIds)
Gets a
MapList corresponding to the given
IdList. |
MapList |
getMapsByParentGenusType(Type mapGenusType)
Gets a
MapList corresponding to the given map genus
Type and include any additional maps with genus types
derived from the specified Type. |
MapList |
getMapsByProvider(Id resourceId)
Gets a
MapList for the given provider. |
MapList |
getMapsByRecordType(Type mapRecordType)
Gets a
MapList containing the given map record
Type. |
void |
useComparativeMapView()
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 |
usePlenaryMapView()
A complete view of the
Map returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
boolean canLookupMaps()
Map
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. false
if lookup methods are not authorized,
true
otherwisemandatory
- This method must be implemented. void useComparativeMapView()
mandatory
- This method is must be implemented. void usePlenaryMapView()
Map
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. Map getMap(Id mapId) throws NotFoundException, OperationFailedException, PermissionDeniedException
Map
specified by its Id.
In
plenary mode, the exact Id
is found or a
NOT_FOUND
results. Otherwise, the returned Map
may have a different Id
than requested, such as the
case where a duplicate Id
was assigned to a Map
and retained for compatibility.mapId
- Id
of the Map
NotFoundException
- mapId
not foundNullArgumentException
- mapId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. MapList getMapsByIds(IdList mapIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
MapList
corresponding to the given
IdList.
In plenary mode, the returned list contains all of the
maps 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 Maps
may be omitted from the list and may
present the elements in any order including returning a unique set.mapIds
- the list of Ids
to retrieve Map
listNotFoundException
- an Id was
not foundNullArgumentException
- mapIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MapList getMapsByGenusType(Type mapGenusType) throws OperationFailedException, PermissionDeniedException
MapList
corresponding to the given map genus
Type
which does not include maps of types derived from
the specified Type.
In plenary mode, the returned list
contains all known maps or an error results. Otherwise, the returned
list may contain only those maps that are accessible through this
session.mapGenusType
- a map genus type Map
listNullArgumentException
- mapGenusType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MapList getMapsByParentGenusType(Type mapGenusType) throws OperationFailedException, PermissionDeniedException
MapList
corresponding to the given map genus
Type
and include any additional maps with genus types
derived from the specified Type.
In plenary mode, the
returned list contains all known maps or an error results. Otherwise,
the returned list may contain only those maps that are accessible
through this session.mapGenusType
- a map genus type Map
listNullArgumentException
- mapGenusType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MapList getMapsByRecordType(Type mapRecordType) throws OperationFailedException, PermissionDeniedException
MapList
containing the given map record
Type.
In plenary mode, the returned list contains all known
maps or an error results. Otherwise, the returned list may contain
only those maps that are accessible through this session.mapRecordType
- a map record type Map
listNullArgumentException
- mapRecordType
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MapList getMapsByProvider(Id resourceId) throws OperationFailedException, PermissionDeniedException
MapList
for the given provider.
In plenary mode, the returned list contains all known maps or an error
results. Otherwise, the returned list may contain only those maps that
are accessible through this session.resourceId
- a resource Id
Map
listNullArgumentException
- resourceId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. MapList getMaps() throws OperationFailedException, PermissionDeniedException
Maps.
In plenary mode, the returned list
contains all known maps or an error results. Otherwise, the returned
list may contain only those maps that are accessible through this
session. Maps
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.