OSID - osid.mapping.LocationAdjacencySession Service Interface Definition

Interface	osid.mapping.LocationAdjacencySession
Implements	`osid.OsidSession`
Description	This session defines methods to traverse through a map.
Method	getMapId
Description	Gets the `Map` `Id` associated with this session.
Return	`osid.id.Id`		the `Map Id` associated with this session
Compliance	`mandatory`		This method must be implemented.
Method	getMap
Description	Gets the `Map` associated with this session.
Return	`osid.mapping.Map`		the map
Errors	OPERATION_FAILED		unable to complete request
Errors	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	canLookupLocationAdjacencies
Description	Tests if this user can query adjacenies of locations 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 lookup operations to unauthorized users.
Return	`boolean`		`false` if location adjacency methods are not authorized, `true` otherwise
Compliance	`mandatory`		This method must be implemented.
Method	useComparativeLocationView
Description	The returns from the traversal 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	usePlenaryLocationView
Description	A complete view of the method 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	useFederatedMapView
Description	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.
Method	useIsolatedMapView
Description	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.
Method	getAdjacentLocations
Description	Gets a list of adjacent locations for the given location. The adjacent locations reflect the locations at the same level of the location hierarchy.
Parameters	`osid.id.Id`	`locationId`	the given location `Id`
Parameters	`cardinal`	`hops`	the number of hops to include. 0 returns an empty list. 1 returns the immediate adjacent locations.
Return	`osid.mapping.LocationList`		a list of locations
Errors	NOT_FOUND		`locationId` is not found
	NULL_ARGUMENT		`locationId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.
Method	isAdjacent
Description	Tests if two locations of the same type are adjacent. A location is not adjacent if contained within another location.
Parameters	`osid.id.Id`	`locationId`	the given location `Id`
Parameters	`osid.id.Id`	`anotherLocationId`	the given location `Id`
Return	`boolean`		`true` of the locations are adjacent, `false` otherwise
Errors	NOT_FOUND		`locationId` or `anotherLocationId` is not found
	NULL_ARGUMENT		`locationId` or `anotherLocationId` is `null`
	OPERATION_FAILED		unable to complete request
	PERMISSION_DENIED		authorization failure
Compliance	`mandatory`		This method must be implemented.