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.apphosting.utils.config.AppEngineWebXml;
   6 import com.google.apphosting.utils.config.BackendsXml;
   7
   8 import java.io.File;
   9 import java.util.Map;
  10
  11 /**
  12  * Provides the backing servlet container support for the {@link DevAppServer},
  13  * as discovered via {@link ServiceProvider}.
  14  * <p>
  15  * More specifically, this interface encapsulates the interactions between the
  16  * {@link DevAppServer} and the underlying servlet container, which by default
  17  * uses Jetty.
  18  *
  19  */
  20 public interface ContainerService {
  21
  22   /**
  23    * The severity with which we'll treat environment variable mismatches.
  24    */
  25   enum EnvironmentVariableMismatchSeverity {
  26     WARNING,
  27     ERROR,
  28     IGNORE
  29   }
  30
  31   /**
  32    * Sets up the necessary configuration parameters.
  33    *
  34    * @param devAppServerVersion Version of the devAppServer.
  35    * @param appDir The location of the application to run.
  36    * @param externalResourceDir If not {@code null}, a resource directory external to the appDir.
  37    *        This will be searched before appDir when looking for resources.
  38    * @param webXmlLocation The location of a file whose format complies with
  39    * http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd.  If null we will use
  40    * <appDir>/WEB-INF/web.xml.
  41    * @param appEngineWebXmlLocation The location of the app engine config file.
  42    * If null we will use <appDir>/WEB-INF/appengine-web.xml.
  43    * @param address The address on which the server will run
  44    * @param port The port to which the server will be bound.  If 0, an
  45    * available port will be selected.
  46    * @param containerConfigProperties Additional properties used in the
  47    * configuration of the specific container implementation.  This map travels
  48    * across classloader boundaries, so all values in the map must be JRE
  49    * classes.
  50    *
  51    * @return A LocalServerEnvironment describing the environment in which
  52    * the server is running.
  53    */
  54   LocalServerEnvironment configure(String devAppServerVersion, File appDir,
  55       File externalResourceDir, File webXmlLocation, File appEngineWebXmlLocation,
  56       String address, int port, Map<String, Object> containerConfigProperties,
  57       DevAppServer devAppServer);
  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   BackendsXml getBackendsXml();
 102
 103   /**
 104    * Overrides the default EnvironmentVariableMismatchSeverity setting, to
 105    * disable exceptions during the testing.
 106    *
 107    * @param val The new EnvironmentVariableMismatchSeverity.
 108    * @see EnvironmentVariableMismatchSeverity
 109    */
 110   void setEnvironmentVariableMismatchSeverity(EnvironmentVariableMismatchSeverity val);
 111
 112   /**
 113    * Get a set of properties to be passed to each service, based on the
 114    * AppEngineWebXml configuration.
 115    *
 116    * @return the map of properties to be passed to each service.
 117    */
 118   Map<String, String> getServiceProperties();
 119 }