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    * Supported for servers that support load balancing (currently {@link ManualServer}).
  37    * The client can check with {@link #isServerLoadBalancingServer(String, int)}.
  38    *
  39    * @param requestedServer Name of the requested server.
  40    * @return the instance id of an available server instance, or -1 if no
  41    *         instance is available.
  42    */
  43   int getAndReserveFreeInstance(String requestedServer);
  44
  45   /**
  46    * Returns a serving permit after a request has completed.
  47    *
  48    * @param serverName The server name
  49    * @param instance The server instance
  50    */
  51   public void returnServingPermit(String serverName, int instance);
  52
  53   /**
  54    * Verifies if a specific server/instance is configured.
  55    *
  56    * @param serverName The server name
  57    * @param instance The server instance
  58    * @return true if the server/instance is configured, false otherwise.
  59    */
  60   boolean checkInstanceExists(String serverName, int instance);
  61
  62   /**
  63    * Verifies if a specific server is configured.
  64    *
  65    * @param serverName The server name
  66    * @return true if the server is configured, false otherwise.
  67    */
  68   boolean checkServerExists(String serverName);
  69
  70   /**
  71    * Verifies if a specific existing server is stopped.
  72    *
  73    * @param serverName The server name
  74    * @return true if the server is stopped, false otherwise.
  75    */
  76   boolean checkServerStopped(String serverName);
  77
  78   /**
  79    * Verifies if a specific existing server/instance is stopped.
  80    *
  81    * @param serverName The server name
  82    * @param instance The server instance
  83    * @return true if the server/instance is stopped, false otherwise.
  84    */
  85   boolean checkInstanceStopped(String serverName, int instance);
  86
  87   /**
  88    * Forward a request to a specific server and instance. This will call the
  89    * specified instance request dispatcher so the request is handled in the
  90    * right server context. The caller must hold a serving permit for the
  91    * requested server and instance before calling this method.
  92    */
  93   void forwardToServer(String requestedServer, int instance, HttpServletRequest hrequest,
  94       HttpServletResponse hresponse) throws IOException, ServletException;
  95
  96   /**
  97    * Returns true if the specified server instance is a designated load balancing
  98    * server which will forward requests to an available instance.
  99    *
 100    * @param serverName The server name
 101    * @param instance The server instance which can be -1.
 102    */
 103   boolean isServerLoadBalancingServer(String serverName, int instance);
 104
 105   /**
 106    * Returns true if internally generated "/_ah/start" requests are provided
 107    * for the specified server and instance.
 108    * <p>
 109    * Http "/_ah/start" requests for such instances where this returns true are presumed to be
 110    * internally generated and receive special treatment by {@link DevAppServerServersFilter}.
 111    * Requests to "/_ah/start" for other instances are treated as normal requests.
 112    *
 113    * @param serverName The server name
 114    * @param instance The server instance which can be -1.
 115    */
 116   boolean expectsGeneratedStartRequests(String serverName, int instance);
 117 }