Add new attachment

Only authorized users are allowed to upload new attachments.

This page (revision-194) was last changed on 29-Nov-2007 14:37 by JohnGill  

This page was created on 27-Jan-2002 12:58 by 212.90.75.172

Only authorized users are allowed to rename pages.

Only authorized users are allowed to delete pages.

Difference between version and

At line 1 changed one line
Here's an idea: Let's define an [XML-RPC] or [SOAP] interface to Wiki. I don't exactly know what we could do with it, but at least we could do things like:
This is an [XML-RPC] interface for Wikis, so that you can do all sorts of interesting scripting and stuff. For example, it has been used to do things like:
At line 3 changed 17 lines
* Automatical notification of page changes (someone would need to write a script that would check the [RecentChanges], then email anyone.
* Combining Wikis in a manner more efficient than [InterWiki].
This would save us from actually requiring to implement all sorts of features into JSPWiki itself, and allow people to make their own modular thingies.
!!Interface
I'm thinking of the following interfaces:
* __getRecentChanges( long timestamp )__: Get list of changed pages since ''timestamp''.
* __getPage( String pagename, int version )__: Get the raw Wiki text of page.
* __getPageText( String pagename, int version )__: Get page data rendered as plain text, with most of formatting removed (this should be really good for when you actually send wiki pages via email or something).
* __getPageHTML( String pagename, int version )__: Return page in rendered HTML. This is of course required because you can never know how the [WikiText|TextFormattingRules] should be applied, since it varies from Wiki to Wiki.
I don't know whether writing would be such a good idea. But with these you could get somewhere anyway.
--[JanneJalkanen]
* [provide an automatic system to send emails when pages change|EmailGenerator]
* [print out all pages of a wiki for inclusion on portable devices|Hula]
* Enable a wiki page to control the configuration of a complicated Python process. This supersedes a process wherein the person desiring changes had to ask an engineer to check out the code and add the info.
At line 21 removed one line
That's a very interesting thought. It allows any outside process to monitor and perform actions based on the current state of the Wiki, but without actually affecting the Wiki.
At line 23 removed 3 lines
As specified above, the only way to get a list of pages is __getRecentChanges()__. It seems a bit limiting to think that all the other process would care about is recently changed files. What about:
*__getAllPages()__: Get list of all Wiki pages.
*__getMatchingPages(String query)__: Get list of all Wiki pages that match the query. Of course, this then begs the question of what matching means. That's kind of annoying.
At line 27 changed one line
getMatchingPages() may be overkill. Perhaps these queries would be better implemented with a SOAPProvider, a WikiPageProvider based on SOAP. Then the matching SOAP service can store the files anyway it likes, be notified the instant that a page is stored, and query the page text any silly way it feels like. A SOAPProvider would also get around the limitation that the API specified above requires the interested party to "poll" the WikiEngine periodically. With a SOAPProvider, if you care about every save or read, you can track them yourself.
!!API
At line 29 changed one line
--[MahlenMorris]
__Version 1__ API is as follows:
At line 31 changed one line
----
* __array getRecentChanges( Date timestamp )__: Get list of changed pages since ''timestamp'', which should be in UTC. The result is an array, where each element is a struct:
** ''name'' (string) : Name of the page. The name is UTF-8 with URL encoding to make it ASCII.
** ''lastModified'' (date) : Date of last modification, in UTC.
** ''author'' (string) : Name of the author (if available). Again, name is UTF-8 with URL encoding.
** ''version'' (int) : Current version.
* A page MAY be specified multiple times. A page MAY NOT be specified multiple
times with the ''same'' modification date.
At line 33 changed one line
This was almost too easy. JSPWiki 1.6.6-cvs now supports an XML-RPC interface at URL http://www.ecyrd.com/JSPWiki/RPC2/ (note the trailing slash).
* __int getRPCVersionSupported()__: Returns 1 with this version of the JSPWiki API.
At line 35 changed one line
To try this one out, go download the Apache [XML-RPC] package from [http://xml.apache.org/dist/xmlrpc/], then type in the following command:
* __base64 getPage( String pagename )__: Get the raw Wiki text of page, latest version. Page name __must__ be UTF-8, with URL encoding. Returned value is a binary object, with UTF-8 encoded page data.
At line 37 changed one line
{{java -cp xmlrpc.jar org.apache.xmlrpc.XmlRpcClient http://www.ecyrd.com/JSPWiki/RPC2/ jspwiki.getPage Main}}
* __base64 getPageVersion( String pagename, int version )__: Get the raw Wiki text of page. Returns UTF-8, expects UTF-8 with URL encoding.
At line 39 changed one line
See below for the available methods.
* __base64 getPageHTML( String pagename )__: Return page in rendered HTML. Returns UTF-8, expects UTF-8 with URL encoding.
At line 41 changed one line
(NB: You can't use the command line to get RecentChanges, you'll have to write a script of your own.)
* __base64 getPageHTMLVersion( String pagename, int version )__: Return page in rendered HTML, UTF-8.
At line 43 changed one line
Please test this and see how it works out.
* __array getAllPages()__: Returns a list of all pages. The result is an array of strings, again UTF-8 in URL encoding.
At line 45 removed 33 lines
--[JanneJalkanen]
----
Nifty! Works really well.
My only quibble is that you allow me to ask by specific version, but i have no idea what versions are acually available. It's current behavior is nice in that if I use a non-existant version number it just uses the most recent, but wouldn't a call like:
* int __getLatestVersion(String pagename)__
help? Just so my program don't have to guess at version numbers.
In fact, could you add a version number to the struct that getRecentChanges() returns? Then an email alerting program could diff between the oldest and the current within the time period, since a page may have changed multiple times in the time period requested (I know i have a tendancy to save a page, and then immediately have another thought).
I agree on using XML-RPC. Much nicer.
-- [MahlenMorris]
----
You __can__ use just plain __getPage( string )__ to get the latest version.
--[JanneJalkanen]
----
The getPageInfo() method has been implemented now. The current API looks thus like this:
* __getRecentChanges( Date timestamp )__: Get list of changed pages since ''timestamp''. The result is an array, where each element is a struct:
** ''name'' (string) : Name of the page.
** ''lastModified'' (date) : Date of last modification.
** ''author'' (string) : Name of the author (if available).
** ''version'' (int) : Current version.
* __getPage( String pagename )__: Get the raw Wiki text of page, latest version.
* __getPage( String pagename, int version )__: Get the raw Wiki text of page.
* __getPageHTML( String pagename )__: Return page in rendered HTML.
* __getPageHTML( String pagename, int version )__: Return page in rendered HTML.
* __getAllPages()__: Returns a list of all pages. The result is an array of strings.
At line 79 changed 2 lines
** ''name'' (string): the canonical page name
** ''lastModified'' (date): Last modification date
** ''name'' (string): the canonical page name, URL-encoded UTF-8.
** ''lastModified'' (date): Last modification date, UTC.
** ''author'' (string): author name, URL-encoded UTF-8.
At line 82 removed 3 lines
** ''author'' (string): author name
* __struct getPageInfo( string pagename, int version )__ : returns a struct
just like plain ''getPageInfo()'', but this time for a specific version.
At line 86 changed one line
There is still a known problem with Date handling... It should probably be UTC, but at the moment all times seem to be local time.
* __struct getPageInfoVersion( string pagename, int version )__ : returns a
struct just like plain ''getPageInfo()'', but this time for a specific
version.
At line 88 changed one line
--[JanneJalkanen].
* __array listLinks( string pagename )__: Lists all links for a given page.
The returned array contains structs, with the following elements:
** ''page'' (string) : The page name or URL the link is to.
** ''type'' (string) : The link type. This is a string, with the following
possible values:
*** "external" : The link is an external hyperlink
*** "local" : This is a local Wiki name for hyperlinking
** ''href'' (string) : The HREF the link points to. Useful for finding this link within the HTML of this page.
At line 90 changed one line
----
As you can see, all data is returned in a ''base64'' -type in UTF-8 encoding, regardless of what JSPWiki preference actually is. Also, all incoming or outcoming strings are really UTF-8, but they have been URL-encoded so that the XML-RPC requirement of ASCII is fulfilled.
At line 92 changed one line
Two problems:
The URL is {{http://www.jspwiki.org/RPC2/}} (note the trailing slash). All methods are prepended with wiki. - for example, {{wiki.getAllPages()}}
At line 94 changed 2 lines
# Date handling.
# UTF-8.
!Errors
At line 97 changed one line
First, dates: The XML-RPC spec has no way to specify the timezone. Which means that you actually would have to know the timezone in which the server resides... And which also means that the XML-RPC client can use whatever timezone it likes to interpret the incoming message. And that ain't fun. We could of course
All methods which handle a page in any way can return a Fault. Current fault
codes are:
At line 99 changed 4 lines
* a) Just send an int meaning seconds of UTC since EPOCH,
* b) Send a long disguised as a String meaning milliseconds of UTC since EPOCH,
* c) Send a ISO format String as the date, or
* d) Try to figure out a way to talk UTC under XML-RPC.
* 1 : No such page was found.
At line 104 changed one line
Second, sending UTF-8. XML-RPC spec says "ASCII". Which sucks, again. Sending ISO-8859-1 seems to work, but is there any guarantee that the recipient can talk UTF-8? And how would he know the incoming character set? Or would that be the responsibility of the XML parser?
!Troubleshooting
You should make sure that XMLRPC is enabled in the deployment descriptor (WEB-INF/web.xml)\\
See comments there.
At line 106 changed one line
At the moment the Apache XML-RPC library seems to use Latin1 ONLY. The euro sign (€) gets killed on the way, as are all UTF-8 characters.
!JSPWiki specific notes
At line 108 changed one line
--[JanneJalkanen]
We also offer a non-spec compliant service at URL:
At line 110 changed one line
----
{{http://www.jspwiki.org/RPCU/}}
At line 112 changed one line
More updates. The UTF-8 issue seems to be talked to the death on the XMLRPC mailing list. The summary seems to be: "While many toolkits might support something else than ASCII in string values, the XML-RPC spec is frozen, and will never change. If you transport something else than ASCII, you're in violation of the spec. Use base64."
The XML-RPC service here is otherwise exactly the same as the one detailed above, except that all
strings are considered to be UTF-8, and all methods that use base64, use strings. So, if you don't
want to do any Base64-conversions for strings, just use the UTF-8 API.
At line 114 changed one line
Using base64 would mean that __all__ methods that use strings now, should use base64 (because JSPWiki supports UTF-8 all across the board - in fact even ISO-Latin1 is not supposed to go through XML-RPC strings). Which means more work to the application writer, since he has to encode/decode all stuff going back and forth. Gng. XML-RPC is not person-to-person interoperable - many people are unable to write their own names as strings.
----
At line 116 changed one line
I'm seriously considering [SOAP] at this point. Or breaking the [XML-RPC] spec knowingly and willingly; call it WikiRPC or something =). (XML-RPC is a registered trademark of Userland Software).
!!Related Code
At line 118 changed one line
Date issue is easier, but java.util.Calendar and the XML-RPC library does not make it exactly simple to assume UTC. Need some shifting back and forth.
* A client Java API for this interface can be found at [Hula], as well as some sample apps.
* A project to present this interface on top of existing Wiki's is noted at [Hoop].
* Also, see [EmailGenerator], [http://www.mahlen.org/jspwiki/], and [TouchGraphWikiBrowser].
At line 120 removed 2 lines
--[JanneJalkanen]
At line 124 changed one line
Be prepared: The API __will__ change in the next release! Return values will be UTF-8 strings wrapped in base64, and input will likely be URL-encoded UTF-8 strings (to be compatible with the [JSPWiki URL scheme]). --[JanneJalkanen]
!!Other implementations
* [OpenWiki]: [http://www.protocol7.com/services/openwiki.asp]
* [TWiki]: [http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki]
* [UseModWiki]: [http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki]
* [MoinMoin]: [http://www.decafbad.com/twiki/bin/view/Main/XmlRpcToWiki]
* [PhpWiki]: [http://phpwiki.sourceforge.net/phpwiki-1.2/index.php?XmlRpc]
At line 128 changed one line
Here is now the new API as of v1.6.9:
!!Related Discussions
At line 130 changed 17 lines
* __getRecentChanges( Date timestamp )__: Get list of changed pages since ''timestamp'', which should be in UTC. The result is an array, where each element is a struct:
** ''name'' (string) : Name of the page. The name is UTF-8 with URL encoding to make it ASCII.
** ''lastModified'' (date) : Date of last modification, in UTC.
** ''author'' (string) : Name of the author (if available). Again, name is UTF-8 with URL encoding.
** ''version'' (int) : Current version.
* __base64 getPage( String pagename )__: Get the raw Wiki text of page, latest version. Page name __must__ be UTF-8, with URL encoding. Returned value is a binary object, with UTF-8 encoded page data.
* __base64 getPage( String pagename, int version )__: Get the raw Wiki text of page. Returns UTF-8, expects UTF-8 with URL encoding.
* __base64 getPageHTML( String pagename )__: Return page in rendered HTML. Returns UTF-8, expects UTF-8 with URL encoding.
* __base64 getPageHTML( String pagename, int version )__: Return page in rendered HTML, UTF-8.
* __array getAllPages()__: Returns a list of all pages. The result is an array of strings, again UTF-8 in URL encoding.
* __struct getPageInfo( string pagename )__ : returns a struct with elements
** ''name'' (string): the canonical page name, URL-encoded UTF-8.
** ''lastModified'' (date): Last modification date, UTC.
** ''version'' (int): current version
** ''author'' (string): author name, URL-encoded UTF-8.
* __struct getPageInfo( string pagename, int version )__ : returns a struct
just like plain ''getPageInfo()'', but this time for a specific version.
* See [WikiRPCInterfaceUTF8VsBase64] for more on UTF-8 issues and time zone stuff.
* See [WikiRPCInterfaceListLinks] for the discussion on the listLinks() method.
* See [WikiRPCInterfaceDiscussion] for generic discussion about this interface.
* See [WikiRPCInterface2] for discussion on the next version of the API.
* [HowWikiComparesToRest|http://internet.conveyor.com/RESTwiki/moin.cgi/HowWikiComparesToRest]
----
At line 148 changed one line
As you can see, all data is returned in a ''base64'' -type in UTF-8 encoding, regardless of what JSPWiki preference actually is. Also, all incoming or outcoming strings are really UTF-8, but they have been URL-encoded so that the XML-RPC requirement of ASCII is fulfilled.
please try to coordinate this effort with other wikis, for example have a look at [http://meta.wikimedia.org/w/wiki.phtml?title=Machine-friendly_wiki_interface] and talk to the people there.
At line 150 changed one line
Let me know if this works...
-- AnonymousCoward
At line 152 changed one line
--[JanneJalkanen]
Well, AFAIK this is the oldest API there is, so others should be co-ordinating with us ;-). Anyway, this API is pretty much obsolete. It's far better to use something like AtomPublishingProtocol.
At line 154 changed 3 lines
[MahlenMorris] It seems to be working fine. I'm turning the base64 back to a String by calling {{new String((byte[]) server.execute(GETPAGE, args), "UTF-8")}}; does that seem right. Like most Americans, I18N is very mysterious to me.
I'm still having trouble getting the time zone right, though. I've been looking at what you did in your code, but no matter what I do i get times that think they are PST but are in fact EET, For example, as i write this it thinks that the [TODOList] was last changed at 00:01 PST. If you were really sending UTC, i don't think I'd be getting that.
-- JanneJalkanen
Version Date Modified Size Author Changes ... Change note
194 29-Nov-2007 14:37 5.787 kB JohnGill to previous Someone replaced the page content with "wo"
193 28-Nov-2007 18:49 0.004 kB 60.190.240.76 to previous | to last
192 12-Oct-2007 06:43 5.787 kB JanneJalkanen to previous | to last
191 12-Oct-2007 05:32 5.797 kB 203.69.39.251 to previous | to last
190 06-Oct-2007 11:28 5.787 kB 141.7.56.2 to previous | to last restore
189 06-Oct-2007 03:10 0.007 kB 217.16.16.218 to previous | to last t922t
188 26-Sep-2007 23:47 5.787 kB JanneJalkanen to previous | to last
187 26-Sep-2007 02:58 5.796 kB SitriCelra to previous | to last
186 21-Jul-2007 03:09 5.787 kB MurrayAltheim to previous | to last removed noise
185 20-Jul-2007 23:57 5.864 kB 1001������ to previous | to last Comment by 1001������
184 20-Jul-2007 23:57 0.008 kB 60.191.36.91 to previous | to last Comment by 1001������
183 21-Jan-2007 17:15 5.815 kB 62.99.252.218 to previous | to last old phpwiki version
182 11-Jan-2007 09:13 5.801 kB GusHome to previous | to last
181 11-Jan-2007 09:10 5.894 kB GusHome to previous | to last Comment by GusHome
« This page (revision-194) was last changed on 29-Nov-2007 14:37 by JohnGill