com.xpn.xwiki.api
Class Context

java.lang.Object
  com.xpn.xwiki.api.Api
      com.xpn.xwiki.api.Context

public class Context
extends Api

The Context class represents a secure proxy for the XWiki context, which in turn represents the execution environment for all the wiki pages. An instance of the Context class is available as a predefined variable for scripting inside any wiki page. You can access it using $context in Velocity scripts or simply context in Groovy ones. The Context class provides a means of getting contextual information about the current request or configuring XWiki on the fly.

Field Summary

Fields inherited from class com.xpn.xwiki.api.Api

context

Constructor Summary

Context(XWikiContext context)

Method Summary

java.lang.Object	get(java.lang.String key) Returns the value associated with the given key in the XWiki context.
java.lang.String	getAction() Returns the current action.
int	getCacheDuration() Returns the amount of time this document should be cached.
XWikiContext	getContext() Returns the XWiki context.
java.lang.String	getDatabase() Returns the current database name.
java.util.List	getDisplayedFields() Returns the list with the currently displayed fields.
XWikiDocument	getDoc() Returns the current requested document.
java.lang.String	getEditorWysiwyg() Returns the list of textarea fields that use the WYSIWYG editor.
java.lang.String	getInterfaceLanguage() Returns the interface language preference of the current user.
java.lang.String	getLanguage() Returns the language of the current request.
java.lang.String	getLinksAction() Returns the action used by XWiki URL factories to replace the view action when creating URLs.
java.lang.String	getLinksQueryString() Returns the extra query string that is added to all the URLs created by XWiki URL factories.
java.lang.String	getLocalUser() Returns the current user which made the request.
java.lang.String	getMainWikiName() Returns the name of the main wiki.
int	getMode() Specifies the container or environment in which XWiki is currently running.
java.lang.String	getOriginalDatabase() Returns the name of the original database.
XWikiRequest	getRequest() Returns the current request object.
XWikiResponse	getResponse() Returns the current response object.
XWikiURLFactory	getURLFactory() Returns the URL factory matching both the protocol used to make the current request and the container or environment in which XWiki is running.
java.lang.String	getUser() Returns the current user which made the request.
Util	getUtil() Returns an instance of the Util class.
XWikiValidationStatus	getValidationStatus() Returns the form field validation status, which contains the exceptions or errors that may have occured during the validation process performed during a save.
XWiki	getXWiki() Returns the XWiki object.
boolean	isMainWiki() Specifies if the current request was made to a virtual (non-main) wiki, or to the main wiki.
void	put(java.lang.String key, java.lang.Object value) Puts an object on the context using the given key.
void	setCacheDuration(int duration) Sets the cache duration in seconds.
void	setDatabase(java.lang.String database) Sets the current database.
void	setDisplayMode(java.lang.String mode) Sets the default field display mode, when using Document.display(String) or Document.display(String, Object).
void	setDoc(XWikiDocument doc) Sets the current document.
void	setFinished(boolean finished) Specifies if the current page should be sent to the client or not.
void	setLinksAction(java.lang.String action) Sets the action to be used instead of the view action inside URLs.
void	setLinksQueryString(java.lang.String value) Sets an extra query string to be added to all the URLs created by XWiki URL factories.
void	unsetLinksAction() Stops the view action from being replaced with another action inside URLs.
void	unsetLinksQueryString() Specifies that no additional query string should be added to XWiki URLs.

Methods inherited from class com.xpn.xwiki.api.Api

convert, convert, getXWikiContext, hasAccessLevel, hasAdminRights, hasProgrammingRights

Methods inherited from class java.lang.Object

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

Constructor Detail

Context

public Context(XWikiContext context)

Method Detail

getRequest

public XWikiRequest getRequest()

Returns the current request object. If the request has been made to a servlet container using the HTTP protocol then the returned object wraps a HttpServletRequest instance.

Returns:

an object wrapping the current request object

getResponse

public XWikiResponse getResponse()

Returns the current response object. If the request has been made to a servlet container using the HTTP protocol then the returned object wraps a HttpServletResponse instance.

Returns:

an object wrapping the current response object

getMode

public int getMode()

Specifies the container or environment in which XWiki is currently running. See the following table for possible values it can return:

Return	Meaning
0	Servlet Container
1	Portlet Container
2	XML RPC
3	Atom
4	PDF
5	GWT
6	GWT Debugging

Returns:

an integer constant identifying the container or environment in which XWiki is currently running

getDatabase

public java.lang.String getDatabase()

Returns the current database name. If isMainWiki() returns true then the current database name is the same as getMainWikiName(). Otherwise, in virtual mode, each virtual wiki has it's own database. In this case the returned string identifies the current virtual wiki we operate on and prefixes document names like in databaseName:spaceName.pageName.

Returns:

The current database name.

