org.apache.catalina.startup
Class Embedded

java.lang.Object
  |
  +--org.apache.catalina.startup.Embedded
All Implemented Interfaces:
Lifecycle

public class Embedded
extends java.lang.Object
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.

IMPLEMENTATION NOTE: The main() method of this class is a simple example that exercizes the features of dynamically starting and stopping various components. You can execute this by executing the following steps (on a Unix platform):

   cd $CATALINA_HOME
   ./bin/catalina.sh embedded
 

Version:
$Revision: 1.11.2.1 $ $Date: 2001/10/11 23:13:00 $
Author:
Craig R. McClanahan

Field Summary
protected  Connector[] connectors
          The set of Connectors that have been deployed in this server.
protected  int debug
          The debugging detail level for this component.
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  Logger logger
          The default logger to be used by this component itself.
protected  Realm realm
          The default realm to be used by all containers associated with this compoennt.
protected static StringManager sm
          The string manager for this package.
protected  java.lang.String socketFactory
          The socket factory that will be used when a secure Connector is created.
protected  boolean started
          Has this component been started yet?
protected  java.beans.PropertyChangeSupport support
          The property change support for this component.
protected  boolean useNaming
          Is naming enabled ?
 
Fields inherited from interface org.apache.catalina.Lifecycle
START_EVENT, STOP_EVENT
 
Constructor Summary
Embedded()
          Construct a new instance of this class with default properties.
Embedded(Logger logger, Realm realm)
          Construct a new instance of this class with specified properties.
 
Method Summary
 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.
 void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
          Add a property change 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.
 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.
 int getDebug()
          Return the debugging detail level for this component.
 java.lang.String getInfo()
          Return descriptive information about this Server implementation and the corresponding version number, in the format <description>/<version>.
 Logger getLogger()
          Return the Logger for this component.
 Realm getRealm()
          Return the default Realm for our Containers.
 java.lang.String getSocketFactory()
          Return the secure socket factory class name.
 boolean isUseNaming()
          Return true if naming is enabled.
static void main(java.lang.String[] args)
          This main program is a unit test to exercize the various methods of the Embedded class.
 void removeConnector(Connector connector)
          Remove the specified Connector from the set of defined Connectors.
 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 removePropertyChangeListener(java.beans.PropertyChangeListener listener)
          Remove a property change listener from this component.
 void setDebug(int debug)
          Set the debugging detail level for this component.
 void setLogger(Logger logger)
          Set the Logger for this component.
 void setRealm(Realm realm)
          Set the default Realm for our Containers.
 void setSocketFactory(java.lang.String socketFactory)
          Set the secure socket factory class name.
 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 java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

connectors

protected Connector[] connectors
The set of Connectors that have been deployed in this server.


debug

protected int debug
The debugging detail level for this component.


useNaming

protected boolean useNaming
Is naming enabled ?


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


logger

protected Logger logger
The default logger to be used by this component itself. Unless this is overridden, log messages will be writted to standard output.


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.


socketFactory

protected java.lang.String socketFactory
The socket factory that will be used when a secure Connector is created. If a standard Connector is created, the internal (to the Connector class default socket factory class) will be used instead.


started

protected boolean started
Has this component been started yet?


support

protected java.beans.PropertyChangeSupport support
The property change support for this component.

Constructor Detail

Embedded

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


Embedded

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

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

getDebug

public int getDebug()
Return the debugging detail level for this component.


setDebug

public void setDebug(int debug)
Set the debugging detail level for this component.

Parameters:
debug - The new debugging detail level

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

getLogger

public Logger getLogger()
Return the Logger for this component.


setLogger

public void setLogger(Logger logger)
Set the Logger for this component.

Parameters:
logger - The new logger

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

getSocketFactory

public java.lang.String getSocketFactory()
Return the secure socket factory class name.


setSocketFactory

public void setSocketFactory(java.lang.String socketFactory)
Set the secure socket factory class name.

Parameters:
socketFactory - The new secure socket factory class name

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

addPropertyChangeListener

public void addPropertyChangeListener(java.beans.PropertyChangeListener listener)
Add a property change listener to this component.

Parameters:
listener - The listener to add

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 listen to, or null to listen on all address on this server
port - Port number to listen to
secure - Should this port be SSL-enabled?

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


removeConnector

public void removeConnector(Connector connector)
Remove the specified Connector from the set of defined Connectors.

Parameters:
connector - The Connector to be removed

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

removePropertyChangeListener

public void removePropertyChangeListener(java.beans.PropertyChangeListener listener)
Remove a property change listener from this component.

Parameters:
listener - The listener to remove

addLifecycleListener

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

Specified by:
addLifecycleListener in interface Lifecycle
Parameters:
listener - The listener to add

removeLifecycleListener

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

Specified by:
removeLifecycleListener in interface Lifecycle
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
Throws:
java.lang.IllegalStateException - if this component has already been started
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
Throws:
java.lang.IllegalStateException - if this component has not been started
LifecycleException - if this component detects a fatal error that needs to be reported

main

public static void main(java.lang.String[] args)
This main program is a unit test to exercize the various methods of the Embedded class. It can be used as an example of the type of code that would be used in a real environment.

Parameters:
args - The command line arguments


Copyright 2000-2001 Apache Software Foundation. All Rights Reserved.