java/src/main/com/google/appengine/tools/development/ModulesFilterHelper.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 DevAppServerModulesFilter}.
  11  */
  12 public interface ModulesFilterHelper {
  13   /**
  14    * This method guards access to module instances to limit the number of concurrent
  15    * requests. Each request running on a module instance must acquire a serving permit.
  16    * If no permits are available a 500 response should be sent.
  17    *
  18    * @param moduleOrBackendName The module or backend 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 moduleOrBackendName, int instanceNumber,
  27       boolean allowQueueOnBackends);
  28   /**
  29    * Acquires a serving permit for an instance with available capacity and returns the
  30    * instance 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 modules that support load balancing (currently {@link ManualModule}).
  37    * The client can check with {@link #isLoadBalancingInstance(String, int)}.
  38    *
  39    * @param requestedModuleOrBackendname Name of the requested module or backend.
  40    * @return the instance id of an available server instance, or -1 if no
  41    *         instance is available.
  42    */
  43   int getAndReserveFreeInstance(String requestedModuleOrBackendname);
  44
  45   /**
  46    * Returns a serving permit after a request has completed.
  47    *
  48    * @param moduleOrBackendName The server name
  49    * @param instance The server instance
  50    */
  51   public void returnServingPermit(String moduleOrBackendName, int instance);
  52
  53   /**
  54    * Verifies if a specific module instance is configured.
  55    *
  56    * @param moduleOrBackendName The module or backend name
  57    * @param instance The module instance
  58    * @return true if the module instance is configured and false otherwise.
  59    */
  60   boolean checkInstanceExists(String moduleOrBackendName, int instance);
  61
  62   /**
  63    * Verifies if a specific module or backend is configured.
  64    *
  65    * @param moduleOrBackendName The module or backend name
  66    * @return true if the module is configured and false otherwise.
  67    */
  68   boolean checkModuleExists(String moduleOrBackendName);
  69
  70   /**
  71    * Verifies if a specific existing module or backend is stopped.
  72    *
  73    * @param moduleOrBackendName The module or backend name
  74    * @return true if the module is stopped, false otherwise.
  75    */
  76   boolean checkModuleStopped(String moduleOrBackendName);
  77
  78   /**
  79    * Verifies if a specific existing module or backend instance is stopped.
  80    *
  81    * @param moduleOrBackendName The module or backedn name
  82    * @param instance The module instance
  83    * @return true if the module instance is stopped and false otherwise.
  84    */
  85   boolean checkInstanceStopped(String moduleOrBackendName, int instance);
  86
  87   /**
  88    * Forward a request to a specified module or backend instance. Calls the
  89    * request dispatcher for the requested instance with the instance
  90    * context. The caller must hold a serving permit for the requested
  91    * instance before calling this method.
  92    */
  93   void forwardToInstance(String requestedModuleOrBackendName, int instance,
  94       HttpServletRequest hrequest, HttpServletResponse hresponse)
  95           throws IOException, ServletException;
  96
  97   /**
  98    * Returns true if the specified module or backend instance is a load balancing
  99    * instance which will forward requests to an available instance.
 100    *
 101    * @param moduleOrBackendName The module or backend name
 102    * @param instance The requested instance which can be -1.
 103    */
 104   boolean isLoadBalancingInstance(String moduleOrBackendName, int instance);
 105
 106   /**
 107    * Returns true if internally generated "/_ah/start" requests are provided
 108    * for the specified module or backend instance.
 109    * <p>
 110    * Http "/_ah/start" requests for instances where this returns true are presumed to be
 111    * internally generated and receive special treatment by {@link DevAppServerModulesFilter}.
 112    * Requests to "/_ah/start" for other instances are treated as normal requests.
 113    *
 114    * @param moduleOrBackendName The module or backend name
 115    * @param instance The module instance which can be -1.
 116    */
 117   boolean expectsGeneratedStartRequests(String moduleOrBackendName, int instance);
 118
 119   /**
 120    * Returns the port for the specified module of backend instance.
 121    *
 122    * @param moduleOrBackendName The module or backend name
 123    * @param instance The requested instance which can be -1.
 124    */
 125   int getPort(String moduleOrBackendName, int instance);
 126 }