com.xpn.xwiki.xmlrpc
Class XWikiXmlRpcApiImpl

java.lang.Object
  extended by com.xpn.xwiki.xmlrpc.XWikiXmlRpcApiImpl
All Implemented Interfaces:
XWikiXmlRpcApi

public class XWikiXmlRpcApiImpl
extends Object
implements XWikiXmlRpcApi

The class containing the implementation of the XML-RPC API. Methods tagged with the ConfluenceAPI are compatible with Confluence.

Version:
$Id: 6ec0d4b58a38eaabcbf49d830d8510027f6bc2eb $

Constructor Summary
XWikiXmlRpcApiImpl()
           
 
Method Summary
 Map addAttachment(String token, Integer contentId, Map attachmentMap, byte[] attachmentData)
          Add an attachment.
 Map addComment(String token, Map commentMap)
          Add a comment.
 Map addSpace(String token, Map spaceMap)
          Add a new space.
 String convert(String token, String source, String initialSyntaxId, String targetSyntaxId)
          Converts a wiki source from a syntax to another syntax.
 byte[] getAttachmentData(String token, String pageId, String fileName, String versionNumber)
          Get the attachment data.
 List getAttachments(String token, String pageId)
          Get attachments.
 Map getClass(String token, String className)
          Get a specific class.
 List getClasses(String token)
          Get classes.
 Map getComment(String token, String commentId)
          Get a specific comment.
 List getComments(String token, String pageId)
           
protected  XWikiContext getContext()
           
 List<String> getInputSyntaxes(String token)
          Gets all syntaxes supported by the rendering parsers as an input for a syntax conversion.
 List getModifiedPagesHistory(String token, Date date, int numberOfResults, int start, boolean fromLatest)
          Returns a list of XWikiPageHistorySummary containing all the pages that have been modified since a given date in all their versions.
 Map getObject(String token, String pageId, String guid)
          The getObject function will return an XWikiObject where only non-null properties are included in the mapping 'field' -> 'value' In order to know all the available fields and their respective types and attributes, clients should refer to the object's class.
 Map getObject(String token, String pageId, String className, Integer id)
          The getObject function will return an XWikiObject where only non-null properties are included in the mapping 'field' -> 'value' In order to know all the available fields and their respective types and attributes, clients should refer to the object's class.
 List getObjects(String token, String pageId)
           
 List<String> getOutputSyntaxes(String token)
          Gets all syntaxes supported by the rendering as an output for a syntax conversion.
 Map getPage(String token, String pageId)
          Retrieves a page.
 List getPageHistory(String token, String pageId)
          Get revision history of a page.
 List getPages(String token, String spaceKey)
           
 String getRenderedContent(String token, String pageId, String syntaxId)
          Gets the rendered content of an existing document.
 Map getServerInfo(String token)
          Get server information.
 Map getSpace(String token, String spaceKey)
          Get information about a given space.
 List getSpaces(String token)
          Get the list of spaces.
 String login(String userName, String password)
          Login.
 Boolean logout(String token)
          Logout.
 Boolean removeAttachment(String token, String pageId, String fileName)
          Remove attachment.
 Boolean removeComment(String token, String commentId)
          Remove a comment.
 Boolean removeObject(String token, String pageId, String className, Integer id)
           
 Boolean removePage(String token, String pageId)
          Remove a page.
 Boolean removeSpace(String token, String spaceKey)
          Removes a space by deleting every page in it.
 String renderContent(String token, String space, String pageId, String content)
          Render a page or content in HTML.
 String renderPageContent(String token, String pageId, String content, String sourceSyntaxId, String targetSyntaxId)
          Renders a text in the context of a wiki page.
 List search(String token, String query, int maxResults)
          Search pages.
 Map storeObject(String token, Map objectMap)
          Update the object or create a new one if it doesn't exist.
 Map storeObject(String token, Map objectMap, boolean checkVersion)
          This is a version of storeObject that fails to store the object if the current version of the page associated to the object doesn't match the one of the object passed as parameter (i.e., the object's page has been modified since the last getObject)
 Map storePage(String token, Map pageMap)
          Store or rename a page, or create it if it doesn't exist.
 Map storePage(String token, Map pageMap, boolean checkVersion)
          This is a version of storePage that fails to store the page if the current version of the page doesn't match the one of the page passed as parameter (i.e., the page has been modified since the last getPage)
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

XWikiXmlRpcApiImpl

public XWikiXmlRpcApiImpl()
Method Detail

getContext

protected XWikiContext getContext()

login

public String login(String userName,
                    String password)
             throws Exception
Login.

