Interface RouteLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

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