repo_zf1/documentation/manual/en/module_specs/Zend_Gdata_Exception.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<sect1 id="zend.gdata.exception">
    <title>Catching Gdata Exceptions</title>

    <para>
        The <classname>Zend_Gdata_App_Exception</classname> class is a base class
        for exceptions thrown by <classname>Zend_Gdata</classname>. You can catch any exception
        thrown by <classname>Zend_Gdata</classname> by catching
        <classname>Zend_Gdata_App_Exception</classname>.
    </para>

    <programlisting language="php"><![CDATA[
try {
    $client =
        Zend_Gdata_ClientLogin::getHttpClient($username, $password);
} catch(Zend_Gdata_App_Exception $ex) {
    // Report the exception to the user
    die($ex->getMessage());
}
]]></programlisting>

    <para>
        The following exception subclasses are used by <classname>Zend_Gdata</classname>:

        <itemizedlist>
            <listitem>
                <para>
                    <classname>Zend_Gdata_App_AuthException</classname>
                    indicates that the user's account credentials were not valid.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Gdata_App_BadMethodCallException</classname>
                    indicates that a method was called for a service
                    that does not support the method. For example,
                    the CodeSearch service does not support <methodname>post()</methodname>.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Gdata_App_HttpException</classname>
                    indicates that an <acronym>HTTP</acronym> request was not successful.
                    Provides the ability to get the full <classname>Zend_Http_Response</classname>
                    object to determine the exact cause of the failure in
                    cases where <command>$e->getMessage()</command> does not provide
                    enough details.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Gdata_App_InvalidArgumentException</classname>
                    is thrown when the application provides a value that
                    is not valid in a given context. For example,
                    specifying a Calendar visibility value of "banana",
                    or fetching a Blogger feed without specifying
                    any blog name.
                </para>
            </listitem>

            <listitem>
                <para>
                    <classname>Zend_Gdata_App_CaptchaRequiredException</classname>
                    is thrown when a ClientLogin attempt receives a
                    <trademark>CAPTCHA</trademark> challenge from the
                    authentication service. This exception contains a token
                    ID and a <acronym>URL</acronym> to a <trademark>CAPTCHA</trademark>
                    challenge image. The image is a visual puzzle that
                    should be displayed to the user. After
                    collecting the user's response to the challenge
                    image, the response can be included with the next
                    ClientLogin attempt.The user can alternatively be
                    directed to this website:
                    <ulink url="https://www.google.com/accounts/DisplayUnlockCaptcha"/>
                    Further information can be found in the
                    <link linkend="zend.gdata.clientlogin">ClientLogin documentation</link>.
                </para>
            </listitem>
        </itemizedlist>
    </para>

    <para>
        You can use these exception subclasses to handle specific exceptions
        differently. See the <acronym>API</acronym> documentation for information on which
        exception subclasses are thrown by which methods in <classname>Zend_Gdata</classname>.
    </para>

    <programlisting language="php"><![CDATA[
try {
    $client = Zend_Gdata_ClientLogin::getHttpClient($username,
                                                    $password,
                                                    $service);
} catch(Zend_Gdata_App_AuthException $authEx) {
    // The user's credentials were incorrect.
    // It would be appropriate to give the user a second try.
    ...
} catch(Zend_Gdata_App_HttpException $httpEx) {
    // Google Data servers cannot be contacted.
    die($httpEx->getMessage);}
]]></programlisting>
</sect1>