org.opencms.relations

Class CmsCategoryService

java.lang.Object

org.opencms.relations.CmsCategoryService

public class CmsCategoryService
extends java.lang.Object

Provides several simplified methods for manipulating category relations.

Since:

6.9.2

See Also:

CmsCategory

Field Summary

Fields

Modifier and Type	Field and Description
static java.lang.String	CENTRALIZED_REPOSITORY The centralized path for categories.
static java.lang.String	REPOSITORY_BASE_FOLDER The folder for the local category repositories.

Constructor Summary

Constructors

Constructor and Description
CmsCategoryService()

Method Summary

Modifier and Type	Method and Description
void	addResourceToCategory(CmsObject cms, java.lang.String resourceName, CmsCategory category) Adds a resource identified by the given resource name to the given category.
void	addResourceToCategory(CmsObject cms, java.lang.String resourceName, java.lang.String categoryPath) Adds a resource identified by the given resource name to the category identified by the given category path.
void	clearCategoriesForResource(CmsObject cms, java.lang.String resourcePath) Removes the given resource from all categories.
void	copyCategories(CmsObject cms, CmsResource fromResource, java.lang.String toResourceSitePath) Adds all categories from one resource to another, skipping categories that are not available for the resource copied to.
CmsCategory	createCategory(CmsObject cms, CmsCategory parent, java.lang.String name, java.lang.String title, java.lang.String description, java.lang.String referencePath) Creates a new category.
void	deleteCategory(CmsObject cms, java.lang.String categoryPath, java.lang.String referencePath) Deletes the category identified by the given path.
CmsCategory	getCategory(CmsObject cms, CmsResource resource) Creates a category from the given resource.
CmsCategory	getCategory(CmsObject cms, java.lang.String categoryRootPath) Creates a category from the given category root path.
java.util.List<java.lang.String>	getCategoryRepositories(CmsObject cms, java.lang.String referencePath) Returns all category repositories for the given reference path.
static CmsCategoryService	getInstance() Returns the singleton instance.
java.lang.String	getRepositoryBaseFolderName(CmsObject cms) Returns the category repositories base folder name.
java.util.List<CmsCategory>	localizeCategories(CmsObject cms, java.util.List<CmsCategory> categories, java.util.Locale locale) Localizes a list of categories by reading locale-specific properties for their title and description, if possible.
CmsCategory	localizeCategory(CmsObject cms, CmsCategory category, java.util.Locale locale) Localizes a single category by reading its locale-specific properties for title and description, if possible.
void	moveCategory(CmsObject cms, java.lang.String oldCatPath, java.lang.String newCatPath, java.lang.String referencePath) Renames/Moves a category from the old path to the new one.
java.util.List<CmsCategory>	readCategories(CmsObject cms, java.lang.String parentCategoryPath, boolean includeSubCats, java.lang.String referencePath) Returns all categories given some search parameters.
java.util.List<CmsCategory>	readCategoriesForRepositories(CmsObject cms, java.lang.String parentCategoryPath, boolean includeSubCats, java.util.List<java.lang.String> repositories) Returns all categories given some search parameters.
java.util.List<CmsCategory>	readCategoriesForRepositories(CmsObject cms, java.lang.String parentCategoryPath, boolean includeSubCats, java.util.List<java.lang.String> repositories, boolean includeRepositories) Returns all categories given some search parameters.
CmsCategory	readCategory(CmsObject cms, java.lang.String categoryPath, java.lang.String referencePath) Reads all categories identified by the given category path for the given reference path.
java.util.List<CmsResource>	readCategoryResources(CmsObject cms, java.lang.String categoryPath, boolean recursive, java.lang.String referencePath) Reads the resources for a category identified by the given category path.
java.util.List<CmsResource>	readCategoryResources(CmsObject cms, java.lang.String categoryPath, boolean recursive, java.lang.String referencePath, CmsResourceFilter resFilter) Reads the resources for a category identified by the given category path.
java.util.List<CmsCategory>	readResourceCategories(CmsObject cms, CmsResource resource) Reads the categories for a resource.
java.util.List<CmsCategory>	readResourceCategories(CmsObject cms, java.lang.String resourceName) Reads the categories for a resource identified by the given resource name.
void	removeResourceFromCategory(CmsObject cms, java.lang.String resourceName, CmsCategory category) Removes a resource identified by the given resource name from the given category.
void	removeResourceFromCategory(CmsObject cms, java.lang.String resourceName, java.lang.String categoryPath) Removes a resource identified by the given resource name from the category identified by the given category path.
void	repairRelations(CmsObject cms, CmsResource resource) Repairs broken category relations.
void	repairRelations(CmsObject cms, java.lang.String resourceName) Repairs broken category relations.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

