org.osid.mapping.route

Interface RouteLookupSession

All Superinterfaces:

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

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.

• 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.

Method Summary

Methods

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.

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.

canLookupRoutes

boolean canLookupRoutes()

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.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeRouteView

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. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryRouteView

void usePlenaryRouteView()

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.

Compliance:

mandatory - This method is must be implemented.

useFederatedMapView

void useFederatedMapView()

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.

Compliance:

mandatory - This method is must be implemented.

useIsolatedMapView

void useIsolatedMapView()

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

Compliance:

mandatory - This method is must be implemented.

useEffectiveRouteView

void useEffectiveRouteView()

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

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveRouteView

void useAnyEffectiveRouteView()

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

Compliance:

mandatory - This method is must be implemented.

getRoute

Route getRoute(Id routeId)
               throws NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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.

Parameters:

routeId - Id of the Route

Returns:

the route

Throws:

NotFoundException - routeId not found

NullArgumentException - routeId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getRoutesByIds

RouteList getRoutesByIds(IdList routeIds)
                         throws NotFoundException,
                                OperationFailedException,
                                PermissionDeniedException

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.

Parameters:

routeIds - the list of Ids to retrieve

Returns:

the returned Route list

Throws:

NotFoundException - an Id was not found

NullArgumentException - routeIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesByGenusType

RouteList getRoutesByGenusType(Type routeGenusType)
                               throws OperationFailedException,
                                      PermissionDeniedException

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.

Parameters:

routeGenusType - a route genus type

Returns:

the returned Route list

Throws:

NullArgumentException - routeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesByParentGenusType

RouteList getRoutesByParentGenusType(Type routeGenusType)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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.

Parameters:

routeGenusType - a route genus type

Returns:

the returned Route list

Throws:

NullArgumentException - routeGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesByRecordType

RouteList getRoutesByRecordType(Type routeRecordType)
                                throws OperationFailedException,
                                       PermissionDeniedException

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.

Parameters:

routeRecordType - a route record type

Returns:

the returned Route list

Throws:

NullArgumentException - routeRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesOnDate

RouteList getRoutesOnDate(DateTime from,
                        DateTime to)
                          throws OperationFailedException,
                                 PermissionDeniedException

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.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Route list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForStartingLocation

RouteList getRoutesForStartingLocation(Id locationId)
                                       throws OperationFailedException,
                                              PermissionDeniedException

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.

Parameters:

locationId - a location Id

Returns:

the returned Route list

Throws:

NullArgumentException - locationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForStartingLocationOnDate

RouteList getRoutesForStartingLocationOnDate(Id locationId,
                                           DateTime from,
                                           DateTime to)
                                             throws OperationFailedException,
                                                    PermissionDeniedException

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.

Parameters:

locationId - a location Id

from - start of date range

to - end of date range

Returns:

the returned Route list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - locationId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForEndingLocation

RouteList getRoutesForEndingLocation(Id locationId)
                                     throws OperationFailedException,
                                            PermissionDeniedException

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.

Parameters:

locationId - a location Id

Returns:

the returned Route list

Throws:

NullArgumentException - locationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForEndingLocationOnDate

RouteList getRoutesForEndingLocationOnDate(Id locationId,
                                         DateTime from,
                                         DateTime to)
                                           throws OperationFailedException,
                                                  PermissionDeniedException

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.

Parameters:

locationId - a location Id

from - start of date range

to - end of date range

Returns:

the returned Route list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - locationId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForStartingAndEndingLocation

RouteList getRoutesForStartingAndEndingLocation(Id startingLocationId,
                                              Id endingLocationId)
                                                throws OperationFailedException,
                                                       PermissionDeniedException

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.

Parameters:

startingLocationId - a location Id

endingLocationId - a location Id

Returns:

the returned Route list

Throws:

NullArgumentException - startingLocationId or endingLocationId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesForStartingAndEndingLocationOnDate

RouteList getRoutesForStartingAndEndingLocationOnDate(Id startingLocationId,
                                                    Id endingLocationId,
                                                    DateTime from,
                                                    DateTime to)
                                                      throws OperationFailedException,
                                                             PermissionDeniedException

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.

Parameters:

startingLocationId - a location Id

endingLocationId - a location Id

from - start of date range

to - end of date range

Returns:

the returned Route list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - startingLocationId, endingLocationId, from, or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutesAlongLocations

RouteList getRoutesAlongLocations(IdList locationIds)
                                  throws OperationFailedException,
                                         PermissionDeniedException

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.

Parameters:

locationIds - the list of Ids to retrieve

Returns:

the returned Route list

Throws:

NullArgumentException - locationIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRoutes

RouteList getRoutes()
                    throws OperationFailedException,
                           PermissionDeniedException

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.

Returns:

a list of Routes

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.