Specified by:
login in interface XWikiXmlRpcApi
Returns:
A token to be used in subsequent calls as an identification.
Throws:
Exception - If authentication fails.

logout

public Boolean logout(String token)
               throws Exception
Logout.

Specified by:
logout in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
True is logout was successful.
Throws:
Exception - An invalid token is provided.

getServerInfo

public Map getServerInfo(String token)
                  throws Exception
Get server information.

Specified by:
getServerInfo in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
The server information
Throws:
Exception - An invalid token is provided.

getSpaces

public List getSpaces(String token)
               throws Exception
Get the list of spaces.

Specified by:
getSpaces in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
A list of Maps that represent SpaceSummary objects.
Throws:
Exception - An invalid token is provided.

getSpace

public Map getSpace(String token,
                    String spaceKey)
             throws Exception
Get information about a given space.

Specified by:
getSpace in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
spaceKey - The space name.
Returns:
A map representing a Space object.
Throws:
Exception - An invalid token is provided or the user doesn't have enough rights to access the space.

addSpace

public Map addSpace(String token,
                    Map spaceMap)
             throws Exception
Add a new space. It basically creates a SpaceKey.WebHome page with no content and the space title as its title.

Specified by:
addSpace in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
spaceMap - The map representing a Space object.
Returns:
The newly created space as a Space object.
Throws:
Exception - An invalid token is provided or the space cannot be created or it already exists and the user has not the rights to modify it

removeSpace

public Boolean removeSpace(String token,
                           String spaceKey)
                    throws Exception
Removes a space by deleting every page in it.

Specified by:
removeSpace in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
spaceKey - The space name.
Returns:
True if the space has been successfully deleted.
Throws:
Exception - An invalid token is provided or there was a problem while deleting the space.

getPages

public List getPages(String token,
                     String spaceKey)
              throws Exception
Specified by:
getPages in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
spaceKey - The space name.
Returns:
A list containing PageSummary objects.
Throws:
Exception - An invalid token is provided.

getPage

public Map getPage(String token,
                   String pageId)
            throws Exception
Retrieves a page. The returned page title is set the current title if the current title != "", otherwise it is set to the page name (i.e., the name part in the page Space.Name id)

Specified by:
getPage in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page[?language=l&version=v&minorVersion=mv]' format.
Returns:
A map representing a Page object containing information about the requested page.
Throws:
Exception - An invalid token is provided or the user has not the right to access the page or the page does not exist.

storePage

public Map storePage(String token,
                     Map pageMap)
              throws Exception
Store or rename a page, or create it if it doesn't exist.

The way confluence clients rename pages is the following:

page = getPage(pageId); page.setSpace("New space"); page.setTitle("New title"); storePage(page);

In XWiki in order to rename a page we need to change its ID, and no client written for confluence will do this. Currently the authoritative source for the page location is the ID (basically storePage ignores the space field) and changing the title will only affect the page title. However if we agree to assume that the when using XMLRPC the semantics of the page title is that of the page name in an XWiki ID, we will be able to be confluence compatible.

There are three possible cases: Let P=(id, space, title) the definition of a page. Let CP be the current page and NP the page to be stored (i.e. the page passed to storePage):

1) CP=("Space.Name", "Space", "Title") NP=("Space.Name", "NewSpace", "Title") Here it is clear that the user wants to "rename" the page by moving it to another space. So we rename the page to ("NewSpace.Name", "NewSpace", "Title")

2) CP=("Space.Name", "Space", "Title") NP=("Space.Name", "NewSpace", "NewTitle"); Here it is also clear that we want to move the page to NewSpace but we have a problem about how to name the new page: NewSpace.Name or NewSpace.NewTitle? According to the assumption stated before, we rename the page and use NewTitle as the page name. The renamed page will have the NewSpace.NewTitle id. We also set the renamed page title to NewTitle.

3) CP=("Space.Name", "Space", "Title") NP=("Space.Name", "Space", "NewTitle"); Here we have an ambiguity. Does the user want to to rename the page or set its title? According to the assumption stated before we assume that the user wants to rename the page so we will rename the page to Space.NewTitle and set its title to NewTitle.

Specified by:
storePage in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageMap - A map representing the Page object to be stored.
Returns:
A map representing a Page object with the updated information.
Throws:
Exception - An invalid token is provided or some data is missing or the page is locked or the user has no right to modify the page.

removePage

public Boolean removePage(String token,
                          String pageId)
                   throws Exception
Remove a page.

Specified by:
removePage in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

getPageHistory

public List getPageHistory(String token,
                           String pageId)
                    throws Exception
Get revision history of a page.

Specified by:
getPageHistory in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page[?language=lang]' format.
Returns:
A list of maps representing PageHistorySummary objects.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