CENTRALIZED_REPOSITORY

public static final java.lang.String CENTRALIZED_REPOSITORY

The centralized path for categories.

See Also:

Constant Field Values

REPOSITORY_BASE_FOLDER

public static final java.lang.String REPOSITORY_BASE_FOLDER

The folder for the local category repositories.

See Also:

Constant Field Values

Constructor Detail

CmsCategoryService

public CmsCategoryService()

Method Detail

getInstance

public static CmsCategoryService getInstance()

Returns the singleton instance.

Returns:

the singleton instance

addResourceToCategory

public void addResourceToCategory(CmsObject cms,
                                  java.lang.String resourceName,
                                  CmsCategory category)
                           throws CmsException

Adds a resource identified by the given resource name to the given category.

The resource has to be locked.

Parameters:

cms - the current cms context

resourceName - the site relative path to the resource to add

category - the category to add the resource to

Throws:

CmsException - if something goes wrong

addResourceToCategory

public void addResourceToCategory(CmsObject cms,
                                  java.lang.String resourceName,
                                  java.lang.String categoryPath)
                           throws CmsException

Adds a resource identified by the given resource name to the category identified by the given category path.

Only the most global category matching the given category path for the given resource will be affected.

The resource has to be locked.

Parameters:

cms - the current cms context

resourceName - the site relative path to the resource to add

categoryPath - the path of the category to add the resource to

Throws:

CmsException - if something goes wrong

clearCategoriesForResource

public void clearCategoriesForResource(CmsObject cms,
                                       java.lang.String resourcePath)
                                throws CmsException

Removes the given resource from all categories.

Parameters:

cms - the cms context

resourcePath - the resource to reset the categories for

Throws:

CmsException - if something goes wrong

copyCategories

public void copyCategories(CmsObject cms,
                           CmsResource fromResource,
                           java.lang.String toResourceSitePath)
                    throws CmsException

Adds all categories from one resource to another, skipping categories that are not available for the resource copied to. The resource where categories are copied to has to be locked.

Parameters:

cms - the CmsObject used for reading and writing.

fromResource - the resource to copy the categories from.

toResourceSitePath - the full site path of the resource to copy the categories to.

Throws:

CmsException - thrown if copying the resources fails.

createCategory

public CmsCategory createCategory(CmsObject cms,
                                  CmsCategory parent,
                                  java.lang.String name,
                                  java.lang.String title,
                                  java.lang.String description,
                                  java.lang.String referencePath)
                           throws CmsException

Creates a new category.

Will use the same category repository as the parent if specified, or the closest category repository to the reference path if specified, or the centralized category repository in all other cases.

Parameters:

cms - the current cms context

parent - the parent category or null for a new top level category

name - the name of the new category

title - the title

description - the description

referencePath - the reference path for the category repository

Returns:

the new created category

Throws:

CmsException - if something goes wrong

deleteCategory

public void deleteCategory(CmsObject cms,
                           java.lang.String categoryPath,
                           java.lang.String referencePath)
                    throws CmsException

Deletes the category identified by the given path.

Only the most global category matching the given category path for the given resource will be affected.

This method will try to lock the involved resource.

Parameters:

cms - the current cms context

categoryPath - the path of the category to delete

referencePath - the reference path to find the category repositories

Throws:

CmsException - if something goes wrong

getCategory

public CmsCategory getCategory(CmsObject cms,
                               CmsResource resource)
                        throws CmsException

