Package com.xpn.xwiki.plugin.tag

Class TagPlugin

java.lang.Object

com.xpn.xwiki.plugin.XWikiDefaultPlugin

com.xpn.xwiki.plugin.tag.TagPlugin

All Implemented Interfaces:

XWikiPluginInterface

public class TagPlugin
extends XWikiDefaultPlugin
implements XWikiPluginInterface

TagPlugin is a plugin that allows to manipulate tags easily. It allows to get, rename and delete tags.

Version:

$Id: f0dfbc48a94b9b2b172642b98fd8238de132991f $

Field Summary

Fields

Modifier and Type	Field	Description
static String	DOC_COMMENT_TAG_ADDED	L10N key for the "tag added" document edit comment.
static org.slf4j.Logger	LOGGER	Logging helper object.
static String	PLUGIN_NAME	The identifier for this plugin; used for accessing the plugin from velocity, and as the action returning the extension content.
static String	TAG_CLASS	XWiki class defining tags.
static String	TAG_PROPERTY	XWiki property of XWiki.TagClass storing tags.

Constructor Summary

Constructors

Constructor	Description
TagPlugin(String name, String className, XWikiContext context)	Tag plugin constructor.

Method Summary

Modifier and Type	Method	Description
TagOperationResult	addTagsToDocument(String tags, XWikiDocument document, XWikiContext context)	Add a list of tags to a document.
TagOperationResult	addTagsToDocument(String tags, String documentName, XWikiContext context)	Add a list of tags to a document.
TagOperationResult	addTagToDocument(String tag, XWikiDocument document, XWikiContext context)	Add a tag to a document.
TagOperationResult	addTagToDocument(String tag, String documentName, XWikiContext context)	Add a tag to a document.
protected TagOperationResult	deleteTag(String tag, XWikiContext context)	Delete a tag.
List<String>	getAllTags(XWikiContext context)	Get all tags within the wiki.
List<String>	getDocumentsWithTag(String tag, boolean includeHiddenDocuments, XWikiContext context)	Get documents with the given tags.
List<String>	getDocumentsWithTag(String tag, XWikiContext context)	Get non-hidden documents with the given tags.
Api	getPluginApi(XWikiPluginInterface plugin, XWikiContext context)
Map<String,Integer>	getTagCount(XWikiContext context)	Get cardinality map of tags within the wiki.
Map<String,Integer>	getTagCount(String spaceReference, XWikiContext context)	Get cardinality map of tags for a specific wiki space (including sub spaces).
Map<String,Integer>	getTagCountForQuery(String fromHql, String whereHql, XWikiContext context)	Get cardinality map of tags matching a hql query.
Map<String,Integer>	getTagCountForQuery(String fromHql, String whereHql, List<?> parameterValues, XWikiContext context)	Get cardinality map of tags matching a parameterized hql query.
Map<String,Integer>	getTagCountForQuery(String fromHql, String whereHql, Map<String,?> parameters, XWikiContext context)	Get cardinality map of tags matching a parameterized hql query.
Map<String,Integer>	getTagCountForSpaces(String spaces, XWikiContext context)	Get cardinality map of tags for a list of wiki spaces (including sub spaces).
List<String>	getTagsFromDocument(XWikiDocument document, XWikiContext context)	Get tags from a document.
List<String>	getTagsFromDocument(String documentName, XWikiContext context)	Get tags from a document.
TagOperationResult	removeTagFromDocument(String tag, XWikiDocument document, XWikiContext context)	Remove a tag from a document.
TagOperationResult	removeTagFromDocument(String tag, String documentName, XWikiContext context)	Remove a tag from a document.
protected TagOperationResult	renameTag(String tag, String newTag, XWikiContext context)	Rename a tag.

Methods inherited from class com.xpn.xwiki.plugin.XWikiDefaultPlugin

beginParsing, beginRendering, commonTagsHandler, downloadAttachment, endParsing, endRendering, endRenderingHandler, flushCache, flushCache, getClassName, getLocalization, getName, init, insidePREHandler, localizePlainOrKey, outsidePREHandler, setClassName, setName, startRenderingHandler, virtualInit

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.xpn.xwiki.plugin.XWikiPluginInterface

beginParsing, beginRendering, commonTagsHandler, downloadAttachment, endParsing, endRendering, endRenderingHandler, flushCache, getName, init, insidePREHandler, outsidePREHandler, startRenderingHandler, virtualInit

Field Detail

LOGGER

public static final org.slf4j.Logger LOGGER

Logging helper object.

PLUGIN_NAME

public static final String PLUGIN_NAME

