org.osid.voting

Interface CandidateAdminSession

All Superinterfaces:

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

All Known Subinterfaces:

CandidateBatchAdminSession

public interface CandidateAdminSession
extends OsidSession

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

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

The delete operations delete Candidates. To unmap a Candidate from the current Polls, the CandidatePollsAssignmentSession should be used. These delete operations attempt to remove the Candidate itself thus removing it from all known Polls 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	aliasCandidate(Id candidateId, Id aliasId) Adds an Id to a Candidate for the purpose of creating compatibility.
boolean	canCreateCandidates() Tests if this user can create Candidates.
boolean	canCreateCandidateWithRecordTypes(Type[] candidateRecordTypes) Tests if this user can create a single Candidate using the desired record types.
boolean	canDeleteCandidates() Tests if this user can delete Candidates.
boolean	canManageCandidateAliases() Tests if this user can manage Id aliases for Candidates.
boolean	canUpdateCandidates() Tests if this user can update Candidates.
Candidate	createCandidate(CandidateForm candidateForm) Creates a new Candidate.
void	deleteCandidate(Id candidateId) Deletes a Candidate.
CandidateForm	getCandidateFormForCreate(Id resourceId, Id raceId, Type[] candidateRecordTypes) Gets the candidate form for creating new candidates.
CandidateForm	getCandidateFormForUpdate(Id candidateId) Gets the candidate form for updating an existing candidate.
Polls	getPolls() Gets the Polls associated with this session.
Id	getPollsId() Gets the Polls Id associated with this session.
void	updateCandidate(CandidateForm candidateForm) Updates an existing candidate.

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

getPollsId

Id getPollsId()

Gets the Polls Id associated with this session.

Returns:

the Polls Id associated with this session

Compliance:

mandatory - This method must be implemented.

getPolls

Polls getPolls()
               throws OperationFailedException,
                      PermissionDeniedException

Gets the Polls associated with this session.

Returns:

the Polls associated with this session

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canCreateCandidates

boolean canCreateCandidates()

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

Compliance:

mandatory - This method must be implemented.

canCreateCandidateWithRecordTypes

boolean canCreateCandidateWithRecordTypes(Type[] candidateRecordTypes)

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

Parameters:

candidateRecordTypes - array of candidate record types

Returns:

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

Throws:

NullArgumentException - candidateRecordTypes is null

Compliance:

mandatory - This method must be implemented.

getCandidateFormForCreate

CandidateForm getCandidateFormForCreate(Id resourceId,
                                      Id raceId,
                                      Type[] candidateRecordTypes)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

Gets the candidate form for creating new candidates. A new form should be requested for each create transaction.

Parameters:

resourceId - the resource Id

raceId - the race Id

candidateRecordTypes - array of candidate record types

Returns:

the candidate form

Throws:

NotFoundException - resourceId or raceId is not found

NullArgumentException - resourceId, raceId or candidateRecordTypes is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - unable to get form with requested record types

Compliance:

mandatory - This method must be implemented.

createCandidate

Candidate createCandidate(CandidateForm candidateForm)
                          throws OperationFailedException,
                                 PermissionDeniedException

Creates a new Candidate.

Parameters:

candidateForm - the form for this Candidate

Returns:

the new Candidate

Throws:

IllegalStateException - candidateForm already used in a create transaction

InvalidArgumentException - one or more of the form elements is invalid

NullArgumentException - candidateForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - candidateForm did not originate from getCandidateFormForCreate()

Compliance:

mandatory - This method must be implemented.

canUpdateCandidates

boolean canUpdateCandidates()

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

Compliance:

mandatory - This method must be implemented.

getCandidateFormForUpdate

CandidateForm getCandidateFormForUpdate(Id candidateId)
                                        throws NotFoundException,
                                               OperationFailedException,
                                               PermissionDeniedException

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

Parameters:

candidateId - the Id of the Candidate

Returns:

the candidate form

Throws:

NotFoundException - candidateId is not found

NullArgumentException - candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

updateCandidate

void updateCandidate(CandidateForm candidateForm)
                     throws OperationFailedException,
                            PermissionDeniedException

Updates an existing candidate.

Parameters:

candidateForm - the form containing the elements to be updated

Throws:

IllegalStateException - candidateForm already used in an update transaction

InvalidArgumentException - the form contains an invalid value

NullArgumentException - candidateForm is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

UnsupportedException - candidateForm did not originate from getCandidateFormForUpdate()

Compliance:

mandatory - This method must be implemented.

canDeleteCandidates

boolean canDeleteCandidates()

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

Compliance:

mandatory - This method must be implemented.

deleteCandidate

void deleteCandidate(Id candidateId)
                     throws NotFoundException,
                            OperationFailedException,
                            PermissionDeniedException

Deletes a Candidate.

Parameters:

candidateId - the Id of the Candidate to remove

Throws:

NotFoundException - candidateId not found

NullArgumentException - candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canManageCandidateAliases

boolean canManageCandidateAliases()

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

Compliance:

mandatory - This method must be implemented.

aliasCandidate

void aliasCandidate(Id candidateId,
                  Id aliasId)
                    throws AlreadyExistsException,
                           NotFoundException,
                           OperationFailedException,
                           PermissionDeniedException

Adds an Id to a Candidate for the purpose of creating compatibility. The primary Id of the Candidate is determined by the provider. The new Id performs as an alias to the primary Id. If the alias is a pointer to another candidate it is reassigned to the given candidate Id.

Parameters:

candidateId - the Id of a Candidate

aliasId - the alias Id

Throws:

AlreadyExistsException - aliasId is already assigned

NotFoundException - candidateId not found

NullArgumentException - aliasId or candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.