Index: xwiki-platform-core/xwiki-core/src/main/java/com/xpn/xwiki/api/Context.java
===================================================================
--- xwiki-platform-core/xwiki-core/src/main/java/com/xpn/xwiki/api/Context.java (revision 8324)
+++ xwiki-platform-core/xwiki-core/src/main/java/com/xpn/xwiki/api/Context.java (working copy)
@@ -30,6 +30,14 @@
import java.util.List;
+/**
+ * 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.
+ */
public class Context extends Api
{
public Context(XWikiContext context)
@@ -38,7 +46,11 @@
}
/**
- * @return an object which contains the Request context
+ * 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.
+ *
+ * @return an object wrapping the current request object
*/
public XWikiRequest getRequest()
{
@@ -46,20 +58,73 @@
}
/**
- * @return an object which contains the response object
+ * 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.
+ *
+ * @return an object wrapping the current response object
*/
public XWikiResponse getResponse()
{
return getXWikiContext().getResponse();
}
+ /**
+ * 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 |
+ *
+ *
+ *
+ * @return an integer constant identifying the container or environment in which XWiki is
+ * currently running
+ */
public int getMode()
{
return getXWikiContext().getMode();
}
/**
+ * Returns the current database name. If {@link #isVirtual()} returns false then
+ * the current database name is the same as {@link #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.
+ *
* @return the current database name
+ * @see #isVirtual()
+ * @see #getMainWikiName()
*/
public String getDatabase()
{
@@ -67,6 +132,9 @@
}
/**
+ * 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.
+ *
* @return the name of the main wiki.
*/
public String getMainWikiName()
@@ -75,7 +143,9 @@
}
/**
- * @return the original database
+ * Returns the name of the original database.
+ *
+ * @return the original database name
*/
public String getOriginalDatabase()
{
@@ -83,9 +153,10 @@
}
/**
- * set the database if you have the programming right
- *
- * @param database the data name
+ * Sets the current database. You need programming rights to be able to call this method.
+ *
+ * @param database a database name
+ * @see #getDatabase()
*/
public void setDatabase(String database)
{
@@ -95,7 +166,14 @@
}
/**
- * @return the url Factory
+ * 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.
+ *
+ * @return the URL factory
*/
public XWikiURLFactory getURLFactory()
{
@@ -103,7 +181,15 @@
}
/**
- * @return true if the server is in virtual mode (ie host more than one wiki)
+ * Specifies if XWiki runs in virtual mode. 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.
+ *
+ * @return true if XWiki is in virtual mode
+ * @see #getDatabase()
+ * @see #getMainWikiName()
*/
public boolean isVirtual()
{
@@ -111,6 +197,12 @@
}
/**
+ * Returns the current action. 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.
+ *
* @return the requested action
*/
public String getAction()
@@ -119,7 +211,14 @@
}
/**
+ * Returns the language 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 cookie, user preferences or from the
+ * navigator language settings, the last having the lower priority.
+ *
* @return the language of the current user
+ * @see XWiki#getXWikiPreference(String)
+ * @see #getInterfaceLanguage()
*/
public String getLanguage()
{
@@ -127,7 +226,14 @@
}
/**
+ * 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.
+ *
* @return the interface language preference of the current user
+ * @see #getLanguage()
*/
public String getInterfaceLanguage()
{
@@ -135,7 +241,11 @@
}
/**
- * @return the XWiki object if you have the programming right
+ * Returns the XWiki object. Programming rights are needed in order to call this method. If you
+ * don't have them you still can access the XWiki object through a secure proxy available as a
+ * predefined variable for scripting inside wiki pages; use $xwiki in Velocity.
+ *
+ * @return the XWiki object, if you have programming rights
*/
public com.xpn.xwiki.XWiki getXWiki()
{
@@ -147,7 +257,12 @@
}
/**
- * @return the current requested document
+ * Returns the current requested document. Programming rights are needed in order to call this
+ * method. If you don't have them you still can access the current document through a secure
+ * proxy available as a predefined variable for scripting inside wiki pages; use
+ * $doc in Velocity.
+ *
+ * @return the current requested document, if you have programming rights
*/
public XWikiDocument getDoc()
{
@@ -159,7 +274,18 @@
}
/**
+ * 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.
+ *
* @return the current user which made the request
+ * @see #getLocalUser()
+ * @see #getDatabase()
*/
public String getUser()
{
@@ -167,7 +293,12 @@
}
/**
- * @return the local username of the current user which made the request
+ * Returns the current user which made the request. The difference from {@link #getUser()} is
+ * that the returned string is never prefixed with the database name, not even in virtual mode.
+ *
+ * @return the current user which made the request
+ * @see #getUser()
+ * @see #getDatabase()
*/
public String getLocalUser()
{
@@ -175,7 +306,9 @@
}
/**
- * set the document if you have the programming right
+ * Sets the current document. Programming rights are needed in order to call this method.
+ *
+ * @param doc a XWiki document
*/
public void setDoc(XWikiDocument doc)
{
@@ -185,7 +318,11 @@
}
/**
- * @return the unwrapped version of the context if you have the programming right
+ * 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.
+ *
+ * @return the unwrapped version of the context if you have programming rights
*/
public XWikiContext getContext()
{
@@ -201,6 +338,18 @@
return getXWikiContext();
}
+ /**
+ * 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.
+ *
+ * @param key the key to look for in the context
+ * @return the value associated with the given key in the XWiki context, if you have programming
+ * rights
+ * @see #put(String, Object)
+ */
public java.lang.Object get(String key)
{
if (hasProgrammingRights()) {
@@ -210,11 +359,24 @@
}
}
+ /**
+ * Returns the WYSIWYG editor object.
+ *
+ * @return the WYSIWYG editor object
+ */
public java.lang.Object getEditorWysiwyg()
{
return getXWikiContext().getEditorWysiwyg();
}
+ /**
+ * Puts an object on the context using the given key. The context can be seen as a map of
+ * (paramName, paramValue) pairs.
+ *
+ * @param key the parameter name
+ * @param value the parameter value
+ * @see #get(String)
+ */
public void put(String key, java.lang.Object value)
{
if (hasProgrammingRights()) {
@@ -222,13 +384,24 @@
}
}
+ /**
+ * Specifies if the current page should be rendered 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.
+ *
+ * @param finished true to avoid rendering of the current page
+ */
public void setFinished(boolean finished)
{
getXWikiContext().setFinished(finished);
}
/**
+ * Returns the cache duration.
+ *
* @return the cache duration
+ * @see #setCacheDuration(int)
*/
public int getCacheDuration()
{
@@ -236,54 +409,126 @@
}
/**
- * @param duration in second
+ * Sets the cache duration in seconds
+ *
+ * @param duration the cache duration specified in seconds
+ * @see #getCacheDuration()
*/
public void setCacheDuration(int duration)
{
getXWikiContext().setCacheDuration(duration);
}
+ /**
+ * 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.
+ *
+ * @param action view action replacement
+ * @see #unsetLinksAction()
+ * @see #getLinksAction()
+ * @see #getURLFactory()
+ */
public void setLinksAction(String action)
{
getXWikiContext().setLinksAction(action);
}
+ /**
+ * Stops the view action from being replaced with another action inside URLs.
+ *
+ * @see #setLinksAction(String)
+ * @see #getLinksAction()
+ */
public void unsetLinksAction()
{
getXWikiContext().unsetLinksAction();
}
+ /**
+ * Returns the action used by XWiki URL factories to replace the view action when
+ * creating URLs. If no view action replacement has been specified it returns
+ * null.
+ *
+ * @return the view action replacement
+ * @see #setLinksAction(String)
+ * @see #unsetLinksAction()
+ * @see #getURLFactory()
+ */
public String getLinksAction()
{
return getXWikiContext().getLinksAction();
}
+ /**
+ * Sets the extra query string to be added to all the URLs created by XWiki URL factories.
+ *
+ * @param value the additional query string to be added to all the URLs created by XWiki URL
+ * factories
+ * @see #unsetLinksQueryString()
+ * @see #getLinksQueryString()
+ * @see #getURLFactory()
+ */
public void setLinksQueryString(String value)
{
getXWikiContext().setLinksQueryString(value);
}
+ /**
+ * Specifies that no additional query string should be added to XWiki URLs.
+ *
+ * @see #setLinksQueryString(String)
+ * @see #getLinksQueryString()
+ */
public void unsetLinksQueryString()
{
getXWikiContext().unsetLinksQueryString();
}
+ /**
+ * 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.
+ *
+ * @return the additional query string that is added to all XWiki URLs
+ * @see #setLinksQueryString(String)
+ * @see #unsetLinksQueryString()
+ * @see #getURLFactory()
+ */
public String getLinksQueryString()
{
return getXWikiContext().getLinksQueryString();
}
+ /**
+ * Returns the validation status, which contains the exceptions or errors that may have occured
+ * during the validation process.
+ *
+ * @return the validation status
+ */
public XWikiValidationStatus getValidationStatus()
{
return getXWikiContext().getValidationStatus();
}
+ /**
+ * 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.
+ *
+ * @return the list with the currently displayed fields
+ * @see Document#display(String)
+ */
public List getDisplayedFields()
{
return getXWikiContext().getDisplayedFields();
}
+
+ /**
+ * Returns an instance of the {@link Util} class.
+ *
+ * @return an instance of the {@link Util} class
+ * @see Util
+ */
public Util getUtil()
{
return context.getUtil();
}
-}
+}
\ No newline at end of file