The identifier for this plugin; used for accessing the plugin from velocity, and as the action returning the extension content.

See Also:

Constant Field Values

TAG_CLASS

public static final String TAG_CLASS

XWiki class defining tags.

See Also:

Constant Field Values

TAG_PROPERTY

public static final String TAG_PROPERTY

XWiki property of XWiki.TagClass storing tags.

See Also:

Constant Field Values

DOC_COMMENT_TAG_ADDED

public static final String DOC_COMMENT_TAG_ADDED

L10N key for the "tag added" document edit comment.

See Also:

Constant Field Values

Constructor Detail

TagPlugin

public TagPlugin(String name,
                 String className,
                 XWikiContext context)

Tag plugin constructor.

Parameters:

name - The name of the plugin, which can be used for retrieving the plugin API from velocity. Unused.

className - The canonical classname of the plugin. Unused.

context - The current request context.

See Also:

XWikiDefaultPlugin(String,String,com.xpn.xwiki.XWikiContext)

Method Detail

getPluginApi

public Api getPluginApi(XWikiPluginInterface plugin,
                        XWikiContext context)

Specified by:

getPluginApi in interface XWikiPluginInterface

Overrides:

getPluginApi in class XWikiDefaultPlugin

getAllTags

public List<String> getAllTags(XWikiContext context)
                        throws XWikiException

Get all tags within the wiki.

Parameters:

context - XWiki context.

Returns:

list of tags (alphabetical order).

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

getTagCount

public Map<String,Integer> getTagCount(XWikiContext context)
                                      throws XWikiException

Get cardinality map of tags within the wiki.

Parameters:

context - XWiki context.

Returns:

map of tags (alphabetical order) with their occurences counts.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

getTagCount

public Map<String,Integer> getTagCount(String spaceReference,
                                             XWikiContext context)
                                      throws XWikiException

Get cardinality map of tags for a specific wiki space (including sub spaces).

Parameters:

spaceReference - the local reference of the space to get tags from. If blank, return tags for the whole wiki.

context - XWiki context.

Returns:

map of tags (alphabetical order) with their occurrences counts.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

Since:

1.2

getTagCountForSpaces

public Map<String,Integer> getTagCountForSpaces(String spaces,
                                                      XWikiContext context)
                                               throws XWikiException

Get cardinality map of tags for a list of wiki spaces (including sub spaces). For example "'Main','Sandbox'" for all tags in the "Main" and "Sandbox" spaces, or "'Apo''stroph'" for all tags in the space "Apo'stroph".

Parameters:

spaces - the list of space to get tags in, as a comma separated, quoted space references strings.

context - XWiki context.

Returns:

map of tags with their occurences counts

Throws:

XWikiException - if search query fails (possible failures: space list parse error, DB problems, etc).

Since:

8.2M1

getTagCountForQuery

public Map<String,Integer> getTagCountForQuery(String fromHql,
                                                     String whereHql,
                                                     XWikiContext context)
                                              throws XWikiException

Get cardinality map of tags matching a hql query.

Parameters:

fromHql - the from fragment of the hql query

whereHql - the where fragment of the hql query

context - XWiki context.

Returns:

map of tags (alphabetical order) with their occurrences counts.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

Since:

1.2

See Also:

TagPluginApi.getTagCountForQuery(String, String)

getTagCountForQuery

public Map<String,Integer> getTagCountForQuery(String fromHql,
                                                     String whereHql,
                                                     List<?> parameterValues,
                                                     XWikiContext context)
                                              throws XWikiException

Get cardinality map of tags matching a parameterized hql query.

Parameters:

fromHql - the from fragment of the hql query

whereHql - the where fragment of the hql query

parameterValues - list of parameter values for the query

context - XWiki context.

Returns:

map of tags (alphabetical order) with their occurrences counts.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

Since:

1.18

See Also:

TagPluginApi.getTagCountForQuery(String, String, java.util.List)

getTagCountForQuery

public Map<String,Integer> getTagCountForQuery(String fromHql,
                                                     String whereHql,
                                                     Map<String,?> parameters,
                                                     XWikiContext context)
                                              throws XWikiException

Get cardinality map of tags matching a parameterized hql query.

Parameters:

fromHql - the from fragment of the hql query

whereHql - the where fragment of the hql query

parameters - map of named parameters for the query

context - XWiki context.

Returns:

map of tags (alphabetical order) with their occurrences counts.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

Since:

11.7RC1

See Also:

TagPluginApi.getTagCountForQuery(String, String, java.util.List)

getDocumentsWithTag

public List<String> getDocumentsWithTag(String tag,
                                        XWikiContext context)
                                 throws XWikiException

