org.apache.catalina.startup
Class Embedded

java.lang.Object
  org.apache.catalina.core.StandardService
      org.apache.catalina.startup.Embedded

All Implemented Interfaces:

javax.management.MBeanRegistration, Lifecycle, Service

Direct Known Subclasses:

Catalina

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.

• Instantiate a new instance of this class.
• Set the relevant properties of this object itself. In particular, you will want to establish the default Logger to be used, as well as the default Realm if you are using container-managed security.
• Call createEngine() to create an Engine object, and then call its property setters as desired.
• Call createHost() to create at least one virtual Host associated with the newly created Engine, and then call its property setters as desired. After you customize this Host, add it to the corresponding Engine with engine.addChild(host).
• Call createContext() to create at least one Context associated with each newly created Host, and then call its property setters as desired. You SHOULD create a Context with a pathname equal to a zero-length string, which will be used to process all requests not mapped to some other Context. After you customize this Context, add it to the corresponding Host with host.addChild(context).
• Call addEngine() to attach this Engine to the set of defined Engines for this object.
• Call createConnector() to create at least one TCP/IP connector, and then call its property setters as desired.
• Call addConnector() to attach this Connector to the set of defined Connectors for this object. The added Connector will use the most recently added Engine to process its received requests.
• Repeat the above series of steps as often as required (although there will typically be only one Engine instance created).
• Call start() to initiate normal operations of all the attached components.

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: 686 $ $Date: 2008-06-27 10:46:12 +0200 (Fri, 27 Jun 2008) $

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 java.util.HashMap	authenticators Custom mappings of login methods to authenticators
protected boolean	await Use await.
protected Engine[]	engines The set of Engines that have been deployed in this server.
protected static java.lang.String	info Descriptive information about this server implementation.
protected LifecycleSupport	lifecycle The lifecycle event support for this component.
protected Realm	realm The default realm to be used by all containers associated with this compoennt.
protected boolean	redirectStreams Is standard streams redirection enabled ?
protected static StringManager	sm The string manager for this package.
protected boolean	started Has this component been started yet?
protected boolean	useNaming Is naming enabled ?

Fields inherited from class org.apache.catalina.core.StandardService

connectors, container, controller, DELAY_CONNECTOR_STARTUP, domain, executors, initialized, mapper, mapperListener, mserver, oname, suffix, support, type

Fields inherited from interface org.apache.catalina.Lifecycle

AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT

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

