com.day.cq.tagging

Interface JcrTagManagerFactory

public interface JcrTagManagerFactory

JcrTagManagerFactory returns a JCR-based implementation of a TagManager. This is the reference implementation of the tagging API.

Getting a JCR-based TagManager

First you need the service instance of this interface. Call getTagManager(Session) on it with a JCR Session to retrieve a TagManager instance:

 /* @scr.reference */
 JcrTagManagerFactory jcrTagManagerFactory;
 
 ...
 
 TagManager tagManager = jcrTagManagerFactory.getTagManager(session);
 

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

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

About the JCR implementation

The JCR-based TagManager instance is not a global singleton and does not cache anything, because it is bound to a specific JCR Session and maps all operations to Nodes, queries and other JCR API operations.

Tags are stored in the repository under a base path, which is /etc/tags by default (it can be changed by setting the OSGI property base.path for the implementation com.day.cq.tagging.impl.JcrTagManagerFactoryImpl). Tag paths are mapped to JCR paths directly (also see the absolute tag path description in Tag). A tag node has the type cq:Tag. The top-most level, ie. everything directly under the tag base path, represents namespaces, everything below tags or container tags (if they have tag children themselves). Namespaces and tags thus have both the same node type cq:Tag. You are free to add other content to namespaces or tags, the node type allows residual properties and any child nodes.

Author tagging: To tag content (ie. nodes in the repository), assign the mixin cq:OwnerTaggable to the node. OwnerTaggable means that the content-creator or author should be able to tag it for organizational purposes. The mixin essentially defines one multi-value property cq:tags, where each value is one tag that is either a tag ID or an absolute path to the tag.

User tagging: Use the mixin cq:UserTaggable if any user of the site should be able to add his own tags to the content. Important note: user-tagging is not yet implemented; it will store the tags in the user's home directory, but access to this is not implemented and the according node types are not final yet.

The implementation allows to manage tags and tag content solely by using the JCR API. It will ensure that tags set in the cq:tags property are not duplicated and that the user that set them had the rights to use this tag. This is done by using a JCR observation listener that will revert any incorrect changes. The creation of tags (eg. denying users to create new tags in a certain namespace) on the other hand must be restricted by setting appropiate ACLs in the repository.

Rights: A typical setting would only allow a group/role "tagadministrator" to modify namespaces (add/modify under /etc/tags), read access for all users/authors to all the namespaces that should be readable to them (mostly all) and write access only for those namespaces where tags should be freely definable by users/authors (add_node under /etc/tags/some_namespace).

Method Summary

Methods

Modifier and Type	Method and Description
TagManager	getTagManager(Session session) Returns a JCR-based TagManager implementation.

Method Detail

getTagManager

TagManager getTagManager(Session session)

Returns a JCR-based TagManager implementation. This one is bound to a JCR session, either from a request (eg. resourceResolver.adaptTo(TagManager.class), in which case you won't have to call this method directly) or by using a self-made session, for example:

 Session adminSession = slingRepository.loginAdministrative(null)
 TagManager tagManager = JcrTagManagerFactory.getTagManager(adminSession);
 

Please note that the visibility of tags and the right to create a tag depend on the user of the session (access rights are simply mapped to node read and creation rights of the repository), so an administrative session like above could do more than a "normal" user. In most cases it is advised to use the current request's session (= the request's user), eg. by using:

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