Get non-hidden documents with the given tags.

Parameters:

tag - a list of tags to match.

context - XWiki context.

Returns:

list of docNames.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

getDocumentsWithTag

public List<String> getDocumentsWithTag(String tag,
                                        boolean includeHiddenDocuments,
                                        XWikiContext context)
                                 throws XWikiException

Get documents with the given tags.

Parameters:

tag - a list of tags to match.

includeHiddenDocuments - if true then also include hidden documents

context - XWiki context.

Returns:

list of docNames.

Throws:

XWikiException - if search query fails (possible failures: DB access problems, etc).

Since:

6.2M1

getTagsFromDocument

public List<String> getTagsFromDocument(String documentName,
                                        XWikiContext context)
                                 throws XWikiException

Get tags from a document.

Parameters:

documentName - name of the document.

context - XWiki context.

Returns:

list of tags.

Throws:

XWikiException - if document read fails (possible failures: insufficient rights, DB access problems, etc).

getTagsFromDocument

public List<String> getTagsFromDocument(XWikiDocument document,
                                        XWikiContext context)
                                 throws XWikiException

Get tags from a document.

Parameters:

document - the document.

context - XWiki context.

Returns:

list of tags.

Throws:

XWikiException - if document read fails (possible failures: insufficient rights, DB access problems, etc).

addTagToDocument

public TagOperationResult addTagToDocument(String tag,
                                           String documentName,
                                           XWikiContext context)
                                    throws XWikiException

Add a tag to a document. The document is saved (minor edit) after this operation.

Parameters:

tag - tag to set.

documentName - name of the document.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails (possible failures: insufficient rights, DB access problems, etc).

addTagToDocument

public TagOperationResult addTagToDocument(String tag,
                                           XWikiDocument document,
                                           XWikiContext context)
                                    throws XWikiException

Add a tag to a document. The document is saved (minor edit) after this operation.

Parameters:

tag - tag to set.

document - the document.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails (possible failures: insufficient rights, DB access problems, etc).

addTagsToDocument

public TagOperationResult addTagsToDocument(String tags,
                                            String documentName,
                                            XWikiContext context)
                                     throws XWikiException

Add a list of tags to a document. The document is saved (minor edit) after this operation.

Parameters:

tags - the comma separated list of tags to set; whitespace around the tags is stripped

documentName - the name of the target document

context - the current request context.

Returns:

the result of the operation. TagOperationResult.NO_EFFECT is returned only if all the tags were already set on the document, TagOperationResult.OK is returned even if only some of the tags are new.

Throws:

XWikiException - if document save fails (possible failures: insufficient rights, DB access problems, etc).

addTagsToDocument

public TagOperationResult addTagsToDocument(String tags,
                                            XWikiDocument document,
                                            XWikiContext context)
                                     throws XWikiException

Add a list of tags to a document. The document is saved (minor edit) after this operation.

Parameters:

tags - the comma separated list of tags to set; whitespace around the tags is stripped

document - the target document

context - the current request context

Returns:

the result of the operation. TagOperationResult.NO_EFFECT is returned only if all the tags were already set on the document, TagOperationResult.OK is returned even if only some of the tags are new.

Throws:

XWikiException - if document save fails (possible failures: insufficient rights, DB access problems, etc).

removeTagFromDocument

public TagOperationResult removeTagFromDocument(String tag,
                                                String documentName,
                                                XWikiContext context)
                                         throws XWikiException

Remove a tag from a document. The document is saved (minor edit) after this operation.

Parameters:

tag - tag to remove.

documentName - name of the document.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails for some reason (Insufficient rights, DB access, etc).

removeTagFromDocument

public TagOperationResult removeTagFromDocument(String tag,
                                                XWikiDocument document,
                                                XWikiContext context)
                                         throws XWikiException

Remove a tag from a document. The document is saved (minor edit) after this operation.

Parameters:

tag - tag to remove.

document - the document.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails for some reason (Insufficient rights, DB access, etc).

renameTag

protected TagOperationResult renameTag(String tag,
                                       String newTag,
                                       XWikiContext context)
                                throws XWikiException

Rename a tag.

Parameters:

tag - tag to rename.

newTag - new tag.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails for some reason (Insufficient rights, DB access, etc).

deleteTag

protected TagOperationResult deleteTag(String tag,
                                       XWikiContext context)
                                throws XWikiException

Delete a tag.

Parameters:

tag - tag to delete.

context - XWiki context.

Returns:

the result of the operation

Throws:

XWikiException - if document save fails for some reason (Insufficient rights, DB access, etc).