OSID Logo
OSID Specifications
mapping route package
Version 3.0.0
Release Candidate Preview
Interfaceosid.mapping.route.RouteLookupSession
Implementsosid.OsidSession
Description

This session provides methods for retrieving premade Routes. The Route represents a set of paths .

This session defines views that offer differing behaviors when retrieving multiple objects.

  • comparative view: elements may be silently omitted or re-ordered
  • plenary view: provides a complete set or is an error condition
  • isolated map view: All route methods in this session operate, retrieve and pertain to routes defined explicitly in the current map. Using an isolated view is useful for managing Routes with the RouteAdminSession.
  • federated map view: All route methods in this session operate, retrieve and pertain to all routes defined in this map and any other routes implicitly available in this map through map inheritence.
  • effective route view: All route lookup methods return routes where the current date falls in between the effective dates inclusive.
  • any effective route view: Routes of any effective date are returned from methods.

Generally, the comparative view should be used for most applications as it permits operation even if there is data that cannot be accessed. The methods useFederatedMapView() and useIsolatedMapView() behave as a radio group and one should be selected before invoking the methods in this session.

MethodgetMapId
Description

Gets the Map Id associated with this session.

Returnosid.id.Idthe Map Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetMap
Description

Gets the Map associated with this session.

Returnosid.mapping.Mapthe map
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanLookupRoutes
Description

Tests if this user can perform Route 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.

Returnboolean false if lookup methods are not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoduseComparativeRouteView
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.

CompliancemandatoryThis method is must be implemented.
MethodusePlenaryRouteView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseFederatedMapView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseIsolatedMapView
Description

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

CompliancemandatoryThis method is must be implemented.
MethoduseEffectiveRouteView
Description

Only routes whose effective dates are current are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethoduseAnyEffectiveRouteView
Description

All routes of any effective dates are returned by methods in this session.

CompliancemandatoryThis method is must be implemented.
MethodgetRoute
Description

Gets the Route specified by its Id.

In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Route may have a different Id than requested, such as the case where a duplicate Id was assigned to a Route and retained for compatibility.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdrouteId Id of the Route
Returnosid.mapping.route.Routethe route
ErrorsNOT_FOUND routeId not found
NULL_ARGUMENT routeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method is must be implemented.
MethodgetRoutesByIds
Description

Gets a RouteList corresponding to the given IdList.

In plenary mode, the returned list contains all of the routes 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 Routes may be omitted from the list and may present the elements in any order including returning a unique set.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdListrouteIdsthe list of Ids to retrieve
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNOT_FOUNDan Id was not found
NULL_ARGUMENT routeIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesByGenusType
Description

Gets a RouteList corresponding to the given route genus Type which does not include routes of genus types derived from the specified Type.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.type.TyperouteGenusTypea route genus type
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT routeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesByParentGenusType
Description

Gets a RouteList corresponding to the given route genus Type and include any additional routes with genus types derived from the specified Type.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.type.TyperouteGenusTypea route genus type
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT routeGenusType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesByRecordType
Description

Gets a RouteList containing the given route record Type.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.type.TyperouteRecordTypea route record type
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT routeRecordType is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesOnDate
Description

Gets a RouteList effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT from or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForStartingLocation
Description

Gets a RouteList for the given starting Location.

In plenary mode, the returned list contains all of the routes, or an error results if a route connected to the location is not found or inaccessible. Otherwise, inaccessible Routes may be omitted from the list.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdlocationIda location Id
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT locationId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForStartingLocationOnDate
Description

Gets a RouteList for the given starting location effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdlocationIda location Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT locationId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForEndingLocation
Description

Gets a RouteList for the given ending Location.

In plenary mode, the returned list contains all of the routes, or an error results if a route connected to the location is not found or inaccessible. Otherwise, inaccessible Routes may be omitted from the list.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdlocationIda location Id
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT locationId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForEndingLocationOnDate
Description

Gets a RouteList for the given ending location effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdlocationIda location Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT locationId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForStartingAndEndingLocation
Description

Gets a RouteList for the given starting and ending Locations.

In plenary mode, the returned list contains all of the routes, or an error results if a route connected to the location is not found or inaccessible. Otherwise, inaccessible Routes may be omitted from the list.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdstartingLocationIda location Id
osid.id.IdendingLocationIda location Id
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT startingLocationId or endingLocationId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesForStartingAndEndingLocationOnDate
Description

Gets a RouteList for the given starting and ending location effective during the entire given date range inclusive but not confined to the date range.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdstartingLocationIda location Id
osid.id.IdendingLocationIda location Id
osid.calendaring.DateTimefromstart of date range
osid.calendaring.DateTimetoend of date range
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsINVALID_ARGUMENT from is greater than to
NULL_ARGUMENT startingLocationId, endingLocationId, from, or to is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutesAlongLocations
Description

Gets a RouteList connected to all the given Locations.

In plenary mode, the returned list contains all of the routes along the locations, or an error results if a route connected to the location is not found or inaccessible. Otherwise, inaccessible Routes may be omitted from the list.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Parametersosid.id.IdListlocationIdsthe list of Ids to retrieve
Returnosid.mapping.route.RouteListthe returned Route list
ErrorsNULL_ARGUMENT locationIds is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodgetRoutes
Description

Gets all Routes.

In plenary mode, the returned list contains all known routes or an error results. Otherwise, the returned list may contain only those routes that are accessible through this session.

In effective mode, routes are returned that are currently effective. In any effective mode, effective routes and those currently expired are returned.

Returnosid.mapping.route.RouteLista list of Routes
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.