org.osid.mapping.route

Interface RouteAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, 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 Summary

Methods

Modifier and Type	Method and Description
void	aliasRoute(Id routeId, Id aliasId) Adds an Id to a Route for the purpose of creating compatibility.
void	aliasRouteSegment(Id routeSegmentId, Id aliasId) Adds an Id to a RouteSegment for the purpose of creating compatibility.
boolean	canCreateRoutes() Tests if this user can create Routes.
boolean	canCreateRouteSegmentWithRecordTypes(Type[] routeSegmentRecordTypes) Tests if this user can create a single RouteSegment using the desired record types.
boolean	canCreateRouteWithRecordTypes(Type[] routeRecordTypes) Tests if this user can create a single Route using the desired record types.
boolean	canDeleteRoutes() Tests if this user can delete Routes.
boolean	canManageRouteAliases() Tests if this user can manage Id aliases for Routes.
boolean	canManageRouteSegmentAliases() Tests if this user can manage Id aliases for RouteSegments.
boolean	canUpdateRoutes() Tests if this user can update Routes.
Route	createRoute(RouteForm routeForm) Creates a new Route.
RouteSegment	createRouteSegment(RouteSegmentForm routeSegmentForm) Creates a new RouteSegment.
void	deleteRoute(Id routeId) Deletes a Route.
void	deleteRouteSegment(Id routeSegmentId) Deletes a RouteSegment.
Map	getMap() Gets the Map associated with this session.
Id	getMapId() Gets the Map Id associated with this session.
RouteForm	getRouteFormForCreate(Id startingLocationId, Id endingLocationId, Type[] routeRecordTypes) Gets the route form for creating new routes.
RouteForm	getRouteFormForUpdate(Id routeId) Gets the route form for updating an existing route.
RouteSegmentForm	getRouteSegmentFormForCreate(Id routeId, Type[] routeSegmentRecordTypes) Gets the route segment form for adding route segments.
RouteSegmentForm	getRouteSegmentFormForUpdate(Id routeSegmentId) Gets the route segment form for adding route segments.
void	updateRoute(RouteForm routeForm) Updates an existing route.
void	updateRouteSegment(RouteSegmentForm routeSegmentForm) Updates a RouteSegment.

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.

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.