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

public interface IDiscussionManager

IDiscussionManager is an interface for discussion-related functionality. It handles discussion message creation, deletion and query.

A discussion contains zero or more messages. A Message is the smallest unit in a discussion and contains zero or one parent message and replies. A child of a message is a reply.

See Discussion Examples.

Method Summary

IDiscussion	createDiscussion(IProject project, java.lang.String name, java.lang.String description) Returns a new IDiscussion object in the given project.
IDiscussionFilter	createDiscussionFilter() Returns a discussion filter object that shows all discussions.
IDiscussionMessageFilter	createDiscussionMessageFilter() Returns a discussion message filter for narrowing query results.
IDiscussion	getDiscussion(int discussionID) Returns a discussion by the given ID.
IDiscussionMessage	getDiscussionMessage(int messageID) Returns a discussion message by its ID.
int[]	getSubscribedUserIDs(IDiscussion discussion) Returns the ids of the users who are subscribed to the given discussion.
IDiscussionMessage[]	queryDiscussionMessages(IDiscussion discussion, IDiscussionMessageFilter messageFilter) Returns an array of IDiscussionMessage containing zero or more discussion messages in a discussion, satisfying the given discussion message filter.
IDiscussionMessage[]	queryDiscussionMessages(IProject project, IDiscussionMessageFilter filter) Returns an array of IDiscussionMessage containing zero or more discussion messages in a given project, satisfying the discussion message filter criteria.
IDiscussion[]	queryDiscussions(IProject project, IDiscussionFilter discussionfilter) Returns an array of IDiscussion that contains discussions within the given project; the returned results will be sorted according to the given IFilter.
void	removeDiscussion(IDiscussion discussion) Removes the given discussion.
void	subscribeUsers(IDiscussion discussion, int[] userIDs) Subscribe users of the given ids to the given discussion and all discussion posts within that discussion.
void	unsubscribeUsers(IDiscussion discussion, int[] userIDs) Unsubscribe users of the given ids from a discussion, including all the posts within the discussion.

Method Detail

createDiscussion

public IDiscussion createDiscussion(IProject project,
                                    java.lang.String name,
                                    java.lang.String description)

Returns a new IDiscussion object in the given project.

Parameters:

project - parent project; cannot be null.

name - name of the discussion; cannot be null.

description - description of the discussion; cannot be null.

Returns:

a discussion that has not been persisted yet, need to call sotre to persist.

Throws:

CollaborationException - if the method call resulted in an error.

createDiscussionFilter

public IDiscussionFilter createDiscussionFilter()

Returns a discussion filter object that shows all discussions. The discussion filter is created with the following defaults: MaximumResult is unlimited, DefaultSecurity is set to false. No sortBy option or filter type is supported for querying discussion.

Returns:

the discussion filter object

createDiscussionMessageFilter

public IDiscussionMessageFilter createDiscussionMessageFilter()

Returns a discussion message filter for narrowing query results. The discussion message filter is set with the following defaults: DiscussionMessageStatusFilterType is set to DiscussionMessageStatusFilterType.ALL; DiscussionMessageModeratorFilterType is set to DiscussionMessageModeratorFilterType.ALL; DiscussionMessageQueryOrders is set to an array of one element with an attribute of DiscussionMessageAttribute.PROJECT_NAME, ascending.

Returns:

the discussion message filter.

getDiscussion

public IDiscussion getDiscussion(int discussionID)
                          throws CollaborationException,
                                 java.rmi.RemoteException

Returns a discussion by the given ID.

Parameters:

discussionID - ID of the discussion; must be positive. The ID of an object can be obtained using the getID method in the object class.

Returns:

the discussion or null if the discussion does not exist, or the user does not have the rights to see the discussion.

Throws:

CollaborationException - if the method call resulted in an error.

java.lang.IllegalArgumentException - if the discussion ID is not > 0.

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

getDiscussionMessage

public IDiscussionMessage getDiscussionMessage(int messageID)
                                        throws CollaborationException,
                                               java.rmi.RemoteException

Returns a discussion message by its ID.

Parameters:

messageID - id of the message; must be positive. The ID of an object can be obtained using the getID method in the object class.

Returns:

the discussion message or null if it does not exist, or the user does not have the rights to see the object.

Throws:

CollaborationException - if the method call resulted in an error.

java.lang.IllegalArgumentException - if the messageID is not > 0.

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

getSubscribedUserIDs

public int[] getSubscribedUserIDs(IDiscussion discussion)
                           throws CollaborationException,
                                  java.rmi.RemoteException

Returns the ids of the users who are subscribed to the given discussion.

Parameters:

discussion - the discussion; cannot be null.

Returns:

the ids of the users who are subscribed to the discussion.

Throws:

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

CollaborationException - it the method resulted in an error.

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

queryDiscussionMessages

public IDiscussionMessage[] queryDiscussionMessages(IProject project,
                                                    IDiscussionMessageFilter filter)
                                             throws CollaborationException,
                                                    java.rmi.RemoteException

Returns an array of IDiscussionMessage containing zero or more discussion messages in a given project, satisfying the discussion message filter criteria.

 //The following sample code shows how to query for discussion messagess in a project.
 IDiscussionMessageFilter messageFilter = discussionManager.createDiscussionMessageFilter();
 
 //search for ALL messages; other options include searching for APPROVED, or UNAPPROVED messages
 messageFilter.setMessageStatusType(DiscussionMessageStatusFilterType.ALL);
 
 //limit the return results to be 10; setting this to 0 will return all results
 messageFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 messageFilter.setRestoreSecurity(false);
 
 //user DiscussionMessageQueryOrder to sort the query result; below DiscussionMessageQueryOrder
 //shows sorting the returned messages by CREATED date in descending order
 DiscussionMessageQueryOrder messageQueryOrder = new DiscussionMessageQueryOrder(DiscussionMessageAttribute.CREATED, false);
 messageFilter.setQueryOrders(new DiscussionMessageQueryOrder[] { messageQueryOrder });
 
 //an array of IDiscussionMessage objects are returned from queryDiscussionMessages(); if no result is retrieved, a zero-length array will be returned
 IDiscussionMessage[] retrievedMessages = discussionManager.queryDiscussionMessages(project, messageFilter);
 

