xmlrpc_js.xml

<?xml version="1.0" encoding="ISO-8859-1"?>
<?xml-stylesheet href="docbook-css/driver.css" type="text/css"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
    "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
JS-XMLRPC User manual
-->
<book lang="en">
  <title>JS-XMLRPC</title>

  <subtitle>version 0.6.2</subtitle>

  <bookinfo>
    <date>19 12 2012</date>

    <author>
      <surname>Gaetano Giunta</surname>
    </author>

    <copyright>
      <year>2007-2022 G. Giunta</year>
    </copyright>
  </bookinfo>

  <chapter>
    <title>Introduction</title>

    <para>This collection of Javascript classes provides a framework for writing XML-RPC and JSON-RPC clients.</para>

    <para>Main goals of the project are ease of use, flexibility and completeness. And of course, full API compatibility
    with the <ulink url="https://github.com/gggeek/phpxmlrpc">PHP-XMLRPC</ulink> library.</para>

    <para>XML-RPC is a format devised by <ulink url="http://www.userland.com/">Userland Software</ulink> for achieving
    remote procedure call via XML using HTTP as the transport. XML-RPC has its own web site, <ulink
    url="http://www.xmlrpc.com/">www.xmlrpc.com.</ulink></para>

    <para><ulink url="https://www.json.org/">JSON</ulink> is a format devised to ease serialization and deserialization
    of common data types without incurring the overhead that is normally associated with XML. It is a subset of the
    Javascript language, and as such it is easily manipulated within web browsers.</para>

    <para><ulink url="https://www.jsonrpc.org">JSON-RPC</ulink> is a remote procedure call protocol that uses HTTP for
    transport and a json syntax extremely similar to the xml-rpc one.</para>

    <para>Many thanks to the original author of the PHP-XMLRPC library: Edd Dumbill of <ulink
    url="http://usefulinc.com/">Useful Information Company</ulink>, to Jan-Klaas Kollhof for the Jsolait library and to
    the Yahoo! YUI team, for building such an incredible toolkit.</para>
  </chapter>

  <chapter>
    <title>What's new</title>

    <sect1>
      <para>For all releases after 0.4, see the release info on GitHub at <ulink
      url="https://github.com/gggeek/jsxmlrpc/releases">https://github.com/gggeek/jsxmlrpc/releases</ulink></para>
    </sect1>

    <sect1>
      <title>version 0.4</title>

      <para><itemizedlist>
          <listitem>
            <para>added method setUserCredentials to xmlrpc_client, as the
            'parent' php lib does in its latest version</para>
          </listitem>

          <listitem>
            <para>added support for the &lt;ex:nil/&gt; tag from the apache
            library, both in input and output (output regulated by the
            xmlrpc_null_apache_encoding variable, input by
            thexmlrpc_null_extension one)</para>
          </listitem>

          <listitem>
            <para>base64_decode now trims whitespace</para>
          </listitem>

          <listitem>
            <para>updated bundled yui to version 2.5.0</para>
          </listitem>

          <listitem>
            <para>fixed a bug in error log handler when using
            firefox+firebug</para>
          </listitem>

          <listitem>
            <para>fixed a bug in xmlrpc_decode with structs</para>
          </listitem>

          <listitem>
            <para>fixed a bug in parsing cookie headers in http
            responses</para>
          </listitem>

          <listitem>
            <para>allow lib to work in Windows Scripting Host
            environments</para>
          </listitem>

          <listitem>
            <para>added two demo files, for WSH and VB</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>version 0.3</title>

      <para><itemizedlist>
          <listitem>
            <para>A lot of bugs have been fixed in all areas of encoding and
            decoding xmlrpc values</para>
          </listitem>

          <listitem>
            <para>The debug and error logging mechanism has been rewritten,
            and will take advantage of Firebug when detected</para>
          </listitem>

          <listitem>
            <para>There is better support for Firefox when setting debug mode
            to clients, and for Safari when the port is not specified in the
            server url</para>
          </listitem>

          <listitem>
            <para>The function <function>wrap_xmlrpc_server</function> (from
            the original PHP api) has been implemented, and a couple of bugs
            fixed in <function>wrap_xmlrpc_method</function></para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>version 0.2</title>

      <para><itemizedlist>
          <listitem>
            <para><methodname>client.send()</methodname> supports async calls.
            In order to activate this functionality, pass a function as third
            parameter. Note that the timeout parameter only has effect in
            async calls.</para>
          </listitem>

          <listitem>
            <para>the <function>wrap_xmlrpc_method</function>() function is
            finally working. It makes the wrapping of remote webservicesinto
            native javascript functions (a.k.a. proxying) a snap</para>
          </listitem>

          <listitem>
            <para>the debugger can nowgenerate example code for invocation of
            remote methods</para>
          </listitem>

          <listitem>
            <para>minor assorted bugfixes, especially for Internet
            Explorer</para>
          </listitem>

          <listitem>
            <para>a minified (ie. compact) version of the library has been
            included in the distribution. It can be used instead of the
            standard version on webservers where bandwidth savings are
            important</para>
          </listitem>

          <listitem>
            <para>better documentation has been included in the distribution,
            most notably the (almost complete) API specification</para>
          </listitem>
        </itemizedlist></para>
    </sect1>

    <sect1>
      <title>version 0.1</title>

      <para>Initial release of the library. Many "nice bits" are still missing
      (see <link linkend="Chapter5">Chapter 5</link> below), but the basic
      encoding/decoding functionality should be ok.</para>
    </sect1>
  </chapter>

  <chapter>
    <title>System requirements</title>

    <para>Any browser or Javascript host with support for ECMAScript 6 including XMLHttpRequest and DOMParser. That
    should include NodeJS version v12.20.0 or v14.13.0 or later and Chrome 61, Edge 16, Firefox 60, Opera 48, Safari 11,
    Chrome Android 108, Firefox for Android 107, Opera Mobile 72, Safari on iOS 11, Samsung Internet 8.2.</para>

    <para>Your mileage may vary on other browsers / javascript hosts.</para>
  </chapter>

  <chapter>
    <title>Files in the distribution</title>

    <para><itemizedlist>
        <listitem>
          <para><filename>lib/xmlrpc_lib.js</filename>: the XML_RPC classes.
          This is the core library needed by all other files</para>
        </listitem>

        <listitem>
          <para><filename>lib/jsonrpc_lib.js</filename>: the JSON-RPC classes</para>
        </listitem>

        <listitem>
          <para><filename>lib/xmlrpc_wrappers.js</filename>: helper functions to "automagically" convert calls to remote
          webservices into javascript classes / functions</para>
        </listitem>

        <listitem>
          <para><filename>lib/index.js</filename>: this file contains all module exports from the 3 files listed above,
          making it easy to import everything from a single `import` line</para>
        </listitem>

        <listitem>
          <para><filename>debugger/debugger.html</filename>: a graphical webservice debugger</para>
        </listitem>

        <listitem>
          <para><filename>debugger/visualeditor.html</filename>,
          <filename>debugger/visualeditor.css</filename>,
          <filename>debugger/xmlrpc_display.js</filename>,
          <filename>debugger/xmlrpc_tree.css</filename>, plus all the other files (taken from the YUI distribution):
          visual editor component for creating arbitrarily nested xml-rpc/json-rpc values. It can be used as part of the
          js-xmlrpc debugger, as well as in the debugger that comes with the PHP-XMLRPC library or the docxmlrpcserver
          class part of phpxmlrpc/extras php package</para>
        </listitem>

        <listitem>
          <para><filename>doc/xmlrpc_js.xml</filename>: the docbook source file for this manual</para>
        </listitem>

        <listitem>
          <para><filename>doc/manual/*.html</filename>,
          <filename>doc/manual/*.css</filename>: this manual, in HTML format</para>
        </listitem>

        <listitem>
          <para><filename>README.md</filename>; <filename>NEWS.md</filename>: as the name implies, useful
          information bits</para>
        </listitem>

      </itemizedlist></para>
  </chapter>

  <chapter>
    <title id="Chapter5">Known bugs and limitations</title>

    <para>Missing functionality that is part of the PHP-XMLRPC library include: handling of charset encoding (where
    explicitly requested by the user); timeout in send() methods for the sync calls; compression of requests; handling
    of compression, chunked encoding in parseResponseHeaders (the response body is decoded correctly by the browser);
    encoding/decoding of anonymous js classes via an xml attribute (since it is hard to recover a class name, we could
    encode instead all methods as code); allow username/password auth be specified in URL when creating a client object;
    using client credentials for https auth</para>

    <para>Other: demo cases, reduce JSLint warnings, a testsuite and speed tests</para>
  </chapter>

  <chapter>
    <title>Support</title>

    <para>JS-XMLRPC is offered "as-is" without any warranty or  commitment to support. However, informal advice and help
    is available via the JS-XMLRPC website.</para>

    <itemizedlist>
      <listitem>
        <para>The <emphasis>JS-XMLRPC</emphasis> development is hosted on <ulink
        url="https://github.com/gggeek/jsxmlrpc">github.com/gggeek/jsxmlrpc</ulink>.  Bugs, feature requests and patches
        can be posted to the <ulink url="https://github.com/gggeek/jsxmlrpc/issues">project's website</ulink>.</para>
      </listitem>
    </itemizedlist>
  </chapter>

  <chapter>
    <title>Class documentation</title>

    <para>Where's the meat?</para>

    <para>Unfortunately, the documentation of the API exposed by the library
    has not (yet) really been integrated into the manual.</para>

    <para>Luckily, it is available in HTML format online at: <ulink url="???">...</ulink>. You can build it locally
    too if so inclined</para>

    <para>For more details, the manual that comes with the php-xmlrpc library might prove helpful: after all the two
    libraries share the exact same API (except for a handful of small quirks due to differences in the underlying
    language, detailed in Apendix A). It is available online at <ulink
    url="https://gggeek.github.io/phpxmlrpc/doc-2/">https://gggeek.github.io/phpxmlrpc/doc-2/</ulink></para>
  </chapter>

  <appendix>
    <title>Known differences from the PHP-XMLRPC API</title>

    <para>Although the library is designed to implent the same programming interfaces of the php-xmlrpc library,
    differences in the languages (javascript vs. pgp) and underlying platform (browser vs. php engine) prevent a complete
    match. This list details the known differences in the behaviour of the two libraries. Please note that most of the
    discrepancies deal with private members of objects, unusual usage patterns and little known corner cases, and are
    mostly of interest to people that wish to extend / modify the library rather than just use it.</para>

    <para><itemizedlist>
        <listitem>
          <para>the internal, private structure of the xmlrpcval objects is slightly different</para>
        </listitem>

        <listitem>
          <para>xmlrpcresp.serialize() produces a complete xml chunk, including the xml prologue. In php-xmlrpc the
          prologue is omitted</para>
        </listitem>

        <listitem>
          <para>adding data to a struct value using the same keys of elements that already exist in the struct might
          produce different results</para>
        </listitem>

        <listitem>
          <para>xmlrpcresp objects have no private member 'content-type'</para>
        </listitem>

        <listitem>
          <para>the values of the global object 'xmlrpcTypes' (an array in php) differ (although the keys are the same)
          </para>
        </listitem>

        <listitem>
          <para>the method <methodname>xmlrpcval::addScalar()</methodname> does not coerce values to the appropriate
          type when declaring them as boolean</para>
        </listitem>

        <listitem>
          <para>the method <methodname>xmlrpcmsg::parseResponse()</methodname> can take a string as second parameter
          (which is assumed to be the full http response headers text)</para>
        </listitem>

        <listitem>
          <para>all classes have an <methodname>init()</methodname> constructor method (used for subclassing)</para>
        </listitem>

        <listitem>
          <para>when using a browser as javascript host, the client object by default inherits the browser settings with
          regard to http connections, eg. it can have keepalive ON, make use of HTTP 1.1 and will support receiving
          compressed content and content in many charsets (the browser taking care of the transcoding)</para>
        </listitem>

        <listitem>
          <para>the client object by default will send to the server any cookie received in previous requests. In
          php-xmlrpc all cookie handling has to be done by hand</para>
        </listitem>

        <listitem>
          <para>the client object does not support setting ssl certificates, proxies, ntlm authorization</para>
        </listitem>

        <listitem>
          <para>all output generated by the lib is performed by two functions:
          <function>xmlrpc_error_log</function> and
          <function>xmlrpc_debug_log</function> (for which the user can set up a message handler), whereas in php it
          is sent to stdout and stderr</para>
        </listitem>

        <listitem>
          <para>method names are case sensitive in javascript, and this lib respects camelCase convention</para>
        </listitem>
      </itemizedlist></para>
  </appendix>
</book>