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

   1 package com.google.appengine.tools.development;
   2
   3 import java.io.IOException;
   4
   5 import javax.servlet.ServletException;
   6 import javax.servlet.http.HttpServletRequest;
   7 import javax.servlet.http.HttpServletResponse;
   8
   9 /**
  10  * Support interface for {@link DevAppServerServersFilter}.
  11  */
  12 public interface ServersFilterHelper {
  13   /**
  14    * This method guards access to servers to limit the number of concurrent
  15    * requests. Each request running on a server must acquire a serving permit.
  16    * If no permits are available a 500 response should be sent.
  17    *
  18    * @param serverName The server for which to acquire a permit.
  19    * @param instanceNumber The server instance for which to acquire a permit.
  20    * @param allowQueueOnBackends If set to false the method will return
  21    *        instantly, if set to true (and the specified server allows pending
  22    *        queues) this method can block for up to 10 s waiting for a serving
  23    *        permit to become available.
  24    * @return true if a permit was acquired, false otherwise
  25    */
  26   boolean acquireServingPermit(String serverName, int instanceNumber,
  27       boolean allowQueueOnBackends);
  28   /**
  29    * Acquires a serving permit for an instance with capacity and returns the instance
  30    * id. If no instance has capacity this returns -1.
  31    * <p>
  32    * For backends which support queued requests this may block for a limited
  33    * time waiting for an instance to become available (see {@link
  34    * AbstractBackendServers#getAndReserveFreeInstance} for details).
  35    *
  36    * @param requestedServer Name of the server the request is to.
  37    * @return the instance id of an available server instance, or -1 if no
  38    *         instance is available.
  39    */
  40   int getAndReserveFreeInstance(String requestedServer);
  41
  42   /**
  43    * Returns a serving permit after a request has completed.
  44    *
  45    * @param serverName The server name
  46    * @param instance The server instance
  47    */
  48   public void returnServingPermit(String serverName, int instance);
  49
  50   /**
  51    * Verifies if a specific server/instance is configured.
  52    *
  53    * @param serverName The server name
  54    * @param instance The server instance
  55    * @return true if the server/instance is configured, false otherwise.
  56    */
  57   boolean checkInstanceExists(String serverName, int instance);
  58
  59   /**
  60    * Verifies if a specific server is configured.
  61    *
  62    * @param serverName The server name
  63    * @return true if the server is configured, false otherwise.
  64    */
  65   boolean checkServerExists(String serverName);
  66
  67   /**
  68    * Verifies if a specific server is stopped.
  69    *
  70    * @param serverName The server name
  71    * @return true if the server is stopped, false otherwise.
  72    */
  73   boolean checkServerStopped(String serverName);
  74
  75   /**
  76    * Verifies if a specific server/instance is stopped.
  77    *
  78    * @param serverName The server name
  79    * @param instance The server instance
  80    * @return true if the server/instance is stopped, false otherwise.
  81    */
  82   boolean checkInstanceStopped(String serverName, int instance);
  83
  84   /**
  85    * Forward a request to a specific server and instance. This will call the
  86    * specified instance request dispatcher so the request is handled in the
  87    * right server context. The caller must hold a serving permit for the
  88    * requested server and instance before calling this method.
  89    */
  90   void forwardToServer(String requestedServer, int instance, HttpServletRequest hrequest,
  91       HttpServletResponse hresponse) throws IOException, ServletException;
  92
  93   /**
  94    * Verifies if a specific server/instance is stopped.
  95    *
  96    * @param serverName The server name
  97    * @param instance The server instance or -1 for automatic and load
  98    *     balancing servers
  99    * @return true if the server/instance is a server load balancing server and false otherwise.
 100    */
 101   boolean isServerLoadBalancingServer(String serverName, int instance);
 102 }