See Also:

isMainWiki(), getMainWikiName()

getMainWikiName

public java.lang.String getMainWikiName()

Returns the name of the main wiki. In non-virtual mode there is only one wiki called xwiki. In virtual mode, the main wiki stores information about all the other virtual wikis.

Returns:

The name of the main wiki.

getOriginalDatabase

public java.lang.String getOriginalDatabase()

Returns the name of the original database. Here, original means the database corresponding to the requested URL, which can be changed when including a document from a different database, by using, for example, #includeTopic("virtualwiki:Some.Document").

Returns:

The original database name

setDatabase

@Programming
public void setDatabase(java.lang.String database)

Sets the current database. You need programming rights to be able to call this method.

Parameters:

database - a database name

See Also:

getDatabase()

getURLFactory

public XWikiURLFactory getURLFactory()

Returns the URL factory matching both the protocol used to make the current request and the container or environment in which XWiki is running. The most used concrete implementations of the XWikiURLFactory are XWikiServletURLFactory and XWikiPortletURLFactory. XWikiURLFactory offers a generic way of creating XWiki specific URLs that should be chosen instead of the basic string concatenation. Hard-coding the protocol used, like HTTP, inside wiki pages should be avoided.

Returns:

The URL factory.

isMainWiki

public boolean isMainWiki()

Specifies if the current request was made to a virtual (non-main) wiki, or to the main wiki.

In virtual mode the server can host more than one wiki, each having it's own database and its own URL. We refer to them as virtual wikis. One of them stores information about the others and it is called the main wiki. You can switch to virtual mode by changing the xwiki.virtual parameter from 0 to 1 in the configuration file.

Returns:

true if XWiki is in the main wiki, or if virtual mode is disabled.

See Also:

getDatabase(), getMainWikiName()

getAction

public java.lang.String getAction()

Returns the current action. XWiki is built on top of the Struts framework, so here "action" means a StrutsAction. Some predefined actions are: view, edit, delete, download and export. Custom actions can be defined. The action and it's target are extracted from the request URL. For instance, in http://platform.xwiki.org/xwiki/bin/view/DevGuide/API the action is view and it's target is the DevGuide.API document.

Returns:

The action corresponding to the request URL.

getLanguage

public java.lang.String getLanguage()

Returns the language of the current request. If multilingual is turned off then the language used is given by the default_language preference. Otherwise, the language is take from either the request object, the cookie, user preferences or from the navigator language settings, the last having the lower priority.

Returns:

The language of the current request.

See Also:

getInterfaceLanguage()

getInterfaceLanguage

public java.lang.String getInterfaceLanguage()

Returns the interface language preference of the current user. If multilingual is turned off then the language used is given by the default_language preference. Otherwise, the language is take from either the request object, the context, the cookie, user preferences or from the navigator language settings, the last having the lower priority.

Returns:

The interface language preference of the current user.

See Also:

getLanguage()

getXWiki

@Programming
public XWiki getXWiki()

Returns the XWiki object. Programming rights are needed in order to call this method. If programming rights are not available in the current document, the XWiki object can still be accessed through a secure API available as a predefined variable for scripting inside wiki pages; use $xwiki in Velocity.

Returns:

The internal XWiki object, if the document has programming rights, or null otherwise.

getDoc

@Programming
public XWikiDocument getDoc()

Returns the current requested document. Programming rights are needed in order to call this method. If programming rights are not available in the current document, the current can can still be accessed document through a secure API available as a predefined variable for scripting inside wiki pages; use $doc in Velocity.

Returns:

The current requested document, if the document has programming rights, or null otherwise.

getUser

public java.lang.String getUser()

Returns the current user which made the request. If there's no currently logged in user in XWiki then the returned string is XWiki.XWikiGuest which represents any anonymous user. Otherwise the returned string has the format databaseName:XWiki.UserLoginName when XWiki runs in virtual mode, or simply XWiki.UserLoginName in non-virtual mode. At the same time this method returns the name of the document containing the current user's profile so in Velocity you can do, for instance, $xwiki.getDocument($context.user) to find out more about the current user, like his/hers real name or e-mail address.

Returns:

The current user which made the request.

See Also:

getLocalUser(), getDatabase()

getLocalUser

public java.lang.String getLocalUser()

Returns the current user which made the request. The difference from getUser() is that the returned string is never prefixed with the database name, not even in virtual mode.

Returns:

The current user which made the request.

See Also:

getUser(), getDatabase()

setDoc

@Programming
public void setDoc(XWikiDocument doc)

Sets the current document. Programming rights are needed in order to call this method.

Parameters:

doc - XWiki document to set as the context document.

getContext

@Programming
public XWikiContext getContext()

Returns the XWiki context. Programming rights are needed in order to call this method. The XWiki context represents the execution environment for all the wiki pages. Accessing it directly in wiki pages may lead to security issues.

