oracle.discussions.ws
Interface MyDiscussionsService

public interface MyDiscussionsService

Web services interface providing methods to access content of user's interest.

The interface exposes methods for users, to

• bookmark Discussions elements
• selectively access content of user's interest
• selectively access most popular/recent Discussions content
• search user's favorites

It also provides bulk methods to add/remove containers,topics to favorite listing.Axis specific Sample code illustrating the invocation/usage of MyDiscussionsService.Relevant changes are to be done, if a non-axis web services client is used.

 //Initialize the webservice locator.The locator contains information about webservices endpoint. 
 MyDiscussionsServiceServiceLocator mdssl = new MyDiscussionsServiceServiceLocator();
 //Retrieve a reference to the remote webservices interface.
 MyDiscussionsService mdsl = mdssl.getMyDiscussionsService();
 //Notify the axis server that client is interested in maintaining session.
 ((MyDiscussionsServiceSoapBindingStub)mdsl).setMaintainSession(true);
 //Set the cookie, retrieved during login service invocation.
 ((javax.xml.rpc.Stub)mdsl)._setProperty(HTTPConstants.HEADER_COOKIE,cookie);
 //Invoke the webservices method.
 AbstractContainer[] containers = mdsl.getFavoriteContainers();
 AbstractContainer aContainer = null;
 if(containers != null)
 {
 //Process the retrieved container listing.
 ........
 }
 

Method Summary

AddContainersToFavoritesBulkResponse[]	addContainersToFavorites(long[] lContainerIds) Adds an array of containers, represented by lContainerIds to the user's favorite listing.
AbstractContainer	addContainerToFavorites(long containerId) Adds the container specified by containerId, to the user's favorite listing.
AddTopicsToFavoritesBulkResponse[]	addTopicsToFavorites(long lForumId, int[] iTopicIds) Adds an array of topics, represented by iTopicIds to the user's favorite listing.
Topic	addTopicToFavorites(long lForumId, int iTopicId) Adds the topic specified by iTopicId to user's favorite listing.
Category[]	getFavoriteCategories() Returns the user's favorite category listing.
AbstractContainer[]	getFavoriteContainers() Returns the user's favorite container listing.
Forum[]	getFavoriteForums() Returns the user's favorite forum listing.
Topic[]	getFavoritePopularTopics() Returns the most popular topics, in the user's favorite topic listing.
ForumMessage[]	getFavoriteRecentPosts() Returns the topics with most recently posted messages, in the user's favorite listing.
ForumMessage[]	getMyPosts() Returns all the messages posted by the user.
ForumMessage[]	getPopularMyPosts() Returns the most popular messages, among all the messages posted by the user.
ForumMessage[]	getPopularRepliesToMyPosts() Returns the most popular messages among the replies to user's posts.
Topic[]	getPopularTopics(long lContainerId) Returns the most popular topics, among all the topics in the container represented by lContainerId.
ForumMessage[]	getRecentMyPosts() Returns the most recently posted messages, among all messages posted by the user.
ForumMessage[]	getRecentPosts(long lContainerId) Returns the most recently posted messages in the container specified by lContainerId.
ForumMessage[]	getRecentRepliesToMyPosts() Returns the most recent messages, among the replies to user's posts.
ForumMessage[]	getRepliesToMyPosts() Returns the messages posted by the user, to which other users have replied.
Topic[]	listAllFavoriteTopics() Returns the listing of user's favorite topics in entire Discussions system.
Topic[]	listFavoriteTopics(long lContainerId) Returns the listing of user's favorite topics in the container specified by lContainerId.
void	removeContainerFromFavorites(long lContainerId) Removes the container specified by containerId, from the user's favorite listing.
DeleteElementBulkResponse[]	removeContainersFromFavorites(long[] lContainerIds) Deletes the containers specified by lContainerIds.
void	removeTopicFromFavorites(long lForumId, int iTopicId) Removes the topic specified by iTopicId from user's favorite listing.
DeleteElementBulkResponse[]	removeTopicsFromFavorites(long lForumId, int[] iTopicIds) Deletes the topics specified by iTopicIds.
ForumMessage[]	search(SearchTerm st) Searches user's favorite containers for the search criterion specified in the search term.

