rebXR Users Guide
by earl, 7158 days ago
This is the official rebXR Users Guide. Downloads and more generic information can be found here. Please note that this Users Guide already reflects the status of the upcoming rebXR release currently available as experimental version.
What is XML-RPC?
Dave Winer: "It's a spec and a set of implementations that allow software running on disparate operating systems, running in different environments to make procedure calls over the Internet. It's remote procedure calling using HTTP as the transport and XML as the encoding. It's designed to be as simple as possible, while allowing complex data structures to be transmitted, processed and returned." - http://www.xmlrpc.com
What is REBOL?
REBOL is a quite revolutionary scripting language, primarily architected by Carl Sassenrath of Amiga fame.
Carl Sassenrath about REBOL: "A friend of mine says it's like the movie 'Matrix' where you are offered either the red pill or the blue pill. Most programmers stick with the blue pill. The folks who take the REBOL red pill wake up and can never go back
"However, REBOL was designed from a meta-circular view of language semantics. That is, REBOL is what you need it to be. It morphs to provide the maximal expressive power for any problem."
Read more about REBOL on http://www.rebol.com/
rebXR Introduction
The solid flavor of rebXR would not have been possible without Gavin McKenzie's brilliant XML libraries for REBOL. Asynchronous networking support is achieved with the async:// library written by Gabriele Santilli, Maarten Koopmans and Romano Paolo Tenca.
For your convenience, all external libraries necessary to use rebXR is bundled in a single package. By running the
%make-lib.r script you can even combine the whole rebXR bundle into a single file to ease usage and redistribution.Type Mapping
Fortunately REBOL features many, many builtin types, so mapping those few XML-RPC types to REBOL types is quite straightforward:
| REBOL | XML-RPC | REBOL Example |
|---|---|---|
| integer! | int/i4 | 1 |
| decimal! | double | 13.7603 |
| string! | string | "Hello!" |
| logic! | boolean | true |
| date! | ISO8601 date/time | 2001-12-24/20:15 |
| binary! | Base64 encoded data | #{68656C6C6F} |
| block! | array | [ 1 2 3 ] |
| hash! | struct | make hash! [ "you" 1 "me" 2 ] |
Client-Side Usage
Synopsis:
xmlrpc-exec server method-block /async callbackThe first element in the method block is supposed to be the remote procedure name, all other elements are supposed to be parameters. Be careful and do not forget to 'reduce the method-block appropriately! Some examples:
xmlrpc-exec http://betty.userland.com/RPC2 [ examples.getStateName 41 ]for i 10 15 1 [
xmlrpc-exec http://betty.userland.com/RPC2 reduce [
'examples.getStateName i
]
]
If you want to use asynchronous networking, you have to provide a callback function which will be invoked when the method call completed and the results were returned. This callback function must accept exactly one parameter (the result) and an
/error refinement. If the method call completed successfully, the callback will be invoked without the /error refinement, the argument will be the result of the method call. If an error occured, the callback will be invoked with the /error refinement and the argument will be the disarmed error object. An example:
got-result: func [ result /error ] [ probe reform [ error result ] ]
xmlrpc-exec/async http://betty.userland.com/RPC2 [ examples.getStateName 41 ] :got-result
forever [ wait system/ports/wait-list ]
Server-Side Usage
rebXR currently supports CGI-based and standalone server. Using them is trivial ;) Simply write down the functions you'd like to provide. Load the rebXR libs and the server lib for the server type you plan to use; the %rebxr.r bundle created by %make-lib.r by default includes the standalone server library. Finally, add one line at the end of the file:
If you are running as CGI:
xmlrpc-serve methods-block /default default-methodIf using a standalone async:// server:
xmlrpc-serve port-number methods-block /default default-methodThe methods-block specifies to which XML-RPC method calls this server should reply. For example:
xmlrpc-serve 9090 [ add subtract ]would serve the two native REBOL functions add and subtract, both taking 2 parameters and doing what you would expect ;) (The example uses the standalone server.)
defh: func [ orig-call ] [ none ]
xmlrpc-serve/default [ add subtract ] 'defhwould also set up a default handler, which will be called whenever a method was requested which was not explicitly served as specified in the :methods-block. When the default handler returns none, the server will send a 'Method not supported' exception to the calling client. Otherwise it will send back the results as returned by the default handler. (This example uses the CGI-based server.)
The default-handler gets the original request passed in as 'orig-call. This is a block, with the method to be invoked as first element followed by its original arguments.
A nice trick (although missing some error handling and obviously a lot of security) to expose all REBOL/Core functions to XML-RPC invocation:
defh: func [ orig-call ] [ do orig-call ]
xmlrpc-serve/default [] 'defhGratitudes
Chris Langreiter for mental support and cheering.
Graham Chiu for extensive bugtesting and worthy feedback.
Maarten Koopmans greatly helped with the async:// support.
Gavin McKenzie for the great XML libs!
Dave Winer for the nice XML-RPC work.
Enjoy!
-- Andreas Bolka
search
5 active users
- unknown (5)
recent stores (more)
echo earlZstrainYat|tr ZY @.
