org.osid.mapping

Interface ResourceLocationSession

All Superinterfaces:

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

public interface ResourceLocationSession
extends OsidSession

This session defines methods to look up resources on a map.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canAccessResourceLocations() Tests if this user can access the locations of resources.
Map	getMap() Gets the Map associated with this session.
Id	getMapId() Gets the Map Id associated with this session.
ResourceLocation	getResourceLocation(Id resourceId) Gets the current closest bounding location of the given resource.
ResourceLocationList	getResourceLocations(IdList resourceIds) Gets the current closest bounding locations of the given resources.
ResourceLocationList	getResourcesAtLocation(Id locationId) Gets the current resources at or within the given location.
ResourceLocationList	getResourcesAtLocationByGenusType(Id locationId, Type resourceGenusType) Gets the current resources at or within the given location for a resource genus type.
ResourceLocationList	getResourcesAtSpatialUnit(SpatialUnit spatialUnit) Gets the current resource within the given spatial unit.
ResourceLocationList	getResourcesAtSpatialUnitByGenusType(SpatialUnit spatialUnit, Type resourceGenusType) Gets the current resource within the given spatial unit for a given resource genus type.
void	useComparativeResourceLocationView() 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	useFederatedMapView() Federates the view for methods in this session.
void	useIsolatedMapView() Isolates the view for methods in this session.
void	usePlenaryResourceLocationView() A complete view of the Location returns is desired.

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

getMapId

Id getMapId()

Gets the Map Id associated with this session.

Returns:

the Map Id associated with this session

Compliance:

mandatory - This method must be implemented.

getMap

Map getMap()
           throws OperationFailedException,
                  PermissionDeniedException

Gets the Map associated with this session.

Returns:

the map

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canAccessResourceLocations

boolean canAccessResourceLocations()

Tests if this user can access the locations of resources. 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 not offer location operations to unauthorized users.

Returns:

false if location methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeResourceLocationView

void useComparativeResourceLocationView()

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.

usePlenaryResourceLocationView

void usePlenaryResourceLocationView()

A complete view of the Location 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.

useFederatedMapView

void useFederatedMapView()

Federates the view for methods in this session. A federated view will include paths in maps which are children of this map in the map hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedMapView

void useIsolatedMapView()

Isolates the view for methods in this session. An isolated view restricts retrievals to this map only.

Compliance:

mandatory - This method is must be implemented.

getResourceLocation

ResourceLocation getResourceLocation(Id resourceId)
                                     throws NotFoundException,
                                            OperationFailedException,
                                            PermissionDeniedException

Gets the current closest bounding location of the given resource. The returned ResourceLocation may not indicate a known location if no location is known.

Parameters:

resourceId - a resource Id

Returns:

the current location

Throws:

NotFoundException - resourceId is not on map

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourceLocations

ResourceLocationList getResourceLocations(IdList resourceIds)
                                          throws NotFoundException,
                                                 OperationFailedException,
                                                 PermissionDeniedException

Gets the current closest bounding locations of the given resources. In plenary mode, the returned list contains all of the locations of the supplied resources or an error results. In comparative mode, inaccessible resources may be omitted or duplicates suppressed or reordered.

Parameters:

resourceIds - a resource list

Returns:

the current locations

Throws:

NotFoundException - a resource Id is not on map

NullArgumentException - resourceIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourcesAtLocation

ResourceLocationList getResourcesAtLocation(Id locationId)
                                            throws NotFoundException,
                                                   OperationFailedException,
                                                   PermissionDeniedException

Gets the current resources at or within the given location.

Parameters:

locationId - a location Id

Returns:

the resources at the location

Throws:

NotFoundException - locationId not found

NullArgumentException - locationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourcesAtLocationByGenusType

ResourceLocationList getResourcesAtLocationByGenusType(Id locationId,
                                                     Type resourceGenusType)
                                                       throws NotFoundException,
                                                              OperationFailedException,
                                                              PermissionDeniedException

Gets the current resources at or within the given location for a resource genus type.

Parameters:

locationId - a location Id

resourceGenusType - a resource genus type

Returns:

the resources at the location

Throws:

NotFoundException - locationId not found

NullArgumentException - locationId or resourceGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourcesAtSpatialUnit

ResourceLocationList getResourcesAtSpatialUnit(SpatialUnit spatialUnit)
                                               throws OperationFailedException,
                                                      PermissionDeniedException

Gets the current resource within the given spatial unit.

Parameters:

spatialUnit - a spatial unit

Returns:

the resources at the location

Throws:

NullArgumentException - spatialUnit is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getResourcesAtSpatialUnitByGenusType

ResourceLocationList getResourcesAtSpatialUnitByGenusType(SpatialUnit spatialUnit,
                                                        Type resourceGenusType)
                                                          throws OperationFailedException,
                                                                 PermissionDeniedException

Gets the current resource within the given spatial unit for a given resource genus type.

Parameters:

spatialUnit - a spatial unit

resourceGenusType - a resource genus type

Returns:

the resources at the location

Throws:

NullArgumentException - spatialUnit or resourceGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.