Package com.day.cq.tagging

Interface TagManager

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);

  • Method Details

    • resolve

      Tag resolve(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(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(String tagTitlePath, 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(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(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(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 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(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, 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:
      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(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, 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:
      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(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 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:
      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(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 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:
      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(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 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:
      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 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 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:
      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 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:

    • 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 a TagManager.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 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(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 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:

    • 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 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:

    • 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 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:

    • getNamespaces

      Tag[] getNamespaces()
      Retrieves all available tag namespaces as array.
      Returns:
      all tag namespaces
      See Also:

    • getNamespacesIter

      Iterator<Tag> getNamespacesIter()
      Retrieves all available tag namespaces as iterator.
      Returns:
      an iterator over all tag namespaces
      See Also:

    • 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, String destination) throws 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:
      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 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 tag
      TagException - 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 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