Jive Forums API (5.5.20.2-oracle) Developer Javadocs

com.jivesoftware.forum
Interface PrivateMessage

All Known Implementing Classes:
DbPrivateMessage, PrivateMessageProxy

public interface PrivateMessage

Private messages are used for user to user communication.

Since:
4.0
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.
 void deleteProperty(java.lang.String name)
          Deletes an extended property.
 int getAttachmentCount()
          Returns the number of attachments this private message has.
 java.util.Iterator getAttachments()
          Returns an Iterator 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.Collection getProperties(java.lang.String parentName)
          Return all immediate children property values of a parent property as an unmodifiable Collection of String values.
 java.lang.String getProperty(java.lang.String name)
          Returns an extended property of this private message.
 java.util.Iterator getPropertyNames()
          Returns an Iterator of String values for all the names of the message properties.
 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 this 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 setProperty(java.lang.String name, java.lang.String value)
          Sets an extended property of this private message.
 void setRead(boolean read)
          Marks this message as read or unread.
 void setSubject(java.lang.String subject)
          Sets the subject of the message.
 

Method Detail

getID

long getID()
Returns the id of the message.

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

java.util.Iterator getAttachments()
Returns an Iterator for all attachments of this private message.

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

getProperty

java.lang.String getProperty(java.lang.String name)
Returns an extended property of this private message. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide enhanced functionality that is not part of the base interface.

For security reasons, you should enable an HTML filter in case properties contain malicious HTML code.

Parameters:
name - the name of the property to get.
Returns:
the value of the property.

getProperties

java.util.Collection getProperties(java.lang.String parentName)
Return all immediate children property values of a parent property as an unmodifiable Collection of String values. A parent/child relationship is denoted by the "." character. For example, given the properties X.Y.A, X.Y.B, X.Y.C and X.Y.C.D, then the immediate child properties of X.Y are X.Y.A, X.Y.B, and X.Y.C (the value of X.Y.C.D would not be returned using this method).

Parameters:
parentName - the name of the parent property to return the children for.
Returns:
all Collection of all child property values for the given parent.

getUnfilteredProperty

java.lang.String getUnfilteredProperty(java.lang.String name)
Returns an extended property of this private message, bypassing any filters. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide 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.

setProperty

void setProperty(java.lang.String name,
                 java.lang.String value)
                 throws UnauthorizedException
Sets an extended property of this private message. Each message can have an arbitrary number of extended properties. This lets particular skins or filters provide enhanced functionality that is not part of the base interface.

Parameters:
name - the name of the property to set.
value - the new value for the property.
Throws:
UnauthorizedException - if not allowed to edit the message.

deleteProperty

void deleteProperty(java.lang.String name)
                    throws UnauthorizedException
Deletes an extended property. If the property specified by name does not exist, this method will do nothing.

Parameters:
name - the name of the property to delete.
Throws:
UnauthorizedException - if not allowed to edit the message.

getPropertyNames

java.util.Iterator getPropertyNames()
Returns an Iterator of String values for all the names of the message properties.

Returns:
an Iterator for the names of all message properties.

isAuthorized

boolean isAuthorized(long permissionType)
Returns true if the handle on this object has the permission specified. For example, if a forum administrator has a handle on this object, then calling isAuthorized(ForumPermissions.FORUM_ADMIN) would return true.

A list of possible permissions can be found in the ForumPermissions 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:
ForumPermissions

Jive Forums Project Page

Copyright © 1999-2006 Jive Software.