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

public interface IDiscussion

An IDiscussion 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 that all operations modifying the discussion will not be stored permanently until 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 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.
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 int array of ids of the current discussion's moderators.
java.lang.String	getName() Returns the discussion name.
int	getOwnerUserID() Returns the user ID of the owner of this object.
boolean	hasCreatedDate() Returns true if created date is available, else false.
boolean	hasLastModifiedDate() Returns true if last modified date is available, else false.
boolean	isActionAllowed(DiscussionPermission permission) Returns 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) Set 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, ie. 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 userID is not positive.

createDiscussionMessage

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

Creates and returns a discussion message. Note that 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

 //Below sample code 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 object access level for a given role type.

Parameters:

roleType - the role type; cannot be null.

Returns:

object access level for a 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 is 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.

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 int array of ids of the current discussion's moderators. The user who creates a discussion is not added automatically as its moderator.

Returns:

ids of the discussion moderators.

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.

Returns:

the discussion name.

Throws:

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

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, else 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, else 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 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 is 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 individual object's security. Default value for isDefaultSecurity is true.

Returns:

true if the object uses project-default security, false if the object is enabled to use its own security, ie. 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 is 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)

Set 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 modify 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 defaultSecurity, calling it with false will disable defaultSecurity.
By default all objects are created with defaultSecurity set to true. To modify security on individual objects in a project, the objects must have defaultSecurity disabled prior to modification. After this method is called, any project-level security modification will not be applied to the objects, and only individual object's security modification will be used.
This method might be used in conjunction with isDefaultSecurity , which would indicate if 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 modification of the discussion will not be stored permanently until this method is called. Can be used to persist a newly created discussion, or edit an exising 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 is a communication problem during the execution of the remote method call.