python/php/sdk/google/appengine/api/modules/ModulesService.php

   1 <?php
   2 /**
   3  * Copyright 2007 Google Inc.
   4  *
   5  * Licensed under the Apache License, Version 2.0 (the "License");
   6  * you may not use this file except in compliance with the License.
   7  * You may obtain a copy of the License at
   8  *
   9  *     http://www.apache.org/licenses/LICENSE-2.0
  10  *
  11  * Unless required by applicable law or agreed to in writing, software
  12  * distributed under the License is distributed on an "AS IS" BASIS,
  13  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14  * See the License for the specific language governing permissions and
  15  * limitations under the License.
  16  */
  17 /**
  18  * An API for fetching information about and controlling App Engine Modules.
  19  *
  20  */
  21
  22 namespace google\appengine\api\modules;
  23
  24 require_once 'google/appengine/api/modules/modules_service_pb.php';
  25 require_once "google/appengine/api/modules/InvalidModuleStateException.php";
  26 require_once "google/appengine/api/modules/ModulesException.php";
  27 require_once "google/appengine/api/modules/TransientModulesException.php";
  28 require_once 'google/appengine/runtime/ApiProxy.php';
  29 require_once 'google/appengine/runtime/ApplicationError.php';
  30
  31 use google\appengine\runtime\ApiProxy;
  32 use google\appengine\runtime\ApplicationError;
  33 use google\appengine\GetDefaultVersionRequest;
  34 use google\appengine\GetDefaultVersionResponse;
  35 use google\appengine\GetHostnameRequest;
  36 use google\appengine\GetHostnameResponse;
  37 use google\appengine\GetModulesRequest;
  38 use google\appengine\GetModulesResponse;
  39 use google\appengine\GetNumInstancesRequest;
  40 use google\appengine\GetNumInstancesResponse;
  41 use google\appengine\GetVersionsRequest;
  42 use google\appengine\GetVersionsResponse;
  43 use google\appengine\ModulesServiceError\ErrorCode;
  44 use google\appengine\SetNumInstancesRequest;
  45 use google\appengine\SetNumInstancesResponse;
  46 use google\appengine\StartModuleRequest;
  47 use google\appengine\StartModuleResponse;
  48 use google\appengine\StopModuleRequest;
  49 use google\appengine\StopModuleResponse;
  50
  51 final class ModulesService {
  52   private static function errorCodeToException($error) {
  53     switch($error) {
  54       case ErrorCode::INVALID_MODULE:
  55         return new ModulesException('Invalid module.');
  56       case ErrorCode::INVALID_VERSION:
  57         return new ModulesException('Invalid version.');
  58       case ErrorCode::INVALID_INSTANCES:
  59         return new ModulesException('Invalid instances.');
  60       case ErrorCode::TRANSIENT_ERROR:
  61         return new TransientModulesException();
  62       case ErrorCode::UNEXPECTED_STATE:
  63         return new InvalidModuleStateException();
  64       default:
  65         return new ModulesException('Error Code: ' . $error);
  66     }
  67   }
  68
  69   /**
  70    * Gets the name of the currently running module.
  71    *
  72    * @return string The name of the current module. For example, if this is
  73    * version "v1" of module "module5" for app "my-app", this function
  74    * will return "module5".
  75    */
  76   public static function getCurrentModuleName() {
  77     return $_SERVER['CURRENT_MODULE_ID'];
  78   }
  79
  80   /**
  81    * Gets the version of the currently running module.
  82    *
  83    * @return string The name of the current module. For example, if this is
  84    * version "v1" of module "module5" for app "my-app", this function
  85    * will return "v1".
  86    */
  87   public static function getCurrentVersionName() {
  88     return explode('.', $_SERVER['CURRENT_VERSION_ID'])[0];
  89   }
  90
  91   /**
  92    * Gets the id of the currently running instance.
  93    *
  94    * @return string The name of the current module. For example, if this is
  95    * instance 2 of version "v1" of module "module5" for app "my-app", this
  96    * function will return "2". For automatically-scaled modules, this function
  97    * will return a unique hex string for the instance (e.g.
  98    * "00c61b117c7f7fd0ce9e1325a04b8f0df30deaaf").
  99    */
 100   public static function getCurrentInstanceId() {
 101     return $_SERVER['INSTANCE_ID'];
 102   }
 103
 104   /**
 105    * Gets an array of all the modules for the application.
 106    *
 107    * @return string[] An array of string containing the names of the modules
 108    * associated with the application. The 'default' module will be included if
 109    * it exists, as will the name of the module that is associated with the
 110    * instance that calls this function.
 111    */
 112   public static function getModules() {
 113     $req = new GetModulesRequest();
 114     $resp = new GetModulesResponse();
 115
 116     ApiProxy::makeSyncCall('modules', 'GetModules', $req, $resp);
 117     return $resp->getModuleList();
 118   }
 119
 120   /**
 121    * Get an array of all versions associated with a module.
 122    *
 123    * @param string $module The name of the module to retrieve the versions for.
 124    * If null then the versions for the current module will be retrieved.
 125    *
 126    * @return string[] An array of strings containing the names of versions
 127    * associated with the module. The current version will also be included in
 128    * this list.
 129    *
 130    * @throws \InvalidArgumentException If $module is not a string.
 131    * @throws ModulesException If the given $module isn't valid.
 132    * @throws TransientModulesException if there is an issue fetching the
 133    * information.
 134    */
 135   public static function getVersions($module = null) {
 136     $req = new GetVersionsRequest();
 137     $resp = new GetVersionsResponse();
 138
 139     if ($module !== null) {
 140       if (!is_string($module)) {
 141         throw new \InvalidArgumentException(
 142             '$module must be a string. Actual type: ' . gettype($module));
 143       }
 144       $req->setModule($module);
 145     }
 146
 147     try {
 148       ApiProxy::makeSyncCall('modules', 'GetVersions', $req, $resp);
 149     } catch (ApplicationError $e) {
 150       throw errorCodeToException($e->getApplicationError());
 151     }
 152     return $resp->getVersionList();
 153   }
 154
 155   /**
 156    * Get the default version of a module.
 157    *
 158    * @param string $module The name of the module to retrieve the default
 159    * versions for. If null then the default versions for the current module
 160    * will be retrieved.
 161    *
 162    * @return string The default version of the module.
 163    *
 164    * @throws \InvalidArgumentException If $module is not a string.
 165    * @throws ModulesException If the given $module is invalid or if no default
 166    * version could be found.
 167    */
 168   public static function getDefaultVersion($module = null) {
 169     $req = new GetDefaultVersionRequest();
 170     $resp = new GetDefaultVersionResponse();
 171
 172     if ($module !== null) {
 173       if (!is_string($module)) {
 174         throw new \InvalidArgumentException(
 175             '$module must be a string. Actual type: ' . gettype($module));
 176       }
 177       $req->setModule($module);
 178     }
 179
 180     try {
 181       ApiProxy::makeSyncCall('modules', 'GetDefaultVersion', $req, $resp);
 182     } catch (ApplicationError $e) {
 183       throw errorCodeToException($e->getApplicationError());
 184     }
 185     return $resp->getVersion();
 186   }
 187
 188   /**
 189    * Get the number of instances set for a version of a module.
 190    *
 191    * This function does not work on automatically-scaled modules.
 192    *
 193    * @param string $module The name of the module to retrieve the count for. If
 194    * null then the count for the current module will be retrieved.
 195    *
 196    * @param string $version The version of the module to retrieve the count for.
 197    * If null then the count for the version of the current instance will be
 198    * retrieved.
 199    *
 200    * @return integer The number of instances set for the current module
 201    * version.
 202    *
 203    * @throws \InvalidArgumentException If $module or $version is not a string.
 204    * @throws ModulesException if the given combination of $module and $version
 205    * is invalid.
 206    */
 207   public static function getNumInstances($module = null, $version = null) {
 208     $req = new GetNumInstancesRequest();
 209     $resp = new GetNumInstancesResponse();
 210
 211     if ($module !== null) {
 212       if (!is_string($module)) {
 213         throw new \InvalidArgumentException(
 214             '$module must be a string. Actual type: ' . gettype($module));
 215       }
 216       $req->setModule($module);
 217     }
 218
 219     if ($version !== null) {
 220       if (!is_string($version)) {
 221         throw new \InvalidArgumentException(
 222             '$version must be a string. Actual type: ' . gettype($version));
 223       }
 224       $req->setVersion($version);
 225     }
 226
 227     try {
 228       ApiProxy::makeSyncCall('modules', 'GetNumInstances', $req, $resp);
 229     } catch (ApplicationError $e) {
 230       throw self::errorCodeToException($e->getApplicationError());
 231     }
 232     return (int) $resp->getInstances();
 233   }
 234
 235   /**
 236    * Set the number of instances for a version of a module.
 237    *
 238    * This function does not work on automatically-scaled modules.
 239    *
 240    * @param string $module The name of the module to set the instance count for.
 241    * If null then the instance count for the current module will be set.
 242    *
 243    * @param string $version The version of the module to set the instance count
 244    * for. If null then the count for the version of the current instance will
 245    * be set.
 246    *
 247    * @throws \InvalidArgumentException If $instances is not an integer or if
 248    * $module or $version is not a string.
 249    * @throws ModulesException if the given combination of $module and $version
 250    * is invalid.
 251    * @throws TransientModulesException if there is an issue setting the
 252    * instance count.
 253    */
 254   public static function setNumInstances($instances,
 255                                          $module = null,
 256                                          $version = null) {
 257     $req = new SetNumInstancesRequest();
 258     $resp = new SetNumInstancesResponse();
 259
 260     if (!is_int($instances)) {
 261       throw new \InvalidArgumentException(
 262           '$instances must be an integer. Actual type: ' . gettype($instances));
 263     }
 264     $req->setInstances($instances);
 265
 266     if ($module !== null) {
 267       if (!is_string($module)) {
 268         throw new \InvalidArgumentException(
 269             '$module must be a string. Actual type: ' . gettype($module));
 270       }
 271       $req->setModule($module);
 272     }
 273
 274     if ($version !== null) {
 275       if (!is_string($version)) {
 276         throw new \InvalidArgumentException(
 277             '$version must be a string. Actual type: ' . gettype($version));
 278       }
 279       $req->setVersion($version);
 280     }
 281
 282     try {
 283       ApiProxy::makeSyncCall('modules', 'SetNumInstances', $req, $resp);
 284     } catch (ApplicationError $e) {
 285       throw self::errorCodeToException($e->getApplicationError());
 286     }
 287   }
 288
 289   /**
 290    * Starts all instances of the given version of a module.
 291    * *
 292    * @param string $module The name of the module to start.
 293    *
 294    * @param string $version The version of the module to start.
 295    *
 296    * @throws \InvalidArgumentException If $module or $version is not a string.
 297    * @throws ModulesException if the given combination of $module and $version
 298    * is invalid.
 299    * @throws InvalidModuleStateException if the given $version is already
 300    * started or cannot be started.
 301    * @throws TransientModulesException if there is an issue starting the module
 302    * version.
 303    */
 304   public static function startVersion($module, $version) {
 305     $req = new StartModuleRequest();
 306     $resp = new StartModuleResponse();
 307
 308     if (!is_string($module)) {
 309       throw new \InvalidArgumentException(
 310           '$module must be a string. Actual type: ' . gettype($module));
 311     }
 312     $req->setModule($module);
 313
 314     if (!is_string($version)) {
 315       throw new \InvalidArgumentException(
 316           '$version must be a string. Actual type: ' . gettype($version));
 317     }
 318     $req->setVersion($version);
 319
 320     try {
 321       ApiProxy::makeSyncCall('modules', 'StartModule', $req, $resp);
 322     } catch (ApplicationError $e) {
 323       throw self::errorCodeToException($e->getApplicationError());
 324     }
 325   }
 326
 327   /**
 328    * Stops all instances of the given version of a module.
 329    * *
 330    * @param string $module The name of the module to stop. If null then the
 331    * current module will be stopped.
 332    *
 333    * @param string $version The version of the module to stop. If null then the
 334    * current version will be stopped.
 335    *
 336    * @throws \InvalidArgumentException If $module or $version is not a string.
 337    * @throws ModulesException if the given combination of $module and $version
 338    * instance is invalid.
 339    * @throws InvalidModuleStateException if the given $version is already
 340    * stopped or cannot be stopped.
 341    * @throws TransientModulesException if there is an issue stopping the module
 342    * version.
 343    */
 344   public static function stopVersion($module = null, $version = null) {
 345     $req = new StopModuleRequest();
 346     $resp = new StopModuleResponse();
 347
 348     if ($module !== null) {
 349       if (!is_string($module)) {
 350         throw new \InvalidArgumentException(
 351             '$module must be a string. Actual type: ' . gettype($module));
 352       }
 353       $req->setModule($module);
 354     }
 355
 356     if ($version !== null) {
 357       if (!is_string($version)) {
 358         throw new \InvalidArgumentException(
 359             '$version must be a string. Actual type: ' . gettype($version));
 360       }
 361       $req->setVersion($version);
 362     }
 363
 364     try {
 365       ApiProxy::makeSyncCall('modules', 'StopModule', $req, $resp);
 366     } catch (ApplicationError $e) {
 367       throw self::errorCodeToException($e->getApplicationError());
 368     }
 369   }
 370
 371   /**
 372    * Returns the hostname to use when contacting a module.
 373    * *
 374    * @param string $module The name of the module whose hostname should be
 375    * returned. If null then the hostname of the current module will be returned.
 376    *
 377    * @param string $version The version of the module whose hostname should be
 378    * returned. If null then the hostname for the version of the current
 379    * instance will be returned.
 380    *
 381    * @param string $instance The instance whose hostname should be returned. If
 382    * null then the load balanced hostname for the module will be returned. If
 383    * the module is not a fixed module then the instance parameter is ignored.
 384    *
 385    * @return string The valid canonical hostname that can be used to communicate
 386    * with the given module/version/instance e.g.
 387    * "0.version1.module5.myapp.appspot.com".
 388
 389    * @throws \InvalidArgumentException If $module or $version is not a string
 390    * or if $instance is not a string or integer.
 391    * @throws ModulesException if the given combination of $module and $instance
 392    * is invalid.
 393    */
 394   public static function getHostname($module = null,
 395                                      $version = null,
 396                                      $instance = null) {
 397     $req = new GetHostnameRequest();
 398     $resp = new GetHostnameResponse();
 399
 400     if ($module !== null) {
 401       if (!is_string($module)) {
 402         throw new \InvalidArgumentException(
 403             '$module must be a string. Actual type: ' . gettype($module));
 404       }
 405       $req->setModule($module);
 406     }
 407
 408     if ($version !== null) {
 409       if (!is_string($version)) {
 410         throw new \InvalidArgumentException(
 411             '$version must be a string. Actual type: ' . gettype($version));
 412       }
 413       $req->setVersion($version);
 414     }
 415
 416     if ($instance !== null) {
 417       if (!is_int($instance) && !is_string($instance)) {
 418         throw new \InvalidArgumentException(
 419             '$instance must be an integer or string. Actual type: ' .
 420             gettype($instance));
 421       }
 422       $req->setInstance((string) $instance);
 423     }
 424
 425     try {
 426       ApiProxy::makeSyncCall('modules', 'GetHostname', $req, $resp);
 427     } catch (ApplicationError $e) {
 428       throw self::errorCodeToException($e->getApplicationError());
 429     }
 430
 431     return $resp->getHostname();
 432   }
 433 }