org.osid.assessment

Interface ItemAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

ItemBatchAdminSession

public interface ItemAdminSession
extends OsidSession

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

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

The delete operations delete ItemForm. To unmap an ItemForm from the current Bank, the ItemBankAssignmentSession should be used. These delete operations attempt to remove the Item itself thus removing it from all known Bank 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	aliasItem(Id itemId, Id aliasId) Adds an Id to an Item for the purpose of creating compatibility.
boolean	canCreateAnswers() Tests if this user can create Answers.
boolean	canCreateAnswersWithRecordTypes(Type[] answerRecordTypes) Tests if this user can create a single Answer using the desired record types.
boolean	canCreateItems() Tests if this user can create Items.
boolean	canCreateItemWithRecordTypes(Type[] itemRecordTypes) Tests if this user can create a single Item using the desired record types.
boolean	canCreateQuestions() Tests if this user can create Questions.
boolean	canCreateQuestionWithRecordTypes(Type[] questionRecordTypes) Tests if this user can create a single Question using the desired record types.
boolean	canDeleteAnswers() Tests if this user can delete Answers.
boolean	canDeleteItems() Tests if this user can delete Items.
boolean	canDeleteQuestions() Tests if this user can delete Questions.
boolean	canManageItemAliases() Tests if this user can manage Id aliases for Items.
boolean	canUpdateAnswers() Tests if this user can update Answers.
boolean	canUpdateItems() Tests if this user can update Items.
boolean	canUpdateQuestions() Tests if this user can update Questions.
Answer	createAnswer(AnswerForm answerForm) Creates a new Answer.
Item	createItem(ItemForm itemForm) Creates a new Item.
Question	createQuestion(QuestionForm questionForm) Creates a new Question.
void	deleteAnswer(Id answerId) Deletes the Answer identified by the given Id.
void	deleteItem(Id itemId) Deletes the Item identified by the given Id.
void	deleteQuestion(Id questionId) Deletes the Question identified by the given Id.
AnswerForm	getAnswerFormForCreate(Id itemId, Type[] answerRecordTypes) Gets the answer form for creating new answers.
AnswerForm	getAnswerFormForUpdate(Id answerId) Gets the answer form for updating an existing answer.
Bank	getBank() Gets the Bank associated with this session.
Id	getBankId() Gets the Bank Id associated with this session.
ItemForm	getItemFormForCreate(Type[] itemRecordTypes) Gets the assessment item form for creating new assessment items.
ItemForm	getItemFormForUpdate(Id itemId) Gets the assessment item form for updating an existing item.
QuestionForm	getQuestionFormForCreate(Id itemId, Type[] questionRecordTypes) Gets the question form for creating new questions.
QuestionForm	getQuestionFormForUpdate(Id questionId) Gets the question form for updating an existing question.
void	updateAnswer(AnswerForm answerForm) Updates an existing answer.
void	updateItem(ItemForm itemForm) Updates an existing item.
void	updateQuestion(QuestionForm questionForm) Updates an existing question.

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

getBankId

Id getBankId()

Gets the Bank Id associated with this session.

Returns:

the Bank Id associated with this session

Compliance:

mandatory - This method must be implemented.

getBank

Bank getBank()
             throws OperationFailedException,
                    PermissionDeniedException

Gets the Bank associated with this session.

Returns:

the Bank associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateItems

boolean canCreateItems()

Tests if this user can create Items. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating an Item 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 Item creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateItemWithRecordTypes

boolean canCreateItemWithRecordTypes(Type[] itemRecordTypes)

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

Parameters:

itemRecordTypes - array of item record types

Returns:

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

Throws:

NullArgumentException - itemRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getItemFormForCreate

ItemForm getItemFormForCreate(Type[] itemRecordTypes)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets the assessment item form for creating new assessment items. A new form should be requested for each create transaction.

Parameters:

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

Returns:

the assessment item form

Throws:

NullArgumentException - itemRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createItem

Item createItem(ItemForm itemForm)
                throws OperationFailedException,
                       PermissionDeniedException

Creates a new Item.

Parameters:

itemForm - the form for this Item

Returns:

the new Item

Throws:

IllegalStateException - itemForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - itemForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - itemForm did not originate from getItemFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateItems

boolean canUpdateItems()

Tests if this user can update Items. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Item 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 assessment item modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getItemFormForUpdate

ItemForm getItemFormForUpdate(Id itemId)
                              throws NotFoundException,
                                     OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

itemId - the Id of the Item

Returns:

the assessment item form

Throws:

NotFoundException - itemId is not found

NullArgumentException - itemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

updateItem

void updateItem(ItemForm itemForm)
                throws OperationFailedException,
                       PermissionDeniedException

Updates an existing item.

Parameters:

itemForm - the form containing the elements to be updated

Throws:

IllegalStateException - itemForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - itemForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - itemForm did not originate from getItemFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteItems

boolean canDeleteItems()

Tests if this user can delete Items. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Item 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 Item deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteItem

void deleteItem(Id itemId)
                throws NotFoundException,
                       OperationFailedException,
                       PermissionDeniedException

Deletes the Item identified by the given Id.

Parameters:

itemId - the Id of the Item to delete

Throws:

NotFoundException - an Item was not found identified by the given Id

