com.jivesoftware.community
Interface Poll

All Superinterfaces:

com.jivesoftware.community.CommentContentResource, com.jivesoftware.community.ContainerAware, JiveContentObject, JiveObject

public interface Poll
extends JiveContentObject, com.jivesoftware.community.CommentContentResource

A poll can be attached to any object in the system or can exist at the global level.

Additionally, polls can exist in a certain time range. For example, one can create a poll and have it be active in 2 weeks for 1 month. Inactive polls can also be displayed and can be later permanently deleted from the system.

See Also:

PollManager

Nested Class Summary

Nested classes/interfaces inherited from interface com.jivesoftware.community.JiveContentObject

JiveContentObject.Field, JiveContentObject.Status

Field Summary

static long	ALLOW_ANONYMOUS_VOTE_MODIFICATION Mode to allow guests to change their vote after casting the vote.
static long	ALLOW_USER_VOTE_MODIFICATION Mode to allow users to change their vote after casting the vote.
static long	MULTIPLE_SELECTIONS_ALLOWED Mode to allow users to select multiple options in a poll.

Method Summary

void	addAnonymousVote(int index, String uniqueID) Add a guest vote for an option in the poll.
void	addOption(String value) Add a new option to the poll.
void	addUserVote(int index, User user) Add a user vote for an option in the poll.
void	changeAnonymousVote(int prevOptionIndex, int newOptionIndex, String uniqueID) Change a guest vote.
void	changeUserVote(int prevOptionIndex, int newOptionIndex, User user) Change a user vote.
void	deleteOption(int index) Remove an option from the poll.
int	getAnonymousVoteCount() Returns a count of all guests user votes for all options in the poll.
int	getAnonymousVoteCount(int index) Returns a count of all user votes for the specified option in the poll.
Iterable<String>	getAnonymousVotes() Returns an Iterator of uniqueID's for guests who have voted for the option at the given index.
Iterable<String>	getAnonymousVotes(int index) Returns an Iterator of uniqueID's for guests who have voted for the option at the given index.
List<Integer>	getAnonymousVotes(String uniqueID) Returns a list of option indexes corresponding to the anonymous votes, or an empty array if the user has not voted.
com.jivesoftware.community.CommentDelegator	getCommentDelegator() Retrieve a comment delegator to manage poll comments.
int	getCommentStatus() Returns the comment status of this poll which may be any one of the following: NONE -- no comments allowed OPEN -- comments are permitted CLOSED -- comments were permitted but are not allowed now Defaults to OPEN.
long	getContainerObjectID() Returns the object ID of the container that 'contains' the poll.
int	getContainerObjectType() Returns the object type of the container that 'contains' the poll.
Date	getCreationDate() Returns the date the poll was created.
String	getDescription() Returns a brief description of the poll.
Date	getEndDate() Returns the date voting for the poll should end.
Date	getExpirationDate() Returns the date the poll should expire.
long	getID() Returns the unique ID of the poll.
Date	getModificationDate() Returns the date the poll was last modified.
String	getName() Returns the name of the poll.
String	getOption(int index) Returns the text of the option at the specified index.
int	getOptionCount() Returns the number of options available in the poll.
Date	getStartDate() Returns the date voting for the poll is set to start.
User	getUser() Returns the user who created the poll or null if the poll was created anonymously.
int	getUserVoteCount() Returns a count of all user votes for all options in the poll.
int	getUserVoteCount(int index) Returns a count of all user votes for the specified option in the poll.
Iterable<User>	getUserVotes() Returns an Iterator of User objects for users who have voted for any options in the poll.
Iterable<User>	getUserVotes(int index) Returns an Iterator of User objects for users who have voted for the option at the given index.
List<Integer>	getUserVotes(User user) Returns a list of option indexes corresponding to the user votes, or an empty array if the user has not voted.
int	getVoteCount() Returns a count of all votes (both guest and user votes) for all options in the poll.
int	getVoteCount(int index) Returns a count of all votes (both guest and user votes) for the specified option in the poll.
boolean	hasAnonymousVoted(String uniqueID) Returns true if the guest associated with the uniqueID has previously voted in the poll, false otherwise.
boolean	hasUserVoted(User user) Returns true if the user specified has previously voted in the poll, false otherwise.
boolean	isAuthorized(long permissionType) Returns true if the handle on the object has the permission specified.
boolean	isModeEnabled(long mode) Returns true if the mode specified is enabled for the poll, false otherwise.
void	removeAnonymousVote(int prevOptionIndex, String uniqueID) Remove a guest vote.
void	removeUserVote(int prevOptionIndex, User user) Remove a user vote.
void	setCommentStatus(int status) Sets the comment status of this poll which may be any one of the following: NONE -- no comments allowed OPEN -- comments are permitted CLOSED -- comments were permitted but are not allowed now
void	setDescription(String description) Sets the description of the poll.
void	setEndDate(Date endDate) Sets the date the poll should end.
void	setExpirationDate(Date expireDate) Sets the date the poll should expire.
void	setMode(long mode, boolean enabled) Sets a mode to be enabled or disabled for the poll.
void	setName(String name) Sets the name of the poll.
void	setOption(int index, String value) Sets the text of the option at the specified index.
void	setOptionIndex(int currentIndex, int newIndex) Moves the option's index.
void	setStartDate(Date startDate) Sets the date voting for the poll should start.

