com.bookpac.server.contentcategory
Interface IWSContentCategoryMgmt

All Superinterfaces:

IWS

public interface IWSContentCategoryMgmt
extends IWS

WS content category mgmt interface for local use

Author:

gregor

Method Summary

void	addCategorySortingScoreExpression(String token, String expression, int scoreBoost) Add a score expression to the catalog defined by the token's nature.
String	createContentCategory(String token, String parentCategoryID, String name, String filter) Creates a new, empty catalog content category.
void	createSourceContentCategoryReplication(String token, String sourceCategoryID, String targetCategoryID, WSTReplicationCreationType replicationCreationType) Creates a source content replication.
void	deleteContentCategory(String token, String categoryID) Deletes a content category and all subcategories.
ArrayList<WSTContentCategory>	getCatalogContentCategoryRoots(String token) Retrieves all content category roots (i.e.
ArrayList<WSTContentCategory>	getCatalogContentCategoryRootsBySearchSource(String token, int minimumDocuments, ArrayList<String> sources) Retrieves the roots for a user.
ArrayList<WSTContentCategory>	getCatalogContentCategoryRootsForUser(String token, int subCategoryLevel, int minimumDocuments) Retrieves the roots for a user.
ArrayList<WSTContentCategoryScoreExpression>	getCategoryScoreExpressions(String token) Get a list with all score expressions applicable to the catalog denoted by the token's nature.
ArrayList<WSTContentCategory>	getChildren(String token, String contentCategoryID, int minimumDocuments, int offset, int count) Retrieves the direct children of a content category ordered by name.
ArrayList<WSTContentCategory>	getChildrenBySearchSource(String token, String contentCategoryID, int minimumDocuments, ArrayList<String> sources, int offset, int count) Retrieves the direct children of a content category ordered by name.
WSTContentCategory	getContentCategory(String token, String contentCategoryID, boolean includeSubCategories, String sortBy, boolean invert, int offset, int count) Retrieves a content category
WSTContentCategory	getContentCategoryBySearchSource(String token, String contentCategoryID, boolean includeSubCategories, String search, ArrayList<String> sources, String sortBy, boolean invert, int offset, int count) Retrieves a content category
WSTContentCategory	getContentCategoryConstrained(String token, String contentCategoryID, boolean includeSubCategories, String search, String sortBy, boolean invert, int offset, int count) Retrieves a content category
WSTContentCategory	getContentCategoryRoot(String token) Deprecated. use getCatalogContentCategoryRoots(String) instead.
ArrayList<WSTContentCategory>	getContentCategoryRootForUser(String token, int subCategoryLevel, int minimumDocuments) Deprecated. use getCatalogContentCategoryRootsForUser(String, int, int) , this method will insert a virtual root category.
WSTContentSourceCategory	getContentSourceCategory(String token, String categoryID) Get the content source category of the given ID.
ArrayList<WSTContentCategory>	getParents(String token, String contentCategoryID, int offset, int count) Deprecated. a category has only a single parent, use getContentCategory(String, String, boolean, String, boolean, int, int) instead. Note, offset, count will be ignored.
ArrayList<String>	getSourceCategoriesForCatalogCategory(String token, String categoryID) Get the replication sources for the given category.
ArrayList<WSTContentSourceCategory>	getSourceContentCategoriesForDocument(String token, String documentID) Retrieves all source content categories for the given document.
ArrayList<WSTContentSourceCategory>	getSourceContentCategoryRoots(String token) Retrieves all source content category roots.
void	rebuildScoreCache(String token) Rebuild the score cache to apply changes to score expressions.
void	removeCategorySortingScoreExpression(String token, String expression) Remove the score given expression from the list applicable to the catalog denoted by the token's nature.
void	updateContentCategory(String token, String categoryID, String name, String filter) Updates a content category.

Method Detail

getContentCategory

WSTContentCategory getContentCategory(String token,
                                      String contentCategoryID,
                                      boolean includeSubCategories,
                                      @Nullable
                                      String sortBy,
                                      boolean invert,
                                      int offset,
                                      int count)
                                      throws WSException

Retrieves a content category

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

includeSubCategories - if the documents of sub categories should be returned, too

sortBy - sort the documents by this search field, may be null

invert - if true, sorting order will be reversed

offset - the offset of the first document of the category to be included in the result

count - the maximum number of documents to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category

Throws:

WSException - if an exception occurs

getContentCategoryConstrained

WSTContentCategory getContentCategoryConstrained(String token,
                                                 String contentCategoryID,
                                                 boolean includeSubCategories,
                                                 @Nullable
                                                 String search,
                                                 @Nullable
                                                 String sortBy,
                                                 boolean invert,
                                                 int offset,
                                                 int count)
                                                 throws WSException

Retrieves a content category

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

includeSubCategories - if the documents of sub categories should be returned, too

search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lowercased english localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

sortBy - sort the documents by this search field, may be null

invert - if true, sorting order will be reversed

offset - the offset of the first document of the category to be included in the result

count - the maximum number of documents to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category

Throws:

WSException - if an exception occurs

getContentCategoryBySearchSource

WSTContentCategory getContentCategoryBySearchSource(String token,
                                                    String contentCategoryID,
                                                    boolean includeSubCategories,
                                                    @Nullable
                                                    String search,
                                                    @Nullable
                                                    ArrayList<String> sources,
                                                    @Nullable
                                                    String sortBy,
                                                    boolean invert,
                                                    int offset,
                                                    int count)
                                                    throws WSException

Retrieves a content category

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

includeSubCategories - if the documents of sub categories should be returned, too

search - the search String. This is either a plain String to search all attributes, or a fielded String like "field:value". All attribute IDs are valid field IDs. You can also user their lowercased english localizations, so "author:gaddis" is equivalent to "20514d7d-7591-49a4-a62d-f5c02a8f5edd:gaddis". There are some special (non-attribute) fields: currentVersionFormat, currentVersionNumber, originalURL, displayName and fileName. Search terms separated by spaces are ANDed. Boolean Operators OR and AND NOT are allowed, so are brackets.

A search returning all PDF documents written by Gaddis would be "author:Gaddis AND currentVersionFormat:PDF", using the author attribute and the currentVersionFormat special field.

sources - see WSTDocumentSearchSource, excluding WSTDocumentSearchSource.OWN and WSTDocumentSearchSource.OTHER

sortBy - sort the documents by this search field, may be null

invert - if true, sorting order will be reversed

offset - the offset of the first document of the category to be included in the result

count - the maximum number of documents to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category

Throws:

WSException - if an exception occurs

getContentCategoryRoot

@Deprecated
WSTContentCategory getContentCategoryRoot(String token)
                                          throws WSException

Deprecated. use getCatalogContentCategoryRoots(String) instead.

Retrieves a content category root. It has no documents in it

Parameters:

token - the session ID, must be != null and valid

Returns:

a document list or null if no such document list exists

Throws:

WSException - if an exception occurs

getCatalogContentCategoryRoots

ArrayList<WSTContentCategory> getCatalogContentCategoryRoots(String token)
                                                             throws WSException

Retrieves all content category roots (i.e. categories without a parent) of the given nature. The list of documents ids of the category object will be empty.

Parameters:

token - the session ID, must be != null and valid

Returns:

a list of category objects

Throws:

WSException - if an exception occurs

getSourceContentCategoryRoots

ArrayList<WSTContentSourceCategory> getSourceContentCategoryRoots(String token)
                                                                  throws WSException

Retrieves all source content category roots.

Parameters:

token - the session ID, must be != null and valid

Returns:

a list of content source categories.

Throws:

WSException - if an exception occurs

getParents

@Deprecated
ArrayList<WSTContentCategory> getParents(String token,
                                                    String contentCategoryID,
                                                    int offset,
                                                    int count)
                                         throws WSException

Deprecated. a category has only a single parent, use getContentCategory(String, String, boolean, String, boolean, int, int) instead. Note, offset, count will be ignored.

Retrieves the parent of a content category. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

offset - the offset of the first content category of the list to be included in the result

count - the maximum number of content categories to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category list

Throws:

WSException - if an exception occurs

getChildren

ArrayList<WSTContentCategory> getChildren(String token,
                                          String contentCategoryID,
                                          int minimumDocuments,
                                          int offset,
                                          int count)
                                          throws WSException

Retrieves the direct children of a content category ordered by name. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

minimumDocuments - skip categories that do not have at least this many documents (including sub-categories)

offset - the offset of the first content category of the list to be included in the result

count - the maximum number of content categories to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category list

Throws:

WSException - if an exception occurs

getChildrenBySearchSource

ArrayList<WSTContentCategory> getChildrenBySearchSource(String token,
                                                        String contentCategoryID,
                                                        int minimumDocuments,
                                                        @Nullable
                                                        ArrayList<String> sources,
                                                        int offset,
                                                        int count)
                                                        throws WSException

Retrieves the direct children of a content category ordered by name. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - the session ID, must be != null and valid

contentCategoryID - the ID of the content category where the documents reside

minimumDocuments - skip categories that do not have at least this many documents (including sub-categories) in the sources provided

sources - see WSTDocumentSearchSource, excluding WSTDocumentSearchSource.OWN and WSTDocumentSearchSource.OTHER

offset - the offset of the first content category of the list to be included in the result

count - the maximum number of content categories to include in the result. Use -1 to indicate that all elements should be included

Returns:

a category list

Throws:

WSException - if an exception occurs

getContentCategoryRootForUser

@Deprecated
ArrayList<WSTContentCategory> getContentCategoryRootForUser(String token,
                                                                       int subCategoryLevel,
                                                                       int minimumDocuments)
                                                            throws WSException

Deprecated. use getCatalogContentCategoryRootsForUser(String, int, int) , this method will insert a virtual root category.

Retrieves the root for a user. It is the first element of the map. If children categories are included, they can be retrieved from the list by their ID. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - a valid token

subCategoryLevel - how many levels of sub categories to get (-1 for unlimited, 0 for the virtual root, 1 for the real root categories only, 2 for the real root categories and children)

minimumDocuments - skip categories that do not have at least this many documents (including sub-categories)

Returns:

a list containing the user's root category and (if requested) its sub categories

Throws:

WSException - if an exception occurs

getCatalogContentCategoryRootsForUser

ArrayList<WSTContentCategory> getCatalogContentCategoryRootsForUser(String token,
                                                                    int subCategoryLevel,
                                                                    int minimumDocuments)
                                                                    throws WSException

Retrieves the roots for a user. They are the first elements of the list. If children categories are included, they can be retrieved from the list by their ID. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - a valid token

subCategoryLevel - how many levels of sub categories to get (-1 for unlimited, 0 for the root categories only, 1 for root categories and children)

minimumDocuments - skip categories that do not have at least this many documents (including sub-categories)

Returns:

a list containing the user's root categories and (if requested) its sub categories

Throws:

WSException - if an exception occurs

getCatalogContentCategoryRootsBySearchSource

ArrayList<WSTContentCategory> getCatalogContentCategoryRootsBySearchSource(String token,
                                                                           int minimumDocuments,
                                                                           @Nullable
                                                                           ArrayList<String> sources)
                                                                           throws WSException

Retrieves the roots for a user. In every content category, the documentIDs field is empty (they have to be retrieved separately).

Parameters:

token - a valid token

minimumDocuments - skip categories that do not have at least this many documents (including sub-categories) in the sources provided

sources - see WSTDocumentSearchSource, excluding WSTDocumentSearchSource.OWN and WSTDocumentSearchSource.OTHER

Returns:

a list containing the user's root categories and (if requested) its sub categories

Throws:

WSException - if an exception occurs

createContentCategory

String createContentCategory(String token,
                             String parentCategoryID,
                             String name,
                             String filter)
                             throws WSException

Creates a new, empty catalog content category.

Parameters:

token - a valid token

parentCategoryID - the parent of the new content category

name - the name of the new content category

filter - a filter in lucene query language. This is for future use, do not use now, pass null

Returns:

the ID of the new category

Throws:

WSException - if an exception occurs

deleteContentCategory

void deleteContentCategory(String token,
                           String categoryID)
                           throws WSException

Deletes a content category and all subcategories.

Parameters:

token - a valid token

categoryID - the parent of the new content category

Throws:

WSException - if an exception occurs

updateContentCategory

void updateContentCategory(String token,
                           String categoryID,
                           @Nullable
                           String name,
                           @Nullable
                           String filter)
                           throws WSException

Updates a content category.

Parameters:

token - a valid token

categoryID - the ID of the content category to update

name - the new name of the category, may be null for no change

filter - the new filter for the category, may be null for no change

Throws:

WSException - if an exception occurs

getContentSourceCategory

@Nonnull
WSTContentSourceCategory getContentSourceCategory(@Nonnull
                                                          String token,
                                                          @Nonnull
                                                          String categoryID)
                                                  throws WSException

Get the content source category of the given ID.

Parameters:

token - a token.

categoryID - a category id.

Returns:

a category, never null

Throws:

WSException - in case of errors.

getSourceCategoriesForCatalogCategory

@Nonnull
ArrayList<String> getSourceCategoriesForCatalogCategory(@Nonnull
                                                                String token,
                                                                @Nonnull
                                                                String categoryID)
                                                        throws WSException

Get the replication sources for the given category.

Parameters:

token - a token.

categoryID - a catalog category id.

Returns:

a possibly empty list of content source category ids.

Throws:

WSException - in case of errors.

createSourceContentCategoryReplication

void createSourceContentCategoryReplication(String token,
                                            String sourceCategoryID,
                                            String targetCategoryID,
                                            WSTReplicationCreationType replicationCreationType)
                                            throws WSException

Creates a source content replication. Replications link content from content source categories into content (catalog) categories. As a result, the content will become visible in the content category. Initially, all content is only available in fixed content source categories. The user nature specific content category trees are more flexible and receive their content from content source category replications. More than one content source category can be mapped into a content category. If replicationCreationType is MAP_SINGLE_LEVEL, this method creates a replication between precisely one content source category and one content category. If replicationCreationType is MAP_AND_MERGE_RECURSIVELY, this method creates a replication between the given categories, and recursively so for all subcategories of the source category. If a category of the same name exists at any level, no new node will be created, just the replication will. If no node for a given source category exists, a new node will be created. A "merged tree" will be created. If replicationCreationType is MAP_AND_FLATTEN_RECURSIVELY, this method will create a replication between the given categories, and recursively between all subcategories of the source category and the given target category. No new subcategories will be created in the target category. The source category tree will be flattened into the target category.

Parameters:

token - a valid token

sourceCategoryID - the ID of the source category to be replicated

targetCategoryID - the ID of the category into which the content shall be replicated. Must belong to the executing user's user nature.

replicationCreationType - depending on the creation type, a simple mapping, a merged tree, or a flattened mapping will be created.

Throws:

WSException - if an exception occurs

addCategorySortingScoreExpression

void addCategorySortingScoreExpression(@Nonnull
                                       String token,
                                       @Nonnull
                                       String expression,
                                       int scoreBoost)
                                       throws WSException

Add a score expression to the catalog defined by the token's nature. A score expression is a lucene expression that will be applied to catalog documents in order to increase (or decrease by means of a negative boost) the sorting score of a document when queried via a category. The sorting score determines the order of the returned list of documents for a category.

Parameters:

token - a token with right EDIT_CATALOG_CATEGORIES.

expression - a lucene expression.

scoreBoost - an increment or decrement to the score if the expression matches.

Throws:

WSException - in case of errors.

removeCategorySortingScoreExpression

void removeCategorySortingScoreExpression(@Nonnull
                                          String token,
                                          @Nonnull
                                          String expression)
                                          throws WSException

Remove the score given expression from the list applicable to the catalog denoted by the token's nature.

Parameters:

token - a token with right EDIT_CATALOG_CATEGORIES.

expression - a lucene expression.

Throws:

WSException - in case of errors.

getCategoryScoreExpressions

@Nonnull
ArrayList<WSTContentCategoryScoreExpression> getCategoryScoreExpressions(@Nonnull
                                                                                 String token)
                                                                         throws WSException

Get a list with all score expressions applicable to the catalog denoted by the token's nature.

Parameters:

token - a token with right EDIT_CATALOG_CATEGORIES.

Returns:

a (possibly empty) list of score expressions.

Throws:

WSException - in case of errors.

rebuildScoreCache

void rebuildScoreCache(@Nonnull
                       String token)
                       throws WSException

Rebuild the score cache to apply changes to score expressions.

Parameters:

token - a token with right EDIT_CATALOG_CATEGORIES.

Throws:

WSException - in case of errors.

getSourceContentCategoriesForDocument

ArrayList<WSTContentSourceCategory> getSourceContentCategoriesForDocument(String token,
                                                                          String documentID)
                                                                          throws WSException

Retrieves all source content categories for the given document.

Parameters:

token - the session ID, must be != null and valid

documentID - the document id.

Returns:

a list of content source categories.

Throws:

WSException - if an exception occurs