library/Zend/Gdata/Gapps.php

   1 <?php
   2
   3 /**
   4  * Zend Framework
   5  *
   6  * LICENSE
   7  *
   8  * This source file is subject to the new BSD license that is bundled
   9  * with this package in the file LICENSE.txt.
  10  * It is also available through the world-wide-web at this URL:
  11  * http://framework.zend.com/license/new-bsd
  12  * If you did not receive a copy of the license and are unable to
  13  * obtain it through the world-wide-web, please send an email
  14  * to license@zend.com so we can send you a copy immediately.
  15  *
  16  * @category   Zend
  17  * @package    Zend_Gdata
  18  * @subpackage Gapps
  19  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  20  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  21  */
  22
  23 /**
  24  * @see Zend_Gdata
  25  */
  26 require_once 'Zend/Gdata.php';
  27
  28 /**
  29  * @see Zend_Gdata_Gapps_UserFeed
  30  */
  31 require_once 'Zend/Gdata/Gapps/UserFeed.php';
  32
  33 /**
  34  * @see Zend_Gdata_Gapps_NicknameFeed
  35  */
  36 require_once 'Zend/Gdata/Gapps/NicknameFeed.php';
  37
  38 /**
  39  * @see Zend_Gdata_Gapps_EmailListFeed
  40  */
  41 require_once 'Zend/Gdata/Gapps/EmailListFeed.php';
  42
  43 /**
  44  * @see Zend_Gdata_Gapps_EmailListRecipientFeed
  45  */
  46 require_once 'Zend/Gdata/Gapps/EmailListRecipientFeed.php';
  47
  48
  49 /**
  50  * Service class for interacting with the Google Apps Provisioning API.
  51  *
  52  * Like other service classes in this module, this class provides access via
  53  * an HTTP client to Google servers for working with entries and feeds.
  54  *
  55  * Because of the nature of this API, all access must occur over an
  56  * authenticated connection.
  57  *
  58  * @link http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html
  59  *
  60  * @category   Zend
  61  * @package    Zend_Gdata
  62  * @subpackage Gapps
  63  * @copyright  Copyright (c) 2005-2009 Zend Technologies USA Inc. (http://www.zend.com)
  64  * @license    http://framework.zend.com/license/new-bsd     New BSD License
  65  */
  66 class Zend_Gdata_Gapps extends Zend_Gdata
  67 {
  68
  69     const APPS_BASE_FEED_URI = 'https://apps-apis.google.com/a/feeds';
  70     const AUTH_SERVICE_NAME = 'apps';
  71
  72     /**
  73      * Path to user feeds on the Google Apps server.
  74      */
  75     const APPS_USER_PATH = '/user/2.0';
  76
  77     /**
  78      * Path to nickname feeds on the Google Apps server.
  79      */
  80     const APPS_NICKNAME_PATH = '/nickname/2.0';
  81
  82     /**
  83      * Path to email list feeds on the Google Apps server.
  84      */
  85     const APPS_EMAIL_LIST_PATH = '/emailList/2.0';
  86
  87     /**
  88      * Path to email list recipient feeds on the Google Apps server.
  89      */
  90     const APPS_EMAIL_LIST_RECIPIENT_POSTFIX = '/recipient';
  91
  92     /**
  93      * The domain which is being administered via the Provisioning API.
  94      *
  95      * @var string
  96      */
  97     protected $_domain = null;
  98
  99     /**
 100      * Namespaces used for Zend_Gdata_Gapps
 101      *
 102      * @var array
 103      */
 104     public static $namespaces = array(
 105         array('apps', 'http://schemas.google.com/apps/2006', 1, 0)
 106     );
 107
 108     /**
 109      * Create Gdata_Gapps object
 110      *
 111      * @param Zend_Http_Client $client (optional) The HTTP client to use when
 112      *          when communicating with the Google Apps servers.
 113      * @param string $domain (optional) The Google Apps domain which is to be
 114      *          accessed.
 115      * @param string $applicationId The identity of the app in the form of Company-AppName-Version
 116      */
 117     public function __construct($client = null, $domain = null, $applicationId = 'MyCompany-MyApp-1.0')
 118     {
 119         $this->registerPackage('Zend_Gdata_Gapps');
 120         $this->registerPackage('Zend_Gdata_Gapps_Extension');
 121         parent::__construct($client, $applicationId);
 122         $this->_httpClient->setParameterPost('service', self::AUTH_SERVICE_NAME);
 123         $this->_domain = $domain;
 124     }
 125
 126     /**
 127      * Convert an exception to an ServiceException if an AppsForYourDomain
 128      * XML document is contained within the original exception's HTTP
 129      * response. If conversion fails, throw the original error.
 130      *
 131      * @param Zend_Gdata_Exception $e The exception to convert.
 132      * @throws Zend_Gdata_Gapps_ServiceException
 133      * @throws mixed
 134      */
 135     public static function throwServiceExceptionIfDetected($e) {
 136         // Check to make sure that there actually response!
 137         // This can happen if the connection dies before the request
 138         // completes. (See ZF-5949)
 139         $response = $e->getResponse();
 140         if (!$response) {
 141           require_once('Zend/Gdata/App/IOException.php');
 142           throw new Zend_Gdata_App_IOException('No HTTP response received (possible connection failure)');
 143         }
 144
 145         try {
 146             // Check to see if there is an AppsForYourDomainErrors
 147             // datastructure in the response. If so, convert it to
 148             // an exception and throw it.
 149             require_once 'Zend/Gdata/Gapps/ServiceException.php';
 150             $error = new Zend_Gdata_Gapps_ServiceException();
 151             $error->importFromString($response->getBody());
 152             throw $error;
 153         } catch (Zend_Gdata_App_Exception $e2) {
 154             // Unable to convert the response to a ServiceException,
 155             // most likely because the server didn't return an
 156             // AppsForYourDomainErrors document. Throw the original
 157             // exception.
 158             throw $e;
 159         }
 160     }
 161
 162     /**
 163      * Imports a feed located at $uri.
 164      * This method overrides the default behavior of Zend_Gdata_App,
 165      * providing support for Zend_Gdata_Gapps_ServiceException.
 166      *
 167      * @param  string $uri
 168      * @param  Zend_Http_Client $client (optional) The client used for
 169      *          communication
 170      * @param  string $className (optional) The class which is used as the
 171      *          return type
 172      * @throws Zend_Gdata_App_Exception
 173      * @throws Zend_Gdata_App_HttpException
 174      * @throws Zend_Gdata_Gapps_ServiceException
 175      * @return Zend_Gdata_App_Feed
 176      */
 177     public static function import($uri, $client = null, $className='Zend_Gdata_App_Feed')
 178     {
 179         try {
 180             return parent::import($uri, $client, $className);
 181         } catch (Zend_Gdata_App_HttpException $e) {
 182             self::throwServiceExceptionIfDetected($e);
 183         }
 184     }
 185
 186     /**
 187      * GET a URI using client object.
 188      * This method overrides the default behavior of Zend_Gdata_App,
 189      * providing support for Zend_Gdata_Gapps_ServiceException.
 190      *
 191      * @param string $uri GET URI
 192      * @param array $extraHeaders Extra headers to add to the request, as an
 193      *        array of string-based key/value pairs.
 194      * @throws Zend_Gdata_App_HttpException
 195      * @throws Zend_Gdata_Gapps_ServiceException
 196      * @return Zend_Http_Response
 197      */
 198     public function get($uri, $extraHeaders = array())
 199     {
 200         try {
 201             return parent::get($uri, $extraHeaders);
 202         } catch (Zend_Gdata_App_HttpException $e) {
 203             self::throwServiceExceptionIfDetected($e);
 204         }
 205     }
 206
 207     /**
 208      * POST data with client object.
 209      * This method overrides the default behavior of Zend_Gdata_App,
 210      * providing support for Zend_Gdata_Gapps_ServiceException.
 211      *
 212      * @param mixed $data The Zend_Gdata_App_Entry or XML to post
 213      * @param string $uri (optional) POST URI
 214      * @param integer $remainingRedirects (optional)
 215      * @param string $contentType Content-type of the data
 216      * @param array $extraHaders Extra headers to add tot he request
 217      * @return Zend_Http_Response
 218      * @throws Zend_Gdata_App_HttpException
 219      * @throws Zend_Gdata_App_InvalidArgumentException
 220      * @throws Zend_Gdata_Gapps_ServiceException
 221      */
 222     public function post($data, $uri = null, $remainingRedirects = null,
 223             $contentType = null, $extraHeaders = null)
 224     {
 225         try {
 226             return parent::post($data, $uri, $remainingRedirects, $contentType, $extraHeaders);
 227         } catch (Zend_Gdata_App_HttpException $e) {
 228             self::throwServiceExceptionIfDetected($e);
 229         }
 230     }
 231
 232     /**
 233      * PUT data with client object
 234      * This method overrides the default behavior of Zend_Gdata_App,
 235      * providing support for Zend_Gdata_Gapps_ServiceException.
 236      *
 237      * @param mixed $data The Zend_Gdata_App_Entry or XML to post
 238      * @param string $uri (optional) PUT URI
 239      * @param integer $remainingRedirects (optional)
 240      * @param string $contentType Content-type of the data
 241      * @param array $extraHaders Extra headers to add tot he request
 242      * @return Zend_Http_Response
 243      * @throws Zend_Gdata_App_HttpException
 244      * @throws Zend_Gdata_App_InvalidArgumentException
 245      * @throws Zend_Gdata_Gapps_ServiceException
 246      */
 247     public function put($data, $uri = null, $remainingRedirects = null,
 248             $contentType = null, $extraHeaders = null)
 249     {
 250         try {
 251             return parent::put($data, $uri, $remainingRedirects, $contentType, $extraHeaders);
 252         } catch (Zend_Gdata_App_HttpException $e) {
 253             self::throwServiceExceptionIfDetected($e);
 254         }
 255     }
 256
 257     /**
 258      * DELETE entry with client object
 259      * This method overrides the default behavior of Zend_Gdata_App,
 260      * providing support for Zend_Gdata_Gapps_ServiceException.
 261      *
 262      * @param mixed $data The Zend_Gdata_App_Entry or URL to delete
 263      * @param integer $remainingRedirects (optional)
 264      * @return void
 265      * @throws Zend_Gdata_App_HttpException
 266      * @throws Zend_Gdata_App_InvalidArgumentException
 267      * @throws Zend_Gdata_Gapps_ServiceException
 268      */
 269     public function delete($data, $remainingRedirects = null)
 270     {
 271         try {
 272             return parent::delete($data, $remainingRedirects);
 273         } catch (Zend_Gdata_App_HttpException $e) {
 274             self::throwServiceExceptionIfDetected($e);
 275         }
 276     }
 277
 278     /**
 279      * Set domain for this service instance. This should be a fully qualified
 280      * domain, such as 'foo.example.com'.
 281      *
 282      * This value is used when calculating URLs for retrieving and posting
 283      * entries. If no value is specified, a URL will have to be manually
 284      * constructed prior to using any methods which interact with the Google
 285      * Apps provisioning service.
 286      *
 287      * @param string $value The domain to be used for this session.
 288      */
 289     public function setDomain($value)
 290     {
 291         $this->_domain = $value;
 292     }
 293
 294     /**
 295      * Get domain for this service instance. This should be a fully qualified
 296      * domain, such as 'foo.example.com'. If no domain is set, null will be
 297      * returned.
 298      *
 299      * @return string The domain to be used for this session, or null if not
 300      *          set.
 301      */
 302     public function getDomain()
 303     {
 304         return $this->_domain;
 305     }
 306
 307     /**
 308      * Returns the base URL used to access the Google Apps service, based
 309      * on the current domain. The current domain can be temporarily
 310      * overridden by providing a fully qualified domain as $domain.
 311      *
 312      * @param string $domain (optional) A fully-qualified domain to use
 313      *          instead of the default domain for this service instance.
 314      * @throws Zend_Gdata_App_InvalidArgumentException
 315      */
 316      public function getBaseUrl($domain = null)
 317      {
 318          if ($domain !== null) {
 319              return self::APPS_BASE_FEED_URI . '/' . $domain;
 320          } else if ($this->_domain !== null) {
 321              return self::APPS_BASE_FEED_URI . '/' . $this->_domain;
 322          } else {
 323              require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 324              throw new Zend_Gdata_App_InvalidArgumentException(
 325                      'Domain must be specified.');
 326          }
 327      }
 328
 329     /**
 330      * Retrieve a UserFeed containing multiple UserEntry objects.
 331      *
 332      * @param mixed $location (optional) The location for the feed, as a URL
 333      *          or Query.
 334      * @return Zend_Gdata_Gapps_UserFeed
 335      * @throws Zend_Gdata_App_Exception
 336      * @throws Zend_Gdata_App_HttpException
 337      * @throws Zend_Gdata_Gapps_ServiceException
 338      */
 339     public function getUserFeed($location = null)
 340     {
 341         if ($location === null) {
 342             $uri = $this->getBaseUrl() . self::APPS_USER_PATH;
 343         } else if ($location instanceof Zend_Gdata_Query) {
 344             $uri = $location->getQueryUrl();
 345         } else {
 346             $uri = $location;
 347         }
 348         return parent::getFeed($uri, 'Zend_Gdata_Gapps_UserFeed');
 349     }
 350
 351     /**
 352      * Retreive NicknameFeed object containing multiple NicknameEntry objects.
 353      *
 354      * @param mixed $location (optional) The location for the feed, as a URL
 355      *          or Query.
 356      * @return Zend_Gdata_Gapps_NicknameFeed
 357      * @throws Zend_Gdata_App_Exception
 358      * @throws Zend_Gdata_App_HttpException
 359      * @throws Zend_Gdata_Gapps_ServiceException
 360      */
 361     public function getNicknameFeed($location = null)
 362     {
 363         if ($location === null) {
 364             $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
 365         } else if ($location instanceof Zend_Gdata_Query) {
 366             $uri = $location->getQueryUrl();
 367         } else {
 368             $uri = $location;
 369         }
 370         return parent::getFeed($uri, 'Zend_Gdata_Gapps_NicknameFeed');
 371     }
 372
 373     /**
 374      * Retreive EmailListFeed object containing multiple EmailListEntry
 375      * objects.
 376      *
 377      * @param mixed $location (optional) The location for the feed, as a URL
 378      *          or Query.
 379      * @return Zend_Gdata_Gapps_EmailListFeed
 380      * @throws Zend_Gdata_App_Exception
 381      * @throws Zend_Gdata_App_HttpException
 382      * @throws Zend_Gdata_Gapps_ServiceException
 383      */
 384     public function getEmailListFeed($location = null)
 385     {
 386         if ($location === null) {
 387             $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
 388         } else if ($location instanceof Zend_Gdata_Query) {
 389             $uri = $location->getQueryUrl();
 390         } else {
 391             $uri = $location;
 392         }
 393         return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListFeed');
 394     }
 395
 396     /**
 397      * Retreive EmailListRecipientFeed object containing multiple
 398      * EmailListRecipientEntry objects.
 399      *
 400      * @param mixed $location The location for the feed, as a URL or Query.
 401      * @return Zend_Gdata_Gapps_EmailListRecipientFeed
 402      * @throws Zend_Gdata_App_Exception
 403      * @throws Zend_Gdata_App_HttpException
 404      * @throws Zend_Gdata_Gapps_ServiceException
 405      */
 406     public function getEmailListRecipientFeed($location)
 407     {
 408         if ($location === null) {
 409             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 410             throw new Zend_Gdata_App_InvalidArgumentException(
 411                     'Location must not be null');
 412         } else if ($location instanceof Zend_Gdata_Query) {
 413             $uri = $location->getQueryUrl();
 414         } else {
 415             $uri = $location;
 416         }
 417         return parent::getFeed($uri, 'Zend_Gdata_Gapps_EmailListRecipientFeed');
 418     }
 419
 420     /**
 421      * Retreive a single UserEntry object.
 422      *
 423      * @param mixed $location The location for the feed, as a URL or Query.
 424      * @return Zend_Gdata_Gapps_UserEntry
 425      * @throws Zend_Gdata_App_Exception
 426      * @throws Zend_Gdata_App_HttpException
 427      * @throws Zend_Gdata_Gapps_ServiceException
 428      */
 429     public function getUserEntry($location)
 430     {
 431         if ($location === null) {
 432             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 433             throw new Zend_Gdata_App_InvalidArgumentException(
 434                     'Location must not be null');
 435         } else if ($location instanceof Zend_Gdata_Query) {
 436             $uri = $location->getQueryUrl();
 437         } else {
 438             $uri = $location;
 439         }
 440         return parent::getEntry($uri, 'Zend_Gdata_Gapps_UserEntry');
 441     }
 442
 443     /**
 444      * Retreive a single NicknameEntry object.
 445      *
 446      * @param mixed $location The location for the feed, as a URL or Query.
 447      * @return Zend_Gdata_Gapps_NicknameEntry
 448      * @throws Zend_Gdata_App_Exception
 449      * @throws Zend_Gdata_App_HttpException
 450      * @throws Zend_Gdata_Gapps_ServiceException
 451      */
 452     public function getNicknameEntry($location)
 453     {
 454         if ($location === null) {
 455             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 456             throw new Zend_Gdata_App_InvalidArgumentException(
 457                     'Location must not be null');
 458         } else if ($location instanceof Zend_Gdata_Query) {
 459             $uri = $location->getQueryUrl();
 460         } else {
 461             $uri = $location;
 462         }
 463         return parent::getEntry($uri, 'Zend_Gdata_Gapps_NicknameEntry');
 464     }
 465
 466     /**
 467      * Retreive a single EmailListEntry object.
 468      *
 469      * @param mixed $location The location for the feed, as a URL or Query.
 470      * @return Zend_Gdata_Gapps_EmailListEntry
 471      * @throws Zend_Gdata_App_Exception
 472      * @throws Zend_Gdata_App_HttpException
 473      * @throws Zend_Gdata_Gapps_ServiceException
 474      */
 475     public function getEmailListEntry($location)
 476     {
 477         if ($location === null) {
 478             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 479             throw new Zend_Gdata_App_InvalidArgumentException(
 480                     'Location must not be null');
 481         } else if ($location instanceof Zend_Gdata_Query) {
 482             $uri = $location->getQueryUrl();
 483         } else {
 484             $uri = $location;
 485         }
 486         return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListEntry');
 487     }
 488
 489     /**
 490      * Retreive a single EmailListRecipientEntry object.
 491      *
 492      * @param mixed $location The location for the feed, as a URL or Query.
 493      * @return Zend_Gdata_Gapps_EmailListRecipientEntry
 494      * @throws Zend_Gdata_App_Exception
 495      * @throws Zend_Gdata_App_HttpException
 496      * @throws Zend_Gdata_Gapps_ServiceException
 497      */
 498     public function getEmailListRecipientEntry($location)
 499     {
 500         if ($location === null) {
 501             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 502             throw new Zend_Gdata_App_InvalidArgumentException(
 503                     'Location must not be null');
 504         } else if ($location instanceof Zend_Gdata_Query) {
 505             $uri = $location->getQueryUrl();
 506         } else {
 507             $uri = $location;
 508         }
 509         return parent::getEntry($uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry');
 510     }
 511
 512     /**
 513      * Create a new user from a UserEntry.
 514      *
 515      * @param Zend_Gdata_Gapps_UserEntry $user The user entry to insert.
 516      * @param string $uri (optional) The URI where the user should be
 517      *          uploaded to. If null, the default user creation URI for
 518      *          this domain will be used.
 519      * @return Zend_Gdata_Gapps_UserEntry The inserted user entry as
 520      *          returned by the server.
 521      * @throws Zend_Gdata_App_Exception
 522      * @throws Zend_Gdata_App_HttpException
 523      * @throws Zend_Gdata_Gapps_ServiceException
 524      */
 525     public function insertUser($user, $uri = null)
 526     {
 527         if ($uri === null) {
 528             $uri = $this->getBaseUrl() . self::APPS_USER_PATH;
 529         }
 530         $newEntry = $this->insertEntry($user, $uri, 'Zend_Gdata_Gapps_UserEntry');
 531         return $newEntry;
 532     }
 533
 534     /**
 535      * Create a new nickname from a NicknameEntry.
 536      *
 537      * @param Zend_Gdata_Gapps_NicknameEntry $nickname The nickname entry to
 538      *          insert.
 539      * @param string $uri (optional) The URI where the nickname should be
 540      *          uploaded to. If null, the default nickname creation URI for
 541      *          this domain will be used.
 542      * @return Zend_Gdata_Gapps_NicknameEntry The inserted nickname entry as
 543      *          returned by the server.
 544      * @throws Zend_Gdata_App_Exception
 545      * @throws Zend_Gdata_App_HttpException
 546      * @throws Zend_Gdata_Gapps_ServiceException
 547      */
 548     public function insertNickname($nickname, $uri = null)
 549     {
 550         if ($uri === null) {
 551             $uri = $this->getBaseUrl() . self::APPS_NICKNAME_PATH;
 552         }
 553         $newEntry = $this->insertEntry($nickname, $uri, 'Zend_Gdata_Gapps_NicknameEntry');
 554         return $newEntry;
 555     }
 556
 557     /**
 558      * Create a new email list from an EmailListEntry.
 559      *
 560      * @param Zend_Gdata_Gapps_EmailListEntry $emailList The email list entry
 561      *          to insert.
 562      * @param string $uri (optional) The URI where the email list should be
 563      *          uploaded to. If null, the default email list creation URI for
 564      *          this domain will be used.
 565      * @return Zend_Gdata_Gapps_EmailListEntry The inserted email list entry
 566      *          as returned by the server.
 567      * @throws Zend_Gdata_App_Exception
 568      * @throws Zend_Gdata_App_HttpException
 569      * @throws Zend_Gdata_Gapps_ServiceException
 570      */
 571     public function insertEmailList($emailList, $uri = null)
 572     {
 573         if ($uri === null) {
 574             $uri = $this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH;
 575         }
 576         $newEntry = $this->insertEntry($emailList, $uri, 'Zend_Gdata_Gapps_EmailListEntry');
 577         return $newEntry;
 578     }
 579
 580     /**
 581      * Create a new email list recipient from an EmailListRecipientEntry.
 582      *
 583      * @param Zend_Gdata_Gapps_EmailListRecipientEntry $recipient The recipient
 584      *          entry to insert.
 585      * @param string $uri (optional) The URI where the recipient should be
 586      *          uploaded to. If null, the default recipient creation URI for
 587      *          this domain will be used.
 588      * @return Zend_Gdata_Gapps_EmailListRecipientEntry The inserted
 589      *          recipient entry as returned by the server.
 590      * @throws Zend_Gdata_App_Exception
 591      * @throws Zend_Gdata_App_HttpException
 592      * @throws Zend_Gdata_Gapps_ServiceException
 593      */
 594     public function insertEmailListRecipient($recipient, $uri = null)
 595     {
 596         if ($uri === null) {
 597             require_once 'Zend/Gdata/App/InvalidArgumentException.php';
 598             throw new Zend_Gdata_App_InvalidArgumentException(
 599                     'URI must not be null');
 600         } elseif ($uri instanceof Zend_Gdata_Gapps_EmailListEntry) {
 601             $uri = $uri->getLink('edit')->href;
 602         }
 603         $newEntry = $this->insertEntry($recipient, $uri, 'Zend_Gdata_Gapps_EmailListRecipientEntry');
 604         return $newEntry;
 605     }
 606
 607     /**
 608      * Provides a magic factory method to instantiate new objects with
 609      * shorter syntax than would otherwise be required by the Zend Framework
 610      * naming conventions. For more information, see Zend_Gdata_App::__call().
 611      *
 612      * This overrides the default behavior of __call() so that query classes
 613      * do not need to have their domain manually set when created with
 614      * a magic factory method.
 615      *
 616      * @see Zend_Gdata_App::__call()
 617      * @param string $method The method name being called
 618      * @param array $args The arguments passed to the call
 619      * @throws Zend_Gdata_App_Exception
 620      */
 621     public function __call($method, $args) {
 622         if (preg_match('/^new(\w+Query)/', $method, $matches)) {
 623             $class = $matches[1];
 624             $foundClassName = null;
 625             foreach ($this->_registeredPackages as $name) {
 626                  try {
 627                      if (!class_exists($name . '_' . $class)) {
 628                         require_once 'Zend/Loader.php';
 629                         @Zend_Loader::loadClass($name . '_' . $class);
 630                      }
 631                      $foundClassName = $name . '_' . $class;
 632                      break;
 633                  } catch (Zend_Exception $e) {
 634                      // package wasn't here- continue searching
 635                  }
 636             }
 637             if ($foundClassName != null) {
 638                 $reflectionObj = new ReflectionClass($foundClassName);
 639                 // Prepend the domain to the query
 640                 $args = array_merge(array($this->getDomain()), $args);
 641                 return $reflectionObj->newInstanceArgs($args);
 642             } else {
 643                 require_once 'Zend/Gdata/App/Exception.php';
 644                 throw new Zend_Gdata_App_Exception(
 645                         "Unable to find '${class}' in registered packages");
 646             }
 647         } else {
 648             return parent::__call($method, $args);
 649         }
 650
 651     }
 652
 653     // Convenience methods
 654     // Specified at http://code.google.com/apis/apps/gdata_provisioning_api_v2.0_reference.html#appendix_e
 655
 656     /**
 657      * Create a new user entry and send it to the Google Apps servers.
 658      *
 659      * @param string $username The username for the new user.
 660      * @param string $givenName The given name for the new user.
 661      * @param string $familyName The family name for the new user.
 662      * @param string $password The password for the new user as a plaintext string
 663      *                 (if $passwordHashFunction is null) or a SHA-1 hashed
 664      *                 value (if $passwordHashFunction = 'SHA-1').
 665      * @param string $quotaLimitInMB (optional) The quota limit for the new user in MB.
 666      * @return Zend_Gdata_Gapps_UserEntry (optional) The new user entry as returned by
 667      *                 server.
 668      * @throws Zend_Gdata_App_Exception
 669      * @throws Zend_Gdata_App_HttpException
 670      * @throws Zend_Gdata_Gapps_ServiceException
 671      */
 672     public function createUser ($username, $givenName, $familyName, $password,
 673             $passwordHashFunction = null, $quotaLimitInMB = null) {
 674         $user = $this->newUserEntry();
 675         $user->login = $this->newLogin();
 676         $user->login->username = $username;
 677         $user->login->password = $password;
 678         $user->login->hashFunctionName = $passwordHashFunction;
 679         $user->name = $this->newName();
 680         $user->name->givenName = $givenName;
 681         $user->name->familyName = $familyName;
 682         if ($quotaLimitInMB !== null) {
 683             $user->quota = $this->newQuota();
 684             $user->quota->limit = $quotaLimitInMB;
 685         }
 686         return $this->insertUser($user);
 687     }
 688
 689     /**
 690      * Retrieve a user based on their username.
 691      *
 692      * @param string $username The username to search for.
 693      * @return Zend_Gdata_Gapps_UserEntry The username to search for, or null
 694      *              if no match found.
 695      * @throws Zend_Gdata_App_InvalidArgumentException
 696      * @throws Zend_Gdata_App_HttpException
 697      */
 698     public function retrieveUser ($username) {
 699         $query = $this->newUserQuery($username);
 700         try {
 701             $user = $this->getUserEntry($query);
 702         } catch (Zend_Gdata_Gapps_ServiceException $e) {
 703             // Set the user to null if not found
 704             if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
 705                 $user = null;
 706             } else {
 707                 throw $e;
 708             }
 709         }
 710         return $user;
 711     }
 712
 713     /**
 714      * Retrieve a page of users in alphabetical order, starting with the
 715      * provided username.
 716      *
 717      * @param string $startUsername (optional) The first username to retrieve.
 718      *          If null or not declared, the page will begin with the first
 719      *          user in the domain.
 720      * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry
 721      *              objects representing all users in the domain.
 722      * @throws Zend_Gdata_App_Exception
 723      * @throws Zend_Gdata_App_HttpException
 724      * @throws Zend_Gdata_Gapps_ServiceException
 725      */
 726     public function retrievePageOfUsers ($startUsername = null) {
 727         $query = $this->newUserQuery();
 728         $query->setStartUsername($startUsername);
 729         return $this->getUserFeed($query);
 730     }
 731
 732     /**
 733      * Retrieve all users in the current domain. Be aware that
 734      * calling this function on a domain with many users will take a
 735      * signifigant amount of time to complete. On larger domains this may
 736      * may cause execution to timeout without proper precautions in place.
 737      *
 738      * @return Zend_Gdata_Gapps_UserFeed Collection of Zend_Gdata_UserEntry
 739      *              objects representing all users in the domain.
 740      * @throws Zend_Gdata_App_Exception
 741      * @throws Zend_Gdata_App_HttpException
 742      * @throws Zend_Gdata_Gapps_ServiceException
 743      */
 744     public function retrieveAllUsers () {
 745         return $this->retrieveAllEntriesForFeed($this->retrievePageOfUsers());
 746     }
 747
 748     /**
 749      * Overwrite a specified username with the provided UserEntry.  The
 750      * UserEntry does not need to contain an edit link.
 751      *
 752      * This method is provided for compliance with the Google Apps
 753      * Provisioning API specification. Normally users will instead want to
 754      * call UserEntry::save() instead.
 755      *
 756      * @see Zend_Gdata_App_Entry::save
 757      * @param string $username The username whose data will be overwritten.
 758      * @param Zend_Gdata_Gapps_UserEntry $userEntry The user entry which
 759      *          will be overwritten.
 760      * @return Zend_Gdata_Gapps_UserEntry The UserEntry returned by the
 761      *          server.
 762      * @throws Zend_Gdata_App_Exception
 763      * @throws Zend_Gdata_App_HttpException
 764      * @throws Zend_Gdata_Gapps_ServiceException
 765      */
 766     public function updateUser($username, $userEntry) {
 767         return $this->updateEntry($userEntry, $this->getBaseUrl() .
 768             self::APPS_USER_PATH . '/' . $username);
 769     }
 770
 771     /**
 772      * Mark a given user as suspended.
 773      *
 774      * @param string $username The username associated with the user who
 775      *          should be suspended.
 776      * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified
 777      *          user.
 778      * @throws Zend_Gdata_App_Exception
 779      * @throws Zend_Gdata_App_HttpException
 780      * @throws Zend_Gdata_Gapps_ServiceException
 781      */
 782     public function suspendUser($username) {
 783         $user = $this->retrieveUser($username);
 784         $user->login->suspended = true;
 785         return $user->save();
 786     }
 787
 788     /**
 789      * Mark a given user as not suspended.
 790      *
 791      * @param string $username The username associated with the user who
 792      *          should be restored.
 793      * @return Zend_Gdata_Gapps_UserEntry The UserEntry for the modified
 794      *          user.
 795      * @throws Zend_Gdata_App_Exception
 796      * @throws Zend_Gdata_App_HttpException
 797      * @throws Zend_Gdata_Gapps_ServiceException
 798      */
 799     public function restoreUser($username) {
 800         $user = $this->retrieveUser($username);
 801         $user->login->suspended = false;
 802         return $user->save();
 803     }
 804
 805     /**
 806      * Delete a user by username.
 807      *
 808      * @param string $username The username associated with the user who
 809      *          should be deleted.
 810      * @throws Zend_Gdata_App_Exception
 811      * @throws Zend_Gdata_App_HttpException
 812      * @throws Zend_Gdata_Gapps_ServiceException
 813      */
 814     public function deleteUser($username) {
 815         $this->delete($this->getBaseUrl() . self::APPS_USER_PATH . '/' .
 816             $username);
 817     }
 818
 819     /**
 820      * Create a nickname for a given user.
 821      *
 822      * @param string $username The username to which the new nickname should
 823      *          be associated.
 824      * @param string $nickname The new nickname to be created.
 825      * @return Zend_Gdata_Gapps_NicknameEntry The nickname entry which was
 826      *          created by the server.
 827      * @throws Zend_Gdata_App_Exception
 828      * @throws Zend_Gdata_App_HttpException
 829      * @throws Zend_Gdata_Gapps_ServiceException
 830      */
 831     public function createNickname($username, $nickname) {
 832         $entry = $this->newNicknameEntry();
 833         $nickname = $this->newNickname($nickname);
 834         $login = $this->newLogin($username);
 835         $entry->nickname = $nickname;
 836         $entry->login = $login;
 837         return $this->insertNickname($entry);
 838     }
 839
 840     /**
 841      * Retrieve the entry for a specified nickname.
 842      *
 843      * @param string $nickname The nickname to be retrieved.
 844      * @return Zend_Gdata_Gapps_NicknameEntry The requested nickname entry.
 845      * @throws Zend_Gdata_App_Exception
 846      * @throws Zend_Gdata_App_HttpException
 847      * @throws Zend_Gdata_Gapps_ServiceException
 848      */
 849     public function retrieveNickname($nickname) {
 850         $query = $this->newNicknameQuery();
 851         $query->setNickname($nickname);
 852         try {
 853             $nickname = $this->getNicknameEntry($query);
 854         } catch (Zend_Gdata_Gapps_ServiceException $e) {
 855             // Set the nickname to null if not found
 856             if ($e->hasError(Zend_Gdata_Gapps_Error::ENTITY_DOES_NOT_EXIST)) {
 857                 $nickname = null;
 858             } else {
 859                 throw $e;
 860             }
 861         }
 862         return $nickname;
 863     }
 864
 865     /**
 866      * Retrieve all nicknames associated with a specific username.
 867      *
 868      * @param string $username The username whose nicknames should be
 869      *          returned.
 870      * @return Zend_Gdata_Gapps_NicknameFeed A feed containing all nicknames
 871      *          for the given user, or null if
 872      * @throws Zend_Gdata_App_Exception
 873      * @throws Zend_Gdata_App_HttpException
 874      * @throws Zend_Gdata_Gapps_ServiceException
 875      */
 876     public function retrieveNicknames($username) {
 877         $query = $this->newNicknameQuery();
 878         $query->setUsername($username);
 879         $nicknameFeed = $this->retrieveAllEntriesForFeed(
 880             $this->getNicknameFeed($query));
 881         return $nicknameFeed;
 882     }
 883
 884     /**
 885      * Retrieve a page of nicknames in alphabetical order, starting with the
 886      * provided nickname.
 887      *
 888      * @param string $startNickname (optional) The first nickname to
 889      *          retrieve. If null or not declared, the page will begin with
 890      *          the first nickname in the domain.
 891      * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry
 892      *              objects representing all nicknames in the domain.
 893      * @throws Zend_Gdata_App_Exception
 894      * @throws Zend_Gdata_App_HttpException
 895      * @throws Zend_Gdata_Gapps_ServiceException
 896      */
 897     public function retrievePageOfNicknames ($startNickname = null) {
 898         $query = $this->newNicknameQuery();
 899         $query->setStartNickname($startNickname);
 900         return $this->getNicknameFeed($query);
 901     }
 902
 903     /**
 904      * Retrieve all nicknames in the current domain. Be aware that
 905      * calling this function on a domain with many nicknames will take a
 906      * signifigant amount of time to complete. On larger domains this may
 907      * may cause execution to timeout without proper precautions in place.
 908      *
 909      * @return Zend_Gdata_Gapps_NicknameFeed Collection of Zend_Gdata_NicknameEntry
 910      *              objects representing all nicknames in the domain.
 911      * @throws Zend_Gdata_App_Exception
 912      * @throws Zend_Gdata_App_HttpException
 913      * @throws Zend_Gdata_Gapps_ServiceException
 914      */
 915     public function retrieveAllNicknames () {
 916         return $this->retrieveAllEntriesForFeed($this->retrievePageOfNicknames());
 917     }
 918
 919     /**
 920      * Delete a specified nickname.
 921      *
 922      * @param string $nickname The name of the nickname to be deleted.
 923      * @throws Zend_Gdata_App_Exception
 924      * @throws Zend_Gdata_App_HttpException
 925      * @throws Zend_Gdata_Gapps_ServiceException
 926      */
 927     public function deleteNickname($nickname) {
 928         $this->delete($this->getBaseUrl() . self::APPS_NICKNAME_PATH . '/' . $nickname);
 929     }
 930
 931     /**
 932      * Create a new email list.
 933      *
 934      * @param string $emailList The name of the email list to be created.
 935      * @return Zend_Gdata_Gapps_EmailListEntry The email list entry
 936      *          as created on the server.
 937      * @throws Zend_Gdata_App_Exception
 938      * @throws Zend_Gdata_App_HttpException
 939      * @throws Zend_Gdata_Gapps_ServiceException
 940      */
 941     public function createEmailList($emailList) {
 942         $entry = $this->newEmailListEntry();
 943         $list = $this->newEmailList();
 944         $list->name = $emailList;
 945         $entry->emailList = $list;
 946         return $this->insertEmailList($entry);
 947     }
 948
 949     /**
 950      * Retrieve all email lists associated with a recipient.
 951      *
 952      * @param string $username The recipient whose associated email lists
 953      *          should be returned.
 954      * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found as
 955      *          Zend_Gdata_EmailListEntry objects.
 956      * @throws Zend_Gdata_App_Exception
 957      * @throws Zend_Gdata_App_HttpException
 958      * @throws Zend_Gdata_Gapps_ServiceException
 959      */
 960     public function retrieveEmailLists($recipient) {
 961         $query = $this->newEmailListQuery();
 962         $query->recipient = $recipient;
 963         return $this->getEmailListFeed($query);
 964     }
 965
 966     /**
 967      * Retrieve a page of email lists in alphabetical order, starting with the
 968      * provided email list.
 969      *
 970      * @param string $startEmailListName (optional) The first list to
 971      *              retrieve. If null or not defined, the page will begin
 972      *              with the first email list in the domain.
 973      * @return Zend_Gdata_Gapps_EmailListFeed Collection of Zend_Gdata_EmailListEntry
 974      *              objects representing all nicknames in the domain.
 975      * @throws Zend_Gdata_App_Exception
 976      * @throws Zend_Gdata_App_HttpException
 977      * @throws Zend_Gdata_Gapps_ServiceException
 978      */
 979     public function retrievePageOfEmailLists ($startNickname = null) {
 980         $query = $this->newEmailListQuery();
 981         $query->setStartEmailListName($startNickname);
 982         return $this->getEmailListFeed($query);
 983     }
 984
 985     /**
 986      * Retrieve all email lists associated with the curent domain. Be aware that
 987      * calling this function on a domain with many email lists will take a
 988      * signifigant amount of time to complete. On larger domains this may
 989      * may cause execution to timeout without proper precautions in place.
 990      *
 991      * @return Zend_Gdata_Gapps_EmailListFeed The list of email lists found
 992      *              as Zend_Gdata_Gapps_EmailListEntry objects.
 993      * @throws Zend_Gdata_App_Exception
 994      * @throws Zend_Gdata_App_HttpException
 995      * @throws Zend_Gdata_Gapps_ServiceException
 996      */
 997     public function retrieveAllEmailLists() {
 998         return $this->retrieveAllEntriesForFeed($this->retrievePageOfEmailLists());
 999     }
1000
1001     /**
1002      * Delete a specified email list.
1003      *
1004      * @param string $emailList The name of the emailList to be deleted.
1005      * @throws Zend_Gdata_App_Exception
1006      * @throws Zend_Gdata_App_HttpException
1007      * @throws Zend_Gdata_Gapps_ServiceException
1008      */
1009     public function deleteEmailList($emailList) {
1010         $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/'
1011             . $emailList);
1012     }
1013
1014     /**
1015      * Add a specified recipient to an existing emailList.
1016      *
1017      * @param string $recipientAddress The address of the recipient to be
1018      *              added to the email list.
1019      * @param string $emailList The name of the email address to which the
1020      *              recipient should be added.
1021      * @return Zend_Gdata_Gapps_EmailListRecipientEntry The recipient entry
1022      *              created by the server.
1023      * @throws Zend_Gdata_App_Exception
1024      * @throws Zend_Gdata_App_HttpException
1025      * @throws Zend_Gdata_Gapps_ServiceException
1026      */
1027     public function addRecipientToEmailList($recipientAddress, $emailList) {
1028         $entry = $this->newEmailListRecipientEntry();
1029         $who = $this->newWho();
1030         $who->email = $recipientAddress;
1031         $entry->who = $who;
1032         $address = $this->getBaseUrl() .  self::APPS_EMAIL_LIST_PATH . '/' .
1033             $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/';
1034         return $this->insertEmailListRecipient($entry, $address);
1035     }
1036
1037     /**
1038      * Retrieve a page of email list recipients in alphabetical order,
1039      * starting with the provided email list recipient.
1040      *
1041      * @param string $emaiList The email list which should be searched.
1042      * @param string $startRecipient (optinal) The address of the first
1043      *              recipient, or null to start with the first recipient in
1044      *              the list.
1045      * @return Zend_Gdata_Gapps_EmailListRecipientFeed Collection of
1046      *              Zend_Gdata_EmailListRecipientEntry objects representing all
1047      *              recpients in the specified list.
1048      * @throws Zend_Gdata_App_Exception
1049      * @throws Zend_Gdata_App_HttpException
1050      * @throws Zend_Gdata_Gapps_ServiceException
1051      */
1052     public function retrievePageOfRecipients ($emailList,
1053             $startRecipient = null) {
1054         $query = $this->newEmailListRecipientQuery();
1055         $query->setEmailListName($emailList);
1056         $query->setStartRecipient($startRecipient);
1057         return $this->getEmailListRecipientFeed($query);
1058     }
1059
1060     /**
1061      * Retrieve all recipients associated with an email list. Be aware that
1062      * calling this function on a domain with many email lists will take a
1063      * signifigant amount of time to complete. On larger domains this may
1064      * may cause execution to timeout without proper precautions in place.
1065      *
1066      * @param string $emaiList The email list which should be searched.
1067      * @return Zend_Gdata_Gapps_EmailListRecipientFeed The list of email lists
1068      *              found as Zend_Gdata_Gapps_EmailListRecipientEntry objects.
1069      * @throws Zend_Gdata_App_Exception
1070      * @throws Zend_Gdata_App_HttpException
1071      * @throws Zend_Gdata_Gapps_ServiceException
1072      */
1073     public function retrieveAllRecipients($emailList) {
1074         return $this->retrieveAllEntriesForFeed(
1075                 $this->retrievePageOfRecipients($emailList));
1076     }
1077
1078     /**
1079      * Remove a specified recipient from an email list.
1080      *
1081      * @param string $recipientAddress The recipient to be removed.
1082      * @param string $emailList The list from which the recipient should
1083      *              be removed.
1084      * @throws Zend_Gdata_App_Exception
1085      * @throws Zend_Gdata_App_HttpException
1086      * @throws Zend_Gdata_Gapps_ServiceException
1087      */
1088     public function removeRecipientFromEmailList($recipientAddress, $emailList) {
1089         $this->delete($this->getBaseUrl() . self::APPS_EMAIL_LIST_PATH . '/'
1090             . $emailList . self::APPS_EMAIL_LIST_RECIPIENT_POSTFIX . '/'
1091             . $recipientAddress);
1092     }
1093
1094 }