Interface vpwiki_api

public interface vpwiki_api

VPWiki API Version 0.5.1
Copyright 2003 August Mueller, Michael P. Wilson

Notes:

- All keys in structs are case sensitive.

- All strings are passed as utf-8, and not ascii per the xml-rpc update on 6/30/2003: http://xmlrpc.com/spec#update3

- Anywhere you see the word Vector, you can interchange it with "Array" or "List" depending on what language you prefer. This is the array data type as defined in the xml-rpc spec.

- Anywhere you see the word Hashtable, you can interchange it with "Struct" or "Dictionary" or "Map" depending on what language you prefer. This is the struct data type as defined in the xml-rpc spec.

Types:

pageStruct

a page struct holds the contents of a page.
It's a Hashtable that holds at the minimum, the following entries:

Here is what a python implementation might look like: 

pageStruct = { 'key': 'homepad',                             #string
               'page':'Welcome to my personal wiki... etc',  #string
               'version': 5                                  #int
               'lastModified': 'Thu Aug 21 20:06:38 2003'    #date
             }

A pageStruct may also contain more keys than what are listed.
For example, In the case of VoodooPad 1.1, it's going to send over more values.

Here is what VoodooPad 1.1 sends across: 

pageStruct = { 'key': 'homepad',                            #string
               'page':'Welcome to my personal wiki... etc', #string
               'version': 5                                 #int
               'lastModified': 'Thu Aug 21 20:06:38 2003'   #date
               'rulerIsShowing': No                         #boolean
               'title': 'homepad'                           #string
               'data': <rtfd data>                          #binary/base64
               'alias': 'homepad'                           #alias
             }
Note: the extra entries should really be marked with something like voodoopad_ in front of the key name.

authToken

An authToken is a string that represents the current session. What it looks like is implementation specific.

Here are some unanswered questions and/or thoughts-

appendToPage - what about a method for pages that can't be modified, only appended to?
getCategories/addCategory - should we support categories?
setImplementationMetaData - what are the types/definitions behind this.
deletePage - should we have a "delete page" method?

Here is what a sample login would look like in python:

import xmlrpclib

vpwiki = xmlrpclib.Server('http://somewhere.com/some_endpoint.cgi').vpwiki

authToken = vpwiki.logon("foo wiki", "scott", "tiger")
You would then use the value returned from authToken in the calls to the other methods.

Method Summary
 java.util.Hashtable getAttachment(java.lang.String authToken, java.lang.String pageName, java.lang.String attachmentName)
          Returns the requested attatchment as a Hashtable.
 java.util.Vector getBackLinks(java.lang.String authToken, java.lang.String pageName)
          Get a Vector of the names of pages (as Strings) that point to the page pageName.
 java.util.Hashtable getImplementationMetaData(java.lang.String authToken, java.lang.String metaDataKey)
          Get various pieces of data from the server such as...
 java.util.Hashtable getPage(java.lang.String authToken, java.lang.String pageName, int version)
          This method returns a pageStruct as described in the types section.
 java.util.Hashtable getPageInfo(java.lang.String authToken, java.lang.String pageName, int version)
          This method is just like getPage, except the page is not returned in the struct.
 java.util.Vector getPageNames(java.lang.String authToken)
          Get all the page names in the wiki.
 java.util.Vector getRecentChanges(java.lang.String authToken, Date timestamp)
          Get the names of the pages (as Strings in the returning array/vector) that have changed since the timestamp.
 java.util.Hashtable getRenderedPage(java.lang.String authToken, java.lang.String pageName, java.lang.String representation)
          Return the page as something other than wiki text.
 java.util.Vector listAttachments(java.lang.String authToken, java.lang.String pageName)
          Returns a list of attatchments assigned to a page.
 boolean logoff(java.lang.String authToken)
          Close the session and render the authToken useless.
 java.lang.String logon(java.lang.String repository, java.lang.String user, java.lang.String password)
          Open a session for browsing/editing the wiki.
 boolean putAttachment(java.lang.String authToken, java.lang.String pageName, java.util.Hashtable attatchment)
          Place an attachment to the page.
 int putPage(java.lang.String authToken, java.util.Hashtable pageStruct)
          Place a page in the repository, with at least the minimum keys described in pageStruct.
 

Method Detail

logon

public java.lang.String logon(java.lang.String repository,
                              java.lang.String user,
                              java.lang.String password)
                       throws XmlRPCException
Open a session for browsing/editing the wiki.

Parameters:
repository - the name of the repository to log into for editing
user - the username
password - the password for the user
Returns:
an opaque token to use as a handle in other methods
Throws:
XmlRPCException - if the login was unsucessful.

logoff

public boolean logoff(java.lang.String authToken)
Close the session and render the authToken useless.

Parameters:
authToken - the opaque authentication token
Returns:
a boolean signaling if the logoff was successful or not

getRecentChanges

public java.util.Vector getRecentChanges(java.lang.String authToken,
                                         Date timestamp)
Get the names of the pages (as Strings in the returning array/vector) that have changed since the timestamp.

Parameters:
authToken - the opaque authentication token
timestamp - the date to start looking forward from for changes.
Returns:
a Vector with the names of the pages that have changed in the time period given.

