org.apache.catalina.startup

Class Embedded

public class Embedded extends StandardService implements Lifecycle

Convenience class to embed a Catalina servlet container environment inside another application. You must call the methods of this class in the following order to ensure correct operation. After normal operations have begun, you can add and remove Connectors, Engines, Hosts, and Contexts on the fly. However, once you have removed a particular component, it must be thrown away -- you can create a new one with the same characteristics if you merely want to do a restart.

To initiate a normal shutdown, call the stop() method of this object.

Version: $Revision: 586738 $ $Date: 2007-10-20 16:57:18 +0200 (Sat, 20 Oct 2007) $

Author: Craig R. McClanahan

See Also: For a complete example of how Tomcat is set up and launched as an Embedded application.

Field Summary
protected HashMapauthenticators
Custom mappings of login methods to authenticators
protected booleanawait
Use await.
protected Engine[]engines
The set of Engines that have been deployed in this server.
protected static Stringinfo
Descriptive information about this server implementation.
protected LifecycleSupportlifecycle
The lifecycle event support for this component.
protected Realmrealm
The default realm to be used by all containers associated with this compoennt.
protected booleanredirectStreams
Is standard streams redirection enabled ?
protected static StringManagersm
The string manager for this package.
protected booleanstarted
Has this component been started yet?
protected booleanuseNaming
Is naming enabled ?
Constructor Summary
Embedded()
Construct a new instance of this class with default properties.
Embedded(Realm realm)
Construct a new instance of this class with specified properties.
Method Summary
voidaddAuthenticator(Authenticator authenticator, String loginMethod)
voidaddConnector(Connector connector)
Add a new Connector to the set of defined Connectors.
voidaddEngine(Engine engine)
Add a new Engine to the set of defined Engines.
voidaddLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.
ConnectorcreateConnector(InetAddress address, int port, boolean secure)
Create, configure, and return a new TCP/IP socket connector based on the specified properties.
ConnectorcreateConnector(String address, int port, boolean secure)
ConnectorcreateConnector(InetAddress address, int port, String protocol)
ConnectorcreateConnector(String address, int port, String protocol)
ContextcreateContext(String path, String docBase)
Create, configure, and return a Context that will process all HTTP requests received from one of the associated Connectors, and directed to the specified context path on the virtual host to which this Context is connected.
EnginecreateEngine()
Create, configure, and return an Engine that will process all HTTP requests received from one of the associated Connectors, based on the specified properties.
HostcreateHost(String name, String appBase)
Create, configure, and return a Host that will process all HTTP requests received from one of the associated Connectors, and directed to the specified virtual host.
LoadercreateLoader(ClassLoader parent)
Create and return a class loader manager that can be customized, and then attached to a Context, before it is started.
LifecycleListener[]findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle.
StringgetCatalinaBase()
StringgetCatalinaHome()
StringgetInfo()
Return descriptive information about this Server implementation and the corresponding version number, in the format <description>/<version>.
RealmgetRealm()
Return the default Realm for our Containers.
protected voidinitDirs()
protected voidinitNaming()
Initialize naming - this should only enable java:env and root naming.
protected voidinitStreams()
booleanisAwait()
booleanisRedirectStreams()
Return true if redirction of standard streams is enabled.
booleanisUseNaming()
Return true if naming is enabled.
voidremoveContext(Context context)
Remove the specified Context from the set of defined Contexts for its associated Host.
voidremoveEngine(Engine engine)
Remove the specified Engine from the set of defined Engines, along with all of its related Hosts and Contexts.
voidremoveHost(Host host)
Remove the specified Host, along with all of its related Contexts, from the set of defined Hosts for its associated Engine.
voidremoveLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.
voidsetAwait(boolean b)
voidsetCatalinaBase(String s)
voidsetCatalinaHome(String s)
voidsetRealm(Realm realm)
Set the default Realm for our Containers.
voidsetRedirectStreams(boolean redirectStreams)
Enables or disables naming support.
protected voidsetSecurityProtection()
Set the security package access/protection.
voidsetUseNaming(boolean useNaming)
Enables or disables naming support.
voidstart()
Prepare for the beginning of active use of the public methods of this component.
voidstop()
Gracefully terminate the active use of the public methods of this component.

Field Detail

authenticators

protected HashMap authenticators
Custom mappings of login methods to authenticators

await

protected boolean await
Use await.

engines

protected Engine[] engines
The set of Engines that have been deployed in this server. Normally there will only be one.

info

protected static final String info
Descriptive information about this server implementation.

lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.

realm

protected Realm realm
The default realm to be used by all containers associated with this compoennt.

redirectStreams

protected boolean redirectStreams
Is standard streams redirection enabled ?

sm

protected static StringManager sm
The string manager for this package.

started

protected boolean started
Has this component been started yet?

useNaming

protected boolean useNaming
Is naming enabled ?

Constructor Detail

Embedded

public Embedded()
Construct a new instance of this class with default properties.

Embedded

public Embedded(Realm realm)
Construct a new instance of this class with specified properties.

Parameters: realm Realm implementation to be inherited by all components (unless overridden further down the container hierarchy)

Method Detail

addAuthenticator

