com.jivesoftware.community.webservices
Interface PollService

public interface PollService

Method Summary

void	addAnonymousVote(long pollID, int index, java.lang.String uniqueID) Add a guest vote for an option in the poll.
void	addOption(long pollID, java.lang.String value) Add a new option to the poll.
void	addUserVote(long pollID, int index, long userID) Add a user vote for an option in the poll.
void	changeAnonymousVote(long pollID, int prevOptionIndex, int newOptionIndex, java.lang.String uniqueID) Change a guest vote.
void	changeUserVote(long pollID, int prevOptionIndex, int newOptionIndex, long userID) Change a user vote.
WSPoll	createPoll(int objectType, long objectID, long userID, java.lang.String name)
void	deleteOption(long pollID, int index) Remove an option from the poll.
void	deletePoll(long pollID) Deletes a poll.
int	getActivePollCount() Returns a count of all active polls in the system.
int	getActivePollCountByObjectTypeAndObjectID(int objectType, long objectID) Returns a count of all active polls of a given type and object ID.
java.util.List<WSPoll>	getActivePolls() Returns an iterable of active polls in the system.
java.util.List<WSPoll>	getActivePollsByObjectTypeAndObjectID(int objectType, long objectID) Returns an iterable of active polls associated with the object specified by the objectType and objectID.
int	getAnonymousVoteCount(long pollID) Returns a count of all guests user votes for all options in the poll.
int	getAnonymousVoteCountByIndex(long pollID, int index) Returns a count of all user votes for the specified option in the poll.
int[]	getAnonymousVoteIndices(long pollID, java.lang.String uniqueID) Returns a list of option indexes corresponding to the anonymous votes, or an empty array if the user has not voted.
java.lang.String[]	getAnonymousVotes(long pollID) Returns a list of uniqueID's for guests who have voted for the option at the given index.
java.lang.String[]	getAnonymousVotesByIndex(long pollID, int index) Returns an Iterator of uniqueID's for guests who have voted for the option at the given index.
int	getLivePollCount() Returns a count of all live polls in the system.
int	getLivePollCountByObjectTypeAndObjectID(int objectType, long objectID) Returns a count of all live polls of a given type and object ID.
java.util.List<WSPoll>	getLivePolls() Returns a List of live polls in the system.
java.util.List<WSPoll>	getLivePollsByObjectTypeAndObjectID(int objectType, long objectID) Returns an iterable of live polls associated with the object specified by the objectType and objectID.
WSPoll	getPoll(long pollID) Returns the Poll specified by the poll ID.
int	getPollCount() Returns a count of all polls, both active and inactive.
int	getPollCountByObjectTypeAndObjectID(int objectType, long objectID) Returns an count of polls, both active and inactive, associated with the object specified by the objectType and objectID.
java.util.List<WSPoll>	getPolls() Returns an iterable of all polls, both active and inactive.
java.util.List<WSPoll>	getPollsByObjectTypeAndObjectID(int objectType, long objectID) Returns an iterable of polls, both active and inactive, associated with the object specified by the objectType and objectID.
int	getUserVoteCount(long pollID) Returns a count of all user votes for all options in the poll.
int	getUserVoteCountByIndex(long pollID, int index) Returns a count of all user votes for the specified option in the poll.
int[]	getUserVoteIndices(long pollID, long userID) Returns a list of option indexes corresponding to the user votes, or an empty array if the user has not voted.
WSUser[]	getUserVotes(long pollID) Returns a List of User objects for users who have voted for any options in the poll.
WSUser[]	getUserVotesByIndex(long pollID, int index) Returns a list of User objects for users who have voted for the option at the given index.
int	getVoteCount(long pollID) Returns a count of all votes (both guest and user votes) for all options in the poll.
int	getVoteCountByIndex(long pollID, int index) Returns a count of all votes (both guest and user votes) for the specified option in the poll.
boolean	hasAnonymousVoted(long pollID, java.lang.String uniqueID) Returns true if the guest associated with the uniqueID has previously voted in the poll, false otherwise.
boolean	hasUserVoted(long pollID, long userID) Returns true if the user specified has previously voted in the poll, false otherwise.
boolean	isModeEnabled(long pollID, long mode) Returns true if the mode specified is enabled for the poll, false otherwise.
void	removeAnonymousVote(long pollID, int prevOptionIndex, java.lang.String uniqueID) Remove a guest vote.
void	removeUserVote(long pollID, int prevOptionIndex, long userID) Remove a user vote.
void	setMode(long pollID, long mode, boolean enabled) Sets a mode to be enabled or disabled for the poll.
void	setOption(long pollID, int index, java.lang.String value) Sets the text of the option at the specified index.
void	setOptionIndex(long pollID, int currentIndex, int newIndex) Moves the option's index.
void	update(WSPoll poll)

