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

   1 // Copyright 2008 Google Inc. All Rights Reserved.
   2
   3 package com.google.appengine.tools.development;
   4
   5 import com.google.appengine.tools.development.ApplicationConfigurationManager.ServerConfigurationHandle;
   6 import com.google.apphosting.utils.config.AppEngineWebXml;
   7
   8 import java.io.File;
   9 import java.io.IOException;
  10 import java.util.Map;
  11
  12 import javax.servlet.ServletException;
  13 import javax.servlet.http.HttpServletRequest;
  14 import javax.servlet.http.HttpServletResponse;
  15
  16 /**
  17  * Provides the backing servlet container support for the {@link DevAppServer},
  18  * as discovered via {@link ServiceProvider}.
  19  * <p>
  20  * More specifically, this interface encapsulates the interactions between the
  21  * {@link DevAppServer} and the underlying servlet container, which by default
  22  * uses Jetty.
  23  *
  24  */
  25 interface ContainerService {
  26
  27   /**
  28    * Sets up the necessary configuration parameters.
  29    *
  30    * @param devAppServerVersion Version of the devAppServer.
  31    * @param address The address on which the server will run
  32    * @param port The port to which the server will be bound.  If 0, an
  33    *        available port will be selected.
  34    * @param serverConfigurationHandle Handle to access and reread the configuration.
  35    * @param externalResourceDirectory If not {@code null}, a resource directory external
  36    *        to the applicationDirectory. This will be searched before
  37    *        applicationDirectory when looking for resources.
  38    * @param instance the 0 based instance number for this container's instance or
  39    *        {@link LocalEnvironment#MAIN_INSTANCE}.
  40    * @param containerConfigProperties Additional properties used in the
  41    *        configuration of the specific container implementation.  This map travels
  42    *        across classloader boundaries, so all values in the map must be JRE
  43    *        classes.
  44    *
  45    * @return A LocalServerEnvironment describing the environment in which
  46    * the server is running.
  47    */
  48   LocalServerEnvironment configure(String devAppServerVersion, String address, int port,
  49       ServerConfigurationHandle serverConfigurationHandle, File externalResourceDirectory,
  50       Map<String, Object> containerConfigProperties, int instance, DevAppServer devAppServer);
  51
  52   /**
  53    * Create's this containers network connections. After this returns
  54    * {@link #getAddress}, {@link #getPort} and {@link getHostName} return
  55    * correct values for this container.
  56    */
  57   void createConnection() throws Exception;
  58
  59   /**
  60    * Starts up the servlet container.
  61    *
  62    * @throws Exception Any exception from the container will be rethrown as is.
  63    */
  64   void startup() throws Exception;
  65
  66   /**
  67    * Shuts down the servlet container.
  68    *
  69    * @throws Exception Any exception from the container will be rethrown as is.
  70    */
  71   void shutdown() throws Exception;
  72
  73   /**
  74    * Returns the listener network address, however it's decided during
  75    * the servlet container deployment.
  76    */
  77   String getAddress();
  78
  79   /**
  80    * Returns the listener port number, however it's decided during the servlet
  81    * container deployment.
  82    */
  83   int getPort();
  84
  85   /**
  86    * Returns the host name of the server, however it's decided during the
  87    * the servlet container deployment.
  88    */
  89   String getHostName();
  90
  91   /**
  92    * Returns the context representing the currently executing webapp.
  93    */
  94   AppContext getAppContext();
  95
  96   /**
  97    * Return the AppEngineWebXml configuration of this container
  98    */
  99   AppEngineWebXml getAppEngineWebXmlConfig();
 100
 101   /**
 102    * Get a set of properties to be passed to each service, based on the
 103    * AppEngineWebXml configuration.
 104    *
 105    * @return the map of properties to be passed to each service.
 106    */
 107   Map<String, String> getServiceProperties();
 108
 109   /**
 110    * Forwards an HttpRequest request to this container.
 111    */
 112   void forwardToServer(HttpServletRequest hrequest, HttpServletResponse hresponse)
 113       throws IOException, ServletException;
 114
 115 }