renderContent

public String renderContent(String token,
                            String space,
                            String pageId,
                            String content)
                     throws Exception
Render a page or content in HTML.

Specified by:
renderContent in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
space - Ignored
pageId - The page id in the form of Space.Page
content - The content to be rendered. If content == "" then the page content is rendered.
Returns:
The rendered content.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

getComments

public List getComments(String token,
                        String pageId)
                 throws Exception
Specified by:
getComments in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
Returns:
A list of maps representing Comment objects.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

getComment

public Map getComment(String token,
                      String commentId)
               throws Exception
Get a specific comment. This method is here just for completeness because getComments already returns the list containing all the objects that might be retrieved using this method.

Specified by:
getComment in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
commentId - The comment id.
Returns:
A map representing a Comment object.
Throws:
Exception - An invalid token is provided or if the comment cannot be retrieved. access it.

addComment

public Map addComment(String token,
                      Map commentMap)
               throws Exception
Add a comment.

Specified by:
addComment in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
commentMap - A map representing a Comment object.
Returns:
A map representing a Comment object with updated information.
Throws:
Exception - An invalid token is provided or if the user has not the right to access it.

removeComment

public Boolean removeComment(String token,
                             String commentId)
                      throws Exception
Remove a comment.

Specified by:
removeComment in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
True if the comment has been successfully removed.
Throws:
Exception - An invalid token is provided or the user has not the right to access it.

getAttachments

public List getAttachments(String token,
                           String pageId)
                    throws Exception
Get attachments.

Specified by:
getAttachments in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
Returns:
A list of maps representing Attachment objects.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

addAttachment

public Map addAttachment(String token,
                         Integer contentId,
                         Map attachmentMap,
                         byte[] attachmentData)
                  throws Exception
Add an attachment.

Specified by:
addAttachment in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
contentId - Ignored
attachmentMap - The Attachment object used to identify the page id, and attachment metadata.
attachmentData - The actual attachment data.
Returns:
An Attachment object describing the newly added attachment.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

getAttachmentData

public byte[] getAttachmentData(String token,
                                String pageId,
                                String fileName,
                                String versionNumber)
                         throws Exception
Get the attachment data.

Specified by:
getAttachmentData in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
versionNumber - (Ignored)
Returns:
An array of bytes with the actual attachment content.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it or the attachment with the given fileName does not exist on the given page.

removeAttachment

public Boolean removeAttachment(String token,
                                String pageId,
                                String fileName)
                         throws Exception
Remove attachment.

Specified by:
removeAttachment in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
Returns:
True if the attachment has been removed.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it or the attachment with the given fileName does not exist on the given page.

getClasses

public List getClasses(String token)
                throws Exception
Get classes.

Specified by:
getClasses in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
A list of maps representing XWikiClass objects.
Throws:
Exception - An invalid token is provided.

getClass

public Map getClass(String token,
                    String className)
             throws Exception
Get a specific class.

Specified by:
getClass in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
className - The class name.
Returns:
A map representing a XWikiClass object.
Throws:
Exception - An invalid token is provided or if the given class does not exist.

getObjects

public List getObjects(String token,
                       String pageId)
                throws Exception
Specified by:
getObjects in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
Returns:
A list of maps representing XWikiObject objects.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

getObject

public Map getObject(String token,
                     String pageId,
                     String className,
                     Integer id)
              throws Exception
The getObject function will return an XWikiObject where only non-null properties are included in the mapping 'field' -> 'value' In order to know all the available fields and their respective types and attributes, clients should refer to the object's class.

Specified by:
getObject in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
className - The class of the object.
id - The id (number) of the object.
Returns:
The XWikiObject containing the information about all the properties contained in the selected object.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it or no object with the given id exist in the page.

storeObject

public Map storeObject(String token,
                       Map objectMap)
                throws Exception
Update the object or create a new one if it doesn't exist.

Specified by:
storeObject in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
objectMap - A map representing the XWikiObject to be updated/created.
Returns:
A map representing the XWikiObject with the updated information.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it.

removeObject

public Boolean removeObject(String token,
                            String pageId,
                            String className,
                            Integer id)
                     throws Exception
Specified by:
removeObject in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId in the 'Space.Page' format.
id - The object's id.
Returns:
True if the object has been successfully deleted.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it or no object with the given id exist in the page.

search

public List search(String token,
                   String query,
                   int maxResults)
            throws Exception
Search pages.

Specified by:
search in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
query - The string to be looked for. If it is "__ALL_PAGES__" the search will return all the page ids available in the Wiki.
Returns:
A list of maps representing Search Results.
Throws:
Exception - An invalid token is provided.

