org.osid.offering

Interface ResultAdminSession

All Superinterfaces:

java.lang.AutoCloseable, java.io.Closeable, OsidSession

All Known Subinterfaces:

ResultBatchAdminSession

public interface ResultAdminSession
extends OsidSession

This session creates, updates, and deletes Results. 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 an Result, an ResultForm is requested using getResultFormForCreate() specifying the desired relationship peers and record Types or none if no record Types are needed. The returned ResultForm 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 ResultForm is submiited to a create operation, it cannot be reused with another create operation unless the first operation was unsuccessful. Each ResultForm corresponds to an attempted transaction.

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

The delete operations delete Results. To unmap an Result from the current Catalogue, the ResultCatalogueAssignmentSession should be used. These delete operations attempt to remove the Result itself thus removing it from all known Catalogue 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	aliasResult(Id resultId, Id aliasId) Adds an Id to an Result for the purpose of creating compatibility.
boolean	canCreateResults() Tests if this user can create results.
boolean	canCreateResultWithRecordTypes(Type[] resultRecordTypes) Tests if this user can create a single Result using the desired record types.
boolean	canDeleteResults() Tests if this user can delete results.
boolean	canManageResultAliases() Tests if this user can manage Id aliases for Results.
boolean	canUpdateResults() Tests if this user can update results.
Result	createResult(ResultForm resultForm) Creates a new Result.
void	deleteResult(Id resultId) Deletes an Result.
Catalogue	getCatalogue() Gets the Catalogue associated with this session.
Id	getCatalogueId() Gets the Catalogue Id associated with this session.
ResultForm	getResultFormForCreate(Id canonicalUnitId, Id particpantId, Type[] resultRecordTypes) Gets the result form for creating new results.
ResultForm	getResultFormForUpdate(Id resultId) Gets the result form for updating an existing result.
void	updateResult(ResultForm resultForm) Updates an existing result.

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

getCatalogueId

Id getCatalogueId()

Gets the Catalogue Id associated with this session.

Returns:

the Catalogue Id associated with this session

Compliance:

mandatory - This method must be implemented.

getCatalogue

Catalogue getCatalogue()
                       throws OperationFailedException,
                              PermissionDeniedException

Gets the Catalogue associated with this session.

Returns:

the catalogue

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateResults

boolean canCreateResults()

Tests if this user can create results. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Result will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer create operations to unauthorized users.

Returns:

false if Result creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateResultWithRecordTypes

boolean canCreateResultWithRecordTypes(Type[] resultRecordTypes)

Tests if this user can create a single Result using the desired record types. While OfferingManager.getResultRecordTypes() can be used to examine which records are supported, this method tests which record(s) are required for creating a specific Result. Providing an empty array tests if an Result can be created with no records.

Parameters:

resultRecordTypes - array of result record types

Returns:

true if Result creation using the specified record Types is supported, false otherwise

Throws:

NullArgumentException - resultRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getResultFormForCreate

ResultForm getResultFormForCreate(Id canonicalUnitId,
                                Id particpantId,
                                Type[] resultRecordTypes)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

Gets the result form for creating new results. A new form should be requested for each create transaction.

Parameters:

canonicalUnitId - the canonical unit Id

particpantId - the particpant Id

resultRecordTypes - array of result record types to be included in the create operation or an empty list if none

Returns:

the result form

Throws:

NotFoundException - canonicalUnitId or particpantId is not found

NullArgumentException - canonicalUnitId, particpantId, or resultRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - cannot get form for requested record types

Compliance:

mandatory - This method must be implemented.

createResult

Result createResult(ResultForm resultForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Result.

Parameters:

resultForm - the form for this Result

Returns:

the new Result

Throws:

IllegalStateException - resultForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - resultForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - resultForm did not originate from getResultFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateResults

boolean canUpdateResults()

Tests if this user can update results. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Result will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer update operations to unauthorized users.

Returns:

false if Result modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getResultFormForUpdate

ResultForm getResultFormForUpdate(Id resultId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

resultId - the Id of the Result

Returns:

the result form

Throws:

NotFoundException - resultId is not found

NullArgumentException - resultId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateResult

void updateResult(ResultForm resultForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing result.

Parameters:

resultForm - the form containing the elements to be updated

Throws:

IllegalStateException - resultForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - resultForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - resultForm did not originate from getResultFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteResults

boolean canDeleteResults()

Tests if this user can delete results. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Result will result in a PERMISSION_DENIED. This is intended as a hint to an application that may not wish to offer delete operations to unauthorized users.

Returns:

false if Result deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteResult

void deleteResult(Id resultId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes an Result.

Parameters:

resultId - the Id of the Result to remove

Throws:

NotFoundException - resultId not found

NullArgumentException - resultId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageResultAliases

boolean canManageResultAliases()

Tests if this user can manage Id aliases for Results. 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 Result aliasing is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

aliasResult

void aliasResult(Id resultId,
               Id aliasId)
                 throws AlreadyExistsException,
                        NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Adds an Id to an Result for the purpose of creating compatibility. The primary Id of the Result is determined by the provider. The new Id is an alias to the primary Id. If the alias is a pointer to another result, it is reassigned to the given result Id.

Parameters:

resultId - the Id of an Result

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - resultId not found

NullArgumentException - resultId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.