Methods inherited from interface com.jivesoftware.community.JiveContentObject

getBody, getContainerID, getContainerType, getIndexContent, getPlainBody, getPlainSubject, getStatus, getSubject, getUnfilteredSubject

Methods inherited from interface com.jivesoftware.community.JiveObject

getObjectType

Methods inherited from interface com.jivesoftware.community.JiveObject

getObjectType

Field Detail

ALLOW_USER_VOTE_MODIFICATION

static final long ALLOW_USER_VOTE_MODIFICATION

Mode to allow users to change their vote after casting the vote. Not set by default.

See Also:

Constant Field Values

ALLOW_ANONYMOUS_VOTE_MODIFICATION

static final long ALLOW_ANONYMOUS_VOTE_MODIFICATION

Mode to allow guests to change their vote after casting the vote. Not set by default.

See Also:

Constant Field Values

MULTIPLE_SELECTIONS_ALLOWED

static final long MULTIPLE_SELECTIONS_ALLOWED

Mode to allow users to select multiple options in a poll. Not set by default.

See Also:

Constant Field Values

Method Detail

getUser

User getUser()

Returns the user who created the poll or null if the poll was created anonymously.

Specified by:

getUser in interface JiveContentObject

Returns:

the user who created the poll or null if the poll was created anonymously.

getContainerObjectType

int getContainerObjectType()

Returns the object type of the container that 'contains' the poll. The container type returned wiill be a value in JiveConstants (e.g. JiveConstants.COMMUNITY).

Returns:

the object type of the container that 'contains' the poll.

getContainerObjectID

long getContainerObjectID()

Returns the object ID of the container that 'contains' the poll.

Returns:

the object ID of the container that 'contains' the poll.

getID

long getID()

Returns the unique ID of the poll.

Specified by:

getID in interface JiveObject

Returns:

the unique ID of the poll.

getName

String getName()

Returns the name of the poll.

Returns:

the name of the poll.

setName

void setName(String name)
             throws UnauthorizedException

Sets the name of the poll. If the name passed in is null, an IllegalArguementException will be thrown.

Parameters:

name - the new name of the poll.

Throws:

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

getDescription

String getDescription()

Returns a brief description of the poll.

Returns:

a brief description of the poll.

setDescription

void setDescription(String description)
                    throws UnauthorizedException

Sets the description of the poll.

Parameters:

description - the description of the poll.

Throws:

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

isModeEnabled

boolean isModeEnabled(long mode)

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

Returns:

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

setMode

void setMode(long mode,
             boolean enabled)
             throws UnauthorizedException

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.

getCreationDate

Date getCreationDate()

Returns the date the poll was created.

Specified by:

getCreationDate in interface JiveContentObject

Returns:

the date the poll was created.

getModificationDate

Date getModificationDate()

Returns the date the poll was last modified. The last modified date only applies to the poll itself, it does not take into account votes for options in the poll.

Specified by:

getModificationDate in interface JiveContentObject

Returns:

the date the poll was last modified.

getStartDate

Date getStartDate()

Returns the date voting for the poll is set to start.

Returns:

the date voting for the poll is set to start.

setStartDate

void setStartDate(Date startDate)
                  throws UnauthorizedException

Sets the date voting for the poll should start.

Parameters:

startDate - the date voting for the poll should start.

Throws:

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

getEndDate

Date getEndDate()

Returns the date voting for the poll should end.

Returns:

the date voting for the poll should end.

setEndDate

void setEndDate(Date endDate)
                throws UnauthorizedException

Sets the date the poll should end.

Parameters:

endDate - the date the poll should end.

Throws:

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

getExpirationDate

Date getExpirationDate()

Returns the date the poll should expire. The expire date is different from the end date in that users will be able to see the poll but not vote between the end date and the expire date.

Returns:

the date the poll should expire.

setExpirationDate

void setExpirationDate(Date expireDate)
                       throws UnauthorizedException

Sets the date the poll should expire. This date must be on or after the end date. This date is automatically set to the end date by default.

Parameters:

expireDate - the date the poll should expire.

Throws:

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

getOptionCount

int getOptionCount()

Returns the number of options available in the poll.

Returns:

the number of options available in the poll.

getOption

String getOption(int index)

Returns the text of the option at the specified index.

