Package org.apache.catalina.startup

Class Embedded

  • All Implemented Interfaces:
    Lifecycle, Service
    Direct Known Subclasses:
    Catalina, EmbeddedWebContainer
    public class Embedded
extends StandardService
    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: 1.12 $ $Date: 2007/03/29 00:59:41 $
    Author:
    Craig R. McClanahan

    • Field Detail

      • log

        protected static final Logger log

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

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

      • socketFactory

        protected 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?

      • await

        protected boolean await
        Use await.

      • embeddedDirectoryListing

        protected boolean embeddedDirectoryListing

    • 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

      • 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 String getSocketFactory()
        Return the secure socket factory class name.

      • setSocketFactory

        public void setSocketFactory​(String socketFactory)
        Set the secure socket factory class name.
        Parameters:
        socketFactory - The new secure socket factory class name

      • setAwait

        public void setAwait​(boolean b)

      • isAwait

        public boolean isAwait()

      • setCatalinaHome

        public void setCatalinaHome​(String s)

      • setCatalinaBase

        public void setCatalinaBase​(String s)

      • getCatalinaHome

        public String getCatalinaHome()

      • getCatalinaBase

        public String getCatalinaBase()

      • setDirectoryListing

        public void setDirectoryListing​(boolean listings)

      • isDirectoryListing

        public boolean isDirectoryListing()

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

      • getEngines

        public Engine[] getEngines()

      • 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)

      • 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

      • getInfo

        public 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,
                             String loginMethod)

      • 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()

      • setSecurityProtection

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