org.osid.voting

Interface RaceLookupSession

All Superinterfaces:

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

public interface RaceLookupSession
extends OsidSession

This session defines methods for retrieving races. A Race represents a statistic.

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
• federated polls view: includes races in polls which are children of this polls in the polls hierarchy
• isolated polls view: restricts lookups to this polls only
• active race view: active races are returned from methods in this session
• any status race view: active and inactive races are returned from methods in this session

Method Summary

Methods

Modifier and Type	Method and Description
boolean	canLookupRaces() Tests if this user can lookup races.
Polls	getPolls() Gets the Polls associated with this session.
Id	getPollsId() Gets the Polls Id associated with this session.
Race	getRace(Id raceId) Gets the Race specified by its Id.
RaceList	getRaces() Gets all races.
RaceList	getRacesByCandidate(Id candidateId) Gets a RaceList containing the given Candidate.
RaceList	getRacesByGenusType(Type raceGenusType) Gets a RaceList corresponding to the given race genus Type which does not include races of types derived from the specified Type.
RaceList	getRacesByIds(IdList raceIds) Gets a RaceList corresponding to the given IdList.
RaceList	getRacesByParentGenusType(Type raceGenusType) Gets a RaceList corresponding to the given race genus Type and include races of types derived from the specified Type.
RaceList	getRacesByProvider(Id resourceId) Gets a RaceList from the given provider.
RaceList	getRacesByRecordType(Type raceRecordType) Gets a RaceList containing the given race record Type.
RaceList	getRacesForBallot(Id ballotId) Gets a RaceList for the given Ballot.
void	useActiveRaceView() Only active races are returned from methods in this session.
void	useAnyStatusRaceView() Borth active and inactive races are returned from methods in this session.
void	useComparativeRaceView() 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	usePlenaryRaceView() A complete view of the Race 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

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

canLookupRaces

boolean canLookupRaces()

Tests if this user can lookup races. 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 reading operations.

Returns:

false if lookup methods are not authorized, true otherwise

Compliance:

mandatory - This method must be implemented.

useComparativeRaceView

void useComparativeRaceView()

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.

usePlenaryRaceView

void usePlenaryRaceView()

A complete view of the Race 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 races 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 retrievals to this polls only.

Compliance:

mandatory - This method is must be implemented.

useActiveRaceView

void useActiveRaceView()

Only active races are returned from methods in this session.

Compliance:

mandatory - This method is must be implemented.

useAnyStatusRaceView

void useAnyStatusRaceView()

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

Compliance:

mandatory - This method is must be implemented.

getRace

Race getRace(Id raceId)
             throws NotFoundException,
                    OperationFailedException,
                    PermissionDeniedException

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

Parameters:

raceId - the Id of the Race to retrieve

Returns:

the returned Race

Throws:

NotFoundException - no Race found with the given Id

NullArgumentException - raceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByIds

RaceList getRacesByIds(IdList raceIds)
                       throws NotFoundException,
                              OperationFailedException,
                              PermissionDeniedException

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

Parameters:

raceIds - the list of Ids to retrieve

Returns:

the returned Race list

Throws:

NotFoundException - an Id was not found

NullArgumentException - raceIds is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByGenusType

RaceList getRacesByGenusType(Type raceGenusType)
                             throws OperationFailedException,
                                    PermissionDeniedException

Gets a RaceList corresponding to the given race genus Type which does not include races of types derived from the specified Type. In plenary mode, the returned list contains all known races or an error results. Otherwise, the returned list may contain only those races that are accessible through this session.

Parameters:

raceGenusType - a race genus type

Returns:

the returned Race list

Throws:

NullArgumentException - raceGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByParentGenusType

RaceList getRacesByParentGenusType(Type raceGenusType)
                                   throws OperationFailedException,
                                          PermissionDeniedException

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

Parameters:

raceGenusType - a race genus type

Returns:

the returned Race list

Throws:

NullArgumentException - raceGenusType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByRecordType

RaceList getRacesByRecordType(Type raceRecordType)
                              throws OperationFailedException,
                                     PermissionDeniedException

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

Parameters:

raceRecordType - a race record type

Returns:

the returned Race list

Throws:

NullArgumentException - raceRecordType is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByProvider

RaceList getRacesByProvider(Id resourceId)
                            throws OperationFailedException,
                                   PermissionDeniedException

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

Parameters:

resourceId - a resource Id

Returns:

the returned Race list

Throws:

NullArgumentException - resourceId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesForBallot

RaceList getRacesForBallot(Id ballotId)
                           throws OperationFailedException,
                                  PermissionDeniedException

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

Parameters:

ballotId - a ballot Id

Returns:

the returned Race list

Throws:

NullArgumentException - ballotId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRacesByCandidate

RaceList getRacesByCandidate(Id candidateId)
                             throws OperationFailedException,
                                    PermissionDeniedException

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

Parameters:

candidateId - a candidate Id

Returns:

the returned Race list

Throws:

NullArgumentException - candidateId is null

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.

getRaces

RaceList getRaces()
                  throws OperationFailedException,
                         PermissionDeniedException

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

Returns:

a list of races

Throws:

OperationFailedException - unable to complete request

PermissionDeniedException - authorization failure

Compliance:

mandatory - This method must be implemented.