/*   
 *  Copyright 1999-2004 The Apache Sofware Foundation.
 *
 *  Licensed under the Apache License, Version 2.0 (the "License");
 *  you may not use this file except in compliance with the License.
 *  You may obtain a copy of the License at
 *
 *      http://www.apache.org/licenses/LICENSE-2.0
 *
 *  Unless required by applicable law or agreed to in writing, software
 *  distributed under the License is distributed on an "AS IS" BASIS,
 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 *  See the License for the specific language governing permissions and
 *  limitations under the License.
 */

package org.apache.tomcat.core;

import org.apache.tomcat.util.log.Log;

import java.util.Hashtable;
import java.util.Vector;
import java.util.Enumeration;


/**
  ContextManager controls requests processing and server configuration.
  It maintains a list of Contexts ( web applications )  and a list of
  global modules that deal with server configuration and request processing,
  and global properties ( directories, general settings, etc ).

  The request processing is similar with Apache and other servers, with the
  addition of a "contextMap" chain that will select a tomcat-specific.
 
  
Configuration and startup

  Starting tomcat involves a number of actions and states. In order to
  start tomcat:
  
  

  
 Create ContextManager. The server state is STATE_NEW

  
 Set properties for ContextManager ( home, debug, etc).

  
 Add the initial set of modules ( addInterceptor() ). ContextManager
       will call setContextManager() and then the addInterceptor() hook.

  
 Add the initial set of web applications ( Contexts ). Configuration
       modules can also add web applications - but no "addContext" hook
       will be called ( since the server is not initialized ).

  
 Call init().
       

         
Init will notify all modules using the engineInit() hook. At
	 this point the ContextManager will be in STATE_CONFIG.
	 
It'll then call addContext() hooks for each context that were
	 added by config modules. Contexts will be in STATE_ADDED.
	 
It'll then call context.init() hooks for each context that were
	 added by config modules. Contexts will be in STATE_READY.
	 
After all contexts are added and initialized, server will be
	 in STATE_INIT.
       
  XXX Do we need finer control ? ( like initModules(), initContexts() ? )
       
  
 At this point the server is fully configured, but not started.
       The user can add/remove modules and applications - the rules are
       defined in "run-time configuration".

  
 Call start(). The engineStart() hook will be called,
  the connector modules should accept and serve requests. 

  
 Call stop() to stop the server ( engineStop() hook will be called,
  no requests more will be accepted )

  
 Call shutdown() to clean up all resources in use by web applications
  and modules. The server will revert to STATE_CONFIG.
       

         
contextShutdown() will be called for each application. Modules
	 must clean any resources allocated for that context. 

	 
removeContext() will be called for each application.

	 
engineShutdown() will be called for each module
       

  


  
Runtime configuration

  XXX The only "supported" feature is adding/removing web applications.
  Since each module can have a set of local modules, you can change the
  configuration or modules for each context. Changing "global" modules may
  work, but it's not finalized or tested.
  
  While tomcat is running, you can temporarily disable web applications,
  remove and add new applications.
  
  @author James Duncan Davidson [duncan@eng.sun.com]
  @author James Todd [gonzo@eng.sun.com]
  @author Harish Prabandham
  @author Costin Manolache
  @author Hans Bergsten [hans@gefionsoftware.com]
 */
public class ContextManager {
    /** Official name and version
     */
    public static final String TOMCAT_VERSION = "3.3.2 Final";
    public static final String TOMCAT_NAME = "Tomcat Web Server";
    
    /** System property used to set the base directory ( tomcat home ).
     *  use -DTOMCAT_HOME= in java command line or as a System.setProperty.
     */
    public static final String TOMCAT_HOME="tomcat.home";

    /** System property used to set the install directory ( tomcat install ).
     *  use -DTOMCAT_INSTALL= in java command line or as a System.setProperty.
     */
    public static final String TOMCAT_INSTALL="tomcat.install";

    // State

    /**
     *  Server is beeing configured - modules are added.
     */
    public static final int STATE_NEW=0;