getModifiedPagesHistory

public List getModifiedPagesHistory(String token,
                                    Date date,
                                    int numberOfResults,
                                    int start,
                                    boolean fromLatest)
                             throws Exception
Returns a list of XWikiPageHistorySummary containing all the pages that have been modified since a given date in all their versions.

Specified by:
getModifiedPagesHistory in interface XWikiXmlRpcApi
Parameters:
token -
date - The starting date
numberOfResults - The number of results to be returned
start - The start offset in the result set
fromLatest - True if the result set will list recent changed pages before.
Returns:
A list of maps representing XWikiPageHistorySummary
Throws:
Exception - An invalid token is provided.

storePage

public Map storePage(String token,
                     Map pageMap,
                     boolean checkVersion)
              throws Exception
This is a version of storePage that fails to store the page if the current version of the page doesn't match the one of the page passed as parameter (i.e., the page has been modified since the last getPage)

Specified by:
storePage in interface XWikiXmlRpcApi
Parameters:
token -
pageMap - A map representing the Page object to be stored.
checkVersion - True if the current version of the page and the one of the page passed as parameter must match.
Returns:
A map representing an XWikiPage with updated information, or an XWikiPage whose fields are all empty if there is a version mismatch.
Throws:
Exception - An invalid token is provided.

storeObject

public Map storeObject(String token,
                       Map objectMap,
                       boolean checkVersion)
                throws Exception
This is a version of storeObject that fails to store the object if the current version of the page associated to the object doesn't match the one of the object passed as parameter (i.e., the object's page has been modified since the last getObject)

Specified by:
storeObject in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
objectMap - A map representing the XWikiObject to be updated/created.
checkVersion - True if the current version of the object's page and the one of the one passed as parameter must match.
Returns:
A map representing the XWikiObject with the updated information, or an XWikiObject whose fields are all empty if there is a version mismatch.
Throws:
Exception - An invalid token is provided.

getObject

public Map getObject(String token,
                     String pageId,
                     String guid)
              throws Exception
The getObject function will return an XWikiObject where only non-null properties are included in the mapping 'field' -> 'value' In order to know all the available fields and their respective types and attributes, clients should refer to the object's class.

Specified by:
getObject in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The pageId.
guid - The object's guid.
Returns:
The XWikiObject containing the information about all the properties contained in the selected object.
Throws:
Exception - An invalid token is provided or if the page does not exist or the user has not the right to access it or no object with the given id exist in the page.

convert

public String convert(String token,
                      String source,
                      String initialSyntaxId,
                      String targetSyntaxId)
               throws Exception
Converts a wiki source from a syntax to another syntax.

Specified by:
convert in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
source - The content to be converted.
initialSyntaxId - The initial syntax of the source.
targetSyntaxId - The final syntax of the returned content.
Returns:
The converted source.
Throws:
Exception - An invalid token is provided, the syntaxId is not supported, the source is invalid or the conversion fails.

getInputSyntaxes

public List<String> getInputSyntaxes(String token)
                              throws Exception
Gets all syntaxes supported by the rendering parsers as an input for a syntax conversion.

Specified by:
getInputSyntaxes in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
A list containing all syntaxes supported by rendering parsers.
Throws:
Exception - An invalid token is provided or the syntax lookup fails.

getOutputSyntaxes

public List<String> getOutputSyntaxes(String token)
                               throws Exception
Gets all syntaxes supported by the rendering as an output for a syntax conversion.

Specified by:
getOutputSyntaxes in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
Returns:
A list containing all syntaxes supported by renderers.
Throws:
Exception - An invalid token is provided or the syntax lookup fails.

renderPageContent

public String renderPageContent(String token,
                                String pageId,
                                String content,
                                String sourceSyntaxId,
                                String targetSyntaxId)
                         throws Exception
Renders a text in the context of a wiki page.

Specified by:
renderPageContent in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The id of the page.
content - The context to be rendered.
sourceSyntaxId - The syntax of the content.
targetSyntaxId - The target syntax of the rendered content
Returns:
The rendered content.
Throws:
Exception - If a invalid token is provided, an unsupported syntax id is given or the rendering fails.

getRenderedContent

public String getRenderedContent(String token,
                                 String pageId,
                                 String syntaxId)
                          throws Exception
Gets the rendered content of an existing document.

Specified by:
getRenderedContent in interface XWikiXmlRpcApi
Parameters:
token - The authentication token.
pageId - The id of the page.
syntaxId - The target syntax of the rendered content
Returns:
The rendered content
Throws:
Exception - If a invalid token is provided, an unsupported syntax id is given or the rendering fails.


Copyright © 2004-2013 XWiki. All Rights Reserved.