org.apache.tomcat.core
Class ContextManager

java.lang.Object
  |
  +--org.apache.tomcat.core.ContextManager

public class ContextManager
extends java.lang.Object

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:
  1. Create ContextManager. The server state is STATE_NEW
  2. Set properties for ContextManager ( home, debug, etc).
  3. Add the initial set of modules ( addInterceptor() ). ContextManager will call setContextManager() and then the addInterceptor() hook.
  4. 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 ).
  5. Call init().
    1. Init will notify all modules using the engineInit() hook. At this point the ContextManager will be in STATE_CONFIG.
    2. It'll then call addContext() hooks for each context that were added by config modules. Contexts will be in STATE_ADDED.
    3. It'll then call context.init() hooks for each context that were added by config modules. Contexts will be in STATE_READY.
    4. After all contexts are added and initialized, server will be in STATE_INIT.
    XXX Do we need finer control ? ( like initModules(), initContexts() ? )
  6. 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".
  7. Call start(). The engineStart() hook will be called, the connector modules should accept and serve requests.
  8. Call stop() to stop the server ( engineStop() hook will be called, no requests more will be accepted )
  9. Call shutdown() to clean up all resources in use by web applications and modules. The server will revert to STATE_CONFIG.
    1. contextShutdown() will be called for each application. Modules must clean any resources allocated for that context.
    2. removeContext() will be called for each application.
    3. 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], James Todd [gonzo@eng.sun.com], Harish Prabandham, Costin Manolache, Hans Bergsten [hans@gefionsoftware.com]

Field Summary
static int CONTAINER_NOTE
           
static int HANDLER_NOTE
           
static int MAX_NOTES
          Maximum number of notes supported
static int MODULE_NOTE
           
static int NOTE_COUNT
          Note id counters.
static int REQ_RE_NOTE
           
static int REQUEST_NOTE
           
static int RESERVED
           
static int SERVER_NOTE
           
static int SESSION_NOTE
           
static int STATE_CONFIG
          Server and global modules are initialized and stable.
static int STATE_INIT
          Web applications are configured and initialized.
static int STATE_NEW
          Server is beeing configured - modules are added.
static int STATE_START
          Server is started and may process requests.
static java.lang.String TOMCAT_HOME
          System property used to set the base directory ( tomcat home ).
static java.lang.String TOMCAT_INSTALL
          System property used to set the install directory ( tomcat install ).
static java.lang.String TOMCAT_NAME
           
static java.lang.String TOMCAT_VERSION
          Official name and version
 
Constructor Summary
ContextManager()
          Construct a new ContextManager instance with default values.
 
