oracle.discussions.ws
Interface TopicService

public interface TopicService

Webservice interface representing the operations related to Oracle Discussions Topic. A topic is a root level message in a forum.It is a stem from which all other messages originate. The interface provides operations for ul>

• Creation of a topic
• Deletion of a topic
• Listing of messages under a topic
• Locking/Unlocking a topic
• Retrieving a topic
• Moving a topic fromone forum to another
• Editing the contents of a topic

It also provides bulk operations to create/delete multiple topics in one invocation.
Axis specific Sample code illustrating the invocation/usage of TopicService.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. 
 TopicServiceServiceLocator mdssl = new TopicServiceServiceLocator();
 //Retrieve a reference to the remote webservices interface.
 TopicService mdsl = mdssl.getTopicService();
 //Notify the axis server that client is interested in maintaining session.
 ((TopicServiceSoapBindingStub)mdsl).setMaintainSession(true);
 //Set the cookie, retrieved during login service invocation.
 ((javax.xml.rpc.Stub)mdsl)._setProperty(HTTPConstants.HEADER_COOKIE,cookie);
 //Prepare the input parameters
 MessageDefinition cDefn = new MessageDefinition();
 cDefn.setSubject("First category");
 cDefn.setBody("First Category");
 //Invoke the webservices method.
 ForumMessage message = mdsl.create(1045,cDefn);
 if(message != null)
 {
 //Process the message bean, representing the first message of the topic created.
 ........
 }
 

See Also:

MessageService

Method Summary

ForumMessage	create(long lForumId, MessageDefinition mDefn) Creates a topic from the specified message definition bean.
ForumMessage	createTopicFromByte(long lForumId, byte[] msg) Creates a topic from the specified byte array.
CreateTopicBulkResponse[]	createTopics(long lForumId, MessageDefinition[] mDefn) Creates topics from the specified message definition bean array.
Forum	delete(long lForumId, int iTopicId) Deletes the topic specified by iTopicId, in the forum, specified by lForumId.
DeleteElementBulkResponse[]	deleteTopics(long lForumId, int[] iTopicIds) Deletes the topics specified by iTopicId array, from the forum, specified by lForumId.
Topic	edit(long lForumId, int iTopicId, java.lang.String subject, java.lang.String body) Edits the topic subject and content with those supplied.
Topic	editTopicWithByte(long lForumId, int iTopicId, byte[] topic) Edits the topic with the byte array supplied.
Topic	getTopic(long lForumId, int iTopicId) Returns the topic specified by iTopicId, in the forum lForumId.
byte[]	getTopicInByte(long lForumId, int iTopicId) Returns a MIME compatible byte array representing the topic retrieved.
ForumMessage[]	listMessages(long lForumId, int iTopicId, boolean bSortByPostDate) Lists the messages in the topic specified by iTopicId.
Topic	lock(long lForumId, int iTopicId) Locks the topic, specified by iTopicId, in forum specified by lForumId.
Topic	unlock(long lForumId, int iTopicId) Unlocks the topic, specified by iTopicId, in forum specified by lForumId.

Method Detail

lock

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

Locks the topic, specified by iTopicId, in forum specified by lForumId.

Once a topic is locked, it cannnot be edited/replied-to normally. A topic can be locked by users with forum moderator and higher role. Topic creators also can lock the topic, that they created.
Only users with forum moderator or higher role can edit/reply-to that topic.

Parameters:

lForumId - - Id representing a forum, in which the topic to be locked is present.

iTopicId - - Id representing topic to be locked.

Throws:

TdWSException - - Thrown on

• any exception in locking the topic
• if lForumId doesnot represent the parent forum of the topic
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to forum specified by lForumId
• if the topic is already locked
• if the user doesnot have permissions to lock the topic

delete

public Forum delete(long lForumId,
                    int iTopicId)
             throws TdWSException

Deletes the topic specified by iTopicId, in the forum, specified by lForumId.

All the messages of the topic, are also deleted along with the topic. Once a topic is deleted, it cannot be recovered again.

Parameters:

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

iTopicId - - Id representing the topic, to be deleted.

Returns:

Forum - Bean representing the forum, from which topic is deleted.

Throws:

TdWSException - - Thrown on

• any exception in deleting the topic
• if lForumId doesnot represent the parent forum of the topic
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to forum specified by lForumId
• if the iTopicId doesnot represent a valid topic
• if the user doesnot have permissions to delete the topic

create

public ForumMessage create(long lForumId,
                           MessageDefinition mDefn)
                    throws TdWSException

Creates a topic from the specified message definition bean.

A topic should have either a subject or a body. The topic posted will be of text/plain content type.
lForumId should represent a forum into which the topic should be posted.

Parameters:

lForumId - - Id representing forum, in which the topic is to be created.

Returns:

ForumMessage - Bean representing newly created topic.

Throws:

TdWSException - - Thrown on

• any exception in posting the topic
• if the user doesnot have access to forum specified by lForumId
• if lForumId doesnot represent the parent forum of the topic.
• if lForumId doesnot represent a valid forum.
• if mDefn is null or invalid
• if the user doesnot have permission to post the topic in the forum

See Also:

createTopicFromByte

unlock

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

Unlocks the topic, specified by iTopicId, in forum specified by lForumId.

Once a topic is unlocked, it can be edited/replied-to normally. Only users with forum moderator or higher role can unlock a topic. A topic creator cna unlock his own topic.

Parameters:

lForumId - - Id representing a forum, in which the topic to be unlocked is present.

iTopicId - - Id representing topic to be unlocked.