Method Detail

createPoll

WSPoll createPoll(int objectType,
                  long objectID,
                  long userID,
                  java.lang.String name)
                  throws UserNotFoundException

Throws:

UserNotFoundException

getPoll

WSPoll getPoll(long pollID)
               throws UnauthorizedException,
                      NotFoundException

Returns the Poll specified by the poll ID.

Parameters:

pollID - the id of the poll to return.

Returns:

the Poll specified by the pollID.

Throws:

UnauthorizedException - if no permissions to view the poll.

NotFoundException - if the poll of the given ID was not found.

deletePoll

void deletePoll(long pollID)
                throws UnauthorizedException,
                       PollException,
                       NotFoundException

Deletes a poll.

Parameters:

pollID - the poll to delete

Throws:

UnauthorizedException - if no permissions to delete the poll.

PollException - if the poll could not be deleted

NotFoundException - if the poll is not found

getPollCount

int getPollCount()

Returns a count of all polls, both active and inactive.

Returns:

a count of all polls, both active and inactive.

getPolls

java.util.List<WSPoll> getPolls()

Returns an iterable of all polls, both active and inactive. The ordering of the polls is from active to inactive polls and then from newest to oldest in each group.

Returns:

an iterable of all polls, both active and inactive.

getPollCountByObjectTypeAndObjectID

int getPollCountByObjectTypeAndObjectID(int objectType,
                                        long objectID)
                                        throws UnauthorizedException

Returns an count of polls, both active and inactive, associated with the object specified by the objectType and objectID.

Parameters:

objectType - the object type of the object the poll is associated with.

objectID - the objectID of the object the poll is associated with.

Returns:

an count of polls, both active and inactive, associated with the object specified by the objectType and objectID.

Throws:

UnauthorizedException - if no permissions to view polls for the specified objectType and objectID.

getPollsByObjectTypeAndObjectID

java.util.List<WSPoll> getPollsByObjectTypeAndObjectID(int objectType,
                                                       long objectID)
                                                       throws UnauthorizedException

Returns an iterable of polls, both active and inactive, associated with the object specified by the objectType and objectID.

Parameters:

objectType - the object type of the object the poll is associated with.

objectID - the objectID of the object the poll is associated with.

Returns:

an iterable of Poll objects for polls, both active and inactive, associated with the object specified by the objectType and objectID.

Throws:

UnauthorizedException - if no permissions to view polls for the specified objectType and objectID.

getActivePolls

java.util.List<WSPoll> getActivePolls()

Returns an iterable of active polls in the system. Active polls are defined as polls where the current date is between the poll's start and expire dates.

Returns:

an iterable of active polls in the system.

getActivePollCount

int getActivePollCount()

Returns a count of all active polls in the system. Active polls are defined as polls where the current date is between the poll's start and expire dates.

Returns:

a count of all active polls in the system.

getActivePollsByObjectTypeAndObjectID

java.util.List<WSPoll> getActivePollsByObjectTypeAndObjectID(int objectType,
                                                             long objectID)
                                                             throws UnauthorizedException

Returns an iterable of active polls associated with the object specified by the objectType and objectID. Active polls are defined as polls where the current date is between the poll's start and expire dates.

Parameters:

objectType - the object type of the object the poll is associated with.

objectID - the objectID of the object the poll is associated with.

Returns:

an iterable of Poll objects for active polls associated with the object specified by the objectType and objectID.

Throws:

UnauthorizedException - if no permissions to view polls for the specified objectType and objectID.

getActivePollCountByObjectTypeAndObjectID

int getActivePollCountByObjectTypeAndObjectID(int objectType,
                                              long objectID)

Returns a count of all active polls of a given type and object ID. Active polls are defined as polls where the current date is between the poll's start and expire dates.

