com.jivesoftware.community.webservices
Interface PrivateMessageService

public interface PrivateMessageService

Provides the ability to manipulate private messages. Send, retrieve, move, list.

Method Summary

PrivateMessageFolder	createFolder(long userID, java.lang.String name) Creates a new folder.
PrivateMessage	createMessage(long senderID) Creates a new private message.
void	deleteFolder(long userID, int folderID) Deletes a folder.
void	deleteMessage(long userID, long messageID) Deletes a private message from the folder by moving it to the trash folder.
PrivateMessageFolder	getFolder(long userID, int folderID) Returns the specified folder for a user.
PrivateMessageFolder[]	getFolders(long userID) Returns an Iterator of PrivateMessageFolder objects for the folders the user has.
PrivateMessage	getMessage(long privateMessageID) Returns the specified private message.
int	getMessageCount(long userID) Returns the total number of private messages a user has in their mailbox.
int	getMessageCountForFolder(long userID, int folderID) Returns the message count on a specific folder.
PrivateMessage[]	getMessages(long userID, long folderID) Returns all the messages in the folder sorted by date descending.
int	getUnreadMessageCount(long userID) Returns the total number of unread private messages a user has in their mailbox.
int	getUnreadMessageCountForFolder(long userID, int folderID) Returns the total number of unread private messages a user has in a specific folder.
boolean	isPrivateMessagesEnabled() Returns true if the feature is enabled, false otherwise.
void	moveMessage(long userID, long messageID, int destinationFolderID) Moves a private message to another folder.
void	saveMessageAsDraft(PrivateMessage privateMessage) Saves a message as a draft by storing it in the sender's Drafts folder.
void	sendMessage(PrivateMessage privateMessage, long recipientID, boolean copyToSentFolder) Sends a private message to another user.

Method Detail

isPrivateMessagesEnabled

boolean isPrivateMessagesEnabled()

Returns true if the feature is enabled, false otherwise.

Returns:

true if the feature is enabled, false otherwise.

getMessages

PrivateMessage[] getMessages(long userID,
                             long folderID)
                             throws UserNotFoundException,
                                    com.jivesoftware.community.PrivateMessageFolderNotFoundException

Returns all the messages in the folder sorted by date descending.

Returns:

all messages in the folder.

Throws:

UserNotFoundException

com.jivesoftware.community.PrivateMessageFolderNotFoundException

deleteMessage

void deleteMessage(long userID,
                   long messageID)
                   throws UserNotFoundException,
                          com.jivesoftware.community.PrivateMessageFolderNotFoundException,
                          com.jivesoftware.community.PrivateMessageNotFoundException

Deletes a private message from the folder by moving it to the trash folder. Messages in the Trash folder will be routinely automatically deleted. If this is the Trash folder, this method will do nothing.

Parameters:

messageID - the private message to delete.

Throws:

UserNotFoundException

com.jivesoftware.community.PrivateMessageFolderNotFoundException

com.jivesoftware.community.PrivateMessageNotFoundException

moveMessage

void moveMessage(long userID,
                 long messageID,
                 int destinationFolderID)
                 throws UserNotFoundException,
                        com.jivesoftware.community.PrivateMessageFolderNotFoundException,
                        com.jivesoftware.community.PrivateMessageNotFoundException

Moves a private message to another folder.

Parameters:

userID - of the user

messageID - of the message to move.

destinationFolderID - of the folder to move the message to.

Throws:

UserNotFoundException

com.jivesoftware.community.PrivateMessageFolderNotFoundException

com.jivesoftware.community.PrivateMessageNotFoundException

getMessageCount

int getMessageCount(long userID)
                    throws UnauthorizedException,
                           UserNotFoundException

Returns the total number of private messages a user has in their mailbox. This calculation does not count any messages in the user's Trash folder.

Parameters:

userID - of the user.

Returns:

the total number of private messages the user has.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

getMessageCountForFolder

int getMessageCountForFolder(long userID,
                             int folderID)
                             throws UnauthorizedException,
                                    UserNotFoundException,
                                    com.jivesoftware.community.PrivateMessageFolderNotFoundException

Returns the message count on a specific folder.

Parameters:

userID - of the user

folderID - the folder id

Returns:

the message count on a specific folder.

Throws:

UnauthorizedException - if not an administrator or the user

UserNotFoundException - if the user could not be found

com.jivesoftware.community.PrivateMessageFolderNotFoundException

getUnreadMessageCount

int getUnreadMessageCount(long userID)
                          throws UnauthorizedException,
                                 UserNotFoundException

Returns the total number of unread private messages a user has in their mailbox. This calculation does not count any messages in the user's Trash folder.

Parameters:

userID - of the user.

