public interface RouteLookupSession extends OsidSession
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.
Routes
with the RouteAdminSession.
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.
Modifier and Type | Method and Description |
---|---|
boolean |
canLookupRoutes()
Tests if this user can perform
Route lookups. |
Map |
getMap()
Gets the
Map associated with this session. |
Id |
getMapId()
Gets the
Map Id associated with this
session. |
Route |
getRoute(Id routeId)
Gets the
Route specified by its Id. |
RouteList |
getRoutes()
Gets all
Routes. |
RouteList |
getRoutesAlongLocations(IdList locationIds)
Gets a
RouteList connected to all the given
Locations. |
RouteList |
getRoutesByGenusType(Type routeGenusType)
Gets a
RouteList corresponding to the given route genus
Type which does not include routes of genus types
derived from the specified Type. |
RouteList |
getRoutesByIds(IdList routeIds)
Gets a
RouteList corresponding to the given
IdList. |
RouteList |
getRoutesByParentGenusType(Type routeGenusType)
Gets a
RouteList corresponding to the given route genus
Type and include any additional routes with genus types
derived from the specified Type. |
RouteList |
getRoutesByRecordType(Type routeRecordType)
Gets a
RouteList containing the given route record
Type. |
RouteList |
getRoutesForEndingLocation(Id locationId)
Gets a
RouteList for the given ending Location. |
RouteList |
getRoutesForEndingLocationOnDate(Id locationId,
DateTime from,
DateTime to)
Gets a
RouteList for the given ending location
effective during the entire given date range inclusive but not
confined to the date range. |
RouteList |
getRoutesForStartingAndEndingLocation(Id startingLocationId,
Id endingLocationId)
Gets a
RouteList for the given starting and ending
Locations. |
RouteList |
getRoutesForStartingAndEndingLocationOnDate(Id startingLocationId,
Id endingLocationId,
DateTime from,
DateTime to)
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. |
RouteList |
getRoutesForStartingLocation(Id locationId)
Gets a
RouteList for the given starting
Location. |
RouteList |
getRoutesForStartingLocationOnDate(Id locationId,
DateTime from,
DateTime to)
Gets a
RouteList for the given starting location
effective during the entire given date range inclusive but not
confined to the date range. |
RouteList |
getRoutesOnDate(DateTime from,
DateTime to)
Gets a
RouteList effective during the entire given date
range inclusive but not confined to the date range. |
void |
useAnyEffectiveRouteView()
All routes of any effective dates are returned by methods in this
session.
|
void |
useComparativeRouteView()
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 |
useEffectiveRouteView()
Only routes whose effective dates are current are returned by methods
in this session.
|
void |
useFederatedMapView()
Federates the view for methods in this session.
|
void |
useIsolatedMapView()
Isolates the view for methods in this session.
|
void |
usePlenaryRouteView()
A complete view of the
Route returns is desired. |
getAuthenticatedAgent, getAuthenticatedAgentId, getClockRate, getDate, getEffectiveAgent, getEffectiveAgentId, getFormatType, getLocale, isAuthenticated, startTransaction, supportsTransactions
close
Id getMapId()
Map
Id
associated with this
session. Map Id
associated with this sessionmandatory
- This method must be implemented. Map getMap() throws OperationFailedException, PermissionDeniedException
Map
associated with this session.OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. boolean canLookupRoutes()
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. false
if lookup methods are not authorized,
true
otherwisemandatory
- This method must be implemented. void useComparativeRouteView()
mandatory
- This method is must be implemented. void usePlenaryRouteView()
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.mandatory
- This method is must be implemented. void useFederatedMapView()
mandatory
- This method is must be implemented. void useIsolatedMapView()
mandatory
- This method is must be implemented. void useEffectiveRouteView()
mandatory
- This method is must be implemented. void useAnyEffectiveRouteView()
mandatory
- This method is must be implemented. Route getRoute(Id routeId) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.routeId
- Id
of the Route
NotFoundException
- routeId
not foundNullArgumentException
- routeId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method is must be implemented. RouteList getRoutesByIds(IdList routeIds) throws NotFoundException, OperationFailedException, PermissionDeniedException
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.routeIds
- the list of Ids
to retrieve Route
listNotFoundException
- an Id was
not foundNullArgumentException
- routeIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesByGenusType(Type routeGenusType) throws OperationFailedException, PermissionDeniedException
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.routeGenusType
- a route genus type Route
listNullArgumentException
- routeGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesByParentGenusType(Type routeGenusType) throws OperationFailedException, PermissionDeniedException
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.routeGenusType
- a route genus type Route
listNullArgumentException
- routeGenusType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesByRecordType(Type routeRecordType) throws OperationFailedException, PermissionDeniedException
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.routeRecordType
- a route record type Route
listNullArgumentException
- routeRecordType
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesOnDate(DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.from
- start of date rangeto
- end of date range Route
listInvalidArgumentException
- from
is
greater than to
NullArgumentException
- from or to
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForStartingLocation(Id locationId) throws OperationFailedException, PermissionDeniedException
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.locationId
- a location Id
Route
listNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForStartingLocationOnDate(Id locationId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.locationId
- a location Id
from
- start of date rangeto
- end of date range Route
listInvalidArgumentException
- from
is
greater than to
NullArgumentException
- locationId, from, or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForEndingLocation(Id locationId) throws OperationFailedException, PermissionDeniedException
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.locationId
- a location Id
Route
listNullArgumentException
- locationId
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForEndingLocationOnDate(Id locationId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.locationId
- a location Id
from
- start of date rangeto
- end of date range Route
listInvalidArgumentException
- from
is
greater than to
NullArgumentException
- locationId, from, or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForStartingAndEndingLocation(Id startingLocationId, Id endingLocationId) throws OperationFailedException, PermissionDeniedException
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.startingLocationId
- a location Id
endingLocationId
- a location Id
Route
listNullArgumentException
- startingLocationId
or endingLocationId
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesForStartingAndEndingLocationOnDate(Id startingLocationId, Id endingLocationId, DateTime from, DateTime to) throws OperationFailedException, PermissionDeniedException
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.startingLocationId
- a location Id
endingLocationId
- a location Id
from
- start of date rangeto
- end of date range Route
listInvalidArgumentException
- from
is
greater than to
NullArgumentException
- startingLocationId,
endingLocationId, from, or to
is null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutesAlongLocations(IdList locationIds) throws OperationFailedException, PermissionDeniedException
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.locationIds
- the list of Ids
to retrieve Route
listNullArgumentException
- locationIds
is
null
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented. RouteList getRoutes() throws OperationFailedException, PermissionDeniedException
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. Routes
OperationFailedException
- unable to complete requestPermissionDeniedException
- authorization failuremandatory
- This method must be implemented.