com.day.cq.tagging

Interface TagManager

All Known Subinterfaces:

SocialTagManager

@ProviderType
public interface TagManager

TagManager allows for resolving and creating tags by paths and names. See Tag for a detailed description of tagging concepts, terminology and the structure of tag IDs.

This interface is generic, but there is a JCR-based reference implementation which can be obtained by the JcrTagManagerFactory - all you need is an existing JCR Session (what tags can be "seen" and which can be created depends on the user of that session):

 TagManager tagManager = JcrTagManagerFactory.getTagManager(session);
 

In the typical Sling context you can also adapt to a TagManager from the ResourceResolver:

 TagManager tagManager = resourceResolver.adaptTo(TagManager.class);
 

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static class	TagManager.FindResults

Method Summary

Modifier and Type	Method and Description
boolean	canCreateTag(java.lang.String tagID) Returns whether the current user (eg.
boolean	canCreateTagByTitle(java.lang.String tagTitlePath) Returns whether the current user (eg.
boolean	canCreateTagByTitle(java.lang.String tagTitlePath, java.util.Locale locale) Returns whether the current user (eg.
Tag	createTag(java.lang.String tagID, java.lang.String title, java.lang.String description) Creates a new tag (or namespace) by creating it in the tag store, eg.
Tag	createTag(java.lang.String tagID, java.lang.String title, java.lang.String description, boolean autoSave) Creates a new tag (or namespace) by creating it in the tag store, eg.
Tag	createTagByTitle(java.lang.String titlePath) Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()).
Tag	createTagByTitle(java.lang.String titlePath, boolean autoSave) Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()).
Tag	createTagByTitle(java.lang.String tagTitlePath, java.util.Locale locale) Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()).
void	deleteTag(Tag tag) Deletes the given tag.
void	deleteTag(Tag tag, boolean autoSave) Deletes the given tag.
RangeIterator<Resource>	find(java.lang.String tagID) Returns all content (Sling Resources, typically JCR Nodes) tagged with the given tag.
RangeIterator<Resource>	find(java.lang.String basePath, java.util.List<java.lang.String[]> tagSetIDs) Returns all content (Sling Resources, typically JCR Nodes) tagged with all or one of the given tags, but only content that lies below the given base path. In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag. Furthermore, when passing a container tag, such as fruit with eg.
RangeIterator<Resource>	find(java.lang.String basePath, java.lang.String[] tagIDs) Returns all content (Sling Resources, typically JCR Nodes) tagged with all of the given tags, but only content that lies below the given base path. In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag. Furthermore, when passing a container tag, such as fruit with eg.
RangeIterator<Resource>	find(java.lang.String basePath, java.lang.String[] tagIDs, boolean oneMatchIsEnough) Returns all content (Sling Resources, typically JCR Nodes) tagged with all or one of the given tags, but only content that lies below the given base path. In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag. Furthermore, when passing a container tag, such as fruit with eg.
TagManager.FindResults	findByTitle(java.lang.String title) Searches for all content that is tagged with a tag that contains the given title as tag title.
java.lang.Iterable<Tag>	findTagsByKeyword(java.lang.String keyword, java.util.Locale locale, java.lang.String tagId) Partial Searches for tags with the given keyword from the title.
Tag[]	findTagsByTitle(java.lang.String keyword, java.util.Locale locale) Searches for tags with the given keyword in the title.
Tag[]	getNamespaces() Retrieves all available tag namespaces as array.
java.util.Iterator<Tag>	getNamespacesIter() Retrieves all available tag namespaces as iterator.
ResourceResolver	getResourceResolver() Convenience method that returns the underlying resource resolver.
Session	getSession() Deprecated. Deprecate in favor of getResourceResolver(). This is consistent with recommended api JcrTagManagerFactory.getTagManager(ResourceResolver) Convenience method that returns the underlying session. Can be used to easily save the session when eg. creating tags with autoSave = false.
java.util.List<java.lang.String>	getSupportedLanguageCodes() Returns the List of language codes support by Tag
Tag[]	getTags(Resource resource) Retrieves the tags set on the given resource.
Tag[]	getTagsForSubtree(Resource resource, boolean shallow) Retrieves the tags set on the given resource and/or all its child resources (aka subtree).
void	mergeTag(Tag tag, Tag destination) Merges a tag with another one.
Tag	moveTag(Tag tag, java.lang.String destination) Moves a tag.
Tag	resolve(java.lang.String tagID) Resolves a tag (or namespace) object by a shorthand tag id, such as sky or dam:fruit/apple, or by the absolute path to a tag, such as {base.path}/dam/fruit/apple.
Tag	resolveByTitle(java.lang.String tagTitlePath) Resolves a tag (or namespace) object by a title or path of titles (corresponding to Tag.getTitlePath()).
Tag	resolveByTitle(java.lang.String tagTitlePath, java.util.Locale locale) Resolves a tag (or namespace) object by a title or path of titles (corresponding to Tag.getTitlePath()) in the given locale.
void	setTags(Resource resource, Tag[] tags) Sets tags on the given resource.
void	setTags(Resource resource, Tag[] tags, boolean autoSave) Sets tags on the given resource.

