oracle.discussions.ws
Interface ForumService

public interface ForumService

Webservice interface representing Oracle Discussions Forum related operations. A forum in Discussions represents a container, to which topics/messages are posted. The web services interface provides operations for

• Creating a forum
• Deleting a forum
• Updating a forum
• Retrieving/Updating forum properties
• Listing contents of the forum

Apart from the above mentioned operations, it also provides bulk operations to create/delete multiple forums in a single invocation.
Axis specific Sample code illustrating the invocation/usage of ForumService.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. 
 ForumServiceServiceLocator mdssl = new ForumServiceServiceLocator();
 //Retrieve a reference to the remote webservices interface.
 ForumService mdsl = mdssl.getForumService();
 //Notify the axis server that client is interested in maintaining session.
 ((ForumServiceSoapBindingStub)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.
 ........
 }
 

See Also:

CategoryService, ContainerService

Method Summary

Forum	create(long lParentId, ForumDefinition fDefn) Creates a forum under the container represented by lParentId, with the properties specified in the fDefn.
CreateForumBulkResponse[]	createForums(long lParentId, ForumDefinition[] fDefn) Creates forums under the container represented by lParentId, with the properties specified in the fDefn bean array.
void	delete(long lForumId) Deletes the forum represented by lForumId.
DeleteElementBulkResponse[]	deleteForums(long[] lForumIds) Deletes the forums represented by lForumIds array.
Forum	getForumById(long lForumId) Returns a forum bean corresponding to the forum represented by lForumId.
ForumSettings	getForumSettings(long lForumId) Returns the settings of the forum represented by lForumId.
Topic[]	listTopics(long lForumId, int iFetchStart, int iFetchMax, boolean bSortByCreation, boolean bAscending) Lists topics under the forum represented by lForumId.
Forum	lock(long lForumId) Locks a forum represented by lForumId.
Forum	unlock(long lForumId) Unlocks a forum represented by lForumId.
ForumSettings	updateForumSettings(long lForumId, ForumSettings fs) Updates the forum settings for the forum represented by lForumId, with the settings supplied in fs.

Method Detail

lock

public Forum lock(long lForumId)
           throws TdWSException

Locks a forum represented by lForumId.

Once the forum is locked, it is not available for normal topic/message posting, until it is unlocked again.
Only users with forum moderator or higher role can post/edit topics/messages in a locked forum.
Users with forum moderator and higher role can lock a forum.

Parameters:

lForumId - - Id representing the forum to be locked.

Returns:

Forum - Returns a forum bean representing the locked forum.

Throws:

TdWSException - - Thrown on

• any exception in locking the forum
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to the forum
• if the forum is already locked
• if the user doesnot have enough permissions to lock the forum

delete

public void delete(long lForumId)
            throws TdWSException

Deletes the forum represented by lForumId.

All the elements under the forum are also deleted. Once a forum is deleted, it cannot be recovered again.

Parameters:

lForumId - - Id representing the forum to be deleted.

Throws:

TdWSException - - Thrown on

• any exception in deleting the forum
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to the forum
• if the user doesnot have enough permissions to delete the forum

create

public Forum create(long lParentId,
                    ForumDefinition fDefn)
             throws TdWSException

Creates a forum under the container represented by lParentId, with the properties specified in the fDefn.

Care should be taken, so that no two forums at the same level have same name and display name.An exception is raised otherwise.
Once a forum is created, forum name cannot be changed.
Default settings are applied to the forum, and they can be updated later.
lParentId should represent a valid category, to which the user has access to

Parameters:

lParentId - - Id representing parent container, under which forum is to be created.

fDefn - - Forum definition bean, representing properties of new forum to be created.

Returns:

Forum - Forum bean, representing newly created forum.

Throws:

TdWSException - - Thrown on

• any exception in creating the forum
• if lParentId doesnot represent a valid category
• if the user doesnot have access to the category specified by lParentId
• if the user doesnot have permissions to create a forum in category
• if fDefn is null or invalid
• if another forum with same name/display name/email is present at the same level

See Also:

createForums

getForumById

public Forum getForumById(long lForumId)
                   throws TdWSException

Returns a forum bean corresponding to the forum represented by lForumId.

Parameters:

lForumId - - Id representig the forum to be returned.

Returns:

Forum - Forum bean representing to the forum being returned.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the forum
• if the user doesnot have access to the forum specified by lForumId
• if lForumId doesnot represent a valid forum

