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

    • 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​(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.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.
      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.
      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().
      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)

      • 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