Parameters:

objectType - the type of object we're looking at (defined in the JiveConstants class.

objectID - the ID of the object we're looking at.

Returns:

a count of all active polls for the given object.

getLivePolls

java.util.List<WSPoll> getLivePolls()

Returns a List of live polls in the system. Live polls are defined as polls where the current date is between the poll's start and end dates.

Returns:

an iterable of live polls in the system.

getLivePollCount

int getLivePollCount()

Returns a count of all live polls in the system. Live polls are defined as polls where the current date is between the poll's start and end dates.

Returns:

a count of all live polls in the system.

getLivePollsByObjectTypeAndObjectID

java.util.List<WSPoll> getLivePollsByObjectTypeAndObjectID(int objectType,
                                                           long objectID)
                                                           throws UnauthorizedException

Returns an iterable of live polls associated with the object specified by the objectType and objectID. Live polls are defined as polls where the current date is between the poll's start and end dates.

Parameters:

objectType - the object type of the object the poll is associated with.

objectID - the objectID of the object the poll is associated with.

Returns:

an iterable of Poll objects for live polls associated with the object specified by the objectType and objectID.

Throws:

UnauthorizedException - if no permissions to view polls for the specified objectType and objectID.

getLivePollCountByObjectTypeAndObjectID

int getLivePollCountByObjectTypeAndObjectID(int objectType,
                                            long objectID)
                                            throws UnauthorizedException

Returns a count of all live polls of a given type and object ID. Live polls are defined as polls where the current date is between the poll's start and end dates.

Parameters:

objectType - the type of object we're looking at (defined in the JiveConstants class.

objectID - the ID of the object we're looking at.

Returns:

a count of all live polls for the given object.

Throws:

UnauthorizedException - if not allowed

isModeEnabled

boolean isModeEnabled(long pollID,
                      long mode)
                      throws NotFoundException

Returns true if the mode specified is enabled for the poll, false otherwise. Valid modes are defined as static final constants in this interface.

Parameters:

mode - a valid poll mode

pollID - of the poll we're querying

Returns:

true if the mode specified is enabled for the poll, false otherwise.

Throws:

NotFoundException

setMode

void setMode(long pollID,
             long mode,
             boolean enabled)
             throws UnauthorizedException,
                    NotFoundException

Sets a mode to be enabled or disabled for the poll. Valid modes are defined as static final constants in this interface.

Parameters:

mode - a valid mode

enabled - true if the poll should be enabled, false if not

Throws:

UnauthorizedException - if the user does not have permissions to administer the poll.

NotFoundException

addOption

void addOption(long pollID,
               java.lang.String value)
               throws UnauthorizedException,
                      NotFoundException

Add a new option to the poll. The option will be added to the end of the option list for the poll.

Parameters:

value - the text for the new option.

Throws:

UnauthorizedException - if the user does not have permissions to administer the poll.

NotFoundException

deleteOption

void deleteOption(long pollID,
                  int index)
                  throws UnauthorizedException,
                         NotFoundException

Remove an option from the poll.

Parameters:

index -

Throws:

UnauthorizedException - if the user does not have permissions to administer the poll.

NotFoundException

setOption

void setOption(long pollID,
               int index,
               java.lang.String value)
               throws UnauthorizedException,
                      NotFoundException

Sets the text of the option at the specified index.

Parameters:

index - the index of the option to set the text for.

value - the new text for the option.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

UnauthorizedException - if the user does not have permissions to administer the poll.

NotFoundException

setOptionIndex

void setOptionIndex(long pollID,
                    int currentIndex,
                    int newIndex)
                    throws UnauthorizedException,
                           NotFoundException

Moves the option's index.

Parameters:

currentIndex - the current index of the option.

newIndex - the new index of the option.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > oldIndex/newIndex > getOptionCount() - 1

UnauthorizedException - if the user does not have permissions to administer the poll.

NotFoundException

getVoteCount

int getVoteCount(long pollID)
                 throws PollException,
                        NotFoundException

Returns a count of all votes (both guest and user votes) for all options in the poll.

Returns:

a count of all votes for all options in the poll.

Throws:

PollException - reserved for future changes.

NotFoundException

getVoteCountByIndex

