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.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 interface ContainerService {
  21
  22   /**
  23    * Sets up the necessary configuration parameters.
  24    *
  25    * @param devAppServerVersion Version of the devAppServer.
  26    * @param address The address on which the server will run
  27    * @param port The port to which the server will be bound.  If 0, an
  28    *        available port will be selected.
  29    * @param serverConfigurationHandle Handle to access and reread the configuration.
  30    * @param externalResourceDirectory If not {@code null}, a resource directory external
  31    *        to the applicationDirectory. This will be searched before
  32    *        applicationDirectory when looking for resources.
  33    * @param instance the 0 based instance number for this container's instance or
  34    *        {@link LocalEnvironment#MAIN_INSTANCE}.
  35    * @param containerConfigProperties Additional properties used in the
  36    *        configuration of the specific container implementation.  This map travels
  37    *        across classloader boundaries, so all values in the map must be JRE
  38    *        classes.
  39    *
  40    * @return A LocalServerEnvironment describing the environment in which
  41    * the server is running.
  42    */
  43   LocalServerEnvironment configure(String devAppServerVersion, String address, int port,
  44       ServerConfigurationHandle serverConfigurationHandle, File externalResourceDirectory,
  45       Map<String, Object> containerConfigProperties, int instance, DevAppServer devAppServer);
  46
  47   /**
  48    * Create's this containers network connections. After this returns
  49    * {@link #getAddress}, {@link #getPort} and {@link getHostName} return
  50    * correct values for this container.
  51    */
  52   void createConnection() throws Exception;
  53
  54   /**
  55    * Starts up the servlet container.
  56    *
  57    * @throws Exception Any exception from the container will be rethrown as is.
  58    */
  59   void startup() throws Exception;
  60
  61   /**
  62    * Shuts down the servlet container.
  63    *
  64    * @throws Exception Any exception from the container will be rethrown as is.
  65    */
  66   void shutdown() throws Exception;
  67
  68   /**
  69    * Returns the listener network address, however it's decided during
  70    * the servlet container deployment.
  71    */
  72   String getAddress();
  73
  74   /**
  75    * Returns the listener port number, however it's decided during the servlet
  76    * container deployment.
  77    */
  78   int getPort();
  79
  80   /**
  81    * Returns the host name of the server, however it's decided during the
  82    * the servlet container deployment.
  83    */
  84   String getHostName();
  85
  86   /**
  87    * Returns the context representing the currently executing webapp.
  88    */
  89   AppContext getAppContext();
  90
  91   /**
  92    * Return the AppEngineWebXml configuration of this container
  93    */
  94   AppEngineWebXml getAppEngineWebXmlConfig();
  95
  96   /**
  97    * Get a set of properties to be passed to each service, based on the
  98    * AppEngineWebXml configuration.
  99    *
 100    * @return the map of properties to be passed to each service.
 101    */
 102   Map<String, String> getServiceProperties();
 103 }