Interface TagManager
-
public interface TagManager
TagManager
allows for resolving and creating tags by paths and names. SeeTag
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 JCRSession
(what tags can be "seen" and which can be created depends on the user of that session):
In the typical Sling context you can also adapt to aTagManager tagManager = JcrTagManagerFactory.getTagManager(session);
TagManager
from theResourceResolver
:TagManager tagManager = resourceResolver.adaptTo(TagManager.class);
-
-
Nested Class Summary
Nested Classes Modifier and Type Interface Description static class
TagManager.FindResults
-
Method Summary
All Methods Instance Methods Abstract Methods Deprecated Methods Modifier and Type Method Description boolean
canCreateTag(String tagID)
Returns whether the current user (eg.boolean
canCreateTagByTitle(String tagTitlePath)
Returns whether the current user (eg.boolean
canCreateTagByTitle(String tagTitlePath, Locale locale)
Returns whether the current user (eg.Tag
createTag(String tagID, String title, String description)
Creates a new tag (or namespace) by creating it in the tag store, eg.Tag
createTag(String tagID, String title, String description, boolean autoSave)
Creates a new tag (or namespace) by creating it in the tag store, eg.Tag
createTagByTitle(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 toTag.getTitlePath()
).Tag
createTagByTitle(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 toTag.getTitlePath()
).Tag
createTagByTitle(String tagTitlePath, 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 toTag.getTitlePath()
).void
deleteTag(Tag tag)
Deletes the given tag.void
deleteTag(Tag tag, boolean autoSave)
Deletes the given tag.RangeIterator<Resource>
find(String tagID)
RangeIterator<Resource>
find(String basePath, 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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg.RangeIterator<Resource>
find(String basePath, 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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg.RangeIterator<Resource>
find(String basePath, List<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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg.TagManager.FindResults
findByTitle(String title)
Searches for all content that is tagged with a tag that contains the given title as tag title.Iterable<Tag>
findTagsByKeyword(String keyword, Locale locale, String tagId)
Partial Searches for tags with the given keyword from the title.Tag[]
findTagsByTitle(String keyword, Locale locale)
Searches for tags with the given keyword in the title.Tag[]
getNamespaces()
Retrieves all available tag namespaces as array.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 ofgetResourceResolver()
.List<String>
getSupportedLanguageCodes()
Returns the List of language codes support by TagTag[]
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, String destination)
Moves a tag.Tag
resolve(String tagID)
Resolves a tag (or namespace) object by a shorthand tag id, such assky
ordam:fruit/apple
, or by the absolute path to a tag, such as{base.path}/dam/fruit/apple
.Tag
resolveByTitle(String tagTitlePath)
Resolves a tag (or namespace) object by a title or path of titles (corresponding toTag.getTitlePath()
).Tag
resolveByTitle(String tagTitlePath, Locale locale)
Resolves a tag (or namespace) object by a title or path of titles (corresponding toTag.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(String tagID)
Resolves a tag (or namespace) object by a shorthand tag id, such assky
ordam: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(String tagTitlePath)
Resolves a tag (or namespace) object by a title or path of titles (corresponding toTag.getTitlePath()
). Note that the system does not ensure unique title paths, but this method should be used before creating a new tag usingcreateTagByTitle(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(String tagTitlePath, Locale locale)
Resolves a tag (or namespace) object by a title or path of titles (corresponding toTag.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 IDslocale
- 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(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 tocreateTag(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 parametertagID
is not a valid tag ID
-
canCreateTagByTitle
boolean canCreateTagByTitle(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 toTag.getTitlePath()
). If the tag already exists,false
is returned. Basically it checks if a call tocreateTagByTitle(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 returntrue
if the tag is already existing.- Throws:
InvalidTagFormatException
- if the parametertitlePath
references a non-existing namespace (please note that you cannot create namespaces viacreateTagByTitle(String)
)
-
canCreateTagByTitle
boolean canCreateTagByTitle(String tagTitlePath, 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 toTag.getTitlePath()
). If the tag already exists,false
is returned. Basically it checks if a call tocreateTagByTitle(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 IDslocale
- 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 returntrue
if the tag is already existing.- Throws:
InvalidTagFormatException
- if the parametertitlePath
references a non-existing namespace (please note that you cannot create namespaces viacreateTagByTitle(String)
)
-
createTag
Tag createTag(String tagID, String title, String description) throws 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, anAccessControlException
will be thrown and no changes will be made.The tag is defined by a shorthand tag id, such as
sky
ordam: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 pathtitle
- a title for the tag (can benull
)description
- a longer description for the tag (can benull
)- Returns:
- a Tag object (never
null
) - Throws:
AccessControlException
- if the tag must be created, but the user is not allowed to do soInvalidTagFormatException
- if the parametertagID
is not a valid tag ID
-
createTag
Tag createTag(String tagID, String title, String description, boolean autoSave) throws 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, anAccessControlException
will be thrown and no changes will be made.The tag is defined by a shorthand tag id, such as
sky
ordam: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 pathtitle
- a title for the tag (can benull
)description
- a longer description for the tag (can benull
)autoSave
- whether the session should be automatically saved or not- Returns:
- a Tag object (never
null
) - Throws:
AccessControlException
- if the tag must be created, but the user is not allowed to do soInvalidTagFormatException
- if the parametertagID
is not a valid tag ID
-
createTagByTitle
Tag createTagByTitle(String titlePath) throws 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 toTag.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:
AccessControlException
- if the tag must be created, but the user is not allowed to do soInvalidTagFormatException
- if the parametertitlePath
references a non-existing namespace (please note that this method won't create namespaces)
-
createTagByTitle
Tag createTagByTitle(String titlePath, boolean autoSave) throws 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 toTag.getTitlePath()
).- Parameters:
titlePath
- a path that includes titles rather than IDsautoSave
- whether the session should be automatically saved or not- Returns:
- a Tag object (never
null
) - Throws:
AccessControlException
- if the tag must be created, but the user is not allowed to do soInvalidTagFormatException
- if the parametertitlePath
references a non-existing namespace (please note that this method won't create namespaces)
-
createTagByTitle
Tag createTagByTitle(String tagTitlePath, Locale locale) throws 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 toTag.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 IDslocale
- the locale of the titlePath- Returns:
- a Tag object (never
null
) - Throws:
AccessControlException
- if the tag must be created, but the user is not allowed to do soInvalidTagFormatException
- if the parametertitlePath
references a non-existing namespace (please note that this method won't create namespaces)
-
deleteTag
void deleteTag(Tag tag) throws AccessControlException
Deletes the given tag.This will automatically save the session.
- Parameters:
tag
- tag to delete- Throws:
AccessControlException
- if the user is not allowed to delete the tag
-
deleteTag
void deleteTag(Tag tag, boolean autoSave) throws AccessControlException
Deletes the given tag.- Parameters:
tag
- tag to deleteautoSave
- 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:
AccessControlException
- if the user is not allowed to delete the tag
-
find
RangeIterator<Resource> find(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 acq:tags
property that contains either the tagID or the full absolute path to that tag. Furthermore, when passing a container tag, such asfruit
with eg. sub-tagsfruit/apple
,fruit/apple/braeburn
andfruit/banana
, all content tagged with it or one of the sub-tags will be found. Convenience method, see alsofind(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 theRangeIterator
that supports generics. Returnsnull
if the tag does not exist - See Also:
Tag.find()
,find(String, String[])
-
findByTitle
TagManager.FindResults findByTitle(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 aTagManager.FindResults
struct-like class.- Parameters:
title
- title of tag to find- Returns:
- a find result
-
findTagsByTitle
Tag[] findTagsByTitle(String keyword, 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 searchedlocale
- to search in a certain localized tag title only; usenull
to search in the default title- Returns:
- an array of tags found as a result
-
find
RangeIterator<Resource> find(String basePath, 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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg. sub-tagsfruit/apple
,fruit/apple/braeburn
andfruit/banana
, all content tagged with it or one of the sub-tags will be found.- Parameters:
basePath
- The starting node of the searchtagIDs
- a list of tag IDs or full paths to tags- Returns:
- a
RangeIterator
containing all found resources (Note: this is a version of theRangeIterator
that supports generics. Returnsnull
if the tag does not exist - See Also:
Tag.find()
,find(String)
,find(String, String[], boolean)
-
find
RangeIterator<Resource> find(String basePath, 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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg. sub-tagsfruit/apple
,fruit/apple/braeburn
andfruit/banana
, all content tagged with it or one of the sub-tags will be found.- Parameters:
basePath
- The starting node of the searchtagIDs
- a list of tag IDs or full paths to tagsoneMatchIsEnough
- iftrue
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 theRangeIterator
that supports generics. Returnsnull
if the tag does not exist - See Also:
Tag.find()
,find(String)
-
find
RangeIterator<Resource> find(String basePath, List<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 acq:tags
property that contains either the tagID or the full absolute path to that tag.
Furthermore, when passing a container tag, such asfruit
with eg. sub-tagsfruit/apple
,fruit/apple/braeburn
andfruit/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 searchtagSetIDs
- 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 theRangeIterator
that supports generics. Returnsnull
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
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 togetTagsForSubtree(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 ontags
- 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 ontags
- the tags to setautoSave
- 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 fromshallow
- 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 ofgetResourceResolver()
. This is consistent with recommended apiJcrTagManagerFactory.getTagManager(ResourceResolver)
Convenience method that returns the underlying session. Can be used to easily save the session when eg. creating tags withautoSave = 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 withautoSave = false
.- Returns:
- the underlying resource resolver instance
-
moveTag
Tag moveTag(Tag tag, String destination) throws AccessControlException, InvalidTagFormatException, TagException
Moves a tag.- Parameters:
tag
- the tag to movedestination
- new location of the tag, given as shorthand tag id or an absolute tag path- Returns:
- the new tag at the new location
- Throws:
AccessControlException
- if user is not allowed to move the tagInvalidTagFormatException
- if the parameterdestination
is not a valid tag IDTagException
- if the tag could not be moved
-
mergeTag
void mergeTag(Tag tag, Tag destination) throws 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:
AccessControlException
- if user is not allowed to merge the tagTagException
- if the tag could not be merged
-
getSupportedLanguageCodes
List<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
Iterable<Tag> findTagsByKeyword(String keyword, Locale locale, 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 searchedlocale
- to search in a certain localized tag title only; usenull
to search in the default titletagId
- Tag Id of the Tag/NameSpace under which tag to be searched.- Returns:
- an array of tags found as a result
-
-