Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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

  See Also:
    Constant Field Values

### TOMCAT_NAME

    public static final java.lang.String TOMCAT_NAME

See Also:
  Constant Field Values

### 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.

  See Also:
    Constant Field Values

### 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.

  See Also:
    Constant Field Values

### STATE_NEW

    public static final int STATE_NEW

  Server is beeing configured - modules are added.

  See Also:
    Constant Field Values

### STATE_CONFIG

    public static final int STATE_CONFIG

  Server and global modules are initialized and stable.

  See Also:
    Constant Field Values

### STATE_INIT

    public static final int STATE_INIT

  Web applications are configured and initialized.

  See Also:
    Constant Field Values

### STATE_START

    public static final int STATE_START

  Server is started and may process requests.

  See Also:
    Constant Field Values

### 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

  See Also:
    Constant Field Values

### MAX_NOTES

    public static final int MAX_NOTES

  Maximum number of notes supported

  See Also:
    Constant Field Values

### RESERVED

    public static final int RESERVED

See Also:
  Constant Field Values

### SERVER_NOTE

    public static final int SERVER_NOTE

See Also:
  Constant Field Values

### CONTAINER_NOTE

    public static final int CONTAINER_NOTE

See Also:
  Constant Field Values

### REQUEST_NOTE

    public static final int REQUEST_NOTE

See Also:
  Constant Field Values

### HANDLER_NOTE

    public static final int HANDLER_NOTE

See Also:
  Constant Field Values

### SESSION_NOTE

    public static final int SESSION_NOTE

See Also:
  Constant Field Values

### MODULE_NOTE

    public static final int MODULE_NOTE

See Also:
  Constant Field Values

### REQ_RE_NOTE

    public static final int REQ_RE_NOTE

See Also:
  Constant Field Values

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.

  Throws:
    `TomcatException`

### 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.

  Throws:
    `TomcatException`

### removeInterceptor

    public void removeInterceptor(BaseInterceptor ri)
                           throws TomcatException

  Remove a module. Hooks will be called to allow the module to free the resources.

  Throws:
    `TomcatException`

### 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

  Throws:
    `TomcatException`

### start

    public void start()
               throws TomcatException

  Will start the connectors and begin serving requests. It must be called after init.

  Throws:
    `TomcatException`

### stop

    public void stop()
              throws TomcatException

  Will stop all connectors

  Throws:
    `TomcatException`

### shutdown

    public void shutdown()
                  throws TomcatException

  Remove all contexts. - call removeContext ( that will call Interceptor.removeContext hooks ) - call Interceptor.engineShutdown() hooks.

  Throws:
    `TomcatException`

### 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.
  Throws:
    `TomcatException`

### removeContext

    public void removeContext(Context context)
                       throws TomcatException

  Shut down and removes a context from service.

  Throws:
    `TomcatException`

### 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.
  Throws:
    `TomcatException`

### 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

  Throws:
    `TomcatException`

### setNote

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

  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()

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2001 Apache Software Foundation. All Rights Reserved.