Method Detail

addContainerToFavorites

public AbstractContainer addContainerToFavorites(long containerId)
                                          throws TdWSException

Adds the container specified by containerId, to the user's favorite listing.

A bean representing the container added to favorites is returned to the user.
If a favorite container is again added to favorites, the method just returns the bean, corresponding to the container. The Discussions root container cannot be added/removed from user's favorites listing.

Parameters:

containerId - - Id representing the container to be added to favorites.

Returns:

AbstractContainer - Bean representing the contanier added to favorites.

Throws:

TdWSException - - Thrown on

• any exception in adding the container to favorites
• if containerId does not represent a valid container
• if the user doesnot have access to the contanier

removeContainerFromFavorites

public void removeContainerFromFavorites(long lContainerId)
                                  throws TdWSException

Removes the container specified by containerId, from the user's favorite listing.

If a non-favorite container is removed from favorites, the method just returns. The Discussions root container cannot be added/removed from user's favorites listing.

Parameters:

lContainerId - - Id representing the container to be added to favorites.

Throws:

TdWSException - - Thrown on

• any exception in removing the container from favorites
• if containerId does not represent a valid container
• if the user doesnot have access to the contanier

getFavoriteContainers

public AbstractContainer[] getFavoriteContainers()
                                          throws TdWSException

Returns the user's favorite container listing.

Returns null, if there are no containers in the user's favorite list. The containers returned can include forums and categories as well.
ContainerType attribute/isCategoryType() method of AbstractContainer bean can be used to distinguish between a category and forum.

Returns:

AbstractContainer[] - An array of abstract container beans, representing the user's favorite container listing.

Throws:

TdWSException - - Thrown on any exception in retrieving the favorite container listing.

getFavoriteCategories

public Category[] getFavoriteCategories()
                                 throws TdWSException

Returns the user's favorite category listing.

Similar to getFavoriteContainers() method, but this method returns only favorite categories.
Returns null, if there are no categories in the user's favorite list. ContainerType attribute/isCategoryType() method of Category bean can be used to check if the container returned is a category.

Returns:

Category[] - An array of category beans, representing the user's favorite category listing.

Throws:

TdWSException - - Thrown on any exception in retrieving the favorite category listing.

getFavoriteForums

public Forum[] getFavoriteForums()
                          throws TdWSException

Returns the user's favorite forum listing.

Similar to getFavoriteContainers() method, but this method returns only favorite forums.
Returns null, if there are no forums in the user's favorite list. ContainerType attribute/isCategoryType() method of Forum bean can be used to check if the container returned is a forum.

Returns:

Forum[] - An array of forum beans, representing the user's favorite forum listing.

Throws:

TdWSException - - Thrown on any exception in retrieving the favorite forum listing.

addTopicToFavorites

public Topic addTopicToFavorites(long lForumId,
                                 int iTopicId)
                          throws TdWSException

Adds the topic specified by iTopicId to user's favorite listing.

A bean representing the topic, added to favorites is returned to the user.
If a favorite topic is again added to favorites, the method just returns the bean, corresponding to the topic.
lForumId should represent the parent forum of the topic being added to favorites.

Parameters:

lForumId - - Id representing the parent forum of the topic being added to favorites.

iTopicId - - Id representing the topic being added to favorites.

Returns:

Topic - Bean representing, the topic added to favorites

Throws:

TdWSException - - Thrown on

• any exception in adding the topic to favorite listing
• if lForumId doesnot represent a valid forum
• if iTopicId doesnot represent a valid topic in the forum represented by lForumId
• if the user doesnot have access to the forum.

removeTopicFromFavorites

public void removeTopicFromFavorites(long lForumId,
                                     int iTopicId)
                              throws TdWSException

