com.jivesoftware.community
Interface PrivateMessage

All Superinterfaces:

JiveObject

public interface PrivateMessage
extends JiveObject

Private messages are used for user to user communication.

See Also:

PrivateMessageFolder, PrivateMessageManager

Method Summary

Attachment	createAttachment(java.lang.String name, java.lang.String contentType, java.io.InputStream data) Creates a new attachment for this private message.
void	deleteAttachment(Attachment attachment) Deletes an attachment that belongs to this private message.
int	getAttachmentCount() Returns the number of attachments this private message has.
JiveIterator<Attachment>	getAttachments() Returns an Iterable for all attachments of this private message.
java.lang.String	getBody() Returns the message body.
java.util.Date	getDate() Returns the date the message was saved or sent, or null if the message hasn't been sent or saved yet.
PrivateMessageFolder	getFolder() Returns the folder the private message or null if the message does not yet belong to a folder.
long	getID() Returns the id of the message.
java.util.Map<java.lang.String,java.lang.String>	getProperties() Retrieve a map of all the extended properties for the private message.
User	getRecipient() Returns the user the message was sent to.
User	getSender() Returns the user the message was sent by, or null if the message was sent by the system.
java.lang.String	getSubject() Returns the message subject.
java.lang.String	getUnfilteredBody() Returns the message body, bypassing any active filters.
java.lang.String	getUnfilteredProperty(java.lang.String name) Returns an extended property of the private message, bypassing any filters.
java.lang.String	getUnfilteredSubject() Returns the message subject, bypassing any active filters.
boolean	isAuthorized(long permissionType) Returns true if the handle on this object has the permission specified.
boolean	isRead() Returns true if this message has been marked as read.
void	setBody(java.lang.String body) Sets the body of the message.
void	setRead(boolean read) Marks this message as read or unread.
void	setSubject(java.lang.String subject) Sets the subject of the message.

Methods inherited from interface com.jivesoftware.community.JiveObject

getObjectType

Method Detail

getID

long getID()

Returns the id of the message.

Specified by:

getID in interface JiveObject

Returns:

the unique id of the message.

getDate

java.util.Date getDate()

Returns the date the message was saved or sent, or null if the message hasn't been sent or saved yet.

Returns:

the date the message was sent or saaved, or null if not yet sent.

getFolder

PrivateMessageFolder getFolder()

Returns the folder the private message or null if the message does not yet belong to a folder.

Returns:

the folder the message belongs to.

getSubject

java.lang.String getSubject()

Returns the message subject. If message filters are active, the subject returned will be a filtered one. Because filters often provide security functionality, this method is the preferred way to get the subject of a message.

Returns:

the subject of the message.

getUnfilteredSubject

java.lang.String getUnfilteredSubject()

Returns the message subject, bypassing any active filters. Because filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving Jive content to another persistence mechanism such as an XML format. Another is when you need to skip filter formatting, such as when a user is responding to another user's message.

Returns:

the subject of the message.

setSubject

void setSubject(java.lang.String subject)
                throws UnauthorizedException

Sets the subject of the message.

Parameters:

subject - the subject of the message.

Throws:

UnauthorizedException - if not allowed to edit the message.

getBody

java.lang.String getBody()

Returns the message body. If message filters are active, the body returned will be a filtered one. Because filters often provide security functionality such as stripping out HTML and Javascript, this method is the preferred way to get the body of a message.

Returns:

the body of the message.

getUnfilteredBody

java.lang.String getUnfilteredBody()

Returns the message body, bypassing any active filters. Because filters often provide security, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Unfiltered content is necessary for a few reasons. One is when saving Jive content to another persistence mechanism such as an XML format. Another is when you need to skip filter formatting, such as when a user is responding to another user's message.

Returns:

the body of the message.

setBody

void setBody(java.lang.String body)
             throws UnauthorizedException

Sets the body of the message.

Parameters:

body - the body of the message.

Throws:

UnauthorizedException - if does not have ADMIN permissions.

getSender

User getSender()

Returns the user the message was sent by, or null if the message was sent by the system.

Returns:

the user that sent the message.

getRecipient

User getRecipient()

Returns the user the message was sent to.

Returns:

the user the message was sent to.

isRead

boolean isRead()

Returns true if this message has been marked as read.

Returns:

true if the message is read.

setRead

void setRead(boolean read)

Marks this message as read or unread.

Parameters:

read - true to mark the message as read.

createAttachment

Attachment createAttachment(java.lang.String name,
                            java.lang.String contentType,
                            java.io.InputStream data)
                            throws java.lang.IllegalStateException,
                                   AttachmentException,
                                   UnauthorizedException

Creates a new attachment for this private message. Each attachment has a name, content type and binary data. Rules about who can create attachments and what kind attachments are allowed are controlled via an AttachmentManager.

Parameters:

name - the name of the new attachment, usually the file name.

contentType - the content type of the attachment.

data - an InputStream that contains the binary data of the attachment. The stream will never be closed so you must close it manually after calling this method.

Returns:

an Attachment object representing the new attachment created.

Throws:

AttachmentException - if an error occured while creating the attachment. Errors can occur because the attachment is too large or because the private message already has too many attachments.

UnauthorizedException - if not allowed to create attachments.

java.lang.IllegalStateException

See Also:

Attachment, AttachmentManager

getAttachmentCount

int getAttachmentCount()

Returns the number of attachments this private message has.

Returns:

the number of attachments this private message has.

getAttachments

JiveIterator<Attachment> getAttachments()

Returns an Iterable for all attachments of this private message.

Returns:

an Iterable for the message's attachments.

See Also:

Attachment

deleteAttachment

void deleteAttachment(Attachment attachment)
                      throws AttachmentException,
                             UnauthorizedException

Deletes an attachment that belongs to this private message. Only administrators or the creator of this message are allowed to call this method.

Parameters:

attachment - the attachment to delete.

Throws:

java.lang.IllegalArgumentException - if the attachment doesn't belong to this message.

UnauthorizedException - if not authorized to delete the attachment.

AttachmentException - if there was an error deleting the attachment.

getProperties

java.util.Map<java.lang.String,java.lang.String> getProperties()

Retrieve a map of all the extended properties for the private message. Each private message can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface. The map is alterable if the user is authorized to modify the message. Null keys and values are not allowed.

If the user is not authorized to modify the private message any method which modifies the map will fail with a UnsupportedOperationException;

Returns:

a map of private message extended properties.

getUnfilteredProperty

java.lang.String getUnfilteredProperty(java.lang.String name)

Returns an extended property of the private message, bypassing any filters. Each private message can have an arbitrary number of extended properties. This allows for enhanced functionality that is not part of the base interface.

Because properties are not filtered before being returned, this method should be used with caution. In particular, you should avoid showing unfiltered data in an environment where embedded HTML might be interpreted.

Parameters:

name - the name of the property to get.

Returns:

the value of the property.

isAuthorized

boolean isAuthorized(long permissionType)

Returns true if the handle on this object has the permission specified. For example, if a community administrator has a handle on this object, then calling isAuthorized(Permissions.COMMUNITY_ADMIN) 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.

See Also:

Permissions