void	addAuthenticator(Authenticator authenticator, java.lang.String loginMethod)
void	addConnector(Connector connector) Add a new Connector to the set of defined Connectors.
void	addEngine(Engine engine) Add a new Engine to the set of defined Engines.
void	addLifecycleListener(LifecycleListener listener) Add a lifecycle event listener to this component.
Connector	createConnector(java.net.InetAddress address, int port, boolean secure) Create, configure, and return a new TCP/IP socket connector based on the specified properties.
Connector	createConnector(java.net.InetAddress address, int port, java.lang.String protocol)
Connector	createConnector(java.lang.String address, int port, boolean secure)
Connector	createConnector(java.lang.String address, int port, java.lang.String protocol)
Context	createContext(java.lang.String path, java.lang.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.
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.
Host	createHost(java.lang.String name, java.lang.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.
Loader	createLoader(java.lang.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.
java.lang.String	getCatalinaBase()
java.lang.String	getCatalinaHome()
java.lang.String	getInfo() Return descriptive information about this Server implementation and the corresponding version number, in the format <description>/<version>.
Realm	getRealm() Return the default Realm for our Containers.
protected void	initDirs()
protected void	initNaming() Initialize naming - this should only enable java:env and root naming.
protected void	initStreams()
boolean	isAwait()
boolean	isRedirectStreams() Return true if redirction of standard streams is enabled.
boolean	isUseNaming() Return true if naming is enabled.
void	removeContext(Context context) Remove the specified Context from the set of defined Contexts for its associated Host.
void	removeEngine(Engine engine) Remove the specified Engine from the set of defined Engines, along with all of its related Hosts and Contexts.
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.
void	removeLifecycleListener(LifecycleListener listener) Remove a lifecycle event listener from this component.
void	setAwait(boolean b)
void	setCatalinaBase(java.lang.String s)
void	setCatalinaHome(java.lang.String s)
void	setRealm(Realm realm) Set the default Realm for our Containers.
void	setRedirectStreams(boolean redirectStreams) Enables or disables naming support.
protected void	setSecurityProtection() Set the security package access/protection.
void	setUseNaming(boolean useNaming) Enables or disables naming support.
void	start() Prepare for the beginning of active use of the public methods of this component.
void	stop() Gracefully terminate the active use of the public methods of this component.

Methods inherited from class org.apache.catalina.core.StandardService

addExecutor, addPropertyChangeListener, destroy, findConnectors, findExecutors, getConnectorNames, getContainer, getContainerName, getDomain, getExecutor, getMapper, getName, getObjectName, getServer, init, initialize, postDeregister, postRegister, preDeregister, preRegister, removeConnector, removeExecutor, removePropertyChangeListener, setContainer, setName, setServer, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Field Detail

useNaming

protected boolean useNaming

Is naming enabled ?

redirectStreams

protected boolean redirectStreams

Is standard streams redirection enabled ?

engines

protected Engine[] engines

The set of Engines that have been deployed in this server. Normally there will only be one.

authenticators

protected java.util.HashMap authenticators

Custom mappings of login methods to authenticators

info

protected static final java.lang.String info

Descriptive information about this server implementation.

See Also:

Constant Field Values

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.

sm

protected static StringManager sm

The string manager for this package.

started

protected boolean started

Has this component been started yet?

await

protected boolean await

Use await.

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

isUseNaming

public boolean isUseNaming()

Return true if naming is enabled.

setUseNaming

public void setUseNaming(boolean useNaming)

Enables or disables naming support.

Parameters:

useNaming - The new use naming value

isRedirectStreams

public boolean isRedirectStreams()

Return true if redirction of standard streams is enabled.

setRedirectStreams

public void setRedirectStreams(boolean redirectStreams)

Enables or disables naming support.

Parameters:

useNaming - The new use naming value

getRealm

public Realm getRealm()

Return the default Realm for our Containers.

setRealm

public void setRealm(Realm realm)

Set the default Realm for our Containers.

Parameters:

realm - The new default realm

setAwait

public void setAwait(boolean b)

isAwait

public boolean isAwait()

setCatalinaHome

public void setCatalinaHome(java.lang.String s)

setCatalinaBase

public void setCatalinaBase(java.lang.String s)

getCatalinaHome

public java.lang.String getCatalinaHome()

getCatalinaBase

public java.lang.String getCatalinaBase()

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.

Specified by:

addConnector in interface Service

Overrides:

addConnector in class StandardService

Parameters:

connector - The connector to be added

Throws:

java.lang.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

createConnector

public Connector createConnector(java.net.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(java.lang.String address,
                                 int port,
                                 boolean secure)

createConnector

public Connector createConnector(java.net.InetAddress address,
                                 int port,
                                 java.lang.String protocol)

createConnector

public Connector createConnector(java.lang.String address,
                                 int port,
                                 java.lang.String protocol)

createContext

public Context createContext(java.lang.String path,
                             java.lang.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:

java.lang.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(java.lang.String name,
                       java.lang.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:

java.lang.IllegalArgumentException - if an invalid parameter is specified

createLoader

public Loader createLoader(java.lang.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

getInfo

public java.lang.String getInfo()

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

Specified by:

getInfo in interface Service

Overrides:

getInfo in class StandardService

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

addAuthenticator

public void addAuthenticator(Authenticator authenticator,
                             java.lang.String loginMethod)

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)

Add a lifecycle event listener to this component.

Specified by:

addLifecycleListener in interface Lifecycle

Overrides:

addLifecycleListener in class StandardService

Parameters:

listener - The listener to add

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.

Specified by:

findLifecycleListeners in interface Lifecycle

Overrides:

findLifecycleListeners in class StandardService

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)

Remove a lifecycle event listener from this component.

Specified by:

removeLifecycleListener in interface Lifecycle

Overrides:

removeLifecycleListener in class StandardService

Parameters:

listener - The listener to remove

start

public void start()
           throws LifecycleException

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.

Specified by:

start in interface Lifecycle

Overrides:

start in class StandardService

Throws:

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

stop

public void stop()
          throws LifecycleException

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.

Specified by:

stop in interface Lifecycle

Overrides:

stop in class StandardService

Throws:

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

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

initDirs

protected void initDirs()

initStreams

protected void initStreams()

setSecurityProtection

protected void setSecurityProtection()

Set the security package access/protection.