int getVoteCountByIndex(long pollID,
                        int index)
                        throws PollException,
                               NotFoundException

Returns a count of all votes (both guest and user votes) for the specified option in the poll.

Returns:

a count of all votes for the specified option in the poll.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

NotFoundException

getUserVoteCount

int getUserVoteCount(long pollID)
                     throws PollException,
                            NotFoundException

Returns a count of all user votes for all options in the poll.

Returns:

a count of all user votes for all options in the poll.

Throws:

PollException - reserved for future changes.

NotFoundException

getUserVoteCountByIndex

int getUserVoteCountByIndex(long pollID,
                            int index)
                            throws PollException,
                                   NotFoundException

Returns a count of all user votes for the specified option in the poll.

Returns:

a count of all user votes for the specified option in the poll.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

NotFoundException

getAnonymousVoteCount

int getAnonymousVoteCount(long pollID)
                          throws PollException,
                                 NotFoundException

Returns a count of all guests user votes for all options in the poll.

Returns:

a count of all guest votes for all options in the poll.

Throws:

PollException - reserved for future changes.

NotFoundException

getAnonymousVoteCountByIndex

int getAnonymousVoteCountByIndex(long pollID,
                                 int index)
                                 throws PollException,
                                        NotFoundException

Returns a count of all user votes for the specified option in the poll.

Returns:

a count of all user votes for the specified option in the poll.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

NotFoundException

getAnonymousVotes

java.lang.String[] getAnonymousVotes(long pollID)
                                     throws PollException,
                                            NotFoundException

Returns a list of uniqueID's for guests who have voted for the option at the given index.

Returns:

an Iterator of uniqueID's for guests who have voted for the option at the given index.

Throws:

PollException - reserved for future changes.

NotFoundException

getAnonymousVotesByIndex

java.lang.String[] getAnonymousVotesByIndex(long pollID,
                                            int index)
                                            throws PollException,
                                                   NotFoundException

Returns an Iterator of uniqueID's for guests who have voted for the option at the given index.

Parameters:

index - the index to return the voting guests for.

Returns:

an Iterator of uniqueID's for guests who have voted for the option at the given index.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

NotFoundException

hasUserVoted

boolean hasUserVoted(long pollID,
                     long userID)
                     throws NotFoundException

Returns true if the user specified has previously voted in the poll, false otherwise.

Parameters:

userID - id of the user to check to see if they've voted already.

Returns:

true if the user specified has previously voted in the poll, false otherwise.

Throws:

NotFoundException

hasAnonymousVoted

boolean hasAnonymousVoted(long pollID,
                          java.lang.String uniqueID)
                          throws NotFoundException

Returns true if the guest associated with the uniqueID has previously voted in the poll, false otherwise.

Parameters:

uniqueID - the uniqueID of the guest to check to see if they've voted already.

Returns:

true if the guest specified has previously voted in the poll, false otherwise.

Throws:

NotFoundException

addUserVote

void addUserVote(long pollID,
                 int index,
                 long userID)
                 throws PollException,
                        UnauthorizedException,
                        NotFoundException

Add a user vote for an option in the poll.

Parameters:

index - the index of the option that the user is voting for

userID - the user making the vote

Throws:

PollException - if the user has previously voted in the poll (2 second leeway is provided for posting multiple votes if that mode is enabled) or the poll is not active.

UnauthorizedException - if the user does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

NotFoundException

addAnonymousVote

void addAnonymousVote(long pollID,
                      int index,
                      java.lang.String uniqueID)
                      throws PollException,
                             UnauthorizedException,
                             NotFoundException

Add a guest vote for an option in the poll.

Parameters:

index - the index of the option that the guest is voting for

uniqueID - a uniqueID for the guest. We suggest either using a session ID or the remote IP of the guest voting.

Throws:

PollException - if the guest has previously voted in the poll (2 second leeway is provided for posting multiple votes if that mode is enabled) or the poll is not active.

UnauthorizedException - if the guest does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

NotFoundException

changeUserVote

void changeUserVote(long pollID,
                    int prevOptionIndex,
                    int newOptionIndex,
                    long userID)
                    throws PollException,
                           UnauthorizedException,
                           NotFoundException

Change a user vote. This method will throw a PollException unless the mode 'ALLOW_USER_VOTE_MODIFICATION' is enabled for the poll.

