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.startup
Class EmbededTomcat

    java.lang.Object
      org.apache.tomcat.startup.EmbededTomcat

public class EmbededTomcat
extends java.lang.Object

Use this class to embed tomcat in your application. If all you want is to start/stop tomcat, with minimal customization, you can use Main.main() This class is designed as a java bean, where you set different properties, then call methods to perform actions. The main method is "execute", that will start tomcat. Few other methods allow to perform different other tasks. EmbededTomcat is usable as an "ant" task as well, using the TaskAdapter. ( see sample - TODO XXX ). Adding tomcat to your application: - Create a java class that will act as adapter and start tomcat ( and hold your customization code ). The class and all the files in TOMCAT_HOME/lib/common must be available in the class loader. lib/container and lib/apps should _not_ be visible, EmbededTomcat will handle that. All the application files you want visible from tomcat must be included as well. ADVANCED1. Completely separated classloader - In your adapter, create an instance of EmbededTomcat. - set properties you want to customize. - add all interceptors including your application-specific. That includes the connector modules ( shortcuts are provided for common sets of modules and for common connector configuration ). - add the root context ( required ) and any other contexts you want. More context can be added at runtime. You can also use existing configuration modules that automatically add/deploy Contexts. - call start(). Tomcat will initialize and start. The method returns when everything is ready. - You can add/remove contexts at runtime. - call stop(). Tomcat will clean up all resources and shutdown ( clean shutdown ). All common modules have been tested and shouldn't leave any garbage, however it is possible that user code will leave threads or other garbage ( i.e. not clean on destroy ). If tomcat is run in a sandbox, this shouldn't be a problem ( as untrusted servlets can't create threads ). It is your responsiblity to make sure all apps you trust or custom modules support clean shutdown. - ADVANCED2. You can throw away the classloader, and use another one if you start again. That would take care of all garbage and classes except threads and associated objects ( there is no way to handle dangling threads except killing them, assuming you can distinguish them from your own threads ). All file paths _should_ be absolute. If not, you should set "home" and make sure you include the "PathSetter" module before anything else. Example1

        // Assume EmbededTomcat and all common jars are in CLASSPATH
        EmbededTomcat tomcat=new EmbededTomcat();
        tomcat.setInstallDir( installDir );

        // tomcat.setDebug( debug );
        // tomcat.setAutoDeploy( false ); // no webapps/ is used
        // tomcat.setEstart(true ); // server.xml will not be used

        tomcat.initClassLoaders();

        if( explicitModules ) {
          // For each module you want to add ( you must include a minimal set )
          int mid=tomcat.addModule( "org.apache.tomcat.modules.xxxx" );
          tomcat.setModuleProperty( mid, "property", "value" );
        } else {
          // Nothing - server.xml will be used if setEstart(false) ( default )
          //           the default set will be used if setEstart(true)
        }

        // If you don't add one explicitely, the defaults are used ( HTTP/8080,
        //  Ajp12/8007 for shutdown )
        // tomcat.addEndpoint( port, null, null );
        // You can add other connectors using addModule()

        // tomcat.addApplicationAdapter( myModule );

        // If you also want "webapps/" ( if you don addContext this is automatic )
        // tomcat.addAutoDeploy();
        // tomcat.addContext( path, docBase, null);

        tomcat.execute();

Author:
  Costin Manolache

Field Summary
`protected java.lang.Object` | `application`
`protected java.lang.String[]` | `args`
`protected java.util.Vector` | `connectors`
`protected ContextManager` | `contextM`
`protected int` | `dL`
`protected boolean` | `initialized`
`protected java.lang.String[]` | `moduleSet1`
`protected java.lang.String[]` | `moduleSetAD`
`static java.lang.String` | `PROPERTY_APPS_LOADER` System property used to set the application class loader, which will be the parent of all webapps.
`static java.lang.String` | `PROPERTY_CONTAINER_LOADER`

Constructor Summary
`EmbededTomcat()`

Method Summary
`int` | `addAjpEndpoint(int port, java.net.InetAddress addr, java.lang.String hostname)` Add AJP12 listener.
`void` | `addApplicationAdapter(BaseInterceptor adapter)` This is an adapter object that provides callbacks into the application.
`void` | `addAutoDeploy()` Add modules needed for auto-deploy function.
`Context` | `addContext(java.lang.String ctxPath, java.net.URL docRoot, java.lang.String[] hosts)` Add and init a context.
`void` | `addDefaultConnectors()` Add the default HTTP/8080, Ajp12-stop/8007, if no explicit addEndpoint was called
`void` | `addDefaultModules()` Add all the default modules, needed for a fully functional container.
`int` | `addEndpoint(int port, java.net.InetAddress addr, java.lang.String hostname)` Add a HTTP listener.
`void` | `addInterceptor(BaseInterceptor ri)`
`int` | `addModule(BaseInterceptor ri)` Add a module explicitely.
`int` | `addModule(java.lang.String className)` Add a custom module.
`protected java.net.URL[]` | `addModulesContainerCP(java.net.URL[] orig)`
`void` | `addProperty(Property prop)`
`int` | `addSecureEndpoint(int port, java.net.InetAddress addr, java.lang.String hostname, java.lang.String keyFile, java.lang.String keyPass)` Add a secure HTTP listener.
`void` | `addServerXmlModules()` Init tomcat using server.xml-style configuration.
`protected void` | `beforeAddInterceptors()` Hook - will be called after all modules are configured, before they are added to the ContextManager.
`void` | `cleanupPrevious()` Cleanup from a previous run
`BaseInterceptor` | `createModule(java.lang.String classN)`
`void` | `debug(java.lang.String s)`
`void` | `debug(java.lang.String s, java.lang.Throwable t)`
`void` | `execute()` Main and Ant action.
`void` | `execute1()`
`int` | `findModule(java.lang.String className, int startPos)` Find a module from the set added with addModule() or addDefaultModules()
`protected java.net.URL[]` | `findModulesCP(java.lang.String dir)`
`java.lang.Object` | `getApplication()` Keep a reference to the application in which we are embeded
`java.lang.ClassLoader` | `getContainerClassLoader()`
`Context` | `getContext(java.lang.String host, java.lang.String cpath)` Find the context mounted at /cpath for a virtual host.
`ContextManager` | `getContextManager()` Access to the ContextManager.
`protected java.net.URL[]` | `getModulesCommonCP()` Allow modules to add libs in the common CP.
`void` | `initClassLoaders()` Initialize class loaders with the defaults, if not set
`void` | `initContextManager()` Initialize the context manager.
`boolean` | `isInitialized()`
`static void` | `main(java.lang.String[] args)`
`static void` | `printUsage()`
`boolean` | `processArgs(java.lang.String[] args)`
`void` | `setAjpPort(int port)` Set the port for ajp connections.
`void` | `setApplication(java.lang.Object app)` Keep a reference to the application in which we are embeded
`void` | `setAppsClassLoader(java.lang.ClassLoader cl)` Parent class loader for all web applications.
`void` | `setArgs(java.lang.String[] args)`
`void` | `setAttribute(java.lang.String name, java.lang.Object v)`
`void` | `setCommonClassLoader(java.lang.ClassLoader cl)` Class loader containing lib/common ( or equivalent ).
`void` | `setCommonClassPath(java.net.URL[] cp)` Classpath used for common class loader ( probably not needed of URLClassLoader is used ).
`void` | `setConfig(java.lang.String s)` Set location of the server.xml file, to be used by ServerXml reader.
`void` | `setContainerClassLoader(java.lang.ClassLoader cl)` Class loader used to load tomcat internal classes, not visible to webapps.
`void` | `setDebug(int debug)` Debug for EmbededTomcat, enable debugging on tomcat and the LogEvents module.
`void` | `setEstart(boolean b)` Use 'embeded' configuration to start tomcat.
`void` | `setF(java.lang.String s)`
`void` | `setH(java.lang.String s)`
`void` | `setHelp(boolean b)` Don't run, just display the help message.
`void` | `setHome(java.lang.String s)` Set the home dir for tomcat, where webapps/ will be located.
`void` | `setHttpPort(int port)` Used from estart ( i.e.
`void` | `setI(java.lang.String s)`
`void` | `setInstall(java.lang.String install)` Set install dir for tomcat, where libs will be located.
`void` | `setJkconf(boolean b)` Generate Jk configuration, without running tomcat.
`void` | `setModuleProperty(int id, java.lang.String name, java.lang.String value)` Configure a module property.
`void` | `setModulesFile(java.lang.String mf)` Set the location of the `modules.xml` file, to be used by ServXml reader.
`void` | `setNoClassloaders(boolean b)`
`void` | `setParentClassLoader(java.lang.ClassLoader cl)` Parent class loader is the parent of "common" loader.
`void` | `setProperty(java.lang.String name, java.lang.String v)`
`void` | `setRun(boolean b)` Dummy, "-run" on the command line.
`void` | `setSandbox(boolean b)` Tomcat will run in a sandboxed environment, under SecurityManager.
`void` | `setSecurity(boolean b)`
`void` | `setStart(boolean b)` Dummy, "-start" on the command line.
`void` | `setStartb(boolean b)` set if we need to block.
`void` | `shutdown()` Shutdown contextM - may exit the VM.
`void` | `start()` Start the context manager.
`void` | `stop()` Stop contextM - will not exit the VM.

Methods inherited from class java.lang.Object
`clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Field Detail

### contextM

    protected ContextManager contextM

### application

    protected java.lang.Object application

### connectors

    protected java.util.Vector connectors

### dL

    protected int dL

### initialized

    protected boolean initialized

### args

    protected java.lang.String[] args

### PROPERTY_APPS_LOADER

    public static final java.lang.String PROPERTY_APPS_LOADER

  System property used to set the application class loader, which will be the parent of all webapps.

  See Also:
    Constant Field Values

### PROPERTY_CONTAINER_LOADER

    public static final java.lang.String PROPERTY_CONTAINER_LOADER

See Also:
  Constant Field Values

### moduleSet1

    protected java.lang.String[] moduleSet1

### moduleSetAD

    protected java.lang.String[] moduleSetAD

Constructor Detail

### EmbededTomcat

    public EmbededTomcat()

Method Detail

### getContextManager

    public ContextManager getContextManager()

  Access to the ContextManager.

### setDebug

    public void setDebug(int debug)

  Debug for EmbededTomcat, enable debugging on tomcat and the LogEvents module. "-debug debug" on the command line

### setStartb

    public void setStartb(boolean b)

  set if we need to block.

### setNoClassloaders

    public void setNoClassloaders(boolean b)

### setHome

    public void setHome(java.lang.String s)

  Set the home dir for tomcat, where webapps/ will be located. "-home dir" on the command line.

### setInstall

    public void setInstall(java.lang.String install)

  Set install dir for tomcat, where libs will be located. "-install dir" on the command line.

### setConfig

    public void setConfig(java.lang.String s)

  Set location of the server.xml file, to be used by ServerXml reader. Not used if EStart() is used. "-config foo" on the command line.

### setModulesFile

    public void setModulesFile(java.lang.String mf)

  Set the location of the `modules.xml` file, to be used by ServXml reader. `-modulesFile foo` on the command line.

### setSandbox

    public void setSandbox(boolean b)

  Tomcat will run in a sandboxed environment, under SecurityManager. "-sandbox" on the command line

### setJkconf

    public void setJkconf(boolean b)

  Generate Jk configuration, without running tomcat. Equivalent with "-jkconf" on the command line.

### setStart

    public void setStart(boolean b)

  Dummy, "-start" on the command line.

### setEstart

    public void setEstart(boolean b)

  Use 'embeded' configuration to start tomcat. If Estart is false ( the default ), we'll load server.xml and all the modules inside. If it is set to true, we'll load the a hard-coded set of modules. If you add explicitely your own set of module it will be used instead of the defaults. Modules need to be added before adding the first connector or initContextManager is called. Equivalent with "-estart" on the command line.

### setHttpPort

    public void setHttpPort(int port)

  Used from estart ( i.e. no server.xml, minimal config )

### setAjpPort

    public void setAjpPort(int port)

  Set the port for ajp connections. If not set, ajp will not be enabled. Used for estart.

### setRun

    public void setRun(boolean b)

  Dummy, "-run" on the command line.

### setHelp

    public void setHelp(boolean b)

  Don't run, just display the help message. "-help" on the command line.

### setProperty

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

### setAttribute

    public void setAttribute(java.lang.String name,
                             java.lang.Object v)

### addProperty

    public void addProperty(Property prop)

### setApplication

    public void setApplication(java.lang.Object app)

  Keep a reference to the application in which we are embeded

### getApplication

    public java.lang.Object getApplication()

  Keep a reference to the application in which we are embeded

### addModule

    public int addModule(BaseInterceptor ri)
                  throws TomcatException

  Add a module explicitely. You can use server.xml, a pre-defined set of modules, or your own set. Must be called before adding the first endpoint or context and before initContextManger. If you add a module you must also call addDefaultModules (before or after your modules ) - or you can add all the required modules manually.

  Throws:
    `TomcatException`

### addModule

    public int addModule(java.lang.String className)
                  throws TomcatException

  Add a custom module. It'll return the module id, that can be used to set properties

  Throws:
    `TomcatException`
  See Also:
    `addModule( BaseInterceptor ri )`

### findModule

    public int findModule(java.lang.String className,
                          int startPos)

  Find a module from the set added with addModule() or addDefaultModules()

### setModuleProperty

    public void setModuleProperty(int id,
                                  java.lang.String name,
                                  java.lang.String value)
                           throws TomcatException

  Configure a module property. Since modules can be added from child classloaders this is the best way to configure them. If the module is in the same class loader you can also set the property explicitely, but for more flexibility it's better to use this method.

  Throws:
    `TomcatException`

### addServerXmlModules

    public void addServerXmlModules()
                             throws TomcatException

  Init tomcat using server.xml-style configuration. Called automatically if no module was explicitely added and Estart is true ( default ). The automatic call happens before addContext, addEndpoint or execute()

  Throws:
    `TomcatException`

### addDefaultModules

    public void addDefaultModules()
                           throws TomcatException

  Add all the default modules, needed for a fully functional container. You must setEtomcat( true ) if you don't want server.xml to be used.

  Throws:
    `TomcatException`

### addAutoDeploy

    public void addAutoDeploy()
                       throws TomcatException

  Add modules needed for auto-deploy function. By default you need to explicitely add ( using addContext() ) any webapp. Use this with addDefaultModules(). Will be called automcatically if no context was added, you must call it if you want both autodeploy and manually-added contexts.

  Throws:
    `TomcatException`

### addContext

    public Context addContext(java.lang.String ctxPath,
                              java.net.URL docRoot,
                              java.lang.String[] hosts)
                       throws TomcatException

  Add and init a context. Must be called after all modules and endpoints are added. This will initialize the context manager.

  Throws:
    `TomcatException`

### getContext

    public Context getContext(java.lang.String host,
                              java.lang.String cpath)

  Find the context mounted at /cpath for a virtual host.

### initContextManager

    public void initContextManager()
                            throws TomcatException

  Initialize the context manager. Called automatically before the first addContext or on execute(). You can call it explicitely if you want to 'tweak' the cm before execute.

  Throws:
    `TomcatException`

### start

    public void start()
               throws TomcatException

  Start the context manager. Will do nothing if -jkConfig or -help ( or the equivalent setters ) are used.

  Throws:
    `TomcatException`

### shutdown

    public void shutdown()
                  throws TomcatException

  Shutdown contextM - may exit the VM. This method is intrinsically dangerous, so use at your own risk. It is very possible that the entire VM will shut down after calling this method. You should only call this method if you need to implement advanced functionality.

  Throws:
    `TomcatException`

### stop

    public void stop()
              throws TomcatException

  Stop contextM - will not exit the VM.

  Throws:
    `TomcatException`

### addEndpoint

    public int addEndpoint(int port,
                           java.net.InetAddress addr,
                           java.lang.String hostname)
                    throws TomcatException

  Add a HTTP listener. Must be called after all 'core' modules are called. If no endpoint is added explicitely the defaults will be added.

  Throws:
    `TomcatException`

### addAjpEndpoint

    public int addAjpEndpoint(int port,
                              java.net.InetAddress addr,
                              java.lang.String hostname)
                       throws TomcatException

  Add AJP12 listener.

  Throws:
    `TomcatException`

### addSecureEndpoint

    public int addSecureEndpoint(int port,
                                 java.net.InetAddress addr,
                                 java.lang.String hostname,
                                 java.lang.String keyFile,
                                 java.lang.String keyPass)
                          throws TomcatException

  Add a secure HTTP listener.

  Throws:
    `TomcatException`

### addDefaultConnectors

    public void addDefaultConnectors()
                              throws TomcatException

  Add the default HTTP/8080, Ajp12-stop/8007, if no explicit addEndpoint was called

  Throws:
    `TomcatException`

### execute

    public void execute()
                 throws java.lang.Exception

  Main and Ant action. It's expected to be overriden with completely different functionality - do not use super.execute(), but call directly the methods you need.

  Throws:
    `java.lang.Exception`

### execute1

    public void execute1()
                  throws java.lang.Exception

  Throws:
    `java.lang.Exception`

### setArgs

    public void setArgs(java.lang.String[] args)

### processArgs

    public boolean processArgs(java.lang.String[] args)

### main

    public static void main(java.lang.String[] args)

### cleanupPrevious

    public void cleanupPrevious()

  Cleanup from a previous run

### setParentClassLoader

    public void setParentClassLoader(java.lang.ClassLoader cl)

  Parent class loader is the parent of "common" loader. It can be used as a parent for the webapps, if you want them to have the minimal visibility of tomcat. If you do so, make sure you include at least servlet.jar.

### setCommonClassLoader

    public void setCommonClassLoader(java.lang.ClassLoader cl)

  Class loader containing lib/common ( or equivalent ). This will be the parent of both the server container and also parent of webapp loaders. Typically used to load EmbededTomcat ( defaults to this.getClassLoader()). For backward compat, the caller can include all elements of the org.apache.tomcat.common.classpath property.

### setCommonClassPath

    public void setCommonClassPath(java.net.URL[] cp)

  Classpath used for common class loader ( probably not needed of URLClassLoader is used ). Used for javac.

### setAppsClassLoader

    public void setAppsClassLoader(java.lang.ClassLoader cl)

  Parent class loader for all web applications. Defaults to common + lib/apps + all elements of org.apache.tomcat.apps.classpath

### setContainerClassLoader

    public void setContainerClassLoader(java.lang.ClassLoader cl)

  Class loader used to load tomcat internal classes, not visible to webapps. Defaults to common + ${TOMCAT_HOME}/lib/container/ + ${TOMCAT_HOME}/classes + ${JAVA_HOME}/lib/tools.jar

### getContainerClassLoader

    public java.lang.ClassLoader getContainerClassLoader()

### initClassLoaders

    public void initClassLoaders()
                          throws java.io.IOException,
                                 java.net.MalformedURLException

  Initialize class loaders with the defaults, if not set

  Throws:
    `java.io.IOException`
    `java.net.MalformedURLException`

### getModulesCommonCP

    protected java.net.URL[] getModulesCommonCP()

  Allow modules to add libs in the common CP. This reduce the setup overhead when installing modules.

### findModulesCP

    protected java.net.URL[] findModulesCP(java.lang.String dir)

### addModulesContainerCP

    protected java.net.URL[] addModulesContainerCP(java.net.URL[] orig)

### debug

    public void debug(java.lang.String s)

### debug

    public void debug(java.lang.String s,
                      java.lang.Throwable t)

### createModule

    public BaseInterceptor createModule(java.lang.String classN)

### setSecurity

    public void setSecurity(boolean b)

### setH

    public void setH(java.lang.String s)

### setI

    public void setI(java.lang.String s)

### setF

    public void setF(java.lang.String s)

### addInterceptor

    public void addInterceptor(BaseInterceptor ri)
                        throws TomcatException

  Throws:
    `TomcatException`

### isInitialized

    public boolean isInitialized()

### addApplicationAdapter

    public void addApplicationAdapter(BaseInterceptor adapter)
                               throws TomcatException

  This is an adapter object that provides callbacks into the application.

  Throws:
    `TomcatException`

### printUsage

    public static void printUsage()

### beforeAddInterceptors

    protected void beforeAddInterceptors()
                                  throws TomcatException

  Hook - will be called after all modules are configured, before they are added to the ContextManager.

  Throws:
    `TomcatException`

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.