Embedded (Catalina Internal API Documentation)
Keywords: org.apache.catalina.startup.Embedded class

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

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

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: 289023 $ $Date: 2004-08-26 18:06:34 -0400 (Thu, 26 Aug 2004) $
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
`AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, 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.
`Connector` | `createConnector(java.net.InetAddress 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.
`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?

### createConnector

    public Connector createConnector(java.net.InetAddress 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>`.

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

### 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`

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

Overview | Package | Class | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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