1 package com
.google
.appengine
.tools
.development
;
3 import java
.io
.IOException
;
5 import javax
.servlet
.ServletException
;
6 import javax
.servlet
.http
.HttpServletRequest
;
7 import javax
.servlet
.http
.HttpServletResponse
;
10 * Support interface for {@link DevAppServerModulesFilter}.
12 public interface ModulesFilterHelper
{
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.
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
26 boolean acquireServingPermit(String moduleOrBackendName
, int instanceNumber
,
27 boolean allowQueueOnBackends
);
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.
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).
36 * Supported for modules that support load balancing (currently {@link ManualModule}).
37 * The client can check with {@link #isLoadBalancingInstance(String, int)}.
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.
43 int getAndReserveFreeInstance(String requestedModuleOrBackendname
);
46 * Returns a serving permit after a request has completed.
48 * @param moduleOrBackendName The server name
49 * @param instance The server instance
51 public void returnServingPermit(String moduleOrBackendName
, int instance
);
54 * Verifies if a specific module instance is configured.
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.
60 boolean checkInstanceExists(String moduleOrBackendName
, int instance
);
63 * Verifies if a specific module or backend is configured.
65 * @param moduleOrBackendName The module or backend name
66 * @return true if the module is configured and false otherwise.
68 boolean checkModuleExists(String moduleOrBackendName
);
71 * Verifies if a specific existing module or backend is stopped.
73 * @param moduleOrBackendName The module or backend name
74 * @return true if the module is stopped, false otherwise.
76 boolean checkModuleStopped(String moduleOrBackendName
);
79 * Verifies if a specific existing module or backend instance is stopped.
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.
85 boolean checkInstanceStopped(String moduleOrBackendName
, int instance
);
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.
93 void forwardToInstance(String requestedModuleOrBackendName
, int instance
,
94 HttpServletRequest hrequest
, HttpServletResponse hresponse
)
95 throws IOException
, ServletException
;
98 * Returns true if the specified module or backend instance is a load balancing
99 * instance which will forward requests to an available instance.
101 * @param moduleOrBackendName The module or backend name
102 * @param instance The requested instance which can be -1.
104 boolean isLoadBalancingInstance(String moduleOrBackendName
, int instance
);
107 * Returns true if internally generated "/_ah/start" requests are provided
108 * for the specified module or backend instance.
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.
114 * @param moduleOrBackendName The module or backend name
115 * @param instance The module instance which can be -1.
117 boolean expectsGeneratedStartRequests(String moduleOrBackendName
, int instance
);
120 * Returns the port for the specified module of backend instance.
122 * @param moduleOrBackendName The module or backend name
123 * @param instance The requested instance which can be -1.
125 int getPort(String moduleOrBackendName
, int instance
);