    /**
     *  Server and global modules are initialized and stable.
     */
    public static final int STATE_CONFIG=1;

    /**
     *  Web applications are  configured and initialized.
     */
    public static final int STATE_INIT=2;
 
    /**
     *  Server is started and may process requests.
     */
    public static final int STATE_START=3;

    // -------------------- local variables --------------------

    private int state=STATE_NEW;
    
    // All contexts managed by the server ( can belong to different
    // virtual hosts )
    private Vector contextsV=new Vector();
    private Hashtable contexts=new Hashtable();

    private int debug=0;

    /** Private workspace for this server
     */
    private String workDir="work";

    /** The base directory where this instance runs.
     *  It can be different from the install directory to
     *  allow one install per system and multiple users
     */
    private String home;

    /** The directory where tomcat is installed
     */
    private String installDir;
    
    // Server properties ( interceptors, etc ) - it's one level above "/"
    private Container defaultContainer;

    // the embedding application loader. @see getParentLoader
    private ClassLoader parentLoader;

    // the common class loader, shared by container and apps
    private ClassLoader commonLoader;

    // the container class loader, used to load all container modules
    private ClassLoader containerLoader;

    // the webapp loader, with classes shared by all webapps.
    private ClassLoader appsLoader;

    private Hashtable properties=new Hashtable();
    
    /**
     * Construct a new ContextManager instance with default values.
     */
    public ContextManager() {
        defaultContainer=createContainer();
        defaultContainer.setContext( null );
	defaultContainer.setContextManager( this );
        defaultContainer.setPath( null ); // default container
    }

    // -------------------- setable properties --------------------

    /**
     *  The home of the tomcat instance - you can have multiple
     *  users running tomcat, with a shared install directory.
     *  
     *  Home is used as a base for logs, webapps, local config.
     *  Install dir ( if different ) is used to find lib ( jar
     *   files ).
     *
     *  The "tomcat.home" system property is used if no explicit
     *  value is set. XXX
     */
    public void setHome(String home) {
	this.home=home;
	if( home != null ) 
	    System.getProperties().put(TOMCAT_HOME, home );
    }

    public String getHome() {
	return home;
    }

    /**
     *  Get installation directory. This is used to locate
     *  jar files ( lib ). If tomcat instance is shared,
     *  home is used for webapps, logs, config.
     *  If either home or install is not set, the other
     *  is used as default.
     * 
     */
    public String getInstallDir() {
	return installDir;
    }

    public void setInstallDir( String tH ) {
	installDir=tH;
    }

    /**
     * WorkDir property - where all working files will be created
     */
    public void setWorkDir( String wd ) {
	if(debug>0) log("set work dir " + wd);
	this.workDir=wd;
    }

    public String getWorkDir() {
	return workDir;
    }


    /** Debug level
     */
    public void setDebug( int level ) {
	if( level != debug )
	    log( "Setting debug level to " + level);
	debug=level;
    }

    public final int getDebug() {
	return debug;
    }

    //  XmlMapper will call setProperty(name,value) if no explicit setter
    // is found - it's better to use this mechanism for special
    // properties ( that are not generic enough and used by few specific
    // module )

    /** Generic properties support. You can get properties like
     *  "showDebugInfo", "randomClass", etc.
     */
    public String getProperty( String name ) {
	return (String)properties.get( name );
    }

    public void setProperty( String name, String value ) {
	if( name!=null && value!=null )
	    properties.put( name, value );
    }

    public Hashtable getProperties() {
	return properties;
    }
    
    // -------------------- Other properties --------------------

    /** Return the current state of the tomcat server.
     */
    public final int getState() {
	return state;
    }

    /** Change the state, after notifying all modules about the change
     *  Any error will be propagated - the server will not change the
     *  state and should fail if any module can't handle that.
     */
    public void setState( int state )
	throws TomcatException
    {
	BaseInterceptor existingI[]=defaultContainer.getInterceptors();
	for( int i=0; i
     *  parentLoader  -> tomcat.core.loader [ -> trusted.webapp.loader ]
     *                -> webapp.loaders
     *