Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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.

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

For additional information on the IDK, including tutorials, blogs, code samples and more,see the AquaLogic User Interaction Developer Center on BEA dev2dev.

Copyright ©2007 BEA Systems, Inc. All Rights Reserved.