org.osid.voting

Interface VoteLookupSession

All Superinterfaces:

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

public interface VoteLookupSession
extends OsidSession

This session provides methods for looking up votes.

This session defines views that offer differing behaviors when retrieving multiple objects.

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete set or is an error votes
• isolated polls view: All vote methods in this session operate, retrieve and pertain to votes defined explicitly in the current polls. Using an isolated view is useful for managing votes with the VoteAdminSession.
• federated polls view: All vote methods in this session operate, retrieve and pertain to all votes defined in these polls and any other catalogs implicitly available in this polls through polls inheritence.
• effective vote view: All vote lookup methods return votes where the current date falls in between the effective dates inclusive.
• any effective vote view: Votes of any effective date are returned from methods.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupVotes() Tests if this user can access votes.
Polls	getPolls() Gets the Polls associated with this session.
Id	getPollsId() Gets the Polls Id associated with this session.
Vote	getVote(Id voteId) Gets a Vote specified by its Id.
VoteList	getVotes() Gets all votes.
VoteList	getVotesByGenusType(Type voteGenusType) Gets the votes for the given vote genus type.
VoteList	getVotesByIds(IdList voteIds) Gets a VoteList corresponding to the given IdList.
VoteList	getVotesByParentGenusType(Type voteGenusType) Gets the votes for the given vote genus type and include any votes with a genus type derived from the specified genus type.
VoteList	getVotesByRecordType(Type voteRecordType) Gets the votes for the given vote record type.
VoteList	getVotesForBallot(Id ballotId) Gets the votes cast in the given ballot.
VoteList	getVotesForBallotOnDate(Id ballotId, DateTime from, DateTime to) Gets a list of votes in a ballot effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForCandidate(Id candidateId) Gets the Votes for a candidate.
VoteList	getVotesForCandidateOnDate(Id candidateId, DateTime from, DateTime to) Gets a list of votes for a candidate effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForRace(Id raceId) Gets the votes cast in the given race.
VoteList	getVotesForRaceOnDate(Id raceId, DateTime from, DateTime to) Gets a list of votes in a race effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForVoter(Id resourceId) Gets the votes cast by the given voter.
VoteList	getVotesForVoterAndBallot(Id resourceId, Id ballotId) Gets the votes cast by the given voter and ballot.
VoteList	getVotesForVoterAndBallotOnDate(Id resourceId, Id ballotId, DateTime from, DateTime to) Gets a list of votes for a voter and ballot effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForVoterAndCandidate(Id resourceId, Id candidateId) Gets the votes cast by the given voter and candidate.
VoteList	getVotesForVoterAndCandidateOnDate(Id resourceId, Id candidateId, DateTime from, DateTime to) Gets a list of votes for a voter and candidate effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForVoterAndRace(Id resourceId, Id raceId) Gets the votes cast by the given voter and race.
VoteList	getVotesForVoterAndRaceOnDate(Id resourceId, Id raceId, DateTime from, DateTime to) Gets a list of votes for a voter and race effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesForVoterOnDate(Id resourceId, DateTime from, DateTime to) Gets a list of votes for a voter effective during the entire given date range inclusive but not confined to the date range.
VoteList	getVotesOnDate(DateTime from, DateTime to) Gets a list of votes effective during the entire given date range inclusive but not confined to the date range.
void	useAnyEffectiveVoteView() All votes of any effective dates are returned by methods in this session.
void	useComparativeVoteView() The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error.
void	useEffectiveVoteView() Only votes whose effective dates are current are returned by methods in this session.
void	useFederatedPollsView() Federates the view for methods in this session.
void	useIsolatedPollsView() Isolates the view for methods in this session.
void	usePlenaryVoteView() A complete view of the vote returns is desired.

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.

canLookupVotes

boolean canLookupVotes()

Tests if this user can access votes. A return of true does not guarantee successful authorization. A return of false indicates that it is known all methods in this session will result in a PERMISSION_DENIED. This is intended as a hint to an application that may opt not to offer vote operations.

Returns:

false if voting methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeVoteView

void useComparativeVoteView()

The returns from the lookup methods may omit or translate elements based on this session, such as authorization, and not result in an error. This view is used when greater interoperability is desired at the expense of precision.

Compliance:

mandatory - This method is must be implemented.

usePlenaryVoteView

void usePlenaryVoteView()

A complete view of the vote returns is desired. Methods will return what is requested or result in an error. This view is used when greater precision is desired at the expense of interoperability.

Compliance:

mandatory - This method is must be implemented.

useFederatedPollsView

void useFederatedPollsView()

Federates the view for methods in this session. A federated view will include votes in polls which are children of this polls in the polls hierarchy.

Compliance:

mandatory - This method is must be implemented.

useIsolatedPollsView

void useIsolatedPollsView()

Isolates the view for methods in this session. An isolated view restricts votes to these polls only.

Compliance:

mandatory - This method is must be implemented.

useEffectiveVoteView

void useEffectiveVoteView()

Only votes whose effective dates are current are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyEffectiveVoteView

void useAnyEffectiveVoteView()

All votes of any effective dates are returned by methods in this session.

Compliance:

mandatory - This method is must be implemented.

getVote

Vote getVote(Id voteId)
             throws NotFoundException,
                    OperationFailedException,
                    PermissionDeniedException

Gets a Vote specified by its Id.

Parameters:

voteId - Id of the Vote

Returns:

the vote

Throws:

NotFoundException - voteId not found

NullArgumentException - voteId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method is must be implemented.

getVotesByIds

VoteList getVotesByIds(IdList voteIds)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

Gets a VoteList corresponding to the given IdList. In plenary mode, the returned list contains all of the votes specified in the Id list, in the order of the list, including duplicates, or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible Votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

