Interface RouteAdminSession

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

This session creates, updates, and deletes Routes . The data for create and update is provided by the consumer via the form object. OsidForms are requested for each create or update and may not be reused.

Create and update operations differ in their usage. To create a Route , a RouteForm is requested using getRouteFormForCreate() specifying the desired record Types or none if no record Types are needed. The returned RouteForm will indicate that it is to be used with a create operation and can be used to examine metdata or validate data prior to creation. Once the RouteForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each RouteForm corresponds to an attempted transaction.

For updates, RouteForms are requested to the Route Id that is to be updated using getRouteFormForUpdate() . Similarly, the RouteForm has metadata about the data that can be updated and it can perform validation before submitting the update. The RouteForm can only be used once for a successful update and cannot be reused.

The delete operations delete Routes . To unmap a Route from the current Map , the RouteMapAssignmentSession should be used. These delete operations attempt to remove the Route itself thus removing it from all known Map catalogs.

This session includes an Id aliasing mechanism to assign an external Id to an internally assigned Id.

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

    • canCreateRoutes

      boolean canCreateRoutes()
      Tests if this user can create Routes . A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Route will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer create operations to an unauthorized user.
      Returns:
      false if Route creation is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • canCreateRouteWithRecordTypes

      boolean canCreateRouteWithRecordTypes(Type[] routeRecordTypes)
      Tests if this user can create a single Route using the desired record types. While MappingRouteManager.getRouteRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Route . Providing an empty array tests if a Route can be created with no records.
      Parameters:
      routeRecordTypes - array of route record types
      Returns:
      true if Route creation using the specified record Types is supported, false otherwise
      Throws:
      NullArgumentException - routeRecordTypes is null
      Compliance:
      mandatory - This method must be implemented.

    • getRouteFormForCreate

      RouteForm getRouteFormForCreate(Id startingLocationId, Id endingLocationId, Type[] routeRecordTypes) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the route form for creating new routes. A new form should be requested for each create transaction.
      Parameters:
      startingLocationId - the Id of the starting location.
      endingLocationId - the Id of the ending location.
      routeRecordTypes - array of route record types
      Returns:
      the route form
      Throws:
      NotFoundException - startingLocationId or endingLocationId is not found
      NullArgumentException - startingLocationId, endingLocationId or routeRecordTypes is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - unable top get form with given record types
      Compliance:
      mandatory - This method must be implemented.

    • createRoute

      Route createRoute(RouteForm routeForm) throws OperationFailedException, PermissionDeniedException
      Creates a new Route .
      Parameters:
      routeForm - the form for this Route
      Returns:
      the new Route
      Throws:
      IllegalStateException - routeForm already used in a create transaction
      InvalidArgumentException - one or more of the form elements is invalid
      NullArgumentException - routeForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - routeForm did not originate from getRouteFormForCreate()
      Compliance:
      mandatory - This method must be implemented.

    • canUpdateRoutes

      boolean canUpdateRoutes()
      Tests if this user can update Routes . A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Route will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer update operations to an unauthorized user.
      Returns:
      false if Route modification is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • getRouteFormForUpdate

      RouteForm getRouteFormForUpdate(Id routeId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the route form for updating an existing route. A new route form should be requested for each update transaction.
      Parameters:
      routeId - the Id of the Route
      Returns:
      the route form
      Throws:
      NotFoundException - routeId is not found
      NullArgumentException - routeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • updateRoute

      void updateRoute(RouteForm routeForm) throws OperationFailedException, PermissionDeniedException
      Updates an existing route.
      Parameters:
      routeForm - the form containing the elements to be updated
      Throws:
      IllegalStateException - routeForm already used in an update transaction
      InvalidArgumentException - the form contains an invalid value
      NullArgumentException - routeForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - routeForm did not originate from getRouteFormForUpdate()
      Compliance:
      mandatory - This method must be implemented.

    • canDeleteRoutes

      boolean canDeleteRoutes()
      Tests if this user can delete Routes . A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Route will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer delete operations to an unauthorized user.
      Returns:
      false if Route deletion is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • deleteRoute

      void deleteRoute(Id routeId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Deletes a Route .
      Parameters:
      routeId - the Id of the Route to remove
      Throws:
      NotFoundException - routeId not found
      NullArgumentException - routeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canManageRouteAliases

      boolean canManageRouteAliases()
      Tests if this user can manage Id aliases for Routes . A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
      Returns:
      false if Route aliasing is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • aliasRoute

      void aliasRoute(Id routeId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
      Adds an Id to a Route for the purpose of creating compatibility. The primary Id of the Route is determined by the provider. The new Id performs as an alias to the primary Id .The new Id performs as an alias to the primary Id . If the alias is a pointer to another route, it is reassigned to the given route Id .
      Parameters:
      routeId - the Id of a Route
      aliasId - the alias Id
      Throws:
      AlreadyExistsException - aliasId is already assigned
      NotFoundException - routeId not found
      NullArgumentException - routeId or aliasId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canCreateRouteSegmentWithRecordTypes

      boolean canCreateRouteSegmentWithRecordTypes(Type[] routeSegmentRecordTypes)
      Tests if this user can create a single RouteSegment using the desired record types. While MappingRouteManager.getRouteSegmentRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Route . Providing an empty array tests if a Route can be created with no records.
      Parameters:
      routeSegmentRecordTypes - array of route segment record types
      Returns:
      true if RouteSegment creation using the specified record Types is supported, false otherwise
      Throws:
      NullArgumentException - routeSegmentRecordTypes is null
      Compliance:
      mandatory - This method must be implemented.

    • getRouteSegmentFormForCreate

      RouteSegmentForm getRouteSegmentFormForCreate(Id routeId, Type[] routeSegmentRecordTypes) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the route segment form for adding route segments. A new form should be requested for each create transaction.
      Parameters:
      routeId - the Id of a Route
      routeSegmentRecordTypes - array of route segment record types
      Returns:
      the route segment form
      Throws:
      NotFoundException - routeId is not found
      NullArgumentException - routeId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - unable to get form with given record types
      Compliance:
      mandatory - This method must be implemented.

    • createRouteSegment

      RouteSegment createRouteSegment(RouteSegmentForm routeSegmentForm) throws OperationFailedException, PermissionDeniedException
      Creates a new RouteSegment .
      Parameters:
      routeSegmentForm - the form for this RouteSegment
      Returns:
      the new RouteSegment
      Throws:
      IllegalStateException - routeSegmentForm already used in a create transaction
      InvalidArgumentException - one or more of the form elements is invalid
      NullArgumentException - routeForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - routeForm did not originate from getRouteSegmentFormForCreate()
      Compliance:
      mandatory - This method must be implemented.

    • getRouteSegmentFormForUpdate

      RouteSegmentForm getRouteSegmentFormForUpdate(Id routeSegmentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Gets the route segment form for adding route segments. A new form should be requested for each create transaction.
      Parameters:
      routeSegmentId - the Id of the RouteSegment
      Returns:
      the route segment form
      Throws:
      NotFoundException - routeSegmentId is not found
      NullArgumentException - routeSegmentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • updateRouteSegment

      void updateRouteSegment(RouteSegmentForm routeSegmentForm) throws OperationFailedException, PermissionDeniedException
      Updates a RouteSegment .
      Parameters:
      routeSegmentForm - the form for this RouteSegment
      Throws:
      IllegalStateException - routeSegmentForm already used in an update transaction
      InvalidArgumentException - one or more of the form elements is invalid
      NullArgumentException - routeForm is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      UnsupportedException - routeForm did not originate from getRouteSegmentFormForUpdate()
      Compliance:
      mandatory - This method must be implemented.

    • deleteRouteSegment

      void deleteRouteSegment(Id routeSegmentId) throws NotFoundException, OperationFailedException, PermissionDeniedException
      Deletes a RouteSegment .
      Parameters:
      routeSegmentId - the Id of the route segment to delete
      Throws:
      NotFoundException - routeSegmentId is not found
      NullArgumentException - routeSegmentId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.

    • canManageRouteSegmentAliases

      boolean canManageRouteSegmentAliases()
      Tests if this user can manage Id aliases for RouteSegments . A return of true does not guarantee successful authorization. A return of false indicates that it is known changing an alias will result in a PERMISSION_DENIED . This is intended as a hint to an application that may opt not to offer alias operations to an unauthorized user.
      Returns:
      false if RouteSegment aliasing is not authorized, true otherwise
      Compliance:
      mandatory - This method must be implemented.

    • aliasRouteSegment

      void aliasRouteSegment(Id routeSegmentId, Id aliasId) throws AlreadyExistsException, NotFoundException, OperationFailedException, PermissionDeniedException
      Adds an Id to a RouteSegment for the purpose of creating compatibility. The primary Id of the RouteSegment is determined by the provider. The new Id performs as an alias to the primary Id . If the alias is a pointer to another route segment, it is reassigned to the given route segment Id .
      Parameters:
      routeSegmentId - the Id of a RouteSegment
      aliasId - the alias Id
      Throws:
      AlreadyExistsException - aliasId is already assigned
      NotFoundException - routeSegmentId not found
      NullArgumentException - routeSegmentId or aliasId is null
      OperationFailedException - unable to complete request
      PermissionDeniedException - authorization failure
      Compliance:
      mandatory - This method must be implemented.