Method Summary
 void addContext(Context ctx)
          Adds a new Context to the set managed by this ContextManager.
 void addInterceptor(BaseInterceptor ri)
          Add a global interceptor.
 Container createContainer()
           
 Context createContext()
           
 OutputBuffer createOutputBuffer()
           
 OutputBuffer createOutputBuffer(int size)
           
 Request createRequest()
           
 Request createRequest(Context ctx, java.lang.String urlPath)
          Create a new sub-request in a given context, set the context "hint" This is a particular case of sub-request that can't get out of a context ( and we know the context before - so no need to compute it again) Note that session and all stuff will still be computed.
 Response createResponse(Request req)
           
 ServerSession createServerSession()
           
 java.lang.ClassLoader getAppsLoader()
           
 java.lang.ClassLoader getCommonLoader()
           
 Container getContainer()
          Default container.
 java.lang.ClassLoader getContainerLoader()
           
 Context getContext(Context base, java.lang.String path)
          Find a context by doing a sub-request and mapping the request against the active rules ( that means you could use a /~costin if a UserHomeInterceptor is present ) The new context will be in the same virtual host as base.
 Context getContext(java.lang.String name)
           
 java.util.Enumeration getContextNames()
           
 java.util.Enumeration getContexts()
          Return the list of contexts managed by this server.
 int getDebug()
           
 java.lang.String getHome()
           
 java.lang.String getInstallDir()
          Get installation directory.
 Log getLog()
          So other classes can piggyback on the context manager's log stream.
 java.lang.Object getNote(int pos)
           
 java.lang.Object getNote(java.lang.String name)
           
 int getNoteId(int noteType, java.lang.String name)
          Create a new note id.
 java.lang.String getNoteName(int noteType, int noteId)
           
 java.lang.ClassLoader getParentLoader()
           
 java.util.Hashtable getProperties()
           
 java.lang.String getProperty(java.lang.String name)
          Generic properties support.
 int getState()
          Return the current state of the tomcat server.
 java.lang.String getWorkDir()
           
 void handleError(Request req, Response res, java.lang.Throwable t)
          Call error hook with an exception code.
 void handleStatus(Request req, Response res, int code)
          Called for error-codes.
 void init()
          Init() is called after the context manager is set up (properties) and configured ( modules ).
 void initRequest(Request req, Response resp)
          Prepare the req/resp pair for use in tomcat.
 void log(java.lang.String msg)
           
 void log(java.lang.String msg, int level)
           
 void log(java.lang.String msg, java.lang.Throwable t)
           
 void log(java.lang.String msg, java.lang.Throwable t, int level)
           
 int processRequest(Request req)
          Will find the Handler for a servlet, assuming we already have the Context.
 void removeContext(Context context)
          Shut down and removes a context from service.
 void removeInterceptor(BaseInterceptor ri)
          Remove a module.
 void service(Request req, Response res)
          This is the entry point in tomcat - the connectors ( or any other component able to generate Request/Response implementations ) will call this method to get it processed.
 void setAppsLoader(java.lang.ClassLoader cl)
           
 void setCommonLoader(java.lang.ClassLoader cl)
           
 void setContainer(Container newDefaultContainer)
           
 void setContainerLoader(java.lang.ClassLoader cl)
           
 void setDebug(int level)
          Debug level
 void setHome(java.lang.String home)
          The home of the tomcat instance - you can have multiple users running tomcat, with a shared install directory.
 void setInstallDir(java.lang.String tH)
           
 void setLog(Log log)
           
 void setNote(int pos, java.lang.Object value)
           
 void setNote(java.lang.String name, java.lang.Object value)
           
 void setParentLoader(java.lang.ClassLoader cl)
          Parent loader is the "base" class loader of the application that starts tomcat, and includes no tomcat classes.
 void setProperty(java.lang.String name, java.lang.String value)
           
 void setState(int 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.
protected  void setState1(int state)
           
 void setWorkDir(java.lang.String wd)
          WorkDir property - where all working files will be created
 void shutdown()
          Remove all contexts.
 void start()
          Will start the connectors and begin serving requests.
 void stop()
          Will stop all connectors
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

TOMCAT_VERSION

public static final java.lang.String TOMCAT_VERSION
Official name and version

TOMCAT_NAME

public static final java.lang.String TOMCAT_NAME

TOMCAT_HOME

public static final java.lang.String TOMCAT_HOME
System property used to set the base directory ( tomcat home ). use -DTOMCAT_HOME= in java command line or as a System.setProperty.

TOMCAT_INSTALL

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

STATE_NEW

public static final int STATE_NEW
Server is beeing configured - modules are added.

STATE_CONFIG

public static final int STATE_CONFIG
Server and global modules are initialized and stable.

STATE_INIT

public static final int STATE_INIT
Web applications are configured and initialized.

STATE_START

public static final int STATE_START
Server is started and may process requests.

NOTE_COUNT

public static final int NOTE_COUNT
Note id counters. Synchronized access is not necesarily needed ( the initialization is in one thread ), but anyway we do it

MAX_NOTES

public static final int MAX_NOTES
Maximum number of notes supported

RESERVED

public static final int RESERVED

SERVER_NOTE

public static final int SERVER_NOTE

CONTAINER_NOTE

public static final int CONTAINER_NOTE

REQUEST_NOTE

public static final int REQUEST_NOTE

HANDLER_NOTE

public static final int HANDLER_NOTE

SESSION_NOTE

public static final int SESSION_NOTE

MODULE_NOTE

public static final int MODULE_NOTE

REQ_RE_NOTE

public static final int REQ_RE_NOTE
Constructor Detail

ContextManager

public ContextManager()
Construct a new ContextManager instance with default values.
Method Detail

setHome

public void setHome(java.lang.String home)
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

getHome

public java.lang.String getHome()

getInstallDir

public java.lang.String getInstallDir()
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.

setInstallDir

public void setInstallDir(java.lang.String tH)

setWorkDir

public void setWorkDir(java.lang.String wd)
WorkDir property - where all working files will be created

getWorkDir

public java.lang.String getWorkDir()

setDebug

public void setDebug(int level)
Debug level

getDebug

public final int getDebug()

getProperty

public java.lang.String getProperty(java.lang.String name)
Generic properties support. You can get properties like "showDebugInfo", "randomClass", etc.

setProperty

public void setProperty(java.lang.String name,
                        java.lang.String value)

getProperties

public java.util.Hashtable getProperties()

getState

public final int getState()
Return the current state of the tomcat server.

setState

public void setState(int state)
              throws TomcatException
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.

setState1

protected void setState1(int state)

setParentLoader

public void setParentLoader(java.lang.ClassLoader cl)
Parent loader is the "base" class loader of the application that starts tomcat, and includes no tomcat classes. Each web applications will use a loader that will have it as a parent loader, so all classes visible to parentLoader will be available to servlets. Tomcat will add the right servlet.jar and Facade. Trusted applications will also see the internal tomcat classes. Interceptors may also add custom classes to a webapp, based on tomcat configuration. Tomcat.core and all internal classes will be loaded by another class loader, having the same parentLoader.
  parentLoader  -> tomcat.core.loader [ -> trusted.webapp.loader ]
                -> webapp.loaders
  

getParentLoader

public java.lang.ClassLoader getParentLoader()

setCommonLoader

public void setCommonLoader(java.lang.ClassLoader cl)

getCommonLoader

public java.lang.ClassLoader getCommonLoader()

setContainerLoader

public void setContainerLoader(java.lang.ClassLoader cl)

getContainerLoader

public java.lang.ClassLoader getContainerLoader()

setAppsLoader

public void setAppsLoader(java.lang.ClassLoader cl)

getAppsLoader

public java.lang.ClassLoader getAppsLoader()

getContainer

public Container getContainer()
Default container. The interceptors for this container will be called for all requests, and it will be associated with invalid requests ( where context can't be found ).

setContainer

public void setContainer(Container newDefaultContainer)

addInterceptor

public void addInterceptor(BaseInterceptor ri)
                    throws TomcatException
Add a global interceptor. The addInterceptor() hook will be called. If the module is added after STATE_CONFIG, the engineInit() hook will be called ( otherwise we wait for init() ). If the module is added after STATE_INIT, the addContext and initContext hooks will be called. If the module is added after STATE_START, the engineStart hooks will be called.

removeInterceptor

public void removeInterceptor(BaseInterceptor ri)
                       throws TomcatException
Remove a module. Hooks will be called to allow the module to free the resources.

init

public void init()
          throws TomcatException
Init() is called after the context manager is set up (properties) and configured ( modules ). All engineInit() hooks will be called and the server will move to state= INIT

start

public void start()
           throws TomcatException
Will start the connectors and begin serving requests. It must be called after init.

stop

public void stop()
          throws TomcatException
Will stop all connectors

shutdown

public void shutdown()
              throws TomcatException
Remove all contexts. - call removeContext ( that will call Interceptor.removeContext hooks ) - call Interceptor.engineShutdown() hooks.

getContexts

public java.util.Enumeration getContexts()
Return the list of contexts managed by this server. Tomcat can handle multiple virtual hosts. All contexts are stored in ContextManager when added. Modules can use the information in context ( when addContext hook is called ) and prepare mapping tables.

getContextNames

public java.util.Enumeration getContextNames()

getContext

public Context getContext(java.lang.String name)

addContext

public void addContext(Context ctx)
                throws TomcatException
Adds a new Context to the set managed by this ContextManager. It'll also init the server if it hasn't been already. All addContext hooks will be called. The context will be in STATE_ADDED - it'll not serve requests.
Parameters:
ctx - context to be added.

removeContext

public void removeContext(Context context)
                   throws TomcatException
Shut down and removes a context from service.

initRequest

public void initRequest(Request req,
                        Response resp)
Prepare the req/resp pair for use in tomcat. Call it after you create the request/response objects. ( for example in a connector, or when an internal sub-request is created )

service

public void service(Request req,
                    Response res)
This is the entry point in tomcat - the connectors ( or any other component able to generate Request/Response implementations ) will call this method to get it processed.

processRequest

public int processRequest(Request req)
Will find the Handler for a servlet, assuming we already have the Context. This is also used by Dispatcher and getResource - where the Context is already known. This method will only map the request, it'll not do authorization or authentication.

createRequest

public Request createRequest(Context ctx,
                             java.lang.String urlPath)
Create a new sub-request in a given context, set the context "hint" This is a particular case of sub-request that can't get out of a context ( and we know the context before - so no need to compute it again) Note that session and all stuff will still be computed.

getContext

public Context getContext(Context base,
                          java.lang.String path)
Find a context by doing a sub-request and mapping the request against the active rules ( that means you could use a /~costin if a UserHomeInterceptor is present ) The new context will be in the same virtual host as base.

handleStatus

public void handleStatus(Request req,
                         Response res,
                         int code)
Called for error-codes. Will call the error hook with a status code.

handleError

public void handleError(Request req,
                        Response res,
                        java.lang.Throwable t)
Call error hook with an exception code.

getNoteId

public int getNoteId(int noteType,
                     java.lang.String name)
              throws TomcatException
Create a new note id. Interceptors will get an Id at init time for all notes that it needs. Throws exception if too many notes are set ( shouldn't happen in normal use ).
Parameters:
noteType - The note will be associated with the server, container or request.
name - the name of the note.

getNoteName

public java.lang.String getNoteName(int noteType,
                                    int noteId)

setNote

public final void setNote(int pos,
                          java.lang.Object value)

getNote

public final java.lang.Object getNote(int pos)

getNote

public java.lang.Object getNote(java.lang.String name)
                         throws TomcatException

setNote

public void setNote(java.lang.String name,
                    java.lang.Object value)
             throws TomcatException

getLog

public Log getLog()
So other classes can piggyback on the context manager's log stream.

setLog

public void setLog(Log log)

log

public void log(java.lang.String msg)

log

public void log(java.lang.String msg,
                java.lang.Throwable t)

log

public void log(java.lang.String msg,
                int level)

log

public void log(java.lang.String msg,
                java.lang.Throwable t,
                int level)

createContext

public Context createContext()

createRequest

public Request createRequest()

createResponse

public Response createResponse(Request req)

createContainer

public Container createContainer()

createOutputBuffer

public OutputBuffer createOutputBuffer()

createOutputBuffer

public OutputBuffer createOutputBuffer(int size)

createServerSession

public ServerSession createServerSession()


Copyright © 2001 Apache Software Foundation. All Rights Reserved.