[Xmlrpccom-ss-cvs] scriptserver/docs scriptserver.lyx,1.3,1.4

[Harry F. <ha...@us...>]

Update of /cvsroot/xmlrpccom/scriptserver/docs
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv18441

Modified Files:
	scriptserver.lyx 
Log Message:
Further editing - added notes on changes to error handling

Index: scriptserver.lyx
===================================================================
RCS file: /cvsroot/xmlrpccom/scriptserver/docs/scriptserver.lyx,v
retrieving revision 1.3
retrieving revision 1.4
diff -C2 -d -r1.3 -r1.4
*** scriptserver.lyx	25 Sep 2004 13:41:36 -0000	1.3
--- scriptserver.lyx	12 Oct 2004 12:25:38 -0000	1.4
***************
*** 37,41 ****
  position 1
  inner_position 0
! height "0"
  width "100col%"
  collapsed false
--- 37,41 ----
  position 1
  inner_position 0
! height "0pt"
  width "100col%"
  collapsed false
***************
*** 143,146 ****
--- 143,165 ----
   the users web browser, while data can be fetched dynamically from a remote
   web server, in response to user events.
+ \layout Standard
+ 
+ 
+ \emph on 
+ Note:
+ \emph default 
+  this is not an XML-RPC implementation.
+  In fact it's completely XML-free.
+  See 
+ \begin_inset LatexCommand \ref{sub:Hybrid}
+ 
+ \end_inset 
+ 
+  and 
+ \begin_inset LatexCommand \htmlurl[Keith on ScriptServer]{http://keithdevens.com/weblog/archive/2004/Oct/06/ScriptServer}
+ 
+ \end_inset 
+ 
+  for details.
  \layout Subsection
  
***************
*** 226,230 ****
   Firefox).
   This already accounts for 90%+ of browsers, based on sites publishing browser
!  usage stats).
   Support in Opera should begin with v7.60+ and a workaround already exists,
   for Opera users with Java support (see 
--- 245,249 ----
   Firefox).
   This already accounts for 90%+ of browsers, based on sites publishing browser