Parameters:

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

Returns:

the text of the option at the specified index.

Throws:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

setOption

void setOption(int index,
               String value)
               throws UnauthorizedException

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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

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

setOptionIndex

void setOptionIndex(int currentIndex,
                    int newIndex)
                    throws UnauthorizedException

Moves the option's index.

Parameters:

currentIndex - the current index of the option.

newIndex - the new index of the option.

Throws:

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

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

addOption

void addOption(String value)
               throws UnauthorizedException

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.

deleteOption

void deleteOption(int index)
                  throws UnauthorizedException

Remove an option from the poll.

Parameters:

index -

Throws:

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

getVoteCount

int getVoteCount()
                 throws PollException

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.

getVoteCount

int getVoteCount(int index)
                 throws PollException

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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

getUserVoteCount

int getUserVoteCount()
                     throws PollException

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.

getUserVoteCount

int getUserVoteCount(int index)
                     throws PollException

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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

getAnonymousVoteCount

int getAnonymousVoteCount()
                          throws PollException

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.

getAnonymousVoteCount

int getAnonymousVoteCount(int index)
                          throws PollException

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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

getUserVotes

Iterable<User> getUserVotes()
                            throws PollException

Returns an Iterator 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.

getUserVotes

Iterable<User> getUserVotes(int index)
                            throws PollException

Returns an Iterator 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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

getAnonymousVotes

Iterable<String> getAnonymousVotes()
                                   throws PollException

Returns an Iterator 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.

getAnonymousVotes

Iterable<String> getAnonymousVotes(int index)
                                   throws PollException

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:

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

PollException - reserved for future changes.

hasUserVoted

boolean hasUserVoted(User user)

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

Parameters:

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

hasAnonymousVoted

boolean hasAnonymousVoted(String uniqueID)

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.

addUserVote

void addUserVote(int index,
                 User user)
                 throws PollException,
                        UnauthorizedException

Add a user vote for an option in the poll.

Parameters:

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

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

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

addAnonymousVote

void addAnonymousVote(int index,
                      String uniqueID)
                      throws PollException,
                             UnauthorizedException

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.

IndexOutOfBoundsException - if 0 > index > getOptionCount() - 1

changeUserVote

void changeUserVote(int prevOptionIndex,
                    int newOptionIndex,
                    User user)
                    throws PollException,
                           UnauthorizedException

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.

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

changeAnonymousVote

void changeAnonymousVote(int prevOptionIndex,
                         int newOptionIndex,
                         String uniqueID)
                         throws PollException,
                                UnauthorizedException

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.

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

removeUserVote

void removeUserVote(int prevOptionIndex,
                    User user)
                    throws PollException,
                           UnauthorizedException

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.

IndexOutOfBoundsException - if 0 > prevOptionIndex > getOptionCount() - 1

removeAnonymousVote

void removeAnonymousVote(int prevOptionIndex,
                         String uniqueID)
                         throws PollException,
                                UnauthorizedException

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.

IndexOutOfBoundsException - if 0 > prevOptionIndex > getOptionCount() - 1

getUserVotes

List<Integer> getUserVotes(User user)

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

Parameters:

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

getAnonymousVotes

List<Integer> getAnonymousVotes(String uniqueID)

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.

getCommentStatus

int getCommentStatus()

Returns the comment status of this poll which may be any one of the following:

• NONE -- no comments allowed
• OPEN -- comments are permitted
• CLOSED -- comments were permitted but are not allowed now

Defaults to OPEN.

Specified by:

getCommentStatus in interface com.jivesoftware.community.CommentContentResource

Returns:

status the comment status of this poll

setCommentStatus

void setCommentStatus(int status)
                      throws UnauthorizedException

Sets the comment status of this poll which may be any one of the following:

• NONE -- no comments allowed
• OPEN -- comments are permitted
• CLOSED -- comments were permitted but are not allowed now

Parameters:

status - the comment status of this document

Throws:

UnauthorizedException - if the user does not have permission to modify the poll.

getCommentDelegator

com.jivesoftware.community.CommentDelegator getCommentDelegator()

Retrieve a comment delegator to manage poll comments. Attempting to retrieve a comment manager prior to the poll being created will result in an IllegalStateArgument being thrown.

Specified by:

getCommentDelegator in interface com.jivesoftware.community.CommentContentResource

Returns:

a comment manager to manage document comments.

isAuthorized

boolean isAuthorized(long permissionType)

Returns true if the handle on the object has the permission specified. For example, if a user authorized to vote has a handle on this object, then calling isAuthorized(Permissions.VOTE_IN_POLL) would return true.

A list of possible permissions can be found in the Permissions class. Certain methods of this class are restricted to certain permissions as specified in the method comments.

Parameters:

permissionType - permissionType a permission type.

Returns:

true if the handle on the object has the specified permission.