Returns:

The unwrapped version of the context if you have programming rights, or null otherwise.

get

@Programming
public java.lang.Object get(java.lang.String key)

Returns the value associated with the given key in the XWiki context. Programming rights are needed in order to call this method. The context can be seen as a map of (paramName, paramValue) pairs. This mechanism is useful for passing parameters between pages or from Java to Velocity. For instance an exception caught in Java code can be put on the context and handled in a user-friendly way in Velocity. This method is protected because sensitive information may be placed in the internal context, which shouldn't be publicly accessible.

Parameters:

key - The key to look for in the context.

Returns:

The value associated with the given key in the XWiki context, if you have programming rights, or null otherwise.

See Also:

put(String, Object)

getEditorWysiwyg

public java.lang.String getEditorWysiwyg()

Returns the list of textarea fields that use the WYSIWYG editor. This list is automatically built when displaying textarea properties.

Returns:

A string containing a comma-separated list of textarea field names for which the WYSIWYG editor should be enabled.

put

@Programming
public void put(java.lang.String key,
                            java.lang.Object value)

Puts an object on the context using the given key. The context can be seen as a map of (paramName, paramValue) pairs. Requires programming rights.

Parameters:

key - The parameter name.

value - The parameter value.

See Also:

get(String)

setFinished

public void setFinished(boolean finished)

Specifies if the current page should be sent to the client or not. When the context is finished, the client response contains only the (HTTP) headers and no body (as in the case of a response to a HTTP HEAD request). This is useful for instance when exporting the entire wiki as a .xar archive.

Parameters:

finished - true to avoid rendering of the current page

getCacheDuration

public int getCacheDuration()

Returns the amount of time this document should be cached.

Returns:

The cache duration, in seconds.

See Also:

setCacheDuration(int)

setCacheDuration

public void setCacheDuration(int duration)

Sets the cache duration in seconds. Setting this to a non-zero, pozitive value will cause the rendered document to be stored in a cache, so next time a client requests this document, if it is still in the cache, and the document content did not change, then it will be taken from the cache and will not be parsed/rendered again. While it is a good idea to cache pages containing only static content (no scripting), it should be used with care for documents that gather information from the wiki using queries.

Parameters:

duration - The cache duration specified in seconds.

See Also:

getCacheDuration()

setLinksAction

public void setLinksAction(java.lang.String action)

Sets the action to be used instead of the view action inside URLs. The XWiki URL factories will replace the view action with the given action when creating URLs.

Parameters:

action - view action replacement

See Also:

unsetLinksAction(), getLinksAction(), getURLFactory()

unsetLinksAction

public void unsetLinksAction()

Stops the view action from being replaced with another action inside URLs.

See Also:

setLinksAction(String), getLinksAction()

getLinksAction

public java.lang.String getLinksAction()

Returns the action used by XWiki URL factories to replace the view action when creating URLs. If no action replacement has been specified, it returns null.

Returns:

The view action replacement, or null.

See Also:

setLinksAction(String), unsetLinksAction(), getURLFactory()

setLinksQueryString

public void setLinksQueryString(java.lang.String value)

Sets an extra query string to be added to all the URLs created by XWiki URL factories.

Parameters:

value - The additional query string to be added to all the URLs created by XWiki URL factories.

See Also:

unsetLinksQueryString(), getLinksQueryString(), getURLFactory()

unsetLinksQueryString

public void unsetLinksQueryString()

Specifies that no additional query string should be added to XWiki URLs.

See Also:

setLinksQueryString(String), getLinksQueryString()

getLinksQueryString

public java.lang.String getLinksQueryString()

Returns the extra query string that is added to all the URLs created by XWiki URL factories. If no such string has been specified it returns null.

Returns:

The additional query string that is added to all XWiki URLs, or null.

See Also:

setLinksQueryString(String), unsetLinksQueryString(), getURLFactory()

getValidationStatus

public XWikiValidationStatus getValidationStatus()

Returns the form field validation status, which contains the exceptions or errors that may have occured during the validation process performed during a save.

Returns:

The validation status.

getDisplayedFields

public java.util.List getDisplayedFields()

Returns the list with the currently displayed fields. Each time we call display on a document for a specific field that field is added to the list returned by this method.

Returns:

The list with the currently displayed fields.

See Also:

Document.display(String)

getUtil

public Util getUtil()

Returns an instance of the Util class.

Returns:

an instance of the Util class

See Also:

Util

setDisplayMode

public void setDisplayMode(java.lang.String mode)

Sets the default field display mode, when using Document.display(String) or Document.display(String, Object). It is automatically set to "edit" when the action is "inline", and to "view" in all other cases.

Parameters:

mode - the display mode, one of "view", "edit", "hidden", "search", "rendered".