java/src/main/com/google/appengine/api/labs/modules/ModulesService.java

   1 package com.google.appengine.api.labs.modules;
   2
   3 import java.util.Set;
   4
   5 /**
   6  * ModulesService allows the application to fetch information about its
   7  * own module and version information.  Additionally, the service has the
   8  * ability to start, stop and change the number of instances associated with a
   9  * module version.
  10  *
  11  */
  12 public interface ModulesService {
  13
  14   /**
  15    * Get the name of the current module.
  16    *
  17    * @return the name of the module
  18    */
  19   String getCurrentModule();
  20
  21   /**
  22    * Get the name of the current version.
  23    *
  24    * @return the name of the version
  25    */
  26   String getCurrentVersion();
  27
  28   /**
  29    * Get the id of the current instance.
  30    *
  31    * @return current instance id
  32    * @throws ModulesException when no instance id exists for the current instance
  33    */
  34   String getCurrentInstanceId();
  35
  36   /**
  37    * Get the set of modules that are available to the application.
  38    *
  39    * @return Set of modules available to the application
  40    * @throws ModulesException when an error occurs
  41    */
  42   Set<String> getModules();
  43
  44   /**
  45    * Returns the set of versions that are available to the given module.
  46    *
  47    * @param module the name of the module
  48    * @throws ModulesException when input is invalid
  49    */
  50   Set<String> getVersions(String module);
  51
  52   /**
  53    * Returns the name of the default version for the module.
  54    *
  55    * @param module the name of the module
  56    * @throws ModulesException when an error occurs
  57    */
  58   String getDefaultVersion(String module);
  59
  60   /**
  61    * Returns the number of instances that are available to the given module and version.
  62    *
  63    * @param module the name of the module
  64    * @param version the name of the version
  65    * @throws ModulesException when input is invalid
  66    */
  67   long getNumInstances(String module, String version);
  68
  69   /**
  70    * Set the number of instances that are available to the given module and version.
  71    *
  72    * @param module the name of the module
  73    * @param version the name of the version
  74    * @param instances the number of instances to set
  75    * @throws ModulesException when input is invalid
  76    */
  77   void setNumInstances(String module, String version, long instances);
  78
  79   /**
  80    * Start a given module and version.
  81    *
  82    * @param module the name of the module
  83    * @param version the name of the version
  84    * @throws ModulesException when input or existing state is invalid
  85    */
  86   void startModule(String module, String version);
  87
  88   /**
  89    * Stop a given module and version.
  90    *
  91    * @param module the name of the module
  92    * @param version the name of the version
  93    * @throws ModulesException when input or existing state is invalid
  94    */
  95   void stopModule(String module, String version);
  96
  97   /**
  98    * Returns a hostname to use for the given module and version.
  99    *
 100    * @param module the name of the module or null to indicate the current module
 101    * @param version the name of the version or null to indicate the current version
 102    * @throws ModulesException when input is invalid
 103    */
 104   String getModuleHostname(String module, String version);
 105
 106   /**
 107    * Returns a hostname to use for the given module and version.
 108    *
 109    * @param module the name of the module or null to indicate the current module
 110    * @param version the name of the version or null to indicate the current version
 111    * @param instance the id of a particular instance to address
 112    * @return the hostname of the given instance
 113    * @throws ModulesException when input is invalid
 114    */
 115   String getModuleHostname(String module, String version, int instance);
 116 }