<?php

/**

 * Zend Framework

 *

 * LICENSE

 *

 * This source file is subject to the new BSD license that is bundled

 * with this package in the file LICENSE.txt.

 * It is also available through the world-wide-web at this URL:

 * http://framework.zend.com/license/new-bsd

 * If you did not receive a copy of the license and are unable to

 * obtain it through the world-wide-web, please send an email

 * to license@zend.com so we can send you a copy immediately.

 *

 * @category   Zend

 * @package    Zend_Gdata

 * @subpackage Gapps

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 * @version    $Id: Gapps.php 22511 2010-07-01 01:41:46Z tjohns $

 */

/**

 * @see Zend_Gdata

 */

require_once 'Zend/Gdata.php';

/**

 * @see Zend_Gdata_Gapps_UserFeed

 */

require_once 'Zend/Gdata/Gapps/UserFeed.php';

/**

 * @see Zend_Gdata_Gapps_NicknameFeed

 */

require_once 'Zend/Gdata/Gapps/NicknameFeed.php';

/**

 * @see Zend_Gdata_Gapps_GroupFeed

 */

require_once 'Zend/Gdata/Gapps/GroupFeed.php';

/**

 * @see Zend_Gdata_Gapps_MemberFeed

 */

require_once 'Zend/Gdata/Gapps/MemberFeed.php';

/**

 * @see Zend_Gdata_Gapps_OwnerFeed

 */

require_once 'Zend/Gdata/Gapps/OwnerFeed.php';

/**

 * @see Zend_Gdata_Gapps_EmailListFeed

 */

require_once 'Zend/Gdata/Gapps/EmailListFeed.php';

/**

 * @see Zend_Gdata_Gapps_EmailListRecipientFeed

 */

require_once 'Zend/Gdata/Gapps/EmailListRecipientFeed.php';

/**

 * Service class for interacting with the Google Apps Provisioning API.

 *

 * Like other service classes in this module, this class provides access via

 * an HTTP client to Google servers for working with entries and feeds.

 *

 * Because of the nature of this API, all access must occur over an

 * authenticated connection.

 *

 * @link http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html

 *

 * @category   Zend

 * @package    Zend_Gdata

 * @subpackage Gapps

 * @copyright  Copyright (c) 2005-2010 Zend Technologies USA Inc. (http://www.zend.com)

 * @license    http://framework.zend.com/license/new-bsd     New BSD License

 */

class Zend_Gdata_Gapps extends Zend_Gdata

{

    const APPS_BASE_FEED_URI = 'https://apps-apis.google.com/a/feeds';

    const AUTH_SERVICE_NAME = 'apps';

    /**

     * Path to user feeds on the Google Apps server.

     */

    const APPS_USER_PATH = '/user/2.0';

    /**

     * Path to nickname feeds on the Google Apps server.

     */

    const APPS_NICKNAME_PATH = '/nickname/2.0';

    /**

     * Path to group feeds on the Google Apps server.

     */

    const APPS_GROUP_PATH = '/group/2.0';

    /**

     * Path to email list feeds on the Google Apps server.

     */

    const APPS_EMAIL_LIST_PATH = '/emailList/2.0';

    /**

     * Path to email list recipient feeds on the Google Apps server.

     */

    const APPS_EMAIL_LIST_RECIPIENT_POSTFIX = '/recipient';

    /**

     * The domain which is being administered via the Provisioning API.

     *

     * @var string

     */

    protected $_domain = null;

    /**

     * Namespaces used for Zend_Gdata_Gapps

     *

     * @var array

     */

    public static $namespaces = array(

        array('apps', 'http://schemas.google.com/apps/2006', 1, 0)

    );

    /**

     * Create Gdata_Gapps object

     *

     * @param Zend_Http_Client $client (optional) The HTTP client to use when

     *          when communicating with the Google Apps servers.

     * @param string $domain (optional) The Google Apps domain which is to be

     *          accessed.

     * @param string $applicationId The identity of the app in the form of Company-AppName-Version

     */

    public function __construct($client = null, $domain = null, $applicationId = 'MyCompany-MyApp-1.0')

    {

        $this->registerPackage('Zend_Gdata_Gapps');

        $this->registerPackage('Zend_Gdata_Gapps_Extension');

        parent::__construct($client, $applicationId);

        $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME);

