[s-xml-rpc-cvs] CVS update: public_html/index.html

Sun Jun 13 17:02:14 UTC 2004

Update of /project/s-xml-rpc/cvsroot/public_html
In directory common-lisp.net:/tmp/cvs-serv4833

Modified Files:
	index.html 
Log Message:
Update documentation: by default, almost nothing is exported now.
Show how to make common-lisp available, like before.

Date: Sun Jun 13 10:02:14 2004
Author: rschlatte

Index: public_html/index.html
diff -u public_html/index.html:1.1.1.1 public_html/index.html:1.2

--- public_html/index.html:1.1.1.1	Wed Jun  9 02:02:08 2004
+++ public_html/index.html	Sun Jun 13 10:02:14 2004
@@ -66,7 +66,7 @@
       The function <tt>xml-rpc-aserve:xml-rpc-call-aserve</tt> does the same thing, but uses the (portable) aserve HTTP client API for the networking.
     </p>
     <p>
-      Unit tests throughout the source code (marked by <tt>#+unit-test</tt> and usually wrapped inside an <tt>assert</tt>) can serve as (executable) examples. A more complicated example is the server and client implementation of some tests in <tt>validator1.lisp</tt>. Remember that XML-RPC method (function) names are case-sensitive, as are the names of XML-RPC structure members.
+      The unit tests in the subdirectory <tt>test</tt> can serve as (executable) examples. A more complicated example is the server and client implementation of some tests in <tt>validator1.lisp</tt>. Remember that XML-RPC method (function) names are case-sensitive, as are the names of XML-RPC structure members.
     </p>
 
     <h3>
@@ -74,26 +74,42 @@
     </h3>
     <p>
       Only a single function call is needed to get the server up and running:
-      <pre>? (start-xml-rpc-server :port 8080)</pre>	
-      From now on, your lisp image becomes an XML-RPC server, listening for HTTP requests on port 8080. 
-      By default each function in your lisp image becomes available remotely, provided its signature is compatible.
-      The is not very secure, but it is easy and powerful. 
-      You should customize this behavior for production usage.
+      <pre>? (start-xml-rpc-server :port 8080)</pre> From now on, your
+      lisp image becomes an XML-RPC server, listening for HTTP
+      requests on port 8080.  By default the
+      functions <tt>system.listMethods</tt>, <tt>system.methodSignature</tt>, 
+      <tt>system.methodHelp</tt> and <tt>system.multicall</tt> are
+      available.  You can export additional functions from the server
+      by importing symbols in the package contained
+      in <tt>*xml-rpc-package*</tt> (by default, this is the package
+      S-XML-RPC-EXPORTS).  <tt>(use-package :common-lisp
+      :s-xml-rpc-exports)</tt> makes all of Common Lisp available via
+      xml-rpc.
+    </p>
+  <p>
       In more detail, this is what happens:
       <ul>
 	<li>The XML-RPC call arrives as XML encoded characters in the body of an HTTP POST request</li>
 	<li>The characters received are parsed by the XML parser and decoded on the fly (using a SAX-like interface) following XML-RPC semantics into a a string method name and a possibly empty list of Lisp objects that are the arguments</li>
 	<li>The value of <tt>*xml-rpc-call-hook*</tt> is applied on the string method name and optional argument list</li>
-	<li>The default value of <tt>*xml-rpc-call-hook*</tt> is <tt>execute-xml-rpc-call</tt> which interns the method name in the package <tt>*xml-rpc-package*</tt> (whose default value is the XML-RPC package itself) and applies the function bound to that name to the argument list (if any)</li>
+	<li>The default value of <tt>*xml-rpc-call-hook*</tt>
+	  is <tt>execute-xml-rpc-call</tt> which looks for a function
+	  with the given name in the package <tt>*xml-rpc-package*</tt>
+	  (whose default value is the XML-RPC-EXPORTS package) and
+	  applies the function bound to that name to the argument list
+	  (if any)</li>
 	<li>The result is encoded as an XML-RPC result and returned to the client</li>
-	<li>If anything goes wrong in any of these steps, a Lisp condition is thrown which is catched and then encoded as an XML-RPC fault and returned to the client</li>
+	<li>If anything goes wrong in any of these steps, a Lisp
+	condition is thrown which is caught and then encoded as an XML-RPC fault and returned to the client</li>
       </ul>
-      Customization points are <tt>*xml-rpc-package*</tt> or <tt>*xml-rpc-call-hook*</tt>.
+      Customization points are <tt>*xml-rpc-package*</tt> and <tt>*xml-rpc-call-hook*</tt>.
       Setting the variable <tt>xml-rpc::*xml-rpc-debug*</tt> to <tt>t</tt> makes the server more verbose.
       Note that XML-RPC method names are case sensitive: for example, clients have specify "LISP-IMPLEMENTATION-TYPE" for the corresponding Lisp function; a server has to define a function named <tt>|login|</tt> if his clients look for an implementation of "login". 
     </p>
     <p>
-AppleScript can make client-side XML-RPC calls. So provided you have your lisp XML-RPC server running, you can have lisp to the math like this:
+      AppleScript can make client-side XML-RPC calls. So provided you
+      have your lisp XML-RPC server running and have imported + in
+      XML-RPC-EXPORTS, you can have lisp do the math like this:
       <pre>tell application "http://localhost:8080/RPC2"
   set call_result to call xmlrpc {method name:"+", parameters:{10, 20, 30}}
 end tell
@@ -220,7 +236,7 @@
       The code in the package "S-BASE64" is an implementation of Base64 encoding and decoding (part of RFC 1521). Encoding takes bytes (a binary stream or a byte array) and produces characters (a character stream or a string). Decoding goes the other way.
     </p>
 
-  <p>CVS version $Id: index.html,v 1.1.1.1 2004/06/09 09:02:08 scaekenberghe Exp $</p>
+  <p>CVS version $Id: index.html,v 1.2 2004/06/13 17:02:14 rschlatte Exp $</p>
 
   <div class="footer">
     <p>Back to <a href="http://common-lisp.net/">Common-lisp.net</a>.</p>  



