Interface PathTravelSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, OsidSession
public interface PathTravelSession extends OsidSession

This session provides methods for examining Path travel.

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 path methods in this session operate, retrieve and pertain to paths defined explicitly in the current map.
  • federated map view: All path methods in this session operate, retrieve and pertain to all paths defined in this map and any other paths implicitly available in this map through map inheritence.

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 any lookup methods.

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

    • canLookupPathTravel

      boolean canLookupPathTravel()
      Tests if this user can perform Path 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.

    • useComparativePathView

      void useComparativePathView()
      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.

    • usePlenaryPathView

      void usePlenaryPathView()
      A complete view of the Path 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 paths 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.

    • getObstacles

      ObstacleList getObstacles(Id pathId, Coordinate coordinate, Distance distance) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets an ObstacleList corresponding to the given Path and coordinate range. In plenary mode, the returned list contains all of the obstacles as defined. Otherwise, inaccessible Obstacles may be omitted from the list or overlapping obstacles may be reordered.
      Parameters:
      pathId - Id of the Path
      coordinate - starting coordinate
      distance - a distance from coordinate
      Returns:
      the obstacle list
      Throws:
      InvalidArgumentException - coordinate not on path
      NotFoundException - pathId not found
      NullArgumentException - pathId, coordinate or distance is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getAverageSpeed

      Speed getAverageSpeed(Id pathId, Coordinate coordinate, Distance distance) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the expected average speed for a traveler along a path between the given coordinates. If the path is blocked by an obstacle, then the speed is zero. Some obstacles may have the effect of lowering the expected speed.
      Parameters:
      pathId - Id of the Path
      coordinate - starting coordinate
      distance - a distance from coordinate
      Returns:
      the speed
      Throws:
      InvalidArgumentException - coordinate not on path
      NotFoundException - pathId not found
      NullArgumentException - pathId, coordinate or distance is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getSpeedZones

      SpeedZoneList getSpeedZones(Id pathId, Coordinate coordinate, Distance distance) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a SpeedZoneList corresponding to the given Path and coordinate range. In plenary mode, the returned list contains all of the speed zones as defined. Otherwise, inaccessible SpeedZones may be omitted from the list or overlapping speed zones may be reordered.
      Parameters:
      pathId - Id of the Path
      coordinate - starting coordinate
      distance - a distance from coordinate
      Returns:
      the list of speed zones
      Throws:
      InvalidArgumentException - coordinate not on path
      NotFoundException - pathId not found
      NullArgumentException - pathId, coordinate or distance is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.

    • getSpeedZonesAtResolution

      SpeedZoneList getSpeedZonesAtResolution(Id pathId, Coordinate coordinate, Distance distance, Distance resolution) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets a SpeedZoneList corresponding to the given Path and coordinate range for a given resolution.
      Parameters:
      pathId - Id of the Path
      coordinate - starting coordinate
      distance - a distance from coordinate
      resolution - the resolution
      Returns:
      the list of speed zones
      Throws:
      InvalidArgumentException - coordinate not on path
      NotFoundException - pathId not found
      NullArgumentException - pathId, coordinate, distance or resolution is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method is must be implemented.