org.apache.tomcat.startup
Class EmbededTomcat

java.lang.Object
  extended byorg.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


Copyright ? 2001 Apache Software Foundation. All Rights Reserved.