PageRenderTime 44ms CodeModel.GetById 15ms RepoModel.GetById 0ms app.codeStats 0ms

/Docs/phpAPI.html

http://github.com/yahoo/Pluton
HTML | 263 lines | 210 code | 53 blank | 0 comment | 0 complexity | 25d6183b703f6351a53fd448c91d9462 MD5 | raw file
    

  1. <html>
    2. 

  2. <head>
    3. 

  3. <link rel="shortcut icon" href=images/pluto-symbol.jpg type="image/x-icon" />
    4. 

  4. <title>
    5. 

  5. The Pluton Framework: PHP API
    6. 

  6. </title>
    7. 

  7. </head>
    8. 

  8. 

  9. <body>
    10. 

  10. 

  11. <center>
    12. 

  12. <a href=index.html>
    13. 

  13. <img height=100 src=images/pluto-charon.jpg ALT="[Pluto Charon Image]">
    14. 

  14. </a>
    15. 

  15. </center>
    16. 

  16. 

  17. <h2 align=center>The Pluton Framework: PHP API</h2>
    18. 

  18. 

  19. <h3>Introduction</h3>
    20. 

  20. 

  21. The PHP API is a <a href=http://www.zend.com>ZEND</a> extension
    22. 

  22. around the C++ <a href=clientAPI.html>client</a> and
    23. 

  23. <a href=serviceAPI.html>service</a> APIs.
    24. 

  24. 

  25. The PHP API is semantically very similar to its C++ counterparts; the main differences being
    26. 

  26. the parameters passed to the APIs.
    27. 

  27. <p>
    28. 

  28. 

  29. This document highlights the differences between the C++ API and the
    30. 

  30. PHP API. For a more complete description of each of the APIs please
    31. 

  31. refer the C++ <a href=clientAPI.html>client</a>
    32. 

  32. and <a href=serviceAPI.html>service</a> APIs.
    33. 

  33. <h3>Sample Programs</h3>
    34. 

  34. 

  35. This sample php client demonstrates sending a
    36. 

  36. request to the <code>system.echo.0.raw</code> service.
    37. 

  37. 

  38. <p>
    39. 

  39. <table border=1 width="75%">
    40. 

  40. <td>
    41. 

  41. <pre>
    42. 

  42. 

  43. &lt;?php
    44. 

  44. 

  45. define('SERVICE_KEY', 'test.parrot.0.raw');
    46. 

  46. 

  47. $pc = new PlutonClient('echoClient');
    48. 

  48. $pc->initialize();
    49. 

  49. 

  50. $echoReq = new PlutonClientRequest();
    51. 

  51. 

  52. /* Set the request data */
    53. 

  53. $echoReq->setRequestData("Hello World!");
    54. 

  54. 

  55. /* Add the request to the queue */
    56. 

  56. if(!($pc->addRequest(SERVICE_KEY, $echoReq))) {
    57. 

  57. print_r("[addRequest Error] " . $pc->getFault() . "\n");
    58. 

  58. exit(-1);
    59. 

  59. }
    60. 

  60. 

  61. /* Execute the request */
    62. 

  62. $pc->executeAndWaitAll();
    63. 

  63. if ($pc->hasFault()) {
    64. 

  64.  print_r("[Fault] " . $pc->getFault() . "\n");
    65. 

  65.  exit(-1);
    66. 

  66. }
    67. 

  67. 

  68. $response = "";
    69. 

  69. 

  70. /* Extract the response data */
    71. 

  71. $fault = $echoReq->getResponseData($response);
    72. 

  72. if ($fault == 0) {
    73. 

  73. print_r("Response: " . $response . "\n");
    74. 

  74. }
    75. 

  75. else {
    76. 

  76. print_r("[Fault] " . $echoReq->getFaultText() . "\n");
    77. 

  77. }
    78. 

  78. 

  79. ?&gt;
    80. 

  80. </pre>
    81. 

  81. </table>
    82. 

  82. 

  83. <p>
    84. 

  84. Its corresponding service looks like:
    85. 

  85. <p>
    86. 

  86. <table border=1 width="75%">
    87. 

  87. <td>
    88. 

  88. <pre>
    89. 

  89. 

  90. &lt;?php
    91. 

  91. 

  92. // Create and initialize the Pluton service.
    93. 

  93. $service = new PlutonService('test.parrot.0.raw');
    94. 

  94. $service->initialize();
    95. 

  95. 

  96. // Invoke the call loop.
    97. 

  97. while($service->getRequest()) {
    98. 

  98. 	// Call received, deserialize the request.
    99. 

  99. 	$request = trim($service->getRequestData());
    100. 

  100. 

  101. 	if($request === 'fault') {
    102. 

  102. 		$service->sendFault(11, 'You asked for a fault...so here you go');
    103. 

  103. 	}
    104. 

  104. 	else {
    105. 

  105. 		if(!$service->sendResponse($request)) {
    106. 

  106. 			$service->sendFault(11, 'sendResponse() failed');
    107. 

  107. 		}
    108. 

  108. 	}
    109. 

  109. }
    110. 

  110. 

  111. // Call loop completed, see if the loop exited early due to a fault.
    112. 

  112. if($service->hasFault()) {
    113. 

  113. 	// Call loop exited because of a fault.
    114. 

  114. 	error_log('Service had a fault');
    115. 

  115. }
    116. 

  116. 

  117. // Terminate the service.
    118. 

  118. $service->terminate();
    119. 

  119. 

  120. // Exit code zero indicating no major failure.
    121. 

  121. exit(0);
    122. 

  122. 

  123. ?&gt;
    124. 

  124. 

  125. </pre>
    126. 

  126. </table>
    127. 

  127. 

  128. 

  129. <h3>ClientRequest</h3>
    130. 

  130. <p>
    131. 

  131. <b>Class:</b> PlutonClientRequest
    132. 

  132. <p>
    133. 

  133. The following table lists the PHP Client and Service APIs available and the differences that
    134. 

  134. exists between them and the C++ counterparts.
    135. 

  135. <p>
    136. 

  136. 

  137. <table border=1>
    138. 

  138. <tr valign=top><th align=left>PHP ClientRequest Methods<th align=left>Same as C++<th align=left>Comments</tr>
    139. 

  139. 

  140. 

  141. <tr valign=top><th align=left><a href=clientAPI.html#clearAttribute>clearAttribute()</a><td>Yes<td></tr>
    142. 

  142. <tr valign=top><th align=left><a href=clientAPI.html#getAttribute>getAttribute()</a><td>Yes<td></tr>
    143. 

  143. <tr valign=top><th align=left><a href=clientAPI.html#getClientHandle>getClientHandle()</a><td>Yes<td>Note that the client handle is a 32 bit integer</tr>
    144. 

  144. <tr valign=top><th align=left><a href=clientAPI.html#getFaultCode>getFaultCode()</a><td>Yes<td></tr>
    145. 

  145. <tr valign=top><th align=left><a href=clientAPI.html#getFaultText>getFaultText()</a><td>Yes<td></tr>
    146. 

  146. <tr valign=top><th align=left><a href=clientAPI.html#getResponseData>getResponseData()</a><td>Yes<td></tr>
    147. 

  147. <tr valign=top><th align=left><a href=clientAPI.html#getServiceName>getServiceName()</a><td>Yes<td></tr>
    148. 

  148. <tr valign=top><th align=left><a href=clientAPI.html#hasFault>hasFault()</a><td>Yes<td></tr>
    149. 

  149. <tr valign=top><th align=left><a href=clientAPI.html#inProgress>inProgress()</a><td>Yes<td></tr>
    150. 

  150. <tr valign=top><th align=left><a href=clientAPI.html#requestReset>reset()</a><td>Yes<td></tr>
    151. 

  151. 

  152. <tr valign=top><th align=left><a href=clientAPI.html#setAttribute>setAttribute()</a><td>Yes<td>
    153. 

  153. <pre>
    154. 

  154. The attribute names differ from their C++ counterparts:<br/>
    155. 

  155. PLUTON_ALL_ATTR --> pluton::allAttrs
    156. 

  156. PLUTON_KEEPAFFINITY_ATTR --> pluton::keepAffinityAttr
    157. 

  157. PLUTON_NEEDAFFINITY_ATTR --> pluton::needAffinityAttr
    158. 

  158. PLUTON_NOREMOTE_ATTR --> pluton::noRemoteAttr
    159. 

  159. PLUTON_NORETRY_ATTR --> pluton::noRetryAttr
    160. 

  160. PLUTON_NOWAIT_ATTR --> pluton::noWaitAttr
    161. 

  161. </pre>
    162. 

  162. </tr>
    163. 

  163. 

  164. <tr valign=top><th align=left><a href=clientAPI.html#setClientHandle>setClientHandle()</a><td>Yes<td>Note that the client handle is a 32 bit integer</tr>
    165. 

  165. <tr valign=top><th align=left><a href=clientAPI.html#setContext>setContext()</a><td>Yes<td></tr>
    166. 

  166. <tr valign=top><th align=left><a href=clientAPI.html#setRequestData>setRequestData()</a><td>Yes<td></tr>
    167. 

  167. 

  168. </table>
    169. 

  169. 

  170. <h3>Client Methods</h3>
    171. 

  171. 

  172. <b>Class:</b> PlutonClient
    173. 

  173. <p>
    174. 

  174. The following table lists the PlutonClient methods available as part of the PHP
    175. 

  175. APIs.
    176. 

  176. <p>
    177. 

  177. 

  178. <table border=1>
    179. 

  179. <tr valign=top><th align=left>PHP API<th align=left>Same as C++<th align=left>Comments</tr>
    180. 

  180. 

  181. <tr valign=top><th align=left><a href=clientAPI.html#addRequest>addRequest()</a><td>Yes<td>Supplied parameter is a reference to a<code>PlutonClientRequest</code></tr>
    182. 

  182. <tr valign=top><th align=left><a href=clientAPI.html#clientGetFault>getFault()</a><td>No<td>Returns the long fault message (without prefix) from the <a href=fault.html><code>pluton::fault</code></a> object associated with this client object</tr>
    183. 

  183. <tr valign=top><th align=left><a href=fault.html#getFaultCode>getFaultCode()</a><td>New<td>Returns the fault code from the associated <a href=fault.html><code>pluton::fault</code></a> object associated with the PHP <code>PlutonClient</code> object</tr>
    184. 

  184. <tr valign=top><th align=left><a href=fault.html#getMessage>getFaultMessage()</a><td>New<td>Returns the fault message from the associated <a href=fault.html><code>pluton::fault</code></a> object associated with the PHP <code>PlutonClient</code> object. The parameters to this method are the same as <a href=fault.html#getMessage><code>pluton::fault::getMessage()</code></a></tr>
    185. 

  185. <tr valign=top><th align=left><a href=clientAPI.html#clientHasFault>hasFault()</a><td>Yes<td></tr>
    186. 

  186. <tr valign=top><th align=left><a href=clientAPI.html#executeAndWaitAll>executeAndWaitAll()</a><td>Yes<td></tr>
    187. 

  187. <tr valign=top><th align=left><a href=clientAPI.html#executeAndWaitAny>executeAndWaitAny()</a><td>No<td>Return value is clientHandle of completed request or zero if no request completed.<br>Note that the semantics of this call are experimental and may change to more accurately reflect the C++ interface.</tr>
    188. 

  188. <tr valign=top><th align=left><a href=clientAPI.html#executeAndWaitOne>executeAndWaitOne()</a><td>Yes<td>Supplied parameter is a <code>PlutonClientRequest</code> object</tr>
    189. 

  189. <tr valign=top><th align=left><a href=clientAPI.html#executeAndWaitSent>executeAndWaitSent()</a><td>Yes<td></tr>
    190. 

  190. <tr valign=top><th align=left><a href=clientAPI.html#getAPIVersion>getAPIVersion()</a><td>Yes<td></tr>
    191. 

  191. <tr valign=top><th align=left><a href=clientAPI.html#getTimeoutMilliSeconds>getTimeoutMilliSeconds()</a><td>Yes<td></tr>
    192. 

  192. <tr valign=top><th align=left><a href=clientAPI.html#initialize>initialize()</a><td>Yes<td></tr>
    193. 

  193. <tr valign=top><th align=left><a href=clientAPI.html#setDebug>setDebug()</a><td>Yes<td></tr>
    194. 

  194. <tr valign=top><th align=left><a href=clientAPI.html#setTimeoutMilliSeconds>setTimeoutMilliSeconds()</a><td>Yes<td></tr>
    195. 

  195. <tr valign=top><th align=left><a href=clientAPI.html#clientReset>reset()</a><td>Yes<td></tr>
    196. 

  196. 

  197. </table>
    198. 

  198. 

  199. <h3>Service Methods</h3>
    200. 

  200. <b>Class:</b> PlutonService
    201. 

  201. <p>
    202. 

  202. <p>
    203. 

  203. 

  204. <table border=1>
    205. 

  205. <tr valign=top><th align=left>PHP APIs<th align=left>Same as C++<th align=left>Comments</tr>
    206. 

  206. 

  207. <tr valign=top><th align=left><a href=serviceAPI.html#getAPIVersion>getAPIVersion()</a><td>Yes<td></tr>
    208. 

  208. <tr valign=top><th align=left><a href=serviceAPI.html#getClientName>getClientName()</a><td>No<td>No parameter is passed to this routine</tr>
    209. 

  209. 

  210. <tr valign=top><th align=left><a href=serviceAPI.html#getContext>getContext()</a><td>No<td>No second parameter is passed to this routine - Context data is the return value, eg:
    211. 

  211. <br>
    212. 

  212. <pre>
    213. 

  213. $cd = $r->getContextData("echo.timeoutMS");
    214. 

  214. print_r "Context data is $cd\n";
    215. 

  215. </pre>
    216. 

  216. </tr>
    217. 

  217. 

  218. <tr valign=top><th align=left><a href=serviceAPI.html#serviceGetFault>getFault()</a><td>No<td>
    219. 

  219. Returns the long fault message (without prefix) from
    220. 

  220. the <a href=fault.html><code>pluton::fault</code></a> object associated
    221. 

  221. with this service object</tr>
    222. 

  222. 

  223. <tr valign=top><th align=left><a href=fault.html#getFaultCode>getFaultCode()</a><td>New<td>
    224. 

  224. Returns the fault code from the
    225. 

  225. associated <a href=fault.html><code>pluton::fault</code></a> object
    226. 

  226. associated with this service object</tr>
    227. 

  227. 

  228. <tr valign=top><th align=left><a href=fault.html#getMessage>getFaultMessage()</a><td>New<td>
    229. 

  229. Returns the fault message from the
    230. 

  230. associated <a href=fault.html><code>pluton::fault</code></a> object
    231. 

  231. associated with this service object. The
    232. 

  232. parameters to this method are the same as <a href=fault.html#getMessage><code>pluton::fault::getMessage()</code></a></tr>
    233. 

  233. </tr>
    234. 

  234. 

  235. <tr valign=top><th align=left><a href=serviceAPI.html#getRequest>getRequest()</a><td>Yes<td></tr>
    236. 

  236. <tr valign=top><th align=left><a href=serviceAPI.html#getRequestData>getRequestData()</a><td>No<td>No parameter is passed to this routine - Request data is the return value</tr>
    237. 

  237. <tr valign=top><th align=left><a href=serviceAPI.html#getSerializationType>getSerializationType()</a><td>Yes<td></tr>
    238. 

  238. <tr valign=top><th align=left><a href=serviceAPI.html#getServiceApplication>getServiceApplication()</a><td>No<td>No parameter is passed to this routine</tr>
    239. 

  239. <tr valign=top><th align=left><a href=serviceAPI.html#getServiceFunction>getServiceFunction()</a><td>No<td>No parameter is passed to this routine</tr>
    240. 

  240. <tr valign=top><th align=left><a href=serviceAPI.html#getServiceKey>getServiceKey()</a><td>No<td>No parameter is passed to this routine</tr>
    241. 

  241. <tr valign=top><th align=left><a href=serviceAPI.html#getServiceVersion>getServiceVersion()</a><td>Yes<td></tr>
    242. 

  242. <tr valign=top><th align=left><a href=serviceAPI.html#hasFault>hasFault()</a><td>Yes<td></tr>
    243. 

  243. <tr valign=top><th align=left><a href=serviceAPI.html#initialize>initialize()</a><td>Yes<td></tr>
    244. 

  244. <tr valign=top><th align=left><a href=serviceAPI.html#sendFault>sendFault()</a><td>Yes<td></tr>
    245. 

  245. <tr valign=top><th align=left><a href=serviceAPI.html#sendResponse>sendResponse()</a><td>Yes<td>Only the single parameter version available, eg:<br>
    246. 

  246. <pre>
    247. 

  247. $s = new PlutonService();
    248. 

  248. $s->sendResponse("Here is some data");
    249. 

  249. <pre>
    250. 

  250. </tr>
    251. 

  251. 

  252. <tr valign=top><th align=left><a href=serviceAPI.html#terminate>terminate()</a><td>Yes<td></tr>
    253. 

  253. 

  254. </table>
    255. 

  255. 

  256. <p>
    257. 

  257. <hr>
    258. 

  258. <font size=-1>
    259. 

  259. $Id: phpAPI.html 263414 2009-12-01 00:52:44Z markd $
    260. 

  260. &copy; Copyright Yahoo! Inc, 2008, 2009
    261. 

  261. </font>
    262. 

  262. </body>
    263. 

  263. </html>
    264. 

  264.