Returns:

the total number of unread private messages the user has.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

getUnreadMessageCountForFolder

int getUnreadMessageCountForFolder(long userID,
                                   int folderID)
                                   throws UnauthorizedException,
                                          UserNotFoundException,
                                          com.jivesoftware.community.PrivateMessageFolderNotFoundException

Returns the total number of unread private messages a user has in a specific folder.

Parameters:

userID - of the user

folderID - the folder id

Returns:

the total number of unread private messages a user has in a specific folder.

Throws:

UnauthorizedException - if not an administrator or the user

UserNotFoundException - if the user could not be found

com.jivesoftware.community.PrivateMessageFolderNotFoundException

getFolders

PrivateMessageFolder[] getFolders(long userID)
                                  throws UnauthorizedException,
                                         UserNotFoundException

Returns an Iterator of PrivateMessageFolder objects for the folders the user has. The four built-in folders (Inbox, Sent, Drafts, Trash) are returned first, followed by custom folders in alphabetical order.

Parameters:

userID - of the user.

Returns:

the an Iterator for the user's folders.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

getFolder

PrivateMessageFolder getFolder(long userID,
                               int folderID)
                               throws com.jivesoftware.community.PrivateMessageFolderNotFoundException,
                                      UnauthorizedException,
                                      UserNotFoundException

Returns the specified folder for a user.

Parameters:

userID - of the user.

folderID - the folder ID.

Returns:

the user's folder.

Throws:

com.jivesoftware.community.PrivateMessageFolderNotFoundException - if the folder could not be loaded.

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

createFolder

PrivateMessageFolder createFolder(long userID,
                                  java.lang.String name)
                                  throws UnauthorizedException,
                                         UserNotFoundException

Creates a new folder.

Parameters:

userID - of the user to create the folder for.

name - the name of the folder.

Returns:

the new folder.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

deleteFolder

void deleteFolder(long userID,
                  int folderID)
                  throws UnauthorizedException,
                         UserNotFoundException,
                         com.jivesoftware.community.PrivateMessageFolderNotFoundException

Deletes a folder. All messages in the folder will be moved to the user's Trash folder. Attempting to delete one of the four default folders will move all messages in the folder to Trash but won't delete the folder itself. If the folder is the Trash folder, all messages in the folder will be permanently deleted.

Parameters:

userID - of the folder to associate

folderID - of the folder to delete.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

com.jivesoftware.community.PrivateMessageFolderNotFoundException

getMessage

PrivateMessage getMessage(long privateMessageID)
                          throws UnauthorizedException,
                                 com.jivesoftware.community.PrivateMessageNotFoundException

Returns the specified private message.

Parameters:

privateMessageID - the ID of the private message.

Throws:

UnauthorizedException - if not an administrator or the user.

com.jivesoftware.community.PrivateMessageNotFoundException - if the message could not be loaded.

createMessage

PrivateMessage createMessage(long senderID)
                             throws UnauthorizedException,
                                    UserNotFoundException

Creates a new private message. The message must be either saved as a draft or sent to another user in order to be stored permanently.

Parameters:

senderID - of the user sending the message.

Returns:

a new message.

Throws:

UnauthorizedException - if not an administrator or the user.

UserNotFoundException

saveMessageAsDraft

void saveMessageAsDraft(PrivateMessage privateMessage)
                        throws UnauthorizedException,
                               com.jivesoftware.community.PrivateMessageRejectedException,
                               UserNotFoundException

Saves a message as a draft by storing it in the sender's Drafts folder.

Parameters:

privateMessage - the private message to save as a draft

Throws:

UnauthorizedException - if not an administrator or the user.

com.jivesoftware.community.PrivateMessageRejectedException - if the private message was rejected

UserNotFoundException - if the user could not be found

sendMessage

void sendMessage(PrivateMessage privateMessage,
                 long recipientID,
                 boolean copyToSentFolder)
                 throws UnauthorizedException,
                        com.jivesoftware.community.PrivateMessageRejectedException,
                        UserNotFoundException

Sends a private message to another user. The message will be delivered to the recipient's Inbox. Optionally, a copy of the message will be put in the sender's Sent folder.

If the recipient's mailbox is full, a PrivateMessageRejectedException will be thrown. The exception will also be thrown if the recipient is not allowed to receive private messages or if the user has elected to save a copy of the message in their Sent folder, but doesn't have room to do so.

Parameters:

privateMessage - the message to send.

recipientID - of the user to send the message to.

copyToSentFolder - true if the message should be copied to the Sent folder.

Throws:

UnauthorizedException - if not allowed to send the message.

com.jivesoftware.community.PrivateMessageRejectedException - if the message could not be delivered.

UserNotFoundException