Removes the topic specified by iTopicId from user's favorite listing. If a non-favorite topic is removed from favorites, the method just returns. lForumId should represent the parent forum of the topic being removed from favorites.

Parameters:

lForumId - - Id representing the parent forum of the topic being removed from favorites.

iTopicId - - Id representing the topic being removed from favorites.

Throws:

TdWSException - - Thrown on

• any exception in removing the topic from favorite listing
• if lForumId doesnot represent a valid forum
• if iTopicId doesnot represent a valid topic in the forum represented by lForumId
• if the user doesnot have access to the forum.

listAllFavoriteTopics

public Topic[] listAllFavoriteTopics()
                              throws TdWSException

Returns the listing of user's favorite topics in entire Discussions system.

Returns null, if the user doesnot have any favorite topics.

Returns:

Topic[] - An array of topic beans representing the user's favorite topic listing.

Throws:

TdWSException - - Thrown on any exception in retrieving favorite topic listing.

listFavoriteTopics

public Topic[] listFavoriteTopics(long lContainerId)
                           throws TdWSException

Returns the listing of user's favorite topics in the container specified by lContainerId.

Returns null, if the user doesnot have any favorite topics in the container.

Parameters:

lContainerId - - Id representing the container from which, favorite topics are to be retrieved.

Returns:

Topic[] - An array of topic beans representing the user's favorite topic listing.

Throws:

TdWSException - - Thrown on

• any exception in retrieving favorite topic listing
• if the id doesnot represent a valid container
• if the user doesnot have access to the container

getFavoritePopularTopics

public Topic[] getFavoritePopularTopics()
                                 throws TdWSException

Returns the most popular topics, in the user's favorite topic listing.

Returns null,if there are no favorite popular topics.
Popular topics are defined as those threads, which receive the highest number of the replies in a given amount of time. Most popular threads assist the user in identifying the threads which recently received the highest number of contributions, which is an indication that their topic of discussion is quite relevant for a given board.

Returns:

Topic[] - An array of topic beans representing the most popular topics, ni user's favorite topic listing.

Throws:

TdWSException - - Thrown on any exception in retrieving user's favorite popular topic listing.

getFavoriteRecentPosts

public ForumMessage[] getFavoriteRecentPosts()
                                      throws TdWSException

Returns the topics with most recently posted messages, in the user's favorite listing.

Returns null,if there are no favorite topics, with recently posted messages.
Most Recent Posts is recorded at Facility and Board level. The list of most recently posted messages provides a snapshot of the recent activity in the whole system, a single facility or board.

Returns:

ForumMessage[] - An array of forum message beans, representing the most recently posted messages, in the user's favorite listing.

Throws:

TdWSException - - Thrown on any exception in retrieving user's favorite topics, with recently posted messages.

getPopularTopics

public Topic[] getPopularTopics(long lContainerId)
                         throws TdWSException

Returns the most popular topics, among all the topics in the container represented by lContainerId. Returns null, if there are no popular topics in the container. Popular topics are defined as those threads, which receive the highest number of the replies in a given amount of time. Most popular threads assist the user in identifying the threads which recently received the highest number of contributions, which is an indication that their topic of discussion is quite relevant for a given board.

Parameters:

lContainerId - - Id representing the container, from which the popular topic listing, is to be returned.

Returns:

Topic[] - An array of topic beans, representing the popular topics in the container.

Throws:

TdWSException - Thrown on

• any exception in retrieving popular topics
• if the user doesnot have access to the container
• if lContainerId doesnot represent a valid container

getRecentPosts

public ForumMessage[] getRecentPosts(long lContainerId)
                              throws TdWSException

Returns the most recently posted messages in the container specified by lContainerId.

Returns null, if there are no recently posted messages in the container. Most Recent Posts is recorded at Facility and Board level. The list of most recently posted messages provides a snapshot of the recent activity in the whole system, a single facility or board.

Parameters:

lContainerId - - Id specifying the container from which recent posts are to be retrieved.

Returns:

ForumMessage[] - An array of forum message beans, representing the recent posts returned.

Throws:

TdWSException - - Thrown on

• any exception in retrieving recent posts
• if the user doesnot have access to the container
• if lContainerId doesnot represent a valid container

getMyPosts

public ForumMessage[] getMyPosts()
                          throws TdWSException

Returns all the messages posted by the user.

Returns null, if the user has not posted any messages so far.

Returns:

ForumMessage[] - An array of forum message beans, representing the user's posted messages.

Throws:

TdWSException - - Thrown on any exception in retrieving user posted messages.

getPopularMyPosts

public ForumMessage[] getPopularMyPosts()
                                 throws TdWSException

Returns the most popular messages, among all the messages posted by the user. Returns null, if there are no popular messages in the user's posts. Popular topics are defined as those threads, which receive the highest number of the replies in a given amount of time. Most popular threads assist the user in identifying the threads which recently received the highest number of contributions, which is an indication that their topic of discussion is quite relevant for a given board.

Returns:

ForumMessage[] - An array of forum message beans representing the most popular user's posts

Throws:

TdWSException - - Thrown on any exception in retrieving user's popular posts.

getRecentMyPosts

public ForumMessage[] getRecentMyPosts()
                                throws TdWSException

Returns the most recently posted messages, among all messages posted by the user. Returns null, if the user has not posted any messages recently. Most Recent Posts is recorded at Facility and Board level. The list of most recently posted messages provides a snapshot of the recent activity in the whole system, a single facility or board.

Throws:

TdWSException - - Thrown on any exception in retrieving user's recent posts.

getRepliesToMyPosts

public ForumMessage[] getRepliesToMyPosts()
                                   throws TdWSException

Returns the messages posted by the user, to which other users have replied. Returns null, if none of the other users have replied to any of the currently logged in user's posts. For example, if user XXX logs in and posts a message M1. If any of the Discussions users replies to M1, then M1 will be returned by the call, when invoked by user XXX. If there are no replies to M1, the call returns nothing, when invoked by user XXX. Similar description applies to other users also.

Returns:

ForumMessage[] - An array of forum message beans representing posts by the author, which have been replied.

Throws:

TdWSException - - Thrown on any exception in retrieving the messages.

getPopularRepliesToMyPosts

public ForumMessage[] getPopularRepliesToMyPosts()
                                          throws TdWSException

Returns the most popular messages among the replies to user's posts. Returns null, if there are no popular messages among replies to user's posts.

Returns:

ForumMessage[] - An array of forum message beans representing the popular messages among replies to user's posts.

Throws:

TdWSException - - Thrown on any exception in retrieving the popular replies to user's posts.

getRecentRepliesToMyPosts

public ForumMessage[] getRecentRepliesToMyPosts()
                                         throws TdWSException

Returns the most recent messages, among the replies to user's posts. Returns null, if there are no recent messages in replies to user's posts.

Returns:

ForumMessage[] - An array of forum message beans representing recent messages among replies to users posts.

Throws:

TdWSException - - Thrown on any exception in retrieving the recent replies to user's posts.

search

public ForumMessage[] search(SearchTerm st)
                      throws TdWSException

Searches user's favorite containers for the search criterion specified in the search term.

Returns null, if there are no favorite containers for the user.
The search criterion can be supplied in the searchterm. Wild card searches are also possible.
Search is limited to searching message subject and content as of now.
If the user wants to search on a list of containers of his choice, search service in Container service interface can be made use of.

Parameters:

st - - Searchterm, specifying search criterion.

Returns:

ForumMessage[] - An array of forum message beans representing the search results.

Throws:

TdWSException - - Thrown on any exception in retrieving search results.

See Also:

SearchTerm, ContainerService.search(long[], oracle.discussions.ws.beans.SearchTerm, boolean)

addContainersToFavorites

