oracle.discussions.ws
Interface SubscriptionService

public interface SubscriptionService

Webservice interface providing methods related to Subscriptions on Discussions elements.

Any Oracle Discussions element, added as a favorite can be subscribed.The user subscribing to the element, will receive email notifications, if there is any change in the state of the element.Subscriptions are applies in hierarchial fashion.
For example, if an user subscribed to a forum, he receives a notification on any change in any of the topics/messages in the forum.
A subscription is removed when

• User access is removed on that element
• The element is deleted
• User un-subscribes to that element

Axis specific Sample code illustrating the invocation/usage of SubscriptionService.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. 
 SubscriptionServiceServiceLocator mdssl = new SubscriptionServiceServiceLocator();
 //Retrieve a reference to the remote webservices interface.
 SubscriptionService mdsl = mdssl.getSubscriptionService();
 //Notify the axis server that client is interested in maintaining session.
 ((SubscriptionServiceSoapBindingStub)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 aContainer = mdsl.subscribeToContainer(8791);
 if(aContainer != null)
 {
 //Process the container
 ........
 }
 

See Also:

Subscription

Method Summary

Subscription	getContainerSubscription(long lContainerId) Returns the subscription for the logged in user on the container represented by lContainerId.
Subscription	getTopicSubscription(long lForumId, int iTopicId) Returns the subscription for the logged in user on the topic represented by iTopicId.
Subscription[]	listSubscriptions() Returns all the subscriptions for the logged in user.
Subscription	subscribeToContainer(long lContainerId, int iType) Creates a container subscription for the logged in user, on the container specified by the lContainerId.
SubscribeToContainersBulkResponse[]	subscribeToContainers(long[] lContainerIds, int iType) Creates subscriptions for the logged in user, on the containers specified by the lContainerId array.
Subscription	subscribeToTopic(long lForumId, int lTopicId, int iType) Creates a topic subscription for the logged in user, on the topic specified by the lTopicId.
SubscribeToTopicsBulkResponse[]	subscribeToTopics(long[] lForumIds, int[] iTopicIds, int iType) Creates subscriptions for the logged in user, on the topics specified by the iTopicId array.
void	unsubscribe(Subscription subscription) Removes the user's subscription on the subscription element represented by the id fields in the Subscription bean.
DeleteElementBulkResponse[]	unsubscribeInBulk(Subscription[] subscription) Removes the user's subscriptions on the subscription elements represented by the id fields in the Subscription bean array.
Subscription	updateSubscription(Subscription subscription) Updates the subscription corresponding to the container/topic represented by the id fields in the Subscription bean.
DeleteElementBulkResponse[]	updateSubscriptions(Subscription[] subscription) Updates the subscriptions corresponding to the container/topic represented by the id fields in the Subscription bean array.

Method Detail

subscribeToContainer

public Subscription subscribeToContainer(long lContainerId,
                                         int iType)
                                  throws TdWSException

Creates a container subscription for the logged in user, on the container specified by the lContainerId.

The type of notification sent to the user is represented by iType. Only email notifications are enabled at present.

Parameters:

lContainerId - - Id representing the container on which subscription is to be created.

iType - - Notification type to be sent to the user.

• Type argument accepts only 1 as the argument at present.

  Returns:

  Subscription - Bean representing the container subscription created.

  Throws:

  TdWSException - - Thrown on

  • any exception in subscribing to the container
  • if lContainerId doesnot represent a valid container
  • if iType is invalid
  • if the user doesnot have access to the container

subscribeToTopic

public Subscription subscribeToTopic(long lForumId,
                                     int lTopicId,
                                     int iType)
                              throws TdWSException

Creates a topic subscription for the logged in user, on the topic specified by the lTopicId.

lForumId should represent the parent forum of the topic. The type of notification sent to the user is represented by iType. Only email notifications are enabled at present.

Parameters:

lForumId - - Id representing the forum in which the topic is present.

lTopicId - - Id representing topic being subscribed.

iType - - Type of te notification to be sent. iType takes only the value 1 at present.

Returns:

Subscription - Subscription bean representing the subscription created on the topic.

Throws:

TdWSException - - Thrown on

• any exception in subscribing to the topic
• if lForumId doesnot represent a valid forum
• if iType is invalid
• if the user doesnot have access to the forum
• if lForumId doesnot represent the parent forum of the topic being subscribed
• if lTopicId doesnot represent a valid topic

getContainerSubscription

public Subscription getContainerSubscription(long lContainerId)
                                      throws TdWSException

Returns the subscription for the logged in user on the container represented by lContainerId.

Returns null, if the user doesnot have any subscription on the container.

Parameters:

lContainerId - - Id representing the container, on which subscription is to be returned.

Returns:

Subscription - Subscription bean representing user's subscription on the container.

Throws:

TdWSException - - Thrown on

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

getTopicSubscription

public Subscription getTopicSubscription(long lForumId,
                                         int iTopicId)
                                  throws TdWSException

Returns the subscription for the logged in user on the topic represented by iTopicId.

Returns null, if the user doesnot have any subscription on the topic. lForumId should represent the parent forum of the topic.

Parameters:

lForumId - - Id representing the parent forum of the topic.

iTopicId - - Id representing the topic on which subscription is to be returned.

Returns:

Subscription - Subscription bean representing user's subscription on the topic.

Throws:

TdWSException - - Thrown on

• any exception in retrieving topic subscription
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to the forum
• if lForumId doesnot represent the parent forum of the topic
• if iTopicId doesnot represent a valid topic

listSubscriptions

public Subscription[] listSubscriptions()
                                 throws TdWSException

Returns all the subscriptions for the logged in user. Returns null, if the user doesnot have any subscriptions on any element of the Discussions system.

Returns:

Subscription[] - An array of subscription beans representing user's subscriptions.

Throws:

TdWSException - - Thrown on any exception in retrieving subscription listing for the user.

updateSubscription

public Subscription updateSubscription(Subscription subscription)
                                throws TdWSException

Updates the subscription corresponding to the container/topic represented by the id fields in the Subscription bean.

If the topic id is 0, and if container id represents a valid container then the subscription represents a container subscription and is updated. On the other hand, if both topic and container ids are > 0, and if the ids represent a valid topic, then the topic subscription is updated.
Returns a subscription bean, corresponding to the subscription with the updated values.

Parameters:

subscription - - Subscription bean, representing the values to be updated.

Throws:

TdWSException - - Thrown on

• any exception in updating the subscription
• if subscription bean is null or invalid

unsubscribe

public void unsubscribe(Subscription subscription)
                 throws TdWSException

Removes the user's subscription on the subscription element represented by the id fields in the Subscription bean.

If the topic id is 0, and if container id represents a valid container, then the subscription represents a container subscription, and is unsubscribed. On the other hand, if both topic and contaienr ids are > 0, and if the ids represent a valid topic, then the topic subscription is removed.

Parameters:

subscription - - Subscription bean, representing the subscription to be removed.

Throws:

TdWSException - - Thrown on

• any exception in removing the subscription
• if subscription bean is null or invalid

subscribeToContainers

public SubscribeToContainersBulkResponse[] subscribeToContainers(long[] lContainerIds,
                                                                 int iType)
                                                          throws TdWSException

Creates subscriptions for the logged in user, on the containers specified by the lContainerId array.

The type of notification sent to the user is represented by iType. Only email notifications are enabled at present.
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 subscription bean, representing the container subscription created - If the subscription is successful.
• details of the error, like error message, error code, stack trace, if the subscription failed.

Parameters:

lContainerIds - - An array of ids representing the containers on which subscriptions are to be created.

iType - - Notification type to be sent to the user.

• Type argument accepts only 1 as the argument at present.

Returns:

SubscribeToContainersBulkResponse - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in subscribing to containers. If there is an exception 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 any of the containers
• if iType is invalid
• if lContainerIds is null
• if any of ids in lContainerIds doesnot represent a valid container

subscribeToTopics

public SubscribeToTopicsBulkResponse[] subscribeToTopics(long[] lForumIds,
                                                         int[] iTopicIds,
                                                         int iType)
                                                  throws TdWSException

Creates subscriptions for the logged in user, on the topics specified by the iTopicId array.

lForumIds should represent parent forums of topics specified by iTopicIds array. The type of notification sent to the user is represented by iType. Only email notifications are enabled at present.
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 subscription bean, representing the topic subscription created - If the subscription is successful.
• details of the error, like error message, error code, stack trace, if the subscription failed.

Parameters:

lForumIds - - An array of ids representing parent forums of the topics.

iTopicIds - - An array of ids representing topics being subscribed.

iType - - Type of te notification to be sent. iType takes only the value 1 at present.

Returns:

SubscribeToTopicsBulkResponse - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in subscribing to topics. If there is an exception 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 any of the forums
• if iType is invalid
• if lForumIds is null
• if any of ids in lForumIds doesnot represent a valid forum
• if any of the ids in iTopicIds doesnot represent a valid topic
• if the lengths of forum ids and topic ids are not matching
• if any of the forum ids represent a forum, that is not a parent forum of the topic represented by corresponding topicId

unsubscribeInBulk

public DeleteElementBulkResponse[] unsubscribeInBulk(Subscription[] subscription)
                                              throws TdWSException

Removes the user's subscriptions on the subscription elements represented by the id fields in the Subscription bean array.

If the topic id is 0, and if container id represents a valid container, then the subscription represents a container subscription, and is unsubscribed.
On the other hand, if both topic and contaienr ids are > 0, and if the ids represent a valid topic, then the topic subscription is removed.
Returns an array of bulk response beans if there is any error in removing any of the subscriptions. Each of the beans will have information about the element failed, the error message and the error stacktrace. Nothing is returned if the removal of all subscriptions is successful.

Parameters:

subscription - - An array of subscription beans, representing the subscriptions to be removed.

Returns:

DeleteElementBulkResponse[] - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in removal of subscriptions. If there is an exception 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.
• is subscription is null or invalid

updateSubscriptions

public DeleteElementBulkResponse[] updateSubscriptions(Subscription[] subscription)
                                                throws TdWSException

Updates the subscriptions corresponding to the container/topic represented by the id fields in the Subscription bean array.

If the topic id is 0, and if container id represents a valid container then the subscription represents a container subscription and is updated.
On the other hand, if both topic and container ids are > 0, and if the ids represent a valid topic, then the topic subscription is updated.
Returns an array of bulk response beans if there is any error in updating any of the subscriptions. 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 categories is successful.

Parameters:

subscription - - Subscription bean array, representing the subscriptions to be updated.

Returns:

DeleteElementBulkResponse[] - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in updating of subscriptions. If there is an exception 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.
• is subscription is null or invalid