oracle.discussions.ws
Interface CategoryService

public interface CategoryService

Webservice interface providing Oracle Discussions Category related operations.

A Category is an abstraction of a container where in it holds other categories and forums. A category cannot container messages directly under it.
The webservice interface provides operations for

• Category creation
• Category deletion
• Category retrieval
• Retrieving category settings
• Editing category settings
• Listing the contents under a category
• .

Apart from these, it also provides bulk operations to create and delete multiple categories, in a single invocation.Axis specific Sample code illustrating the invocation/usage of CategoryService.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. 
 CategoryServiceServiceLocator mdssl = new CategoryServiceServiceLocator();
 //Retrieve a reference to the remote webservices interface.
 CategoryService mdsl = mdssl.getCategoryService();
 //Notify the axis server that client is interested in maintaining session.
 ((CategoryServiceSoapBindingStub)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
 CategoryDefinition cDefn = new CategoryDefinition();
 cDefn.setName("First category");
 cDefn.setDisplayName("First Category");
 //Invoke the webservices method.
 Category category = mdsl.create(-1,cDefn);
 if(category != null)
 {
 //Process the retrieved container listing.
 ........
 }
 

See Also:

ContainerService

Method Summary

Category	create(long lParentId, CategoryDefinition cDef) Creates a new category in the repository.
CreateCategoryBulkResponse[]	createCategories(long lParentId, CategoryDefinition[] cDefn) Creates categories specified by array of cDefn beans, under the container specified by lParentId.
void	delete(long lCategoryId) Deletes the category specified by lCategoryId.
DeleteElementBulkResponse[]	deleteCategories(long[] lCategoryIds) Deletes the categories specified by an array of category ids.
Category	getCategoryById(long lCategoryId) Retrieves the category specified by lCategoryId.
CategorySettings	getCategorySettings(long lCategoryId) Retrieves category settings specified by lCategoryId.
AbstractContainer[]	list(long lContainerId, java.lang.String pattern, boolean bRefresh) Lists all the containers, that the user has access to, under the container represented by lContainerId.
Category[]	listCategories(long lContainerId, java.lang.String pattern, boolean bRefresh) Lists all the categories,that the user has access to, under the container represented by lContainerId.
Forum[]	listForums(long lContainerId, java.lang.String pattern, boolean bRefresh) Lists all the forums,that the user has access to, under the container represented by lContainerId.
CategorySettings	updateCategorySettings(long lCategoryId, CategorySettings cSettings) Updates the settings of the category specified by lCategoryId.

Method Detail

list

public AbstractContainer[] list(long lContainerId,
                                java.lang.String pattern,
                                boolean bRefresh)
                         throws TdWSException

Lists all the containers, that the user has access to, under the container represented by lContainerId.

The container listing can be controlled by specifying pattern. It takes regular expression symbols to show the listing. For example, a * can be provided to retrieve all the containers under the current container. A % can be given to retrievel only first level containers, and so on.
The boolean value specifies if the container listing in the cache is to be refreshed from database, before fetching.

Parameters:

lContainerId - - Id representing the container under which, containers are to be listed.

pattern - - Regular expression string to control the listing.

bRefresh - - Boolean value specifying if the container cache is to be refreshed from database.

Returns:

AbstractContainer[] - An array of containers under the given container.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the container listing
• if the user doesnot have access to the container specified by lContainerId
• if the pattern specified is invalid

listCategories

public Category[] listCategories(long lContainerId,
                                 java.lang.String pattern,
                                 boolean bRefresh)
                          throws TdWSException

Lists all the categories,that the user has access to, under the container represented by lContainerId.

The category listing can be controlled by specifying pattern. It takes regular expression symbols to show the listing. For example, a * can be provided to retrieve all the categories under the current container. A % can be given to retrievel only first level categories, and so on.
The boolean value specifies if the category listing is to be refreshed from database. from database, before fetching.

Parameters:

lContainerId - - Id representing the container under which, categories are to be listed.

pattern - - Regular expression string to control the listing.

bRefresh - - Boolean value specifying if the container cache is to be refreshed before listing.

Returns:

Category[] - An array of categories, under the given category.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the container listing
• if the user doesnot have access to the container specified by lContainerId
• if the pattern specified is invalid

listForums

public Forum[] listForums(long lContainerId,
                          java.lang.String pattern,
                          boolean bRefresh)
                   throws TdWSException

Lists all the forums,that the user has access to, under the container represented by lContainerId.

The forum listing can be controlled by specifying pattern. It takes regular expression symbols to show the listing. For example, a * can be provided to retrieve all the forums under the current container. A % can be given to retrievel only first level forums, and so on.
The boolean value specifies if the forum listing is to be refreshed from database, before fetching.

Parameters:

lContainerId - - Id representing the container under which, forums are to be listed.

pattern - - Regular expression symbol (string) to control the listing.

bRefresh - - Boolean value specifying if the container cache is to be refreshed from database.

Returns:

Forum[] - An array of forums, under the given category.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the container listing
• if the user doesnot have access to the container specified by lContainerId
• if the pattern specified is invalid

delete

public void delete(long lCategoryId)
            throws TdWSException

Deletes the category specified by lCategoryId.

Once deleted, the category cannot be recovered.
All the elements under that category are recursively deleted. Any favorites/subscriptions that users hold on the category elements are cleaned up as well.
Root category, with category id -1 cannot be deleted.

Parameters:

lCategoryId - - Id representing the category to be deleted.

Throws:

TdWSException - - Thrown on

• any exception in deleting the category
• if the user doesnot have permissions to the delete the category
• if the user doesnot have access to the category

create

public Category create(long lParentId,
                       CategoryDefinition cDef)
                throws TdWSException

Creates a new category in the repository.

If lParentId is -1, then a root level category is created.
Otherwise, a category is created under the container represented by lParentId. An exception is raised if lParentId does not materialize to a valid category.
The properties of the category to be created are specified in the category definition bean cDef.
Category Name and Category Displayname are mandatory arguments in category definition bean and hence they cannot be null.
Category name and display name should be carefully choosen so that they do not clash with those of any other category or forum at the same level. Otherwise, an exception is raised.

Parameters:

lParentId - - Id representing parent category under which a new category is to be created.

cDef - - Category definition bean, representing category properties.

Returns:

Category - Category bean, representing category created.

Throws:

TdWSException - - Thrown on

• any exception in creating the category
• if the user doesnot have permissions to the create the category
• if the user doesnot have access to the category specified by lParentId
• if lParentId doesnot represent a valid category
• is cDef is null or invalid

getCategoryById

public Category getCategoryById(long lCategoryId)
                         throws TdWSException

Retrieves the category specified by lCategoryId.

Parameters:

lCategoryId - - Id representing the category to be retrieved.

Returns:

Category - Category bean, representing the category retrieved.

Throws:

TdWSException - - Thrown on

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

getCategorySettings

public CategorySettings getCategorySettings(long lCategoryId)
                                     throws TdWSException

Retrieves category settings specified by lCategoryId.

Settings specify category's

• Description
• Name
• Display name
• Creator
• Creation date and time

They can be configured and edited by the creator of the category or any user with the role higher than or equivalent to that.

Parameters:

lCategoryId - - Id representing the category for which, settings are to be retrieved.

Returns:

CategorySettings - Category settings bean, representing settings retrieved.

Throws:

TdWSException - - Thrown on

• any exception in retrieving the category settings
• if the user doesnot have access to the category specified by lCategoryId
• if lCategoryId doesnot represent a valid category

updateCategorySettings

public CategorySettings updateCategorySettings(long lCategoryId,
                                               CategorySettings cSettings)
                                        throws TdWSException

Updates the settings of the category specified by lCategoryId.

Only the category displayname and description can be edited.
Category name, cannot be edited once the category is created.
Category display name should be edited so that it doesnot clash with the display name of any other category or forum at the same level.
Category display name is mandatory, and hence it cannot be specified as null.

Parameters:

lCategoryId - - Id representing a category whose settings are to be updated.

cSettings - - Category settings bean representing the new settings to be applied.

Returns:

CategorySettings - Updated category settings.

Throws:

TdWSException - - Thrown on

• any exception in updating the category settings
• if the user doesnot have access to the category specified by lCategoryId
• if lCategoryId doesnot represent a valid category
• if the user doesnot have permissions to update the category settings
• if the cSettings bean is null or invalid

createCategories

public CreateCategoryBulkResponse[] createCategories(long lParentId,
                                                     CategoryDefinition[] cDefn)
                                              throws TdWSException

Creates categories specified by array of cDefn beans, under the container specified by lParentId.

Category name and display name are mandatory in each of the category definition beans. An exception is raised if any of name and display name of categories at the same level clash.
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 category bean, representing the category created - If the category creation is successful.
• details of the error, like error message, error code, stack trace, if the category creation failed.

Parameters:

lParentId - - Id specifying the parent container under which the categories are created.

cDefn - - An array of category definition beans.

Returns:

CreateCategoryBulkResponse - An array of bulk response beans.

Throws:

TdWSException - - Thrown on

• any fatal exception in creating the categories. 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 cDefn is null or invalid

deleteCategories

public DeleteElementBulkResponse[] deleteCategories(long[] lCategoryIds)
                                             throws TdWSException

Deletes the categories specified by an array of category ids.

Root category (specified by id -1) cannot be deleted.
Once deleted, a category cannot be recovered again. All the contents of the categories deleted, are deleted as well.
Returns an array of bulk response beans if there is any error in deleting any of the categories. 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:

lCategoryIds - - Array of category ids specifying the categories to be deleted.

Returns:

- An array of bulk response beans representing the failed categories.

Throws:

TdWSException - - Thrown on

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