Parameters:

prevOptionIndex - the index of the option to change the vote from.

newOptionIndex - the index of the option to change the vote to.

Throws:

PollException - if the poll is not active, the user did not vote for the prevOptionIndex or vote modification is not enabled for users.

UnauthorizedException - if the user does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > prevOptionIndex/newOptionIndex > getOptionCount() - 1

NotFoundException

changeAnonymousVote

void changeAnonymousVote(long pollID,
                         int prevOptionIndex,
                         int newOptionIndex,
                         java.lang.String uniqueID)
                         throws PollException,
                                UnauthorizedException,
                                NotFoundException

Change a guest vote. This method will throw a PollException unless the mode 'ALLOW_ANONYMOUS_VOTE_MODIFICATION' is enabled for the poll.

Parameters:

prevOptionIndex - the index of the option to change the vote from.

newOptionIndex - the index of the option to change the vote to.

uniqueID - a uniqueID for the guest.

Throws:

PollException - if the poll is not active, the guest did not vote for the prevOptionIndex or vote modification is not enabled for guests.

UnauthorizedException - if the guest does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > prevOptionIndex/newOptionIndex > getOptionCount() - 1

NotFoundException

removeUserVote

void removeUserVote(long pollID,
                    int prevOptionIndex,
                    long userID)
                    throws PollException,
                           UnauthorizedException,
                           NotFoundException

Remove a user vote. This method will throw a PollException unless the mode 'ALLOW_USER_VOTE_MODIFICATION' is enabled for the poll.

Parameters:

prevOptionIndex - the index of the option to remove the vote from.

Throws:

PollException - if the poll is not active, the user did not vote for the prevOptionIndex or vote modification is not enabled for users.

UnauthorizedException - if the user does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > prevOptionIndex > getOptionCount() - 1

NotFoundException

removeAnonymousVote

void removeAnonymousVote(long pollID,
                         int prevOptionIndex,
                         java.lang.String uniqueID)
                         throws PollException,
                                UnauthorizedException,
                                NotFoundException

Remove a guest vote. This method will throw a PollException unless the mode 'ALLOW_ANONYMOUS_VOTE_MODIFICATION' is enabled for the poll.

Parameters:

prevOptionIndex - the index of the option to remove the vote from.

uniqueID - a uniqueID for the guest.

Throws:

PollException - if the poll is not active, the guest did not vote for the prevOptionIndex or vote modification is not enabled for guests.

UnauthorizedException - if the guest does not have permission to vote.

java.lang.IndexOutOfBoundsException - if 0 > prevOptionIndex > getOptionCount() - 1

NotFoundException

getUserVoteIndices

int[] getUserVoteIndices(long pollID,
                         long userID)
                         throws NotFoundException

Returns a list of option indexes corresponding to the user votes, or an empty array if the user has not voted.

Parameters:

userID - the user to return the indexes of options the user has voted for.

Returns:

a list of option indexes (as Integers) corresponding to the user votes. @param pollID of the poll we're querying on

Throws:

NotFoundException

getAnonymousVoteIndices

int[] getAnonymousVoteIndices(long pollID,
                              java.lang.String uniqueID)
                              throws NotFoundException

Returns a list of option indexes corresponding to the anonymous votes, or an empty array if the user has not voted.

Parameters:

uniqueID - a uniqueID for the guest.

Returns:

a list of option indexes (as Integers) corresponding to the anonymous votes.

Throws:

NotFoundException

getUserVotes

WSUser[] getUserVotes(long pollID)
                      throws PollException,
                             NotFoundException

Returns a List of User objects for users who have voted for any options in the poll.

Returns:

an Iterator of users who have voted for any option in the poll

Throws:

PollException - reserved for future changes.

NotFoundException

getUserVotesByIndex

WSUser[] getUserVotesByIndex(long pollID,
                             int index)
                             throws PollException,
                                    NotFoundException

Returns a list of User objects for users who have voted for the option at the given index.

Parameters:

index - the index to return the voting users for.

Returns:

an Iterator of users who have voted for the option at the given index.

Throws:

java.lang.IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

NotFoundException

update

void update(WSPoll poll)
            throws NotFoundException

Throws:

NotFoundException