!  usage stats.
   Support in Opera should begin with v7.60+ and a workaround already exists,
   for Opera users with Java support (see 
***************
*** 269,272 ****
--- 288,294 ----
   aspects of HTTP (e.g.
   caching, char-sets etc.).
+  Note: the XmlHttpRequest implementations used by Mozilla and IE are aware
+  of a users browser settings such as proxy servers; there's no need for
+  an application using XmlHttpRequest to worry about this.
  \layout Standard
  
***************
*** 295,299 ****
  \end_inset 
  
! : reference in the somewhere
  \layout Itemize
  
--- 317,321 ----
  \end_inset 
  
! : reference in there somewhere
  \layout Itemize
  
***************
*** 398,403 ****
   /> may also be usable, but haven't seen this done).
   The are differing variations on this approach but the all boil down to
!  the same idea; manipulate the tag with JavaScript, varying the document
!  it refers to.
  \layout Standard
  
--- 420,424 ----
   /> may also be usable, but haven't seen this done).
   The are differing variations on this approach but the all boil down to
!  the same idea; manipulate the tag(s) with JavaScript to invoke remote requests.
  \layout Standard
  
***************
*** 408,412 ****
  
  Most projects which have used this approach define a local, JavaScript callback
!  function in the static document and have this triggered by the remote document
   as it loads, allowing a response to be passed asychronously to the calling
   client.
--- 429,433 ----
  
  Most projects which have used this approach define a local, JavaScript callback
!  function in the static document and have this triggered by the remote document,
   as it loads, allowing a response to be passed asychronously to the calling
   client.
***************
*** 420,424 ****
  \end_inset 
  
!  about the client, the content of the response it is expected to deliver.
  \layout Standard
  
--- 441,446 ----
  \end_inset 
  
!  about the client; the content of the response must contain Javascript which
!  triggers the clients callback function.
  \layout Standard
  
***************
*** 545,550 ****
  \layout Standard
  
! Breaking down the available approaches (and ignoring stuff like YAML and
!  MIME-RPC) into loose categorization, they can be summarized as;
  \layout Subsubsection
  
--- 567,581 ----
  \layout Standard
  
! Breaking down the available approaches (and ignoring stuff like 
! \begin_inset LatexCommand \htmlurl[YAML]{http://www.yaml.org/}
! 
! \end_inset 
! 
!  and 
! \begin_inset LatexCommand \htmlurl[MIME-RPC]{http://www.mime-rpc.com/}
! 
! \end_inset 
! 
! ) into loose categorization, they can be summarized as;
  \layout Subsubsection
  
***************
*** 623,627 ****
  ).
   You could simply provide XML or even XHTML and manipulate it with DOM in
!  JavaScript.
   This approach has been most successfully employed by 
  \begin_inset LatexCommand \htmlurl[Amazon's REST API]{http://www.onlamp.com/pub/a/php/2003/10/30/amazon_rest.html}
--- 654,663 ----
  ).
   You could simply provide XML or even XHTML and manipulate it with DOM in
!  JavaScript; XMLHttpRequest comes in very handy working this way - 
! \begin_inset LatexCommand \htmlurl[Quick tip: XMLHttpRequest and innerHTML]{http://www.sitepoint.com/blog-post-view.php?id=185942}
! 
! \end_inset 
! 
! .
   This approach has been most successfully employed by 
  \begin_inset LatexCommand \htmlurl[Amazon's REST API]{http://www.onlamp.com/pub/a/php/2003/10/30/amazon_rest.html}
***************
*** 629,633 ****
  \end_inset 
  
!  while a hybrid XHTML is used by 
  \begin_inset LatexCommand \htmlurl[LiveSearch]{http://blog.bitflux.ch/archive/livesearch_got_keyboard_access.html}
  
--- 665,669 ----
  \end_inset 
  
!  while a hybrid form of XHTML is used by 
  \begin_inset LatexCommand \htmlurl[LiveSearch]{http://blog.bitflux.ch/archive/livesearch_got_keyboard_access.html}
  
***************
*** 653,659 ****
  \layout Standard
  
! In general XML is fine as a choice as a platform independent data format,
!  but introduces processing overhead, particularily in some of the more complex
!  encodings such as SOAP plus needs appropriate client / server implementations.
  \layout Standard
  
--- 689,699 ----
  \layout Standard
  
! In general XML is fine as a choice as a 
! \emph on 
! platform independent
! \emph default 
!  data format, but introduces processing overhead, particularily in some
!  of the more complex encodings such as SOAP plus needs appropriate client
!  / server implementations.
  \layout Standard
  
***************
*** 671,679 ****
  \layout Subsubsection
  
! URL Encoding
  \layout Standard
  
! A more down to earth approach is to use what already works with HTTP, namely
!  encoding the URL encoding (see 
  \begin_inset LatexCommand \htmlurl[RFC 1738]{http://www.rfc-editor.org/rfc/rfc1738.txt}
  
--- 711,720 ----
  \layout Subsubsection
  
! URL Encoded (Requests)
  \layout Standard
  
! A more down to earth approach, when sending data from client to server,
!  is to use what already works with HTTP, namely encoding the URL encoding
!  (see 
  \begin_inset LatexCommand \htmlurl[RFC 1738]{http://www.rfc-editor.org/rfc/rfc1738.txt}
  
***************
*** 707,713 ****
   First this is (generally) a request-only encoding - what does the server
   respond with? Second, clients must be careful to escape values correctly
!  (according to RFC 1738)? Finally there's the issue of how complex data
!  structures, such as arrays and objects, are represented; although it's
!  
  \emph on 
  possible
--- 748,754 ----
   First this is (generally) a request-only encoding - what does the server
   respond with? Second, clients must be careful to escape values correctly
!  (according to RFC 1738).
!  Finally there's the issue of how complex data structures, such as arrays
!  and objects, are represented; although it's 
  \emph on 
  possible
***************
*** 718,721 ****
--- 759,767 ----
  \layout Subsubsection
  
+ 
+ \begin_inset LatexCommand \label{sub:Hybrid}
+ 
+ \end_inset 
+ 
  Hybrid
  \layout Standard
***************
*** 785,789 ****
  \end_inset 
  
!  (for which a PHP definition exists).
   Future ScriptServer implementations may allow translations of JavaScript
   classes to PHP classes (e.g.
--- 831,835 ----
  \end_inset 
  
!  (for which a PHP definition is provided, server-side, by ScriptServer).
   Future ScriptServer implementations may allow translations of JavaScript
   classes to PHP classes (e.g.
***************
*** 794,797 ****
--- 840,847 ----
   defined as JavaScript variables and wrapped in an anonymous function.
   The structure is provided as a string for use with JavaScripts eval() function.
+  For any other platform that Javascript in a web browser, exchanging data
+  as eval()able code would be a serious security risk but because we trust
+  the browser to execute Javascript securely (don't we ;)), ScriptServer
+  can get away with it.
  \layout Standard
  
***************
*** 899,903 ****
  
  The reason for the anonymous function is to provide two stages of error
!  checking.
   The call to eval() could fail if the server simply returned garbage (a
   server error).
--- 949,955 ----
  
  The reason for the anonymous function is to provide two stages of error
!  checking as well as allowing the response payload to be assigned to a local
!  variable (vs.
!  creating new variables directly from the response).
   The call to eval() could fail if the server simply returned garbage (a
   server error).
***************
*** 960,963 ****
--- 1012,1026 ----
  
  ");
+ \layout Standard
+ 
+ In other words ScriptServer uses two encodings.
+  PHP byte stream format for client requests and evalable Javascript for
+  server responses.
+  At first glance it may seem strange to use two types of encoding but the
+  advantage is both formats have native parsers on the receiving end.
+  In general it's alot easier to generate some kind of encoded data than
+  it is to parse (consider how easy it is to generate HTML vs.
+  parsing HTML) it so avoiding writing custom parsers significantly reduces
+  coding effort (and bugs) and reduces performance overheads.
  \layout Subsection
  
***************
*** 965,969 ****
  \layout Standard
  
! The remain areas of the 
  \begin_inset Quotes sld
  \end_inset 
--- 1028,1032 ----
  \layout Standard
  
! The remaining areas of the 
  \begin_inset Quotes sld
  \end_inset 
***************
*** 973,977 ****
  \end_inset 
  
!  to consider are how a JavaScript client 
  \begin_inset Quotes sld
  \end_inset 
--- 1036,1040 ----
  \end_inset 
  
!  relate to how a JavaScript client 
  \begin_inset Quotes sld
  \end_inset 
***************
*** 1156,1160 ****
   What's more, specific to PHP, is generating WSDL from a SOAP server is
   not as easy as it should be, WSDL being strongly typed and requiring an
!  additional layer of description in PHP to translate to it.
  \layout Standard
  
--- 1219,1223 ----
   What's more, specific to PHP, is generating WSDL from a SOAP server is
   not as easy as it should be, WSDL being strongly typed and requiring an
!  additional layer of (hand coded) description in PHP to translate to it.
  \layout Standard
  
***************
*** 1200,1204 ****
   is used to generate a corresponding JavaScript client; an object providing
   methods with the same names / signatures as those on the server.
!  The generated client primed to use the server, placing no requirement of
   the developer to manage the networking, data encoding etc.
   required to access the service.
--- 1263,1267 ----
   is used to generate a corresponding JavaScript client; an object providing
   methods with the same names / signatures as those on the server.
!  The generated client primed to use the server, placing no requirement on
   the developer to manage the networking, data encoding etc.
   required to access the service.
***************
*** 1300,1308 ****
  \end_inset 
  
! ; not true XML but something which can be dropped directly into the user
   interface using minimal DOM manipulation.
   This certainly makes light work on the client side but requires, at least
   to an extent, some awareness on the server side of how the client will
   use the response.
  \layout Standard
  
--- 1363,1375 ----
  \end_inset 
  
! ; not true XHTML but something which can be dropped directly into the user
   interface using minimal DOM manipulation.
   This certainly makes light work on the client side but requires, at least
   to an extent, some awareness on the server side of how the client will
   use the response.
+  That can quickly lead to violating the notions of seperation of concerns
+  and layering, meaning logic for the client side user interface gets mixed
+  up with server side application logic; in other words a mess which is difficult
+  to maintain.
  \layout Standard
  
***************
*** 1342,1345 ****
--- 1409,1416 ----
   The downsides are it's Mozilla specific and RDF is, generally, not widely
   understood.
+  Also, the general sense I get of using RDF in Mozilla with an application
+  that's launch directly from a web site (vs.
+  locally installed) is it takes you into the greyer, undocumented areas
+  of Mozilla.
  \layout Standard
  
***************
*** 1351,1355 ****
  \end_inset 
  
!  or DOM manipulation.
   While this can be painful, it should suit the 
  \begin_inset LatexCommand \htmlurl[luddites]{http://en.wikipedia.org/wiki/Luddite}
--- 1422,1426 ----
  \end_inset 
  
! ) or DOM manipulation.
   While this can be painful, it should suit the 
  \begin_inset LatexCommand \htmlurl[luddites]{http://en.wikipedia.org/wiki/Luddite}
***************
*** 1357,1361 ****
  \end_inset 
  
!  (like me).
  \layout Standard
  
--- 1428,1432 ----
  \end_inset 
  
!  (like me) and is well charted territory.
  \layout Standard
  
***************
*** 1367,1373 ****
  \emph default 
   to be contained in the response.
!  This allows for some interesting possibilities (not yet explored) such
!  as a response which contains a list of data as well as function definition
!  which expects, say, an 
  \begin_inset LatexCommand \htmlurl[HTMLSelectElement]{http://xulplanet.com/references/objref/HTMLSelectElement.html}
  
--- 1438,1444 ----
  \emph default 
   to be contained in the response.
!  This allows for some interesting possibilities such as a response which
!  contains a list of data as well as function definition which expects, say,
!  an 
  \begin_inset LatexCommand \htmlurl[HTMLSelectElement]{http://xulplanet.com/references/objref/HTMLSelectElement.html}
  
***************
*** 1382,1386 ****
  .
   Whether this constitutes correct seperation between client and server is
!  a matter for debate.
  \layout Section
  
--- 1453,1465 ----
  .
   Whether this constitutes correct seperation between client and server is
!  a matter for debate but an example is provided with ScriptServer in 
! \begin_inset Quotes sld
! \end_inset 
! 
! sfsearch_server.php
! \begin_inset Quotes srd
! \end_inset 
! 
! .
  \layout Section
  
***************
*** 1620,1623 ****
--- 1699,1706 ----
  \layout LyX-Code
  
+ <!-- Load the generated client side code...
+  -->
+ \layout LyX-Code
+ 
  <script type='text/javascript' src='http://localhost/server.php?client'></script>
  \layout LyX-Code
***************
*** 1690,1693 ****
--- 1773,1791 ----
  \layout Subsubsection
  
+ Requirements
+ \layout Itemize
+ 
+ PHP: tested with PHP 4.1.2 up to 5.0.2 without problems.
+  No special requirements for ini settings and only needs the PCRE extension
+  which is usually on by default.
+ \layout Itemize
+ 
+ Javascript: Needs a Javascript 1.5+ implementation plus XmlHttpRequest support.
+  Tested with Firefox 9.x+ and Internet Explorer 6.x (should work with IE 5.x
+  also).
+  Should work with recent versions of Safari and Konqueror.
+  Opera should be getting an XmlHttpRequest implementation any time now.
+ \layout Subsubsection
+ 
  Loading the Library in PHP
  \layout Standard
***************
*** 2234,2239 ****
  \layout Standard
  
! This may result is excessive numbers of objects (plus I've heard rumours
!  of wierd bugs that start showing up).
   A smart approach might be to use a of pool clients - right now the API
   doesn't help you much with this unless you access 
--- 2332,2338 ----
  \layout Standard
  
! This may result is excessive numbers of objects (plus I've heard stories
!  of wierd bugs that start showing up when more than a certain number of
!  XmlHttpRequest objects are in use).
   A smart approach might be to use a of pool clients - right now the API
   doesn't help you much with this unless you access 
***************
*** 2245,2249 ****
  \end_inset 
  
!  members but that should change later.
  \layout Standard
  
--- 2344,2348 ----
  \end_inset 
  
!  members but that should change in future.
  \layout Standard
  
***************
*** 2553,2555 ****
--- 2652,2860 ----
  
  }
+ \layout Subsubsection
+ 
+ Error Codes
+ \layout Standard
+ 
+ The following error codes have been implemented in ScriptServer;
+ \layout LyX-Code
+ 
+ [Client_Error]
+ \layout LyX-Code
+ 
+ ; Client Errors (range 1000 - 1999)
+ \layout LyX-Code
+ 
+ ; Range 1000 - 1199 is reserved - avoid using them in your code!
+ \layout LyX-Code
+ 
+ 1000 = "Unable to create XmlHttpRequest: not supported"
+ \layout LyX-Code
+ 
+ 1001 = "Call in progress.
+  XmlHttpClient cannot be until current request is completed"
+ \layout LyX-Code
+ 
+ 1002 = "Invalid HTTP status code in server response: must by 200 OK"
+ \layout LyX-Code
+ 
+ 1003 = "Request timed out: asychronous requests only"
+ \layout LyX-Code
+ 
+ 1004 = "Invalid request parameter name: contains non-word characters - must
+  match [^A-Za-z0-9_]"
+ \layout LyX-Code
+ 
+ 1005 = "Call type not defined: request.type must have value = 'async' ||
+  'sync'"
+ \layout LyX-Code
+ 
+ 1006 = "Javascript to PHP serialization error e.g.
+  recursive references in data structure"
+ \layout LyX-Code
+ 
+ 1007 = "Problem calling XmlHttpRequest.open() e.g.
+  permission denied to access URL in different domain"
+ \layout LyX-Code
+ 
+ \layout LyX-Code
+ 
+ [Server_Error]
+ \layout LyX-Code
+ 
+ ; Server Errors (range 2000 - 2999): see ErrorHandler.php
+ \layout LyX-Code
+ 
+ ; Range 2000 - 2199 is reserved - avoid using them in your code!
+ \layout LyX-Code
+ 
+ 2000 = "Internal Server Error" ; Covers PHP E_NOTICE and E_WARNING messages
+ \layout LyX-Code
+ 
+ 2001 = "Server Notice" ; Results from trigger_error() with E_USER_NOTICE
+ \layout LyX-Code
+ 
+ 2002 = "Server Warning" ; Results from trigger_error() with E_USER_WARNING
+ \layout LyX-Code
+ 
+ 2003 = "Server Error" ; Results from trigger_error() with E_USER_ERROR
+ \layout LyX-Code
+ 
+ 2004 = "Internal Server Alert" ; From E_STRICT errors in PHP5
+ \layout LyX-Code
+ 
+ 2005 = "Internal Server Exception" ; Uncaught PHP5 exception
+ \layout LyX-Code
+ 
+ 2006 = "Junk from server.
+  Response not well formed"; Javascript eval() failed - note e.response contains
+  what was evaled
+ \layout LyX-Code
+ 
+ \layout LyX-Code
+ 
+ [Application_Error]
+ \layout LyX-Code
+ 
+ ;Application Errors (range 3000+) - nothing reserved
+ \layout Standard
+ 
+ These can be found in the file ScriptServer/errors/errors.en.ini.
+  The codes are 
+ \begin_inset Quotes sld
+ \end_inset 
+ 
+ attached
+ \begin_inset Quotes srd
+ \end_inset 
+ 
+  to exceptions using the property Error.code e.g.;
+ \layout LyX-Code
+ 
+ var m = new math(MathHandler);
+ \layout LyX-Code
+ 
+ m.timeout = 200;
+ \layout LyX-Code
+ 
+ m.clientErrorFunc = function(e) {
+ \layout LyX-Code
+ 
+     if ( e.code == 1003 ) {
+ \layout LyX-Code
+ 
+         // Ignore this because it's a timeout
+ \layout LyX-Code
+ 
+     }
+ \layout LyX-Code
+ 
+ }
+ \layout Standard
+ 
+ For some errors, further properties are used to return useful information
+  for troubleshooting.
+  For example error code 1002 (invalid HTTP status) adds the property .headers
+  to the exception, which contains all the HTTP response headers received
+  from the server.
+  Also error code 2006 adds a property .response which contains the text response
+  body from the server.
+ \layout Standard
+ 
+ If you wish to implement your own errors codes, typically these will be
+  in the 3000+ range (application errors).
+  It's a good idea to use error codes as it allows the client side to respond
+  accurately to different problems it may encounter plus allows delivery
+  of localised error messages in languages other than English (see below).
+  The ranges 1000-1199 and 2000-2199 are reserved as possible future ScriptServer
+  error codes (avoid defining them in your own code).
+ \layout Subsubsection*
+ 
+ Localised Error Messages
+ \layout Standard
+ 
+ As a basic mechanism to allow localised error messages to be displayed to
+  users, the ScriptServer_Renderer class provides the method addErrorReader()
+  which generates a client side Javascript function called ScriptServer_ErrorRead
+ er, containing a dictionary of error codes and their messages.
+  The error codes are read, server side, from a file parallel to the errors.en.ini
+  file (currently there are no translations).
+  In principle this could be used like;
+ \layout Standard
+ 
+ Server Side:
+ \layout LyX-Code
+ 
+ <?php
+ \layout LyX-Code
+ 
+ //...
+ \layout LyX-Code
+ 
+ require_once SCRIPT_SERVER .
+  'Renderer.php';
+ \layout LyX-Code
+ 
+ $R = & new ScriptServer_Renderer();
+ \layout LyX-Code
+ 
+ \layout LyX-Code
+ 
+ // Note this function accepts a second argument; a hash
+ \layout LyX-Code
+ 
+ // of application errors - see the source
+ \layout LyX-Code
+ 
+ $R->addErrorReader('de'); // Load the German error messages
+ \layout LyX-Code
+ 
+ \layout LyX-Code
+ 
+ $R->render();
+ \layout LyX-Code
+ 
+ ?>
+ \layout Standard
+ 
+ On the client side the generated ScriptServer_ErrorReader function could
+  be used like;
+ \layout LyX-Code
+ 
+ var MathHandler = {
+ \layout LyX-Code
+ 
+    divideError: function(e) {
+ \layout LyX-Code
+ 
+        // Display the German error message
+ \layout LyX-Code
+ 
+        alert( ScriptServer_ErrorReader(e.code) );
+ \layout LyX-Code
+ 
+    }
+ \layout LyX-Code
+ 
+ }
  \the_end