public AddContainersToFavoritesBulkResponse[] addContainersToFavorites(long[] lContainerIds)
                                                                throws TdWSException

Adds an array of containers, represented by lContainerIds to the user's favorite listing.

An array of beans representing the result of the bulk operation is returned to the user.
Each of the beans in the array wraps around

• an abstract container bean, representing the container added to favorites - If the addition of that container to favorites is successful.
• details of the error, like error message, error code, stack trace, if the addition of the container to favorites failed.

The Discussions root container cannot be added/removed from user's favorites listing.

Parameters:

lContainerIds - - An array of container ids, representing the containers to be added to the user's favorites.

Returns:

AddContainersToFavoritesBulkResponse[] - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in adding the containers to favorites. If there is an exception in adding a container to favorites, the exception details are returned in a bulk response bean. But if the exception is fatal enough to prevent further processsing, it is not handled and is reported to the user.
• if the user doesnot have access to the containers specified.
• if the container id listing is null.
• if any of the container id represents an invalid container.

removeContainersFromFavorites

public DeleteElementBulkResponse[] removeContainersFromFavorites(long[] lContainerIds)
                                                          throws TdWSException

Deletes the containers specified by lContainerIds.

Returns an array of bulk response beans if there is any error in deleting any of the containers. Each of the beans will have information about the element failed, the error message and the error stacktrace. Nothing is returned if the deletion of all the containers is successful.

Parameters:

lContainerIds - - An array of ids representing the containers to be deleted.

Returns:

DeleteElementBulkResponse[] - An array of bulk response beans representing the failed containers.

Throws:

TdWSException - - Thrown on

• any exception in deleting the contaniers. Normally, the exception is handled and is returned in the bulk response, but if the exception is fatal enough to stop further processing, it is not handled and is reported to the user.
• if the container listing is null
• if the used doesnot have permissions to delete one or more containers

addTopicsToFavorites

public AddTopicsToFavoritesBulkResponse[] addTopicsToFavorites(long lForumId,
                                                               int[] iTopicIds)
                                                        throws TdWSException

Adds an array of topics, represented by iTopicIds to the user's favorite listing.

An array of beans representing the result of the bulk operation is returned to the user.
Each of the beans in the array wraps around

• a topic bean, representing the topic added to favorites - If the addition of that topic to favorites is successful.
• details of the error, like error message, error code, stack trace, if the addition of the topic to favorites failed.

lForumId should represent the parent forum of the topics being added.

Parameters:

lForumId - - Id representing the parent forum of the topics being added to favorites.

iTopicIds - - An array of topic ids, representing the topics to be added to the user's favorites.

Returns:

AddTopicsToFavoritesBulkResponse[] - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in adding the topics to favorites. If there is an exception in adding a topic to favorites, the exception details are returned in a bulk response bean. But if the exception is fatal enough to prevent further processsing, it is not handled and is reported to the user.
• if the user doesnot have access to the container specified.
• if the topic id listing is null.
• if lForumId represents an invalid container.
• if lForumId doesnot represent the parent forum of the topics being added to favorites.

removeTopicsFromFavorites

public DeleteElementBulkResponse[] removeTopicsFromFavorites(long lForumId,
                                                             int[] iTopicIds)
                                                      throws TdWSException

Deletes the topics specified by iTopicIds.

Returns an array of bulk response beans if there is any error in deleting any of the topics. Each of the beans will have information about the element failed, the error message and the error stacktrace. Nothing is returned if the deletion of all the topics is successful.
lForumId should represent the parent forum of the topics to be deleted.

Returns:

DeleteElementBulkResponse[] - An array of bulk response beans representing the failed topics.

Throws:

TdWSException - - Thrown on

• any exception in deleting the topics. Normally, the exception is handled and is returned in the bulk response, but if the exception is fatal enough to stop further processing, it is not handled and is reported to the user.
• if the topics listing is null
• if the used doesnot have permissions to delete one or more topics
• if the container doesnot represent the parent forum of the topics to be deleted.