        $this->_domain = $domain;

    }

    /**

     * Convert an exception to an ServiceException if an AppsForYourDomain

     * XML document is contained within the original exception's HTTP

     * response. If conversion fails, throw the original error.

     *

     * @param Zend_Gdata_Exception $e The exception to convert.

     * @throws Zend_Gdata_Gapps_ServiceException

     * @throws mixed

     */

    public static function throwServiceExceptionIfDetected($e) {

        // Check to make sure that there actually response!

        // This can happen if the connection dies before the request

        // completes. (See ZF-5949)

        $response = $e->getResponse();

        if (!$response) {

          require_once('Zend/Gdata/App/IOException.php');

          throw new Zend_Gdata_App_IOException('No HTTP response received (possible connection failure)');

        }

        try {

            // Check to see if there is an AppsForYourDomainErrors

            // datastructure in the response. If so, convert it to

            // an exception and throw it.

            require_once 'Zend/Gdata/Gapps/ServiceException.php';

            $error = new Zend_Gdata_Gapps_ServiceException();

            $error->importFromString($response->getBody());

            throw $error;

        } catch (Zend_Gdata_App_Exception $e2) {

            // Unable to convert the response to a ServiceException,

            // most likely because the server didn't return an

            // AppsForYourDomainErrors document. Throw the original

            // exception.

            throw $e;

        }

    }

    /**

     * Imports a feed located at $uri.

     * This method overrides the default behavior of Zend_Gdata_App,

     * providing support for Zend_Gdata_Gapps_ServiceException.

     *

     * @param  string $uri

     * @param  Zend_Http_Client $client (optional) The client used for

     *          communication

     * @param  string $className (optional) The class which is used as the

     *          return type

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     * @return Zend_Gdata_App_Feed

     */

    public static function import($uri, $client = null, $className='Zend_Gdata_App_Feed')

    {

        try {

            return parent::import($uri, $client, $className);

        } catch (Zend_Gdata_App_HttpException $e) {

            self::throwServiceExceptionIfDetected($e);

        }

    }

    /**

     * GET a URI using client object.

     * This method overrides the default behavior of Zend_Gdata_App,

     * providing support for Zend_Gdata_Gapps_ServiceException.

     *

     * @param string $uri GET URI

     * @param array $extraHeaders Extra headers to add to the request, as an

     *        array of string-based key/value pairs.

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     * @return Zend_Http_Response

     */

    public function get($uri, $extraHeaders = array())

    {

        try {

            return parent::get($uri, $extraHeaders);

        } catch (Zend_Gdata_App_HttpException $e) {

            self::throwServiceExceptionIfDetected($e);

        }

    }

    /**

     * POST data with client object.

     * This method overrides the default behavior of Zend_Gdata_App,

     * providing support for Zend_Gdata_Gapps_ServiceException.

     *

     * @param mixed $data The Zend_Gdata_App_Entry or XML to post

     * @param string $uri (optional) POST URI

     * @param integer $remainingRedirects (optional)

     * @param string $contentType Content-type of the data

     * @param array $extraHaders Extra headers to add tot he request

     * @return Zend_Http_Response

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_App_InvalidArgumentException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function post($data, $uri = null, $remainingRedirects = null,

            $contentType = null, $extraHeaders = null)

    {

        try {

            return parent::post($data, $uri, $remainingRedirects, $contentType, $extraHeaders);

        } catch (Zend_Gdata_App_HttpException $e) {

            self::throwServiceExceptionIfDetected($e);

        }

    }

    /**

     * PUT data with client object

     * This method overrides the default behavior of Zend_Gdata_App,

     * providing support for Zend_Gdata_Gapps_ServiceException.

     *

     * @param mixed $data The Zend_Gdata_App_Entry or XML to post

     * @param string $uri (optional) PUT URI

     * @param integer $remainingRedirects (optional)

     * @param string $contentType Content-type of the data

     * @param array $extraHaders Extra headers to add tot he request

     * @return Zend_Http_Response

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_App_InvalidArgumentException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function put($data, $uri = null, $remainingRedirects = null,

            $contentType = null, $extraHeaders = null)

    {

        try {

            return parent::put($data, $uri, $remainingRedirects, $contentType, $extraHeaders);

        } catch (Zend_Gdata_App_HttpException $e) {

            self::throwServiceExceptionIfDetected($e);

        }

    }

    /**

     * DELETE entry with client object

     * This method overrides the default behavior of Zend_Gdata_App,

     * providing support for Zend_Gdata_Gapps_ServiceException.

     *

     * @param mixed $data The Zend_Gdata_App_Entry or URL to delete

     * @param integer $remainingRedirects (optional)

     * @return void

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_App_InvalidArgumentException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function delete($data, $remainingRedirects = null)

    {

        try {

            return parent::delete($data, $remainingRedirects);

        } catch (Zend_Gdata_App_HttpException $e) {

            self::throwServiceExceptionIfDetected($e);

        }

    }

    /**

     * Set domain for this service instance. This should be a fully qualified

     * domain, such as 'foo.example.com'.

     *

     * This value is used when calculating URLs for retrieving and posting

     * entries. If no value is specified, a URL will have to be manually

     * constructed prior to using any methods which interact with the Google

     * Apps provisioning service.

     *

     * @param string $value The domain to be used for this session.

     */

    public function setDomain($value)

    {

        $this->_domain = $value;

    }

    /**

     * Get domain for this service instance. This should be a fully qualified

     * domain, such as 'foo.example.com'. If no domain is set, null will be

     * returned.

     *

     * @return string The domain to be used for this session, or null if not

     *          set.

     */

    public function getDomain()

    {

        return $this->_domain;

    }

    /**

     * Returns the base URL used to access the Google Apps service, based

     * on the current domain. The current domain can be temporarily

     * overridden by providing a fully qualified domain as $domain.

     *

     * @param string $domain (optional) A fully-qualified domain to use

     *          instead of the default domain for this service instance.

     * @throws Zend_Gdata_App_InvalidArgumentException

     */

     public function getBaseUrl($domain = null)

     {

         if ($domain !== null) {

             return self::APPS_BASE_FEED_URI . '/' . $domain;

         } else if ($this->_domain !== null) {

             return self::APPS_BASE_FEED_URI . '/' . $this->_domain;

         } else {

             require_once 'Zend/Gdata/App/InvalidArgumentException.php';

             throw new Zend_Gdata_App_InvalidArgumentException(

                     'Domain must be specified.');

         }

     }

    /**

     * Retrieve a UserFeed containing multiple UserEntry objects.

     *

     * @param mixed $location (optional) The location for the feed, as a URL

     *          or Query.

     * @return Zend_Gdata_Gapps_UserFeed

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function getUserFeed($location = null)

    {

        if ($location === null) {

            $uri = $this->getBaseUrl() . self::APPS_USER_PATH;

        } else if ($location instanceof Zend_Gdata_Query) {

            $uri = $location->getQueryUrl();

        } else {

            $uri = $location;

        }

        return parent::getFeed($uri, 'Zend_Gdata_Gapps_UserFeed');

    }

    /**

     * Retreive NicknameFeed object containing multiple NicknameEntry objects.

     *

     * @param mixed $location (optional) The location for the feed, as a URL

     *          or Query.

     * @return Zend_Gdata_Gapps_NicknameFeed

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function getNicknameFeed($location = null)

    {

        if ($location === null) {

            $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;

        } else if ($location instanceof Zend_Gdata_Query) {

            $uri = $location->getQueryUrl();

        } else {

            $uri = $location;

        }

        return parent::getFeed($uri, 'Zend_Gdata_Gapps_NicknameFeed');

    }

    /**

     * Retreive GroupFeed object containing multiple GroupEntry

     * objects.

     *

     * @param mixed $location (optional) The location for the feed, as a URL

     *          or Query.

     * @return Zend_Gdata_Gapps_GroupFeed

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function getGroupFeed($location = null)

    {

        if ($location === null) {

            $uri  = self::APPS_BASE_FEED_URI . self::APPS_GROUP_PATH . '/';

            $uri .= $this->getDomain();

        } else if ($location instanceof Zend_Gdata_Query) {

            $uri = $location->getQueryUrl();

        } else {

            $uri = $location;

        }

        return parent::getFeed($uri, 'Zend_Gdata_Gapps_GroupFeed');

    }

    /**

     * Retreive MemberFeed object containing multiple MemberEntry

     * objects.

     *

     * @param mixed $location (optional) The location for the feed, as a URL

     *          or Query.

     * @return Zend_Gdata_Gapps_MemberFeed

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function getMemberFeed($location = null)

    {

        if ($location === null) {

            require_once 'Zend/Gdata/App/InvalidArgumentException.php';

            throw new Zend_Gdata_App_InvalidArgumentException(

                    'Location must not be null');

        } else if ($location instanceof Zend_Gdata_Query) {

            $uri = $location->getQueryUrl();

        } else {

            $uri = $location;

        }

        return parent::getFeed($uri, 'Zend_Gdata_Gapps_MemberFeed');

    }

    /**

     * Retreive OwnerFeed object containing multiple OwnerEntry

     * objects.

     *

     * @param mixed $location (optional) The location for the feed, as a URL

     *          or Query.

     * @return Zend_Gdata_Gapps_OwnerFeed

     * @throws Zend_Gdata_App_Exception

     * @throws Zend_Gdata_App_HttpException

     * @throws Zend_Gdata_Gapps_ServiceException

     */

    public function getOwnerFeed($location = null)

    {

        if ($location === null) {

            require_once 'Zend/Gdata/App/InvalidArgumentException.php';

            throw new Zend_Gdata_App_InvalidArgumentException(