Parameters:

project - project to query discussion messages; cannot be null.

filter - the discussion message query filter; cannot be null.

Returns:

an array of IDiscussionMessage containing zero or more discussion messages in a given discussion, satisfying the discussion message filter criteria.

Throws:

java.lang.IllegalStateException - if the project 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.

queryDiscussionMessages

public IDiscussionMessage[] queryDiscussionMessages(IDiscussion discussion,
                                                    IDiscussionMessageFilter messageFilter)
                                             throws CollaborationException,
                                                    java.rmi.RemoteException

Returns an array of IDiscussionMessage containing zero or more discussion messages in a discussion, satisfying the given discussion message filter.

 //The following sample code shows how to query for discussion messagess in a discussion.
 IDiscussionMessageFilter messageFilter = discussionManager.createDiscussionMessageFilter();
 
 //search for ALL messages; other options include searching for APPROVED, or UNAPPROVED messages
 messageFilter.setMessageStatusType(DiscussionMessageStatusFilterType.ALL);
 
 //limit the return results to be 10; setting this to 0 will return all results
 messageFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 messageFilter.setRestoreSecurity(false);
 
 //user DiscussionMessageQueryOrder to sort the query result; below DiscussionMessageQueryOrder
 //shows sorting the returned messages by CREATED date in descending order
 DiscussionMessageQueryOrder messageQueryOrder = new DiscussionMessageQueryOrder(DiscussionMessageAttribute.CREATED, false);
 messageFilter.setQueryOrders(new DiscussionMessageQueryOrder[] { messageQueryOrder });
 
 //an array of IDiscussionMessage objects are returned from queryDiscussionMessages(); if no result is retrieved, a zero-length array will be returned
 IDiscussionMessage[] retrievedMessages = discussionManager.queryDiscussionMessages(discussion, messageFilter);
 

Parameters:

discussion - the discussion to query from; cannot be null.

messageFilter - the discussion message query filter; cannot be null.

Returns:

an array of IDiscussionMessage containing zero or more discussion messages in a discussion, satisfying the given discussion message filter.

Throws:

java.lang.IllegalStateException - if the discussion 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.

queryDiscussions

public IDiscussion[] queryDiscussions(IProject project,
                                      IDiscussionFilter discussionfilter)
                               throws CollaborationException,
                                      java.rmi.RemoteException

Returns an array of IDiscussion that contains discussions within the given project; the returned results will be sorted according to the given IFilter.

 //The following sample code shows how to query for discussions, maximum results to return = 10.
 IDiscussionFilter discussionFilter = discussionManager.createDiscussionFilter();
 
 //limit the return results to be 10; setting this to 0 will return all results
 discussionFilter.setMaximumResults(10);
 
 //disable security checking on the returned objects against the user who performs this query,
 //so that all objects will be returned
 discussionFilter.setRestoreSecurity(false);
 
 //an array of IDiscussion are returned from queryDiscussions(); if no result is retrieved, a zero-length array will be returned
 IDiscussion[] retrievedDiscussions = discussionManager.queryDiscussions(project, discussionFilter);
 
 

Parameters:

project - the project; cannot be null.

discussionfilter - the filter specifying the sort fields and the sort order, and maximum number of rows to return; cannot be null.

Returns:

an array of IDiscussion that contains discussions within the given project.

Throws:

java.lang.IllegalStateException - if the project 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.

removeDiscussion

public void removeDiscussion(IDiscussion discussion)
                      throws CollaborationException,
                             java.rmi.RemoteException

Removes the given discussion.

Parameters:

discussion - the discussion to be removed; cannot be null.

Throws:

CollaborationException - if the method call resulted in an error.

java.lang.IllegalArgumentException - if the id of the discussion is not > 0.

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

subscribeUsers

public void subscribeUsers(IDiscussion discussion,
                           int[] userIDs)
                    throws CollaborationException,
                           MultipleObjectException,
                           java.rmi.RemoteException

Subscribe users of the given ids to the given discussion and all discussion posts within that discussion.

The calling user must have ADMIN access to the project containing this discussion, and the users to be subscribed have to have at least READ access to the discussion. The call will make a best attempt to subscribe all supplied, valid users. A MultipleObjectException will be thrown specifying the IDs that failed to be subscribed.

Parameters:

discussion - the discussion to subcribe users to; cannot be null.

userIDs - the ids of the users to subscribe; cannot be null; all IDs must be positive.

Throws:

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

MultipleObjectException - if any users cannot be subscribed.

CollaborationException - if the method call resulted in an error.

java.lang.IllegalArgumentException - if any of the userIDs is not > 0.

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

unsubscribeUsers

public void unsubscribeUsers(IDiscussion discussion,
                             int[] userIDs)
                      throws CollaborationException,
                             java.rmi.RemoteException

Unsubscribe users of the given ids from a discussion, including all the posts within the discussion. Invalid non-negative ids or ids that do not described subscribed users will be ignored.

Parameters:

discussion - the discussion to unsubcribe users from.

userIDs - the ids of the users to unsubscribe; cannot be null; all IDs must be positive.

Throws:

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

CollaborationException - it the method resulted in an error.

java.lang.IllegalArgumentException - if any of the userIDs is not > 0.

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