com.plumtree.remote.prc.collaboration.discussion
Interface IDiscussion

public interface IDiscussion

Interface that represents a Collaboration discussion object. A discussion contains zero or more messages and reply messages. This interface handles creation of messages, modifications of discussion metadata and security.
Note: Any modifications made to a discussion will not be stored permanently until the store method is called.

Method Summary

void	addModerator(int userID) Adds a user to the discussion moderator list.
IDiscussionMessage	createDiscussionMessage(java.lang.String subject, java.lang.String body) Creates and returns a discussion message.
AccessLevel	getAccessLevel(RoleType roleType) Returns the object access level for a given role type.
IProject	getContainingProject() Returns the project that this object belongs to.
java.util.Date	getCreatedDate() Returns the creation date.
java.lang.String	getDescription() Returns the discussion description.
java.lang.String	getDetailsURL() Returns the URL at which the discussion details can be viewed.
java.lang.String	getEmailAddress() Returns the discussion email address.
int	getID() Returns the discussion ID.
java.util.Date	getLastModifiedDate() Returns the last modified date; the last modified date will also get updated whenever a new discussion message is created in this discussion.
int[]	getModeratorIDs() Returns an integer array of IDs of the current discussion's moderators.
java.lang.String	getName() Returns the discussion name as a String.
IObjectReference[]	getObjectReferences() Returns an array of IObjectReference.
int	getOwnerUserID() Returns the user ID of the owner of this object.
boolean	hasCreatedDate() Returns true if created date is available, otherwise false.
boolean	hasLastModifiedDate() Returns true if last modified date is available, otherwise false.
boolean	isActionAllowed(DiscussionPermission permission) Returns true if a given DiscussionPermission is allowed for this discussion.
boolean	isDefaultSecurity() Indicates if this object uses project-default security.
void	removeDiscussionMessage(IDiscussionMessage message) Removes a discussion message and all its replies.
void	removeModerator(int userID) Removes a user from the discussion moderator list.
void	setAccessLevel(RoleType roleType, AccessLevel accessLevel) Sets the object access level for a given role type.
void	setDefaultSecurity(boolean isDefaultSecurity) Enables or disables this object's use of project default security.
void	setDescription(java.lang.String description) Sets the discussion description.
void	setName(java.lang.String name) Sets the discussion name.
void	store() Stores the discussion.

Method Detail

addModerator

public void addModerator(int userID)

Adds a user to the discussion moderator list. The added ID will not be validated; adding an invalid, non-negative ID will both be acceptable and retrievable upon calling getModeratorIDs. The user who creates a discussion is not added automatically as its moderator.

Parameters:

userID - the user ID; must be positive

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

java.lang.IllegalArgumentException - if the user ID is not positive

createDiscussionMessage

public IDiscussionMessage createDiscussionMessage(java.lang.String subject,
                                                  java.lang.String body)

Creates and returns a discussion message. Note: This newly created discussion message will not be persistent until store method is called on the new message. This method is only used for creating topic messages (non-reply messages). To create reply messages, use IDiscussionMessage.createDiscussionReplyMessage

 //Sample code below shows how to create a discussion message in a discussion.
 IDiscussionMessage message = discussion.createDiscussionMessage("Sample Message Subject", "Sample Message Body");

 //sets optional message properties
 message.setApproved(true);
 message.setDescription("Option description for discussion message");

 //store() needs to be called to persist the message.
 message.store();
 

Parameters:

subject - the message subject; cannot be null

body - the message body, cannot be null

Returns:

the discussion message

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

getAccessLevel

public AccessLevel getAccessLevel(RoleType roleType)

Returns the object access level for a given role type.

Parameters:

roleType - the role type; cannot be null

Returns:

the object access level for the given role type

Throws:

java.lang.IllegalStateException - if the object has already been removed

getContainingProject

public IProject getContainingProject()
                              throws CollaborationException,
                                     java.rmi.RemoteException

Returns the project that this object belongs to.

Returns:

the project that this object belongs to

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the object has already been removed

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getCreatedDate

public java.util.Date getCreatedDate()

Returns the creation date.

Returns:

the creation date.

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed.

getDescription

public java.lang.String getDescription()

Returns the discussion description.

Returns:

the discussion description

Throws:

java.lang.IllegalStateException - if the object has already been removed

getDetailsURL

public java.lang.String getDetailsURL()

Returns the URL at which the discussion details can be viewed.

Note: This URL is gatewayed using the Collaboration server's primary portal.

Returns:

the discussion details URL

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

getEmailAddress

public java.lang.String getEmailAddress()

Returns the discussion email address. The discussion email address is used for posting messages to the discussion. This is the same value as "Discussion email" in discussion properties.

Returns:

the discussion address, or null if email support has not been enabled for Collaboration

Throws:

java.lang.IllegalStateException - if the object has already been removed

getID

public int getID()

Returns the discussion ID.