voteIds - the list of Ids to retrieve

Returns:

the returned Vote list

Throws:

NotFoundException - an Id was not found

NullArgumentException - voteIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesByGenusType

VoteList getVotesByGenusType(Type voteGenusType)
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets the votes for the given vote genus type. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

voteGenusType - a vote genus type

Returns:

the votes

Throws:

NullArgumentException - voteGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesByParentGenusType

VoteList getVotesByParentGenusType(Type voteGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets the votes for the given vote genus type and include any votes with a genus type derived from the specified genus type. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

voteGenusType - a vote genus type

Returns:

the votes

Throws:

NullArgumentException - voteGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesByRecordType

VoteList getVotesByRecordType(Type voteRecordType)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets the votes for the given vote record type. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

voteRecordType - a vote record type

Returns:

the votes

Throws:

NullArgumentException - voteRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesOnDate

VoteList getVotesOnDate(DateTime from,
                      DateTime to)
                        throws OperationFailedException,
                               PermissionDeniedException

Gets a list of votes effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoter

VoteList getVotesForVoter(Id resourceId)
                          throws OperationFailedException,
                                 PermissionDeniedException

Gets the votes cast by the given voter. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

Returns:

the votes

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterOnDate

VoteList getVotesForVoterOnDate(Id resourceId,
                              DateTime from,
                              DateTime to)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a list of votes for a voter effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForCandidate

VoteList getVotesForCandidate(Id candidateId)
                              throws OperationFailedException,
                                     PermissionDeniedException

Gets the Votes for a candidate. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

candidateId - Id of a Candidate

Returns:

the votes

Throws:

NullArgumentException - candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForCandidateOnDate

VoteList getVotesForCandidateOnDate(Id candidateId,
                                  DateTime from,
                                  DateTime to)
                                    throws OperationFailedException,
                                           PermissionDeniedException

Gets a list of votes for a candidate effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

candidateId - Id of a Candidate

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - candidateId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndCandidate

VoteList getVotesForVoterAndCandidate(Id resourceId,
                                    Id candidateId)
                                      throws OperationFailedException,
                                             PermissionDeniedException

Gets the votes cast by the given voter and candidate. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

candidateId - Id of a Candidate

Returns:

the votes

Throws:

NullArgumentException - resourceId or candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndCandidateOnDate

VoteList getVotesForVoterAndCandidateOnDate(Id resourceId,
                                          Id candidateId,
                                          DateTime from,
                                          DateTime to)
                                            throws OperationFailedException,
                                                   PermissionDeniedException

Gets a list of votes for a voter and candidate effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

candidateId - Id of a Candidate

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, candidateId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForRace

VoteList getVotesForRace(Id raceId)
                         throws OperationFailedException,
                                PermissionDeniedException

Gets the votes cast in the given race. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

raceId - Id of a Race

Returns:

the votes

Throws:

NullArgumentException - ballotId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForRaceOnDate

VoteList getVotesForRaceOnDate(Id raceId,
                             DateTime from,
                             DateTime to)
                               throws OperationFailedException,
                                      PermissionDeniedException

Gets a list of votes in a race effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

raceId - Id of a Race

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - raceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndRace

VoteList getVotesForVoterAndRace(Id resourceId,
                               Id raceId)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets the votes cast by the given voter and race. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

raceId - Id of a Race

Returns:

the votes

Throws:

NullArgumentException - resourceId or raceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndRaceOnDate

VoteList getVotesForVoterAndRaceOnDate(Id resourceId,
                                     Id raceId,
                                     DateTime from,
                                     DateTime to)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Gets a list of votes for a voter and race effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

raceId - Id of a Race

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, raceId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForBallot

VoteList getVotesForBallot(Id ballotId)
                           throws OperationFailedException,
                                  PermissionDeniedException

Gets the votes cast in the given ballot. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

ballotId - Id of a Ballot

Returns:

the votes

Throws:

NullArgumentException - ballotId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForBallotOnDate

VoteList getVotesForBallotOnDate(Id ballotId,
                               DateTime from,
                               DateTime to)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a list of votes in a ballot effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

ballotId - Id of a Ballot

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - ballotId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndBallot

VoteList getVotesForVoterAndBallot(Id resourceId,
                                 Id ballotId)
                                   throws OperationFailedException,
                                          PermissionDeniedException

Gets the votes cast by the given voter and ballot. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

ballotId - Id of a Ballot

Returns:

the votes

Throws:

NullArgumentException - resourceId or ballotId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotesForVoterAndBallotOnDate

VoteList getVotesForVoterAndBallotOnDate(Id resourceId,
                                       Id ballotId,
                                       DateTime from,
                                       DateTime to)
                                         throws OperationFailedException,
                                                PermissionDeniedException

Gets a list of votes for a voter and ballot effective during the entire given date range inclusive but not confined to the date range. In plenary mode, the returned list contains all known votes or an error results. Otherwise, the returned list may contain only those votes that are accessible through this session. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Parameters:

resourceId - Id of a Voter

ballotId - Id of a Ballot

from - start of date range

to - end of date range

Returns:

the returned Vote list

Throws:

InvalidArgumentException - from is greater than to

NullArgumentException - resourceId, ballotId, from or to is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getVotes

VoteList getVotes()
                  throws OperationFailedException,
                         PermissionDeniedException

Gets all votes. In plenary mode, the returned list contains all of the votes mapped to the candidate Id or an error results if an Id in the supplied list is not found or inaccessible. Otherwise, inaccessible votes may be omitted from the list and may present the elements in any order including returning a unique set. In effective mode, votes are returned that are currently effective. In any effective mode, effective votes and those currently expired are returned.

Returns:

the votes

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.