Creates a category from the given resource.

Parameters:

cms - the cms context

resource - the resource

Returns:

a category object

Throws:

CmsException - if something goes wrong

getCategory

public CmsCategory getCategory(CmsObject cms,
                               java.lang.String categoryRootPath)
                        throws CmsException

Creates a category from the given category root path.

Parameters:

cms - the cms context

categoryRootPath - the category root path

Returns:

a category object

Throws:

CmsException - if something goes wrong

getCategoryRepositories

public java.util.List<java.lang.String> getCategoryRepositories(CmsObject cms,
                                                                java.lang.String referencePath)

Returns all category repositories for the given reference path.

Parameters:

cms - the cms context

referencePath - the reference path

Returns:

a list of root paths

getRepositoryBaseFolderName

public java.lang.String getRepositoryBaseFolderName(CmsObject cms)

Returns the category repositories base folder name.

Parameters:

cms - the cms context

Returns:

the category repositories base folder name

localizeCategories

public java.util.List<CmsCategory> localizeCategories(CmsObject cms,
                                                      java.util.List<CmsCategory> categories,
                                                      java.util.Locale locale)

Localizes a list of categories by reading locale-specific properties for their title and description, if possible.

This method does not modify its input list of categories, or the categories in it.

Parameters:

cms - the CMS context to use for reading resources

categories - the list of categories

locale - the locale to use

Returns:

the list of localized categories

localizeCategory

public CmsCategory localizeCategory(CmsObject cms,
                                    CmsCategory category,
                                    java.util.Locale locale)

Localizes a single category by reading its locale-specific properties for title and description, if possible.

Parameters:

cms - the CMS context to use for reading resources

category - the category to localize

locale - the locale to use

Returns:

the localized category

moveCategory

public void moveCategory(CmsObject cms,
                         java.lang.String oldCatPath,
                         java.lang.String newCatPath,
                         java.lang.String referencePath)
                  throws CmsException

Renames/Moves a category from the old path to the new one.

This method will keep all categories in their original repository.

Parameters:

cms - the current cms context

oldCatPath - the path of the category to move

newCatPath - the new category path

referencePath - the reference path to find the category

Throws:

CmsException - if something goes wrong

readCategories

public java.util.List<CmsCategory> readCategories(CmsObject cms,
                                                  java.lang.String parentCategoryPath,
                                                  boolean includeSubCats,
                                                  java.lang.String referencePath)
                                           throws CmsException

Returns all categories given some search parameters.

Parameters:

cms - the current cms context

parentCategoryPath - the path of the parent category to get the categories for

includeSubCats - if to include all categories, or first level child categories only

referencePath - the reference path to find all the category repositories

Returns:

a list of CmsCategory objects

Throws:

CmsException - if something goes wrong

readCategoriesForRepositories

public java.util.List<CmsCategory> readCategoriesForRepositories(CmsObject cms,
                                                                 java.lang.String parentCategoryPath,
                                                                 boolean includeSubCats,
                                                                 java.util.List<java.lang.String> repositories)
                                                          throws CmsException

Returns all categories given some search parameters.

Parameters:

cms - the current cms context

parentCategoryPath - the path of the parent category to get the categories for

includeSubCats - if to include all categories, or first level child categories only

repositories - a list of root paths

Returns:

a list of CmsCategory objects

Throws:

CmsException - if something goes wrong

readCategoriesForRepositories

public java.util.List<CmsCategory> readCategoriesForRepositories(CmsObject cms,
                                                                 java.lang.String parentCategoryPath,
                                                                 boolean includeSubCats,
                                                                 java.util.List<java.lang.String> repositories,
                                                                 boolean includeRepositories)
                                                          throws CmsException

Returns all categories given some search parameters.

Parameters:

cms - the current cms context

parentCategoryPath - the path of the parent category to get the categories for

includeSubCats - if to include all categories, or first level child categories only

repositories - a list of site paths

includeRepositories - flag, indicating if the repositories itself should be returned as category.

Returns:

a list of CmsCategory objects

Throws:

