Interface BallotLookupSession

All Superinterfaces:
AutoCloseable, Closeable, OsidSession, 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 Details

    • 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.

    • getBallotsByCommissioner

      BallotList getBallotsByCommissioner(Id resourceId) throws OperationFailedException, PermissionDeniedException
      Gets a BallotList from the given commissioner.. 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.