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

public interface IDiscussionManager

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 zero or more 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 with the given ID.
IDiscussionMessage	getDiscussionMessage(int messageID) Returns a discussion message with the given ID.
IDiscussionMessage[]	getDiscussionMessages(int messageID) Returns child messages of the message with the given 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 IDiscussionMessages that represent zero or more discussion messages in a discussion, satisfying the given discussion message filter.
IDiscussionMessage[]	queryDiscussionMessages(IProject project, IDiscussionMessageFilter filter) Returns an array of IDiscussionMessages the represent zero or more discussion messages in a given project, satisfying the discussion message filter criteria provided.
IDiscussion[]	queryDiscussions(IProject project, IDiscussionFilter discussionfilter) Returns an array of IDiscussions that represent 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) Subscribes users with the given IDs to the given discussion and all discussion posts within that discussion.
void	unsubscribeUsers(IDiscussion discussion, int[] userIDs) Unsubscribes users with 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 - the parent project; cannot be null

name - the name of the discussion; cannot be null

description - the description of the discussion; cannot be null

Returns:

a discussion that has not been persisted yet (you must call store to save the new discussion)

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 ALL; DiscussionMessageModeratorFilterType is set to 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 with the given ID.

Parameters:

discussionID - the 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 was 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 with the given ID.

Parameters:

messageID - the 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 message ID is not > 0

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

getDiscussionMessages

public IDiscussionMessage[] getDiscussionMessages(int messageID)
                                           throws CollaborationException,
                                                  java.rmi.RemoteException

Returns child messages of the message with the given ID. The child documents will be returned in an undefined order; no effort is made to nest children of children.

Parameters:

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

Returns:

the discussion messages or a zero-length array if there are no children, 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 message ID is not > 0

java.rmi.RemoteException - if there was 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 to query; 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 - if the method resulted in an error

java.rmi.RemoteException - if there was 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 IDiscussionMessages the represent zero or more discussion messages in a given project, satisfying the discussion message filter criteria provided.

 //The following sample code shows how to query for discussion messages 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 - the 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 provided

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 was 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 IDiscussionMessages that represent zero or more discussion messages in a discussion, satisfying the given discussion message filter.

 //The following sample code shows how to query for discussion messages 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; 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 was 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 IDiscussions that represent 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 represent 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 was 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 was 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

Subscribes users with 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 valid users supplied. 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 user IDs is not > 0

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

unsubscribeUsers

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

Unsubscribes users with the given IDs from a discussion, including all the posts within the discussion. Invalid non-negative IDs or IDs that do not describe 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 - if the method resulted in an error

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

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