Returns:

the discussion ID.

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

getLastModifiedDate

public java.util.Date getLastModifiedDate()

Returns the last modified date; the last modified date will also get updated whenever a new discussion message is created in this discussion.

Returns:

the last modified date

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

getModeratorIDs

public int[] getModeratorIDs()

Returns an integer array of IDs of the current discussion's moderators. The user who creates a discussion is not added automatically as its moderator.

Returns:

an integer array of IDs of the moderators for this discussion

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

getName

public java.lang.String getName()

Returns the discussion name as a String.

Returns:

the discussion name.

Throws:

java.lang.IllegalStateException - if the object has already been removed

getObjectReferences

public IObjectReference[] getObjectReferences()
                                       throws CollaborationException,
                                              java.rmi.RemoteException

Returns an array of IObjectReference. For discussions, object references are attached task lists or documents.

Returns:

an array of IObjectReference for the current discussion

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the document has not yet been inserted or has already been removed, or if the version number does not exist.

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

getOwnerUserID

public int getOwnerUserID()

Returns the user ID of the owner of this object. The owner of an object is the user who creates the object.

Returns:

the owner ID.

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed.

hasCreatedDate

public boolean hasCreatedDate()

Returns true if created date is available, otherwise false.

Returns:

true if created date is available, else false

Throws:

java.lang.IllegalStateException - if the object has already been removed

hasLastModifiedDate

public boolean hasLastModifiedDate()

Returns true if last modified date is available, otherwise false.

Returns:

true if last modified date is available, else false

Throws:

java.lang.IllegalStateException - if the object has already been removed

isActionAllowed

public boolean isActionAllowed(DiscussionPermission permission)
                        throws CollaborationException,
                               java.rmi.RemoteException

Returns true if a given DiscussionPermission is allowed for this discussion. This method can be used to determine if a user can perform a given action within the context of a discussion such as editing, copying, and modifying security, etc. See the enumeration type DiscussionPermission for details about specific discussion permissions

Parameters:

permission - discussion permission; cannot be null

Returns:

true if the user can perform the given action, else false

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

CollaborationException - if the method call resulted in an error

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

isDefaultSecurity

public boolean isDefaultSecurity()

Indicates if this object uses project-default security. If true, trying to modify security on the current object alone will not have any effect. setDefaultSecurity must be set to false in order to modify an individual object's security. Default value for isDefaultSecurity is true.

Returns:

true if the object uses project-default security, and false if the object is enabled to use its own security, ( setDefaultSecurity is set to false).

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

removeDiscussionMessage

public void removeDiscussionMessage(IDiscussionMessage message)
                             throws CollaborationException,
                                    java.rmi.RemoteException

Removes a discussion message and all its replies.

Parameters:

message - the discussion message to remove; cannot be null

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call

removeModerator

public void removeModerator(int userID)

Removes a user from the discussion moderator list. Ignored if no user exists with the given ID.

Parameters:

userID - the user ID to remove; must be positive

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

java.lang.IllegalArgumentException - if the userID is not positive

setAccessLevel

public void setAccessLevel(RoleType roleType,
                           AccessLevel accessLevel)

Sets the object access level for a given role type. Any security change on the discussion will be automatically applied to the discussion messages in this discussion.

Parameters:

roleType - the role type for which access level will be set; cannot be null

accessLevel - the access level; cannot be null

Throws:

java.lang.IllegalStateException - if project default security is used; call setDefaultSecurity(false) prior to modifying the object access level

setDefaultSecurity

public void setDefaultSecurity(boolean isDefaultSecurity)

Enables or disables this object's use of project default security. Calling this method with true will enable default security, calling it with false will disable default security.
By default all objects are created with default security set to true. To modify security on individual objects in a project, the objects must have default security disabled prior to modification. After this method is called, any project-level security modification will not be applied to the objects, and only the individual object's security modification will be used.
This method can be used in conjunction with the isDefaultSecurity method, which would indicate whether or not the current object has default security enabled.

Parameters:

isDefaultSecurity - true if it uses default security, otherwise false

Throws:

java.lang.IllegalStateException - if the object has not yet been stored or has already been removed

setDescription

public void setDescription(java.lang.String description)

Sets the discussion description.

Parameters:

description - the discussion description

Throws:

java.lang.IllegalStateException - if the object has already been removed

setName

public void setName(java.lang.String name)

Sets the discussion name.

Parameters:

name - the discussion name

Throws:

java.lang.IllegalStateException - if the object has already been removed

store

public void store()
           throws CollaborationException,
                  java.rmi.RemoteException

Stores the discussion. Any modifications made to discussion will not be stored permanently until this method is called. Can be used to persist a newly created discussion, or edit an existing discussion.

Throws:

CollaborationException - if the method call resulted in an error

java.lang.IllegalStateException - if the object has already been removed

java.rmi.RemoteException - if there was a communication problem during the execution of the remote method call