public void addAuthenticator(Authenticator authenticator, String loginMethod)

addConnector

public void addConnector(Connector connector)
Add a new Connector to the set of defined Connectors. The newly added Connector will be associated with the most recently added Engine.

Parameters: connector The connector to be added

Throws: IllegalStateException if no engines have been added yet

addEngine

public void addEngine(Engine engine)
Add a new Engine to the set of defined Engines.

Parameters: engine The engine to be added

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.

Parameters: listener The listener to add

createConnector

public Connector createConnector(InetAddress address, int port, boolean secure)
Create, configure, and return a new TCP/IP socket connector based on the specified properties.

Parameters: address InetAddress to bind to, or null if the connector is supposed to bind to all addresses on this server port Port number to listen to secure true if the generated connector is supposed to be SSL-enabled, and false otherwise

createConnector

public Connector createConnector(String address, int port, boolean secure)

createConnector

public Connector createConnector(InetAddress address, int port, String protocol)

createConnector

public Connector createConnector(String address, int port, String protocol)

createContext

public Context createContext(String path, String docBase)
Create, configure, and return a Context that will process all HTTP requests received from one of the associated Connectors, and directed to the specified context path on the virtual host to which this Context is connected.

After you have customized the properties, listeners, and Valves for this Context, you must attach it to the corresponding Host by calling:

   host.addChild(context);
 
which will also cause the Context to be started if the Host has already been started.

Parameters: path Context path of this application ("" for the default application for this host, must start with a slash otherwise) docBase Absolute pathname to the document base directory for this web application

Throws: IllegalArgumentException if an invalid parameter is specified

createEngine

public Engine createEngine()
Create, configure, and return an Engine that will process all HTTP requests received from one of the associated Connectors, based on the specified properties.

createHost

public Host createHost(String name, String appBase)
Create, configure, and return a Host that will process all HTTP requests received from one of the associated Connectors, and directed to the specified virtual host.

After you have customized the properties, listeners, and Valves for this Host, you must attach it to the corresponding Engine by calling:

   engine.addChild(host);
 
which will also cause the Host to be started if the Engine has already been started. If this is the default (or only) Host you will be defining, you may also tell the Engine to pass all requests not assigned to another virtual host to this one:
   engine.setDefaultHost(host.getName());
 

Parameters: name Canonical name of this virtual host appBase Absolute pathname to the application base directory for this virtual host

Throws: IllegalArgumentException if an invalid parameter is specified

createLoader

public Loader createLoader(ClassLoader parent)
Create and return a class loader manager that can be customized, and then attached to a Context, before it is started.

Parameters: parent ClassLoader that will be the parent of the one created by this Loader

findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

getCatalinaBase

public String getCatalinaBase()

getCatalinaHome

public String getCatalinaHome()

getInfo

public String getInfo()
Return descriptive information about this Server implementation and the corresponding version number, in the format <description>/<version>.

getRealm

public Realm getRealm()
Return the default Realm for our Containers.

initDirs

protected void initDirs()

initNaming

protected void initNaming()
Initialize naming - this should only enable java:env and root naming. If tomcat is embeded in an application that already defines those - it shouldn't do it. XXX The 2 should be separated, you may want to enable java: but not the initial context and the reverse XXX Can we "guess" - i.e. lookup java: and if something is returned assume false ? XXX We have a major problem with the current setting for java: url

initStreams

protected void initStreams()

isAwait

public boolean isAwait()

isRedirectStreams

public boolean isRedirectStreams()
Return true if redirction of standard streams is enabled.

isUseNaming

public boolean isUseNaming()
Return true if naming is enabled.

removeContext

public void removeContext(Context context)
Remove the specified Context from the set of defined Contexts for its associated Host. If this is the last Context for this Host, the Host will also be removed.

Parameters: context The Context to be removed

removeEngine

public void removeEngine(Engine engine)
Remove the specified Engine from the set of defined Engines, along with all of its related Hosts and Contexts. All associated Connectors are also removed.

Parameters: engine The Engine to be removed

removeHost

public void removeHost(Host host)
Remove the specified Host, along with all of its related Contexts, from the set of defined Hosts for its associated Engine. If this is the last Host for this Engine, the Engine will also be removed.

Parameters: host The Host to be removed

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.

Parameters: listener The listener to remove

setAwait

public void setAwait(boolean b)

setCatalinaBase

public void setCatalinaBase(String s)

setCatalinaHome

public void setCatalinaHome(String s)

setRealm

public void setRealm(Realm realm)
Set the default Realm for our Containers.

Parameters: realm The new default realm

setRedirectStreams

public void setRedirectStreams(boolean redirectStreams)
Enables or disables naming support.

Parameters: useNaming The new use naming value

setSecurityProtection

protected void setSecurityProtection()
Set the security package access/protection.

setUseNaming

public void setUseNaming(boolean useNaming)
Enables or disables naming support.

Parameters: useNaming The new use naming value

start

public void start()
Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.

Throws: LifecycleException if this component detects a fatal error that prevents this component from being used

stop

public void stop()
Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.

Throws: LifecycleException if this component detects a fatal error that needs to be reported

Copyright © 2000-2011 Apache Software Foundation. All Rights Reserved.