unlock

public Forum unlock(long lForumId)
             throws TdWSException

Unlocks a forum represented by lForumId.

Once the forum is unlocked, it is available for normal topic/message posting. Only users with forum moderator or higher role can unlock a forum.

Parameters:

lForumId - - Id representing the forum to be unlocked.

Returns:

Forum - Returns a forum bean representing the unlocked forum.

Throws:

TdWSException - - Thrown on

• any exception in unlocking the forum
• if lForumId doesnot represent a valid forum
• if the user doesnot have access to the forum
• if the forum is already unlocked
• if the user doesnot have enough permissions to unlock the forum

getForumSettings

public ForumSettings getForumSettings(long lForumId)
                               throws TdWSException

Returns the settings of the forum represented by lForumId.

Default settings are applied to the forum, when it is created. So if the forum settings are not updated, after the forum is created, the default settings are returned.

Parameters:

lForumId - - Id representing the forum, for which settings are to be returned.

Returns:

ForumSettings - Bean representing forum settings being returned.

Throws:

TdWSException - - Thrown on

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

updateForumSettings

public ForumSettings updateForumSettings(long lForumId,
                                         ForumSettings fs)
                                  throws TdWSException

Updates the forum settings for the forum represented by lForumId, with the settings supplied in fs.

The default settings are overwritten by those specified in the forum settings bean supplied. Forum Email seting needs special attention. Once an email address is specified to the forum, it cannot be changed again.

Parameters:

lForumId - - Id representing forum, whose settings needs to be updated.

fs - - Forum settings bean, representing settings to be applied to the forum.

Returns:

ForumSettings - Bean representing updated forum settings.

Throws:

TdWSException - - Thrown on

• any exception in updating the forum settings
• if the user doesnot have access to the forum specified by lForumId
• if the user doesnot have permissions to update the forum settings of the forum
• if lForumId doesnot represent a valid forum
• if fs is null or invalid

See Also:

ForumSettings

listTopics

public Topic[] listTopics(long lForumId,
                          int iFetchStart,
                          int iFetchMax,
                          boolean bSortByCreation,
                          boolean bAscending)
                   throws TdWSException

Lists topics under the forum represented by lForumId.

Returns null, if there are no topics under the forum. The listed topics can be sorted by creation date, by specifying bSortByCreation value to true, sorted in the ascending order of the creation date, by specifying bAscending to true.

Parameters:

lForumId - - Id representing forum, from which the topics are listed.

iFetchStart - - Start index, from which topics are returned.

iFetchMax - - Parameter, indicating the number of topics to be retrieved. iFetchStart to iFetchStart + iFetchMax topics are returned.

bSortByCreation - - Boolean value specifying if the returned topics are to be sorted by creation time

bAscending - - Boolean value specifying if the returned topics are to be sorted in the ascending order of creation date.

Returns:

Topic[] - An array of topic beans, representing topics returned.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the topic listing
• if the user doesnot have access to the forum specified by lForumId
• if lForumId doesnot represent a valid forum
• if iFetchStart is less than 0

createForums

public CreateForumBulkResponse[] createForums(long lParentId,
                                              ForumDefinition[] fDefn)
                                       throws TdWSException

Creates forums under the container represented by lParentId, with the properties specified in the fDefn bean array.

Care should be taken, so that no two forums at the same level have same name and display name.An exception is raised otherwise.
Once a forum is created, forum name cannot be changed. Default settings are applied to the forum, and they can be updated later.
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 bean, representing the forum created - If the forum creation is successful.
• details of the error, like error message, error code, stack trace, if the forum creation failed.

Parameters:

lParentId - - Id representing parent container, under which forum is to be created.

Returns:

CreateForumBulkResponse - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in creating the forums. 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 category specified by lParentId
• if lParentId doesnot represent a valid category
• is fDefn is null or invalid

deleteForums

public DeleteElementBulkResponse[] deleteForums(long[] lForumIds)
                                         throws TdWSException

Deletes the forums represented by lForumIds array.

All the elements under the forum are also deleted, once a forum is deleted. Once a forum is deleted, it cannot be recovered.

Returns an array of bulk response beans if there is any error in deleting any of the forums. 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 forums is successful.

Throws:

TdWSException - - Thrown on

• any exception in deleting the forum. 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 any of the forums
• if forum id listing is null