org.osid.voting

Interface BallotLookupSession

All Superinterfaces:

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

public interface BallotLookupSession
extends OsidSession

This session defines methods for retrieving ballots. A Ballot is an arbitrary entity that may represent a person, place or thing used to identify an object used in various services.

This lookup session defines several views:

• comparative view: elements may be silently omitted or re-ordered
• plenary view: provides a complete result set or is an error condition
• isolated polls view: All ballot methods in this session operate, retrieve and pertain to ballots defined explicitly in the current polls. Using an isolated view is useful for managing Ballots with the BallotAdminSession.
• federated polls view: All ballot methods in this session operate, retrieve and pertain to all ballots defined in this polls and any other ballots implicitly available in this polls through polls inheritence.
• active ballot view: active ballots are returned from methods in this session
• any status ballot view: active and inactive ballots are returned from methods in this session

The methods useFederatedPollsView() and useIsolatedPollsView() behave as a radio group and one should be selected before invoking any lookup methods.

Ballots may have an additional records indicated by their respective record types. The record may not be accessed through a cast of the Ballot.

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupBallots() Tests if this user can perform Ballot lookups.
Ballot	getBallot(Id ballotId) Gets the Ballot specified by its Id.
BallotList	getBallots() Gets all Ballots.
BallotList	getBallotsByGenusType(Type ballotGenusType) Gets a BallotList corresponding to the given ballot genus Type which does not include ballot of types derived from the specified Type.
BallotList	getBallotsByIds(IdList ballotIds) Gets a BallotList corresponding to the given IdList.
BallotList	getBallotsByParentGenusType(Type ballotGenusType) Gets a BallotList corresponding to the given ballot genus Type and include any additional ballots with genus types derived from the specified Type.
BallotList	getBallotsByProvider(Id resourceId) Gets a BallotList from the given provider.
BallotList	getBallotsByRecordType(Type ballotRecordType) Gets a BallotList containing the given ballot record Type.
BallotList	getBallotsOnDate(DateTime from, DateTime to) Gets a BallotList that are effective for the entire given date range but not confined to the date range.
Polls	getPolls() Gets the Polls associated with this session.
Id	getPollsId() Gets the Polls Id associated with this session.
void	useActiveBallotView() Only active ballots are returned from methods in this session.
void	useAnyStatusBallotView() Borth active and inactive ballots are returned from methods in this session.
void	useComparativeBallotView() 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	useFederatedPollsView() Federates the view for methods in this session.
void	useIsolatedPollsView() Isolates the view for methods in this session.
void	usePlenaryBallotView() A complete view of the Ballot 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.

canLookupBallots

boolean canLookupBallots()

Tests if this user can perform Ballot lookups. 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 lookup operations.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeBallotView

void useComparativeBallotView()

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.

usePlenaryBallotView

void usePlenaryBallotView()

A complete view of the Ballot 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 ballots 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 lookups to this polls only.

Compliance:

mandatory - This method is must be implemented.

useActiveBallotView

void useActiveBallotView()

Only active ballots are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusBallotView

void useAnyStatusBallotView()

Borth active and inactive ballots are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

getBallot

Ballot getBallot(Id ballotId)
                 throws NotFoundException,
                        OperationFailedException,
                        PermissionDeniedException

Gets the Ballot specified by its Id. In plenary mode, the exact Id is found or a NOT_FOUND results. Otherwise, the returned Ballot may have a different Id than requested, such as the case where a duplicate Id was assigned to a Ballot and retained for compatibility. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

ballotId - the Id of the Ballot to retrieve

Returns:

the returned Ballot

Throws:

NotFoundException - no Ballot found with the given Id

NullArgumentException - ballotId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsByIds

BallotList getBallotsByIds(IdList ballotIds)
                           throws NotFoundException,
                                  OperationFailedException,
                                  PermissionDeniedException

Gets a BallotList corresponding to the given IdList. In plenary mode, the returned list contains all of the ballots 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 Ballots may be omitted from the list and may present the elements in any order including returning a unique set. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

ballotIds - the list of Ids to retrieve

Returns:

the returned Ballot list

Throws:

NotFoundException - an Id was not found

NullArgumentException - ballotIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsByGenusType

BallotList getBallotsByGenusType(Type ballotGenusType)
                                 throws OperationFailedException,
                                        PermissionDeniedException

Gets a BallotList corresponding to the given ballot genus Type which does not include ballot of types derived from the specified Type. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

ballotGenusType - a ballot genus type

Returns:

the returned Ballot list

Throws:

NullArgumentException - ballotGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsByParentGenusType

BallotList getBallotsByParentGenusType(Type ballotGenusType)
                                       throws OperationFailedException,
                                              PermissionDeniedException

Gets a BallotList corresponding to the given ballot genus Type and include any additional ballots with genus types derived from the specified Type. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

ballotGenusType - a ballot genus type

Returns:

the returned Ballot list

Throws:

NullArgumentException - ballotGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsByRecordType

BallotList getBallotsByRecordType(Type ballotRecordType)
                                  throws OperationFailedException,
                                         PermissionDeniedException

Gets a BallotList containing the given ballot record Type. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

ballotRecordType - a ballot record type

Returns:

the returned Ballot list

Throws:

NullArgumentException - ballotRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsByProvider

BallotList getBallotsByProvider(Id resourceId)
                                throws OperationFailedException,
                                       PermissionDeniedException

Gets a BallotList from the given provider. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

resourceId - a resource Id

Returns:

the returned Ballot list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getBallotsOnDate

BallotList getBallotsOnDate(DateTime from,
                          DateTime to)
                            throws OperationFailedException,
                                   PermissionDeniedException

Gets a BallotList that are effective for the entire given date range but not confined to the date range. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Parameters:

from - s atsrting date

to - an ending date

Returns:

the returned Ballot 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.

getBallots

BallotList getBallots()
                      throws OperationFailedException,
                             PermissionDeniedException

Gets all Ballots. In plenary mode, the returned list contains all known ballots or an error results. Otherwise, the returned list may contain only those ballots that are accessible through this session. In active mode, ballots are returned that are currently active. In any status mode, active and inactive ballots are returned.

Returns:

a list of Ballots

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.