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 Detail

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

      • 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