Method Detail

resolve

Tag resolve(java.lang.String tagID)

Resolves a tag (or namespace) object by a shorthand tag id, such as sky or dam:fruit/apple, or by the absolute path to a tag, such as {base.path}/dam/fruit/apple. Namespaces can be resolved by either using the absolute path to a namespace (one level below the tag base path, eg. normally {base.path}/namespace) or by using the tag id form for namespaces: namespace:

Parameters:

tagID - a shorthand tag id or an absolute tag path

Returns:

a Tag object or null if the tag does not exist

resolveByTitle

Tag resolveByTitle(java.lang.String tagTitlePath)

Resolves a tag (or namespace) object by a title or path of titles (corresponding to Tag.getTitlePath()). Note that the system does not ensure unique title paths, but this method should be used before creating a new tag using createTagByTitle(String) to avoid basic collisions.

Parameters:

tagTitlePath - a path that includes titles rather than IDs

Returns:

a Tag object (first one found with this title path) or null if a tag with such a title path does not exist

resolveByTitle

Tag resolveByTitle(java.lang.String tagTitlePath,
                   java.util.Locale locale)

Resolves a tag (or namespace) object by a title or path of titles (corresponding to Tag.getTitlePath()) in the given locale.

Note that the system does not ensure unique title paths, but this method should be used before creating a new tag using createTagByTitle(String) to avoid basic collisions.

Parameters:

tagTitlePath - a path that includes titles rather than IDs

locale - the locale of the titlePath

Returns:

a Tag object (first one found with this title path) or null if a tag with such a title path does not exist

canCreateTag

boolean canCreateTag(java.lang.String tagID)
              throws InvalidTagFormatException

Returns whether the current user (eg. from the underlying JCR session) is allowed to add the specified tag. If the tag already exists, false is returned. Basically it checks if a call to createTag(String, String, String) will be successful.

Parameters:

tagID - a shorthand tag id or an absolute tag path

Returns:

true if the current user could create the tag, false if not or if the tag already exists

Throws:

InvalidTagFormatException - if the parameter tagID is not a valid tag ID

canCreateTagByTitle

boolean canCreateTagByTitle(java.lang.String tagTitlePath)
                     throws InvalidTagFormatException

Returns whether the current user (eg. from the underlying JCR session) is allowed to add the tag specified by a title or path of titles (corresponding to Tag.getTitlePath()). If the tag already exists, false is returned. Basically it checks if a call to createTagByTitle(String) will be successful.

Parameters:

tagTitlePath - a path that includes titles rather than IDs

Returns:

true if the current user could create the tag, false if not. There is no check if the tag exists already, ie. it could return true if the tag is already existing.

Throws:

InvalidTagFormatException - if the parameter titlePath references a non-existing namespace (please note that you cannot create namespaces via createTagByTitle(String))

canCreateTagByTitle

boolean canCreateTagByTitle(java.lang.String tagTitlePath,
                            java.util.Locale locale)
                     throws InvalidTagFormatException

Returns whether the current user (eg. from the underlying JCR session) is allowed to add the tag specified by a title or path of titles (corresponding to Tag.getTitlePath()). If the tag already exists, false is returned. Basically it checks if a call to createTagByTitle(String) will be successful.

This will resolve the parent tag or namespace using the title in the given locale and then set both the default title and the localized title for the new tag.

Parameters:

tagTitlePath - a path that includes titles rather than IDs

locale - the locale of the titlePath