CmsException - if something goes wrong

readCategory

public CmsCategory readCategory(CmsObject cms,
                                java.lang.String categoryPath,
                                java.lang.String referencePath)
                         throws CmsException

Reads all categories identified by the given category path for the given reference path.

Parameters:

cms - the current cms context

categoryPath - the path of the category to read

referencePath - the reference path to find all the category repositories

Returns:

a list of matching categories, could also be empty, if no category exists with the given path

Throws:

CmsException - if something goes wrong

readCategoryResources

public java.util.List<CmsResource> readCategoryResources(CmsObject cms,
                                                         java.lang.String categoryPath,
                                                         boolean recursive,
                                                         java.lang.String referencePath)
                                                  throws CmsException

Reads the resources for a category identified by the given category path.

Parameters:

cms - the current cms context

categoryPath - the path of the category to read the resources for

recursive - true if including sub-categories

referencePath - the reference path to find all the category repositories

Returns:

a list of CmsResource objects

Throws:

CmsException - if something goes wrong

readCategoryResources

public java.util.List<CmsResource> readCategoryResources(CmsObject cms,
                                                         java.lang.String categoryPath,
                                                         boolean recursive,
                                                         java.lang.String referencePath,
                                                         CmsResourceFilter resFilter)
                                                  throws CmsException

Reads the resources for a category identified by the given category path.

Parameters:

cms - the current cms context

categoryPath - the path of the category to read the resources for

recursive - true if including sub-categories

referencePath - the reference path to find all the category repositories

resFilter - the resource filter to use

Returns:

a list of CmsResource objects

Throws:

CmsException - if something goes wrong

readResourceCategories

public java.util.List<CmsCategory> readResourceCategories(CmsObject cms,
                                                          CmsResource resource)
                                                   throws CmsException

Reads the categories for a resource.

Parameters:

cms - the current cms context

resource - the resource to get the categories for

Returns:

the categories list

Throws:

CmsException - if something goes wrong

readResourceCategories

public java.util.List<CmsCategory> readResourceCategories(CmsObject cms,
                                                          java.lang.String resourceName)
                                                   throws CmsException

Reads the categories for a resource identified by the given resource name.

Parameters:

cms - the current cms context

resourceName - the path of the resource to get the categories for

Returns:

the categories list

Throws:

CmsException - if something goes wrong

removeResourceFromCategory

public void removeResourceFromCategory(CmsObject cms,
                                       java.lang.String resourceName,
                                       CmsCategory category)
                                throws CmsException

Removes a resource identified by the given resource name from the given category.

The resource has to be previously locked.

Parameters:

cms - the current cms context

resourceName - the site relative path to the resource to remove

category - the category to remove the resource from

Throws:

CmsException - if something goes wrong

removeResourceFromCategory

public void removeResourceFromCategory(CmsObject cms,
                                       java.lang.String resourceName,
                                       java.lang.String categoryPath)
                                throws CmsException

Removes a resource identified by the given resource name from the category identified by the given category path.

The resource has to be previously locked.

Parameters:

cms - the current cms context

resourceName - the site relative path to the resource to remove

categoryPath - the path of the category to remove the resource from

Throws:

CmsException - if something goes wrong

repairRelations

public void repairRelations(CmsObject cms,
                            CmsResource resource)
                     throws CmsException

Repairs broken category relations.

This could be caused by renaming/moving a category folder, or changing the category repositories base folder name.

Also repairs problems when creating/deleting conflicting category folders across several repositories.

The resource has to be previously locked.

Parameters:

cms - the cms context

resource - the resource to repair

Throws:

CmsException - if something goes wrong

repairRelations

public void repairRelations(CmsObject cms,
                            java.lang.String resourceName)
                     throws CmsException

Repairs broken category relations.

This could be caused by renaming/moving a category folder, or changing the category repositories base folder name.

Also repairs problems when creating/deleting conflicting category folders across several repositories.

The resource has to be previously locked.

Parameters:

cms - the cms context

resourceName - the site relative path to the resource to repair

Throws:

CmsException - if something goes wrong