cvs: peardoc /en/package/webservices/services-geonames getting-started.xml

izi		Fri Jan 23 14:06:37 2009 UTC

  Modified files:              
    /peardoc/en/package/webservices/services-geonames	
                                                     	getting-started.xml 
  Log:
  added doc for exception handling, service url and failover servers
  
http://cvs.php.net/viewvc.cgi/peardoc/en/package/webservices/services-geonames/getting-started.xml?r1=1.1&r2=1.2&diff_format=u
Index: peardoc/en/package/webservices/services-geonames/getting-started.xml
diff -u peardoc/en/package/webservices/services-geonames/getting-started.xml:1.1 peardoc/en/package/webservices/services-geonames/getting-started.xml:1.2
--- peardoc/en/package/webservices/services-geonames/getting-started.xml:1.1	Fri Dec 19 17:30:45 2008
+++ peardoc/en/package/webservices/services-geonames/getting-started.xml	Fri Jan 23 14:06:34 2009
@@ -7,7 +7,7 @@
 >
  <refnamediv>
   <refname>Getting started</refname>
-  <refpurpose>getting started with the <classname>Services_GeoNames</classname> package</refpurpose>
+  <refpurpose>getting started with the <package>Services_GeoNames</package> package</refpurpose>
  </refnamediv>
  <refsection><info><title>Instanciating the <classname>Services_GeoNames</classname> class</title></info>
   <para>
@@ -365,7 +365,7 @@
       </entry>
       <entry></entry>
       <entry>HTTP_Request2</entry>
-      <entry>returns the Services_GeoNames request instance</entry>
+      <entry>returns the HTTP_Request2 request instance</entry>
      </row>
      <row>
       <entry>
@@ -373,17 +373,106 @@
       </entry>
       <entry>HTTP_Request2</entry>
       <entry></entry>
-      <entry>sets the Services_GeoNames request instance</entry>
+      <entry>sets the HTTP_Request2 request instance</entry>
      </row>
     </tbody>
    </tgroup>
   </table>
  </refsection>
 
+ <refsection><info><title>Handling exceptions</title></info>
+  <para>
+   <package>Services_GeoNames</package> always raise either a 
+   <classname>Services_GeoNames_Exception</classname> or a
+   <classname>Services_GeoNames_HTTPException</classname> instance, if you
+   don't care of fine grained exceptions, you can just catch the 
+   <classname>Services_GeoNames_Exception</classname>, as it's the parent class
+   of the  <classname>Services_GeoNames_HTTPException</classname>.
+
+   Here's an example of fine grained exception handling:
+   <programlisting role="php">
+   <![CDATA[
+<?php
+
+require_once 'Services/GeoNames.php';
+
+$geo = new Services_GeoNames();
+
+// now geonames uses your url
+try {
+    $children = $geo->children(3175395);
+} catch (Services_GeoNames_HTTPException $exc) {
+    // an http error occured
+    echo "HTTP error: " . $exc->getMessage();
+} catch (Services_GeoNames_Exception $exc) {
+    // a programming error or an api error occured
+    echo "API error: " . $exc->getMessage();
+}
+
+?>
+   ]]>
+   </programlisting>
+  </para>
+ </refsection>
+
+ <refsection><info><title>Changing the default service url and adding failover servers</title></info>
+  <para>
+   If for some reason you need to change the web service url, you can do the
+   following: 
+   <programlisting role="php">
+   <![CDATA[
+<?php
+
+require_once 'Services/GeoNames.php';
+
+$geo = new Services_GeoNames();
+$geo->url = 'http://alternate.geonames.org';
+
+// now geonames uses your url
+try {
+    $children = $geo->children(3175395);
+} catch (Services_GeoNames_Exception $exc) {
+    echo "Failed: " . $exc->getMessage();
+}
+
+?>
+   ]]>
+   </programlisting>
+  </para>
+  <para>
+   If you need high availability or if you are using the commercial version of
+   the web services, <package>Services_GeoNames</package> allows you to specify
+   an array of failover servers, you would just do:
+   <programlisting role="php">
+   <![CDATA[
+<?php
+
+require_once 'Services/GeoNames.php';
+
+$geo = new Services_GeoNames();
+$geo->failoverServers[] = 'http://failover1.geonames.org';
+$geo->failoverServers[] = 'http://failover2.geonames.org';
+$geo->failoverServers[] = 'http://failover3.geonames.org';
+
+// now geonames will try the main url and if it fails, it will loop through
+// the failovers servers you have just configured
+try {
+    $children = $geo->children(3175395);
+} catch (Services_GeoNames_Exception $exc) {
+    echo "Failed: " . $exc->getMessage();
+}
+
+?>
+   ]]>
+   </programlisting>
+  </para>
+ </refsection>
+
  <refsection><info><title>Customizing the http request</title></info>
   <para>
-   If for some reason you need a custom request, for example if you are behind
-   a proxy, you can modify the Services_GeoNames request instance, for example: 
+   If you need a custom request, for example if you are behind a proxy,
+   you can modify the <classname>Services_GeoNames</classname> request
+   instance, for example: 
    <programlisting role="php">
    <![CDATA[
 <?php
@@ -398,7 +487,11 @@
 ));
 
 // now geonames uses your proxy
-$children = $geo->children(3175395);
+try {
+    $children = $geo->children(3175395);
+} catch (Services_GeoNames_Exception $exc) {
+    echo "Failed: " . $exc->getMessage();
+}
 
 ?>
    ]]>