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

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