OSID Logo
OSID Specifications
mapping route package
Version 3.0.0
Release Candidate Preview
Interfaceosid.mapping.route.RouteAdminSession
Implementsosid.OsidSession
Description

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.

MethodgetMapId
Description

Gets the Map Id associated with this session.

Returnosid.id.Idthe Map Id associated with this session
CompliancemandatoryThis method must be implemented.
MethodgetMap
Description

Gets the Map associated with this session.

Returnosid.mapping.Mapthe map
ErrorsOPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanCreateRoutes
Description

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.

Returnboolean false if Route creation is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodcanCreateRouteWithRecordTypes
Description

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.

Parametersosid.type.Type[]routeRecordTypesarray of route record types
Returnboolean true if Route creation using the specified record Types is supported, false otherwise
ErrorsNULL_ARGUMENT routeRecordTypes is null
CompliancemandatoryThis method must be implemented.
MethodgetRouteFormForCreate
Description

Gets the route form for creating new routes. A new form should be requested for each create transaction.

Parametersosid.id.IdstartingLocationIdthe Id of the starting location.
osid.id.IdendingLocationIdthe Id of the ending location.
osid.type.Type[]routeRecordTypesarray of route record types
Returnosid.mapping.route.RouteFormthe route form
ErrorsNOT_FOUND startingLocationId or endingLocationId is not found
NULL_ARGUMENT startingLocationId, endingLocationId or routeRecordTypes is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTEDunable top get form with given record types
CompliancemandatoryThis method must be implemented.
MethodcreateRoute
Description

Creates a new Route.

Parametersosid.mapping.route.RouteFormrouteFormthe form for this Route
Returnosid.mapping.route.Routethe new Route
ErrorsILLEGAL_STATE routeForm already used in a create transaction
INVALID_ARGUMENTone or more of the form elements is invalid
NULL_ARGUMENT routeForm is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED routeForm did not originate from getRouteFormForCreate()
CompliancemandatoryThis method must be implemented.
MethodcanUpdateRoutes
Description

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.

Returnboolean false if Route modification is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodgetRouteFormForUpdate
Description

Gets the route form for updating an existing route. A new route form should be requested for each update transaction.

Parametersosid.id.IdrouteIdthe Id of the Route
Returnosid.mapping.route.RouteFormthe route form
ErrorsNOT_FOUND routeId is not found
NULL_ARGUMENT routeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodupdateRoute
Description

Updates an existing route.

Parametersosid.mapping.route.RouteFormrouteFormthe form containing the elements to be updated
ErrorsILLEGAL_STATE routeForm already used in an update transaction
INVALID_ARGUMENTthe form contains an invalid value
NULL_ARGUMENT routeForm is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED routeForm did not originate from getRouteFormForUpdate()
CompliancemandatoryThis method must be implemented.
MethodcanDeleteRoutes
Description

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.

Returnboolean false if Route deletion is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethoddeleteRoute
Description

Deletes a Route.

Parametersosid.id.IdrouteIdthe Id of the Route to remove
ErrorsNOT_FOUND routeId not found
NULL_ARGUMENT routeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanManageRouteAliases
Description

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.

Returnboolean false if Route aliasing is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodaliasRoute
Description

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.

Parametersosid.id.IdrouteIdthe Id of a Route
osid.id.IdaliasIdthe alias Id
ErrorsALREADY_EXISTS aliasId is already assigned
NOT_FOUND routeId not found
NULL_ARGUMENT routeId or aliasId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanCreateRouteSegmentWithRecordTypes
Description

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.

Parametersosid.type.Type[]routeSegmentRecordTypesarray of route segment record types
Returnboolean true if RouteSegment creation using the specified record Types is supported, false otherwise
ErrorsNULL_ARGUMENT routeSegmentRecordTypes is null
CompliancemandatoryThis method must be implemented.
MethodgetRouteSegmentFormForCreate
Description

Gets the route segment form for adding route segments. A new form should be requested for each create transaction.

Parametersosid.id.IdrouteIdthe Id of a Route
osid.type.Type[]routeSegmentRecordTypesarray of route segment record types
Returnosid.mapping.route.RouteSegmentFormthe route segment form
ErrorsNOT_FOUND routeId is not found
NULL_ARGUMENT routeId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTEDunable to get form with given record types
CompliancemandatoryThis method must be implemented.
MethodcreateRouteSegment
Description

Creates a new RouteSegment.

Parametersosid.mapping.route.RouteSegmentFormrouteSegmentFormthe form for this RouteSegment
Returnosid.mapping.route.RouteSegmentthe new RouteSegment
ErrorsILLEGAL_STATE routeSegmentForm already used in a create transaction
INVALID_ARGUMENTone or more of the form elements is invalid
NULL_ARGUMENT routeForm is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED routeForm did not originate from getRouteSegmentFormForCreate()
CompliancemandatoryThis method must be implemented.
MethodgetRouteSegmentFormForUpdate
Description

Gets the route segment form for adding route segments. A new form should be requested for each create transaction.

Parametersosid.id.IdrouteSegmentIdthe Id of the RouteSegment
Returnosid.mapping.route.RouteSegmentFormthe route segment form
ErrorsNOT_FOUND routeSegmentId is not found
NULL_ARGUMENT routeSegmentId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodupdateRouteSegment
Description

Updates a RouteSegment.

Parametersosid.mapping.route.RouteSegmentFormrouteSegmentFormthe form for this RouteSegment
ErrorsILLEGAL_STATE routeSegmentForm already used in an update transaction
INVALID_ARGUMENTone or more of the form elements is invalid
NULL_ARGUMENT routeForm is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
UNSUPPORTED routeForm did not originate from getRouteSegmentFormForUpdate()
CompliancemandatoryThis method must be implemented.
MethoddeleteRouteSegment
Description

Deletes a RouteSegment.

Parametersosid.id.IdrouteSegmentIdthe Id of the route segment to delete
ErrorsNOT_FOUND routeSegmentId is not found
NULL_ARGUMENT routeSegmentId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.
MethodcanManageRouteSegmentAliases
Description

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.

Returnboolean false if RouteSegment aliasing is not authorized, true otherwise
CompliancemandatoryThis method must be implemented.
MethodaliasRouteSegment
Description

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.

Parametersosid.id.IdrouteSegmentIdthe Id of a RouteSegment
osid.id.IdaliasIdthe alias Id
ErrorsALREADY_EXISTS aliasId is already assigned
NOT_FOUND routeSegmentId not found
NULL_ARGUMENT routeSegmentId or aliasId is null
OPERATION_FAILEDunable to complete request
PERMISSION_DENIEDauthorization failure
CompliancemandatoryThis method must be implemented.