Throws:

TdWSException - - Thrown on

• any exception in unlocking the topic
• if lForumId doesnot represent the parent forum of the topic
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to forum specified by lForumId
• if the topic is already unlocked
• if the user doesnot have permissions to unlock the topic

getTopic

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

Returns the topic specified by iTopicId, in the forum lForumId. lForumId should represent parent forum of the topic being retrieved.

Parameters:

iTopicId - - Id representing the topic to be returned.

Returns:

Topic - Bean representing the topic retrieved.

Throws:

TdWSException - - Thrown on

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

listMessages

public ForumMessage[] listMessages(long lForumId,
                                   int iTopicId,
                                   boolean bSortByPostDate)
                            throws TdWSException

Lists the messages in the topic specified by iTopicId.

The listed messages can be sorted on their posted date by setting the boolean value bSortByPostDate to true.
iFetchStart indidates the start index from which the topics are returned. lForumId should represent the parent forum of the topic, from which the messages are being listed.

Parameters:

lForumId - - Id representing the forum, in which the messages are present.

iTopicId - - Id representing the topic, in which the messages are present.

bSortByPostDate - - boolean valud representing if the returned messages are to be sorted by their posted date.

Returns:

ForumMessage[] - An array of beans representing the topics returned.

Throws:

TdWSException - - Thrown on

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

createTopicFromByte

public ForumMessage createTopicFromByte(long lForumId,
                                        byte[] msg)
                                 throws TdWSException

Creates a topic from the specified byte array.

The byte[] array should be MIME compatible. Useful in creating topics with attachments. The entire message, along with all the headers and attachments is converted into a byte[]. The same byte[] can be used in creating topic.

Parameters:

lForumId - - Id representing a forum, in which topic is to be created.

msg - - bytes representing the topic to be created.

Returns:

ForumMessage - Bean representing newly created topic.

Throws:

TdWSException - - Thrown on

• any exception in posting the topic
• if the user doesnot have access to forum specified by lForumId
• if lForumId doesnot represent a valid forum.
• if lForumId doesnot represent the parent forum of the topic.
• if msg byte array is null or invalid
• if the user doesnot have permission to post the topic in the forum

edit

public Topic edit(long lForumId,
                  int iTopicId,
                  java.lang.String subject,
                  java.lang.String body)
           throws TdWSException

Edits the topic subject and content with those supplied.

A topic should have either a subject or a body. The topic posted will be of text/plain content type.
lForumId should represent a forum into which the topic should be posted. The old values of the topic subject and conent will be overwritten with the values supplied.

Parameters:

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

iTopicId - - Id representing the topic to be edited.

subject - - Subject to be applied to the topic.

body - - Content to be applied to the topic.

Throws:

TdWSException - - Thrown on

• any exception in editing the topic
• if the user doesnot have access to forum specified by lForumId
• if lForumId doesnot represent a valid forum.
• if lForumId doesnot represent the parent forum of the topic.
• if topic subject and body are null

editTopicWithByte

public Topic editTopicWithByte(long lForumId,
                               int iTopicId,
                               byte[] topic)
                        throws TdWSException

Edits the topic with the byte array supplied.

The byte[] array should be MIME compatible.
The entire topic is replaced with the content of the byte array.A new mime message object is constructed and it overwrites the entire old topic.

Parameters:

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

iTopicId - - Id representing the topic to be edited.

topic - - byte[] representing the new topic.

Throws:

TdWSException - - Thrown on

• any exception in editing the topic
• if the user doesnot have access to forum specified by lForumId
• if lForumId doesnot represent a valid forum.
• if lForumId doesnot represent the parent forum of the topic.
• if topic byte array is null or invalid
• if the user doesnot have permission to edit the topic in the forum

getTopicInByte

public byte[] getTopicInByte(long lForumId,
                             int iTopicId)
                      throws TdWSException

Returns a MIME compatible byte array representing the topic retrieved. The byte array retrieved can be posted as a new message in any Discussions forum, basing its message posting on java mail semantics.

Parameters:

iTopicId - - Id representing the topic to be returned.

Returns:

byte[] - byte array representing the topic retrieved.

Throws:

TdWSException - - Thrown on

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

createTopics

public CreateTopicBulkResponse[] createTopics(long lForumId,
                                              MessageDefinition[] mDefn)
                                       throws TdWSException

Creates topics from the specified message definition bean array.

lForum should represent the parent forum, in which the topics are being created. 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 forum message bean, representing the topic created - If the topic creation is successful.
• details of the error, like error message, error code, stack trace, if the topic creation failed.

Parameters:

lForumId - - Id representing forum, in which the topics are to be created.

Returns:

CreateTopicBulkResponse[] - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in creating the 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 the forum specified by lForumId
• if the user doesnot have permissions to the create the topic in the forum
• if lForumId doesnot represent a valid forum
• if lForumId doesnot represent the parent forum of the topics
• is mDefn is null or invalid

See Also:

create

deleteTopics

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

Deletes the topics specified by iTopicId array, from the forum, specified by lForumId.

All the messages of the topic, are also deleted along with the topic. Once a topic is deleted, it cannot be recovered again.
Only topic creator and users with forum moderator and higher role, can delete a topic.
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.

Parameters:

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

iTopicIds - -Array of topic ids representing topics, to be deleted.

Returns:

DeleteElementBulkResponse - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any exception in deleting the topic. 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 user doesnot have access to the forum specified by lForumId
• if lForumId doesnot represent the parent forum of the topics to be deleted
• if topic id listing is null