NullArgumentException - itemId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

canManageItemAliases

boolean canManageItemAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasItem

void aliasItem(Id itemId,
             Id aliasId)
               throws AlreadyExistsException,
                      NotFoundException,
                      OperationFailedException,
                      PermissionDeniedException

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

Parameters:

itemId - the Id of an Item

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is in use as a primary Id

NotFoundException - itemId not found

NullArgumentException - itemId or aliasId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

canCreateQuestions

boolean canCreateQuestions()

Tests if this user can create Questions. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Question 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 Question creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateQuestionWithRecordTypes

boolean canCreateQuestionWithRecordTypes(Type[] questionRecordTypes)

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

Parameters:

questionRecordTypes - array of question record types

Returns:

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

Throws:

NullArgumentException - questionRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getQuestionFormForCreate

QuestionForm getQuestionFormForCreate(Id itemId,
                                    Type[] questionRecordTypes)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets the question form for creating new questions. A new form should be requested for each create transaction.

Parameters:

itemId - an assessment item Id

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

Returns:

the question form

Throws:

NullArgumentException - questionRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createQuestion

Question createQuestion(QuestionForm questionForm)
                        throws AlreadyExistsException,
                               OperationFailedException,
                               PermissionDeniedException

Creates a new Question.

Parameters:

questionForm - the form for this Question

Returns:

the new Question

Throws:

AlreadyExistsException - a question already exists for this item

IllegalStateException - questionForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - questionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - questionForm did not originate from getQuestionFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateQuestions

boolean canUpdateQuestions()

Tests if this user can update Questions. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating a Question 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 question modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getQuestionFormForUpdate

QuestionForm getQuestionFormForUpdate(Id questionId)
                                      throws NotFoundException,
                                             OperationFailedException,
                                             PermissionDeniedException

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

Parameters:

questionId - the Id of the Question

Returns:

the question form

Throws:

NotFoundException - questionId is not found

NullArgumentException - questionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

updateQuestion

void updateQuestion(QuestionForm questionForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Updates an existing question.

Parameters:

questionForm - the form containing the elements to be updated

Throws:

IllegalStateException - questionForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - questionForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - questionForm did not originate from getQuestionFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteQuestions

boolean canDeleteQuestions()

Tests if this user can delete Questions. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting a Question 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 Question deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteQuestion

void deleteQuestion(Id questionId)
                    throws NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Deletes the Question identified by the given Id.

Parameters:

questionId - the Id of the Question to delete

Throws:

NotFoundException - a Question was not found identified by the given Id

NullArgumentException - questionId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

canCreateAnswers

boolean canCreateAnswers()

Tests if this user can create Answers. A return of true does not guarantee successful authorization. A return of false indicates that it is known creating a Answer 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 Answer creation is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

canCreateAnswersWithRecordTypes

boolean canCreateAnswersWithRecordTypes(Type[] answerRecordTypes)

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

Parameters:

answerRecordTypes - array of answer record types

Returns:

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

Throws:

NullArgumentException - answernRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getAnswerFormForCreate

AnswerForm getAnswerFormForCreate(Id itemId,
                                Type[] answerRecordTypes)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets the answer form for creating new answers. A new form should be requested for each create transaction.

Parameters:

itemId - an assessment item Id

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

Returns:

the answer form

Throws:

NullArgumentException - answerRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - unable to get form for requested record types

Compliance:

mandatory - This method must be implemented.

createAnswer

Answer createAnswer(AnswerForm answerForm)
                    throws OperationFailedException,
                           PermissionDeniedException

Creates a new Answer.

Parameters:

answerForm - the form for this Answer

Returns:

the new Answer

Throws:

IllegalStateException - answerForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - answerForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - answerForm did not originate from getAnswerFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateAnswers

boolean canUpdateAnswers()

Tests if this user can update Answers. A return of true does not guarantee successful authorization. A return of false indicates that it is known updating an Answer 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 answer modification is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

getAnswerFormForUpdate

AnswerForm getAnswerFormForUpdate(Id answerId)
                                  throws NotFoundException,
                                         OperationFailedException,
                                         PermissionDeniedException

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

Parameters:

answerId - the Id of the Answer

Returns:

the answer form

Throws:

NotFoundException - answerId is not found

NullArgumentException - answerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.

updateAnswer

void updateAnswer(AnswerForm answerForm)
                  throws OperationFailedException,
                         PermissionDeniedException

Updates an existing answer.

Parameters:

answerForm - the form containing the elements to be updated

Throws:

IllegalStateException - answerForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - answerForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

UnsupportedException - answerForm did not originate from getAnswerFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteAnswers

boolean canDeleteAnswers()

Tests if this user can delete Answers. A return of true does not guarantee successful authorization. A return of false indicates that it is known deleting an Answer 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 Answer deletion is not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

deleteAnswer

void deleteAnswer(Id answerId)
                  throws NotFoundException,
                         OperationFailedException,
                         PermissionDeniedException

Deletes the Answer identified by the given Id.

Parameters:

answerId - the Id of the Answer to delete

Throws:

NotFoundException - an Answer was not found identified by the given Id

NullArgumentException - answerId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure occurred

Compliance:

mandatory - This method must be implemented.