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
  58   /**
  59    * Starts up the servlet container.
  60    *
  61    * @throws Exception Any exception from the container will be rethrown as is.
  62    */
  63   void startup() throws Exception;
  64
  65   /**
  66    * Shuts down the servlet container.
  67    *
  68    * @throws Exception Any exception from the container will be rethrown as is.
  69    */
  70   void shutdown() throws Exception;
  71
  72   /**
  73    * Returns the listener network address, however it's decided during
  74    * the servlet container deployment.
  75    */
  76   String getAddress();
  77
  78   /**
  79    * Returns the listener port number, however it's decided during the servlet
  80    * container deployment.
  81    */
  82   int getPort();
  83
  84   /**
  85    * Returns the host name of the server, however it's decided during the
  86    * the servlet container deployment.
  87    */
  88   String getHostName();
  89
  90   /**
  91    * Returns the context representing the currently executing webapp.
  92    */
  93   AppContext getAppContext();
  94
  95   /**
  96    * Return the AppEngineWebXml configuration of this container
  97    */
  98   AppEngineWebXml getAppEngineWebXmlConfig();
  99
 100   BackendsXml getBackendsXml();
 101
 102   /**
 103    * Overrides the default EnvironmentVariableMismatchSeverity setting, to
 104    * disable exceptions during the testing.
 105    *
 106    * @param val The new EnvironmentVariableMismatchSeverity.
 107    * @see EnvironmentVariableMismatchSeverity
 108    */
 109   void setEnvironmentVariableMismatchSeverity(EnvironmentVariableMismatchSeverity val);
 110
 111   /**
 112    * Get a set of properties to be passed to each service, based on the
 113    * AppEngineWebXml configuration.
 114    *
 115    * @return the map of properties to be passed to each service.
 116    */
 117   Map<String, String> getServiceProperties();
 118 }