java/src/main/com/google/appengine/tools/development/Module.java

   1 package com.google.appengine.tools.development;
   2
   3 import com.google.apphosting.api.ApiProxy;
   4
   5 import java.util.Map;
   6
   7 /**
   8  * Holder for both configuration and runtime information for a single
   9  * {@link DevAppServer} module and all its instances.
  10  *
  11  */
  12 public interface Module {
  13   /**
  14    * Configure this {@link Module}.
  15    * <p>
  16    * Note {@link #configure} fits into the {@link DevAppServer} startup
  17    * sequence. The user may adjust {@link DevAppServer#setServiceProperties}
  18    * values after construction and before calling {@link DevAppServer#start()}
  19    * which calls {@link #configure}. To retain compatibility operations that
  20    * make use of these user specified settings such as port selection must not
  21    * not be performed during construction.
  22    * @param containerConfigProperties container configuration properties.
  23    * @throws Exception
  24    */
  25   void configure(Map<String, Object>containerConfigProperties) throws Exception;
  26
  27   /**
  28    * Sets the {@link com.google.apphosting.api.ApiProxy.Delegate}.
  29    */
  30   void setApiProxyDelegate(ApiProxy.Delegate<?> apiProxyDelegate);
  31
  32   /**
  33    * Creates the network connections for this {@link Module}.
  34    * @throws Exception
  35    */
  36   void createConnection() throws Exception;
  37
  38   /**
  39    * Starts all the instances for this {@link Module}. Once this returns the
  40    * {@link Module} can handle HTTP requests.
  41    * @throws Exception
  42    */
  43   void startup() throws Exception;
  44
  45   /**
  46    * Stops all the instances for this {@link Module}. Once this returns the
  47    * {@link Module} cannot handle HTTP requests.
  48    * @throws Exception
  49    */
  50   void shutdown() throws Exception;
  51
  52   /**
  53    * Simulates stopping the module in production.
  54    *
  55    * @throws UnsupportedOperationException if this is not a manual module.
  56    * @throws Exception
  57    */
  58   void stopServing() throws Exception;
  59
  60   /**
  61    * Simulates starting the module in production.
  62    *
  63    * @throws UnsupportedOperationException if this is not a manual module.
  64    * @throws Exception
  65    */
  66   void startServing() throws Exception;
  67
  68   /**
  69    * Returns the module name for this {@link Module}.
  70    */
  71   String getModuleName();
  72
  73   /**
  74    * Returns the {@link ContainerService} for the primary instance for this
  75    * {@link Module}.
  76    */
  77   ContainerService getMainContainer();
  78
  79   /**
  80    * Returns the {@link LocalServerEnvironment} for the primary instance for
  81    * this {@link Module}.
  82    */
  83   LocalServerEnvironment getLocalServerEnvironment();
  84
  85   /**
  86    * Returns the host and port for the requested instance or null if the
  87    * instance does not exist.
  88    * @param instance The instance number or {@link LocalEnvironment#MAIN_INSTANCE}.
  89    */
  90   String getHostAndPort(int instance);
  91
  92   /**
  93    * Returns the requested {@link InstanceHolder} or null if the instance does
  94    * not exist.
  95    * @param instance the instance number or {@link LocalEnvironment#MAIN_INSTANCE}.
  96    */
  97   InstanceHolder getInstanceHolder(int instance);
  98
  99   /**
 100    * Returns the number of instances for this module. This will return 0 for
 101    * an {@link AutomaticModule}.
 102    */
 103   int getInstanceCount();
 104
 105   /**
 106    * Acquires a serving permit and returns an {@link InstanceHolder} for an
 107    * instance which is available to handle a request or returns null if there
 108    * is no such instance.
 109    * <p>
 110    * throws {@link UnsupportedOperationException} unless this is a
 111    * {@link ManualModule}.
 112    */
 113   InstanceHolder getAndReserveAvailableInstanceHolder();
 114 }