getPageNames

public java.util.Vector getPageNames(java.lang.String authToken)
Get all the page names in the wiki.

Parameters:
authToken - the opaque authentication token
Returns:
a Vector with the names of all the pages in the wiki.

getPage

public java.util.Hashtable getPage(java.lang.String authToken,
                                   java.lang.String pageName,
                                   int version)
This method returns a pageStruct as described in the types section.
The keys and values must be at least the following:
{ 'page':'Welcome to my personal wiki... etc', #string, the contents of the page
  'version': 5,                                #int, the page revision number.
  'lastModified': 'Thu Aug 21 20:06:38 2003'   #date, the date the page was modified
}

Recommended but optional for the server to return:

{ 'lastModifiedBy':'ccgus', #string, the persion/thing that last modified the page
}
Use of the struct leaves optional client specifict data. (rtfd, alias data, etc.)

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to return

getPageInfo

public java.util.Hashtable getPageInfo(java.lang.String authToken,
                                       java.lang.String pageName,
                                       int version)
This method is just like getPage, except the page is not returned in the struct.
The keys and values returned in the struct must be at least the following:
{ 'version': 5,                                #int, the page revision number.
  'lastModified': 'Thu Aug 21 20:06:38 2003'   #date, the date the page was modified
}

Recommended but optional for the server to return:

{ 'lastModifiedBy':'ccgus', #string, the persion/thing that last modified the page
}
Use of the struct leaves optional client specifict data. (rtfd, alias data, etc.)

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to return

putPage

public int putPage(java.lang.String authToken,
                   java.util.Hashtable pageStruct)
Place a page in the repository, with at least the minimum keys described in pageStruct.
If the page doesn't already exist in the repository, then it is created, and give a version number of 1.

Parameters:
authToken - the opaque authentication token
pageStruct - a Hashtable with the minimum keys and values as required by a pageStruct
Returns:
The new version of the page.

listAttachments

public java.util.Vector listAttachments(java.lang.String authToken,
                                        java.lang.String pageName)
Returns a list of attatchments assigned to a page.
The Vector is made up of Hashtables with at least the following keys and values in it: 
{ 'name':'Company Stationary.pdf',  # string, the name of the attachment
  'mimeType', 'application/pdf',    # string, the mime type of the attatchment 
  'fileSize', 121224,               # int, the size of the attatchment in bytes
  'lastModified', 19980717T14:08:55 # date, the date of the last time the file was modified.
}
Questions:
- should the pageStruct returned in getPage contain a flag saying "hey, there are attatchments!", so a seperate query isn't needed when we pull down the page?

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to get the attachment list of.
Returns:
A Vector of Structs with the keys as described above.

getAttachment

public java.util.Hashtable getAttachment(java.lang.String authToken,
                                         java.lang.String pageName,
                                         java.lang.String attachmentName)
Returns the requested attatchment as a Hashtable.
The Hashtable returned must have at least the following keys: 
{ 'name':'Company Stationary.pdf',  # string, the name of the attachment
  'mimeType', 'application/pdf',    # string, the mime type of the attatchment
  'lastModified', 19980717T14:08:55 # date, the date of the last time the file was modified.
  'file', [binary data]             # base64, the file.
}

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to get the attachment from
attachmentName - the name of the attachment to get.

putAttachment

public boolean putAttachment(java.lang.String authToken,
                             java.lang.String pageName,
                             java.util.Hashtable attatchment)
Place an attachment to the page.
This method takes a Hastable representing the file, with at least the following keys: 
{ 'name':'Company Stationary.pdf',  # string, the name of the attachment
  'mimeType', 'application/pdf',    # string, the mime type of the attatchment
  'file', [binary data]             # base64, the file.
}
If the attachment does not already exist on the page, it is created.

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to set the attachment to

getBackLinks

public java.util.Vector getBackLinks(java.lang.String authToken,
                                     java.lang.String pageName)
Get a Vector of the names of pages (as Strings) that point to the page pageName.

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to find links to.

getRenderedPage

public java.util.Hashtable getRenderedPage(java.lang.String authToken,
                                           java.lang.String pageName,
                                           java.lang.String representation)
Return the page as something other than wiki text.
The idea behind this method is to return the page as something other than a wiki page. As an example, if the value of representation is "html" then a struct would come back with the following keys and values: 
         { "content-type":"text/html",
           'content':     "<html><body>...</body></html>"
         }
If the representation passed is "pdf" then the following would be returned:
         { "content-type":"application/pdf",
           'content':     [binary encoding for pdf]     # passed via xml-rpc as base64
         }
And so on. The allowable values to pass for the representation would be server dependent, and discovered via the getImplementationMetaData method. Some other ideas for representation tokens would be rss, rtf/rtfd, or a word document.

Parameters:
authToken - the opaque authentication token
pageName - the name of the page to find links to.
representation - the type of data to return
Returns:
Hashtable the returned data

getImplementationMetaData

public java.util.Hashtable getImplementationMetaData(java.lang.String authToken,
                                                     java.lang.String metaDataKey)
Get various pieces of data from the server such as...
Description forthcomming.