[Supervisor-checkins] r793 - in supervisor_manual/trunk: . chapters html
Mike Naberezny
mike at maintainable.com
Sat Aug 9 21:59:56 EDT 2008
Author: Mike Naberezny <mike at maintainable.com>
Date: Sat Aug 9 21:59:56 2008
New Revision: 793
Log:
Document the 'system' namespace.
Added:
supervisor_manual/trunk/chapters/api-system.xml
Modified:
supervisor_manual/trunk/html/HTML.manifest
supervisor_manual/trunk/manual.xml
Added: supervisor_manual/trunk/chapters/api-system.xml
==============================================================================
--- (empty file)
+++ supervisor_manual/trunk/chapters/api-system.xml Sat Aug 9 21:59:56 2008
@@ -0,0 +1,287 @@
+<sect1 id="api.system">
+ <title>System Methods</title>
+
+ <para>
+ Many XML-RPC servers support a set of de facto methods organized under a
+ <code>system</code> namespace. When Supervisor's main RPC interface
+ is registered, it provides both the <code>supervisor</code> namespace and
+ also a <code>system</code> namespace. The methods available in the
+ <code>system</code> namespace are described in this section.
+ </para>
+
+ <sect2 id="api.system.listMethods">
+ <title>system.listMethods()</title>
+
+ <para>
+ <programlisting><![CDATA[
+system.listMethods()
+]]></programlisting>
+ </para>
+
+ <table>
+ <title>system.listMethods() Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>system.listMethods() Return Value</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>array</entry>
+ <entry>Method names</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <code>system.listMethods()</code> returns an array containing all of the
+ method names that are available to be called on the Supervisor instance.
+ </para>
+ </sect2>
+
+ <sect2 id="api.system.methodSignature">
+ <title>system.methodHelp()</title>
+
+ <para>
+ <programlisting><![CDATA[
+system.methodHelp()
+]]></programlisting>
+ </para>
+
+ <table>
+ <title>system.methodHelp() Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>string</entry>
+ <entry>name</entry>
+ <entry>Name of the method to look up</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>system.methodHelp() Return Value</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>string</entry>
+ <entry>Description of the method's purpose and parameters</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <code>system.methodHelp()</code> returns a string describing a given
+ method. This is generated automatically from the inline comments in the
+ Supervisor source code. The output is similar to JavaDoc.
+ </para>
+
+ <para>
+ If the given method name is not recognized, the fault
+ <code>SIGNATURE_UNSUPPORTED</code> will be returned.
+ </para>
+ </sect2>
+
+ <sect2 id="api.system.methodSignature">
+ <title>system.methodSignature()</title>
+
+ <para>
+ <programlisting><![CDATA[
+system.methodSignature()
+]]></programlisting>
+ </para>
+
+ <table>
+ <title>system.methodSignature() Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>string</entry>
+ <entry>name</entry>
+ <entry>Name of the method to look up</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>system.methodSignature() Return Value</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>array</entry>
+ <entry>
+ An array of strings, each containing the name of an XML-RPC type
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ <code>system.methodSignature()</code> returns information about a
+ method's return type and the types of any parameters it may receive. The
+ information is returned as an array of strings, where each string
+ contains the name of an XML-RPC type such as <code>integer</code> or
+ <code>boolean</code>.
+ </para>
+
+ <para>
+ The first element in the array will be the method's return type. Any
+ successive elements are the types of the method's parameters. If the
+ method has any optional parameters, those types will always be included
+ at the end of the signature array.
+ </para>
+
+ <para>
+ If the given method name is not recognized, or the method signature
+ could not be generated for any other reason, the fault
+ <code>SIGNATURE_UNSUPPORTED</code> will be returned.
+ </para>
+ </sect2>
+
+ <sect2 id="api.system.multicall">
+ <title>system.multicall()</title>
+
+ <para>
+ <programlisting><![CDATA[
+system.multicall()
+]]></programlisting>
+ </para>
+
+ <table>
+ <title>system.multicall() Parameters</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>array</entry>
+ <entry>calls</entry>
+ <entry>
+ An array of structs, where each struct represents a method call
+ and its parameters like
+ <code>{'methodName': 'supervisor.startProcess', 'params': ['foo']}</code>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <table>
+ <title>system.multicall() Return Value</title>
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry>Type</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>array</entry>
+ <entry>
+ An array where each element contains the return value from a
+ method call. If any method failed, its element will contain
+ a struct like
+ <code>{'faultCode': 10, 'faultName': 'BAD_NAME'}</code>.
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ <para>
+ Each XML-RPC method call normally requires one roundtrip to Supervisor's
+ HTTP server. When it is necessary to make multiple XML-RPC method calls
+ to a Supervisor instance, it may be possible to boxcar them into a
+ single HTTP request using the <code>system.multicall()</code> method.
+ </para>
+
+ <para>
+ <code>system.multicall()</code> takes an array as its only parameter.
+ Each element in the array is a struct representing a single method call.
+ The struct must have a key <code>methodName</code> whose value is a
+ string containing a valid Supervisor XML-RPC method name. The struct
+ must also also have a key <code>params</code> whose value is an array
+ containing the parameters for the method.
+ </para>
+
+ <para>
+ Supervisor will attempt to call each method specified with the given
+ parameters. From the client's perspective, the execution order on the
+ server is unspecified. The methods are effectively executed in parallel,
+ i.e. no method in the call can depend on the execution of any other
+ method in the call.
+ </para>
+
+ <para>
+ The return value from <code>system.multicall()</code> will be an array.
+ Each element in the array will be the return value from a method call.
+ The order of the array is the same order as the input array.
+ </para>
+
+ <para>
+ If any method call executed during a <code>system.multicall</code>
+ returns a fault, its element in the return array will contain a struct
+ with keys <code>faultCode</code> and <code>faultString</code>.
+ </para>
+ </sect2>
+
+</sect1>
+
+<!--
+vim:se ts=4 sw=4 et:
+-->
\ No newline at end of file
Modified: supervisor_manual/trunk/html/HTML.manifest
==============================================================================
--- supervisor_manual/trunk/html/HTML.manifest (original)
+++ supervisor_manual/trunk/html/HTML.manifest Sat Aug 9 21:59:56 2008
@@ -14,5 +14,6 @@
./api.html
./api.process-control.html
./api.process-logging.html
+./api.system.html
./api.faults.html
./the.index.html
Modified: supervisor_manual/trunk/manual.xml
==============================================================================
--- supervisor_manual/trunk/manual.xml (original)
+++ supervisor_manual/trunk/manual.xml Sat Aug 9 21:59:56 2008
@@ -58,6 +58,7 @@
&chapters.api-status-control;
&chapters.api-process-control;
&chapters.api-process-logging;
+ &chapters.api-system;
&chapters.api-faults;
</chapter>
More information about the Supervisor-checkins
mailing list