Returns:

true if the current user could create the tag, false if not. There is no check if the tag exists already, ie. it could return true if the tag is already existing.

Throws:

InvalidTagFormatException - if the parameter titlePath references a non-existing namespace (please note that you cannot create namespaces via createTagByTitle(String))

createTag

Tag createTag(java.lang.String tagID,
              java.lang.String title,
              java.lang.String description)
       throws java.security.AccessControlException,
              InvalidTagFormatException

Creates a new tag (or namespace) by creating it in the tag store, eg. under {base.path}/dam/fruit/apple. If it exists already, the existing tag will be returned, otherwise the object representing the newly created tag. If the current user is not allowed to create a tag, an AccessControlException will be thrown and no changes will be made.

The tag is defined by a shorthand tag id, such as sky or dam:fruit/apple, or by the absolute path to a tag, such as {base.path}/dam/fruit/apple. Namespaces can be created by either using the absolute path to a namespace (one level below the tag base path, eg. normally {base.path}/namespace) or by using the tag id form for namespaces: namespace:

This will automatically save the node or session.

Parameters:

tagID - a shorthand tag id or an absolute tag path

title - a title for the tag (can be null)

description - a longer description for the tag (can be null)

Returns:

a Tag object (never null)

Throws:

java.security.AccessControlException - if the tag must be created, but the user is not allowed to do so

InvalidTagFormatException - if the parameter tagID is not a valid tag ID

createTag

Tag createTag(java.lang.String tagID,
              java.lang.String title,
              java.lang.String description,
              boolean autoSave)
       throws java.security.AccessControlException,
              InvalidTagFormatException

Creates a new tag (or namespace) by creating it in the tag store, eg. under {base.path}/dam/fruit/apple. If it exists already, the existing tag will be returned, otherwise the object representing the newly created tag. If the current user is not allowed to create a tag, an AccessControlException will be thrown and no changes will be made.

The tag is defined by a shorthand tag id, such as sky or dam:fruit/apple, or by the absolute path to a tag, such as {base.path}/dam/fruit/apple. Namespaces can be created by either using the absolute path to a namespace (one level below the tag base path, eg. normally {base.path}/namespace) or by using the tag id form for namespaces: namespace:

Parameters:

tagID - a shorthand tag id or an absolute tag path

title - a title for the tag (can be null)

description - a longer description for the tag (can be null)

autoSave - whether the session should be automatically saved or not

Returns:

a Tag object (never null)

Throws:

java.security.AccessControlException - if the tag must be created, but the user is not allowed to do so

InvalidTagFormatException - if the parameter tagID is not a valid tag ID

createTagByTitle

Tag createTagByTitle(java.lang.String titlePath)
              throws java.security.AccessControlException,
                     InvalidTagFormatException

Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()).

This will automatically save the node or session.

Parameters:

titlePath - a path that includes titles rather than IDs

Returns:

a Tag object (never null)

Throws:

java.security.AccessControlException - if the tag must be created, but the user is not allowed to do so

InvalidTagFormatException - if the parameter titlePath references a non-existing namespace (please note that this method won't create namespaces)

createTagByTitle

Tag createTagByTitle(java.lang.String titlePath,
                     boolean autoSave)
              throws java.security.AccessControlException,
                     InvalidTagFormatException

Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()).

Parameters:

titlePath - a path that includes titles rather than IDs

autoSave - whether the session should be automatically saved or not

Returns:

a Tag object (never null)

Throws:

java.security.AccessControlException - if the tag must be created, but the user is not allowed to do so

InvalidTagFormatException - if the parameter titlePath references a non-existing namespace (please note that this method won't create namespaces)

createTagByTitle

Tag createTagByTitle(java.lang.String tagTitlePath,
                     java.util.Locale locale)
              throws java.security.AccessControlException,
                     InvalidTagFormatException

Creates a new tag (not namespace, can be specified at the beginning, but must exist) from a title or a path of titles (corresponding to Tag.getTitlePath()). This will resolve the parent tag or namespace using the title in the given locale and then set both the default title and the localized title for the new tag.

This will automatically save the node or session.

Parameters:

tagTitlePath - a path that includes titles rather than IDs

locale - the locale of the titlePath

Returns:

a Tag object (never null)

Throws:

java.security.AccessControlException - if the tag must be created, but the user is not allowed to do so

InvalidTagFormatException - if the parameter titlePath references a non-existing namespace (please note that this method won't create namespaces)

deleteTag

void deleteTag(Tag tag)
        throws java.security.AccessControlException

Deletes the given tag.

This will automatically save the session.

Parameters:

tag - tag to delete

Throws:

java.security.AccessControlException - if the user is not allowed to delete the tag

deleteTag

void deleteTag(Tag tag,
               boolean autoSave)
        throws java.security.AccessControlException

Deletes the given tag.

Parameters:

tag - tag to delete

autoSave - whether the session should be automatically saved or not; note that if the tag was activated already, it gets automatically replicated, and as part of this the session will be saved anyway, thus autoSave=false will only be respected if the tag and its backlinks have never been activated before

Throws:

java.security.AccessControlException - if the user is not allowed to delete the tag

find

RangeIterator<Resource> find(java.lang.String tagID)

Returns all content (Sling Resources, typically JCR Nodes) tagged with the given tag. In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag. Furthermore, when passing a container tag, such as fruit with eg. sub-tags fruit/apple, fruit/apple/braeburn and fruit/banana, all content tagged with it or one of the sub-tags will be found. Convenience method, see also find(String, String[]).

Parameters:

tagID - a tag ID or the full path to a tag

Returns:

a RangeIterator containing all found resources (Note: this is a version of the RangeIterator that supports generics. Returns null if the tag does not exist

See Also:

Tag.find(), find(String, String[])

findByTitle

TagManager.FindResults findByTitle(java.lang.String title)

Searches for all content that is tagged with a tag that contains the given title as tag title. "*" can be used as wildcard in the title. As this method first searches for tags that match the given title, these tags are returned along with the real results in a TagManager.FindResults struct-like class.

Parameters:

title - title of tag to find

Returns:

a find result

findTagsByTitle

Tag[] findTagsByTitle(java.lang.String keyword,
                      java.util.Locale locale)

Searches for tags with the given keyword in the title. "*" can be used as wildcard. A locale can be provided to search in a certain localized tag title only.

Parameters:

keyword - The tag title to be searched

locale - to search in a certain localized tag title only; use null to search in the default title

Returns:

an array of tags found as a result

find

RangeIterator<Resource> find(java.lang.String basePath,
                             java.lang.String[] tagIDs)

Returns all content (Sling Resources, typically JCR Nodes) tagged with all of the given tags, but only content that lies below the given base path.
In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such as fruit with eg. sub-tags fruit/apple, fruit/apple/braeburn and fruit/banana, all content tagged with it or one of the sub-tags will be found.

Parameters:

basePath - The starting node of the search

tagIDs - a list of tag IDs or full paths to tags

Returns:

a RangeIterator containing all found resources (Note: this is a version of the RangeIterator that supports generics. Returns null if the tag does not exist

See Also:

Tag.find(), find(String), find(String, String[], boolean)

find

RangeIterator<Resource> find(java.lang.String basePath,
                             java.lang.String[] tagIDs,
                             boolean oneMatchIsEnough)

Returns all content (Sling Resources, typically JCR Nodes) tagged with all or one of the given tags, but only content that lies below the given base path.
In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such as fruit with eg. sub-tags fruit/apple, fruit/apple/braeburn and fruit/banana, all content tagged with it or one of the sub-tags will be found.

Parameters:

basePath - The starting node of the search

tagIDs - a list of tag IDs or full paths to tags

oneMatchIsEnough - if true all the resources are returned that contain at least one of the given tags.

Returns:

a RangeIterator containing all found resources (Note: this is a version of the RangeIterator that supports generics. Returns null if the tag does not exist

See Also:

Tag.find(), find(String)

find

RangeIterator<Resource> find(java.lang.String basePath,
                             java.util.List<java.lang.String[]> tagSetIDs)

Returns all content (Sling Resources, typically JCR Nodes) tagged with all or one of the given tags, but only content that lies below the given base path.
In the standard JCR-implementation, these are all nodes with a cq:tags property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such as fruit with eg. sub-tags fruit/apple, fruit/apple/braeburn and fruit/banana, all content tagged with it or one of the sub-tags will be found.
This method should be used in the case where we need to join more sets of tags. Such as "(a or b) and (c or d)"

Parameters:

basePath - The starting node of the search

tagSetIDs - a list of lists of tag IDs or full paths to tags

Returns:

a RangeIterator containing all found resources (Note: this is a version of the RangeIterator that supports generics. Returns null if the tag does not exist

See Also:

Tag.find(), find(String), find(String, String[], boolean)

getNamespaces

Tag[] getNamespaces()

Retrieves all available tag namespaces as array.

Returns:

all tag namespaces

See Also:

getNamespacesIter()

getNamespacesIter

java.util.Iterator<Tag> getNamespacesIter()

Retrieves all available tag namespaces as iterator.

Returns:

an iterator over all tag namespaces

See Also:

getNamespaces()

getTags

Tag[] getTags(Resource resource)

Retrieves the tags set on the given resource. Will return tag objects representing the whole repository (as opposed to getTagsForSubtree(org.apache.sling.api.resource.Resource, boolean)).

Note that there is no defined order, the result is effectively a set of tags.

Parameters:

resource - the resource to get the tags from

Returns:

all tags for the given resource (in no defined order)

setTags

void setTags(Resource resource,
             Tag[] tags)

Sets tags on the given resource. Please note that this will completely override the previously set tags.

This will automatically save the node or session.

Parameters:

resource - the resource to set the tags on

tags - the tags to set

setTags

void setTags(Resource resource,
             Tag[] tags,
             boolean autoSave)

Sets tags on the given resource. Please note that this will completely override the previously set tags.

Parameters:

resource - the resource to set the tags on

tags - the tags to set

autoSave - whether the session should be automatically saved or not

getTagsForSubtree

Tag[] getTagsForSubtree(Resource resource,
                        boolean shallow)

Retrieves the tags set on the given resource and/or all its child resources (aka subtree). The returned tag objects will only represent the subtree, ie. especially the count only applies to the subtree.

Parameters:

resource - the resource to get the tags from

shallow - whether tags only directly on this resource should be used (true) or the whole subtree is taken into account (false)

Returns:

all tags for the given subtree (in no defined order)

getSession

@Deprecated
Session getSession()

Deprecated. Deprecate in favor of getResourceResolver(). This is consistent with recommended api JcrTagManagerFactory.getTagManager(ResourceResolver) Convenience method that returns the underlying session. Can be used to easily save the session when eg. creating tags with autoSave = false.

Returns:

the underlying session

getResourceResolver

ResourceResolver getResourceResolver()

Convenience method that returns the underlying resource resolver. Can be used to easily save the changes when eg. creating tags with autoSave = false.

Returns:

the underlying resource resolver instance

moveTag

Tag moveTag(Tag tag,
            java.lang.String destination)
     throws java.security.AccessControlException,
            InvalidTagFormatException,
            TagException

Moves a tag.

Parameters:

tag - the tag to move

destination - new location of the tag, given as shorthand tag id or an absolute tag path

Returns:

the new tag at the new location

Throws:

java.security.AccessControlException - if user is not allowed to move the tag

InvalidTagFormatException - if the parameter destination is not a valid tag ID

TagException - if the tag could not be moved

mergeTag

void mergeTag(Tag tag,
              Tag destination)
       throws java.security.AccessControlException,
              TagException

Merges a tag with another one.

Parameters:

tag - the tag to merge into another one (will no longer exist afterwards)

destination - the tag to merge with (will exist afterwards)

Throws:

java.security.AccessControlException - if user is not allowed to merge the tag

TagException - if the tag could not be merged

getSupportedLanguageCodes

java.util.List<java.lang.String> getSupportedLanguageCodes()

Returns the List of language codes support by Tag

Returns:

A List of language codes support by Tag (e.i. en,ja,kok,..)

findTagsByKeyword

java.lang.Iterable<Tag> findTagsByKeyword(java.lang.String keyword,
                                          java.util.Locale locale,
                                          java.lang.String tagId)

Partial Searches for tags with the given keyword from the title. A locale can be provided to search in a certain localized tag title only. It searches under a specific path only(e.g. {base.path}/NeamSpace/tag1) This API is useful for partial search where full title is not provided to search the tag

Parameters:

keyword - The tag title to be searched

locale - to search in a certain localized tag title only; use null to search in the default title

tagId - Tag Id of the Tag/NameSpace under which tag to be searched.

Returns:

an array of tags found as a result