documentation/manual/en/module_specs/Zend_Gdata_Exception.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.gdata.exception">
   4     <title>Catching Gdata Exceptions</title>
   5
   6     <para>
   7         The <classname>Zend_Gdata_App_Exception</classname> class is a base class
   8         for exceptions thrown by <classname>Zend_Gdata</classname>. You can catch any exception
   9         thrown by <classname>Zend_Gdata</classname> by catching
  10         <classname>Zend_Gdata_App_Exception</classname>.
  11     </para>
  12
  13     <programlisting language="php"><![CDATA[
  14 try {
  15     $client =
  16         Zend_Gdata_ClientLogin::getHttpClient($username, $password);
  17 } catch(Zend_Gdata_App_Exception $ex) {
  18     // Report the exception to the user
  19     die($ex->getMessage());
  20 }
  21 ]]></programlisting>
  22
  23     <para>
  24         The following exception subclasses are used by <classname>Zend_Gdata</classname>:
  25
  26         <itemizedlist>
  27             <listitem>
  28                 <para>
  29                     <classname>Zend_Gdata_App_AuthException</classname>
  30                     indicates that the user's account credentials were not valid.
  31                 </para>
  32             </listitem>
  33
  34             <listitem>
  35                 <para>
  36                     <classname>Zend_Gdata_App_BadMethodCallException</classname>
  37                     indicates that a method was called for a service
  38                     that does not support the method. For example,
  39                     the CodeSearch service does not support <methodname>post()</methodname>.
  40                 </para>
  41             </listitem>
  42
  43             <listitem>
  44                 <para>
  45                     <classname>Zend_Gdata_App_HttpException</classname>
  46                     indicates that an <acronym>HTTP</acronym> request was not successful.
  47                     Provides the ability to get the full <classname>Zend_Http_Response</classname>
  48                     object to determine the exact cause of the failure in
  49                     cases where <command>$e->getMessage()</command> does not provide
  50                     enough details.
  51                 </para>
  52             </listitem>
  53
  54             <listitem>
  55                 <para>
  56                     <classname>Zend_Gdata_App_InvalidArgumentException</classname>
  57                     is thrown when the application provides a value that
  58                     is not valid in a given context. For example,
  59                     specifying a Calendar visibility value of "banana",
  60                     or fetching a Blogger feed without specifying
  61                     any blog name.
  62                 </para>
  63             </listitem>
  64
  65             <listitem>
  66                 <para>
  67                     <classname>Zend_Gdata_App_CaptchaRequiredException</classname>
  68                     is thrown when a ClientLogin attempt receives a
  69                     <trademark>CAPTCHA</trademark> challenge from the
  70                     authentication service. This exception contains a token
  71                     ID and a <acronym>URL</acronym> to a <trademark>CAPTCHA</trademark>
  72                     challenge image. The image is a visual puzzle that
  73                     should be displayed to the user. After
  74                     collecting the user's response to the challenge
  75                     image, the response can be included with the next
  76                     ClientLogin attempt.The user can alternatively be
  77                     directed to this website:
  78                     <ulink url="https://www.google.com/accounts/DisplayUnlockCaptcha"/>
  79                     Further information can be found in the
  80                     <link linkend="zend.gdata.clientlogin">ClientLogin documentation</link>.
  81                 </para>
  82             </listitem>
  83         </itemizedlist>
  84     </para>
  85
  86     <para>
  87         You can use these exception subclasses to handle specific exceptions
  88         differently. See the <acronym>API</acronym> documentation for information on which
  89         exception subclasses are thrown by which methods in <classname>Zend_Gdata</classname>.
  90     </para>
  91
  92     <programlisting language="php"><![CDATA[
  93 try {
  94     $client = Zend_Gdata_ClientLogin::getHttpClient($username,
  95                                                     $password,
  96                                                     $service);
  97 } catch(Zend_Gdata_App_AuthException $authEx) {
  98     // The user's credentials were incorrect.
  99     // It would be appropriate to give the user a second try.
 100     ...
 101 } catch(Zend_Gdata_App_HttpException $httpEx) {
 102     // Google Data servers cannot be contacted.
 103     die($httpEx->getMessage);}
 104 ]]></programlisting>
 105 </sect1>