Package org.apache.catalina.startup
Class Embedded
- java.lang.Object
-
- org.apache.catalina.core.StandardService
-
- org.apache.catalina.startup.Embedded
-
- 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 withengine.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 withhost.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.
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 Summary
Fields Modifier and Type Field Description protected HashMap<String,Authenticator>
authenticators
Custom mappings of login methods to authenticatorsprotected boolean
await
Use await.protected boolean
embeddedDirectoryListing
protected Engine[]
engines
The set of Engines that have been deployed in this server.protected static String
info
Descriptive information about this server implementation.protected LifecycleSupport
lifecycle
The lifecycle event support for this component.protected static Logger
log
protected Logger
logger
The default logger to be used by this component itself.protected static ResourceBundle
rb
protected Realm
realm
The default realm to be used by all containers associated with this compoennt.protected String
socketFactory
The socket factory that will be used when asecure
Connector is created.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, connectorsMonitor, container, debug, domain, initialized, oname, support
-
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, INIT_EVENT, START_EVENT, STOP_EVENT
-
-
Method Summary
All Methods Instance Methods Concrete Methods Modifier and Type Method Description void
addAuthenticator(Authenticator authenticator, 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(String address, int port, boolean secure)
Connector
createConnector(String address, int port, String protocol)
Connector
createConnector(InetAddress address, int port, boolean secure)
Create, configure, and return a new TCP/IP socket connector based on the specified properties.Connector
createConnector(InetAddress address, int port, String protocol)
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.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(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.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.void
destroy()
List<LifecycleListener>
findLifecycleListeners()
Gets the (possibly empty) list of lifecycle listeners associated with this Embedded instance.String
getCatalinaBase()
String
getCatalinaHome()
Engine[]
getEngines()
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.String
getSocketFactory()
Return the secure socket factory class name.protected void
initDirs()
protected void
initNaming()
Initialize naming - this should only enable java:env and root naming.boolean
isAwait()
boolean
isDirectoryListing()
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(String s)
void
setCatalinaHome(String s)
void
setDirectoryListing(boolean listings)
void
setLogger(Logger logger)
Set the Logger for this component.void
setRealm(Realm realm)
Set the default Realm for our Containers.protected void
setSecurityProtection()
Set the security package access/protection.void
setSocketFactory(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 org.apache.catalina.core.StandardService
addPropertyChangeListener, findConnector, findConnectors, getBroadcaster, getConnectorNames, getContainer, getContainerName, getDebug, getDomain, getName, getObjectName, getServer, init, initialize, removeConnector, removePropertyChangeListener, setBroadcaster, setContainer, setDebug, setName, setServer, toString
-
-
-
-
Field Detail
-
log
protected static final Logger log
-
rb
protected static final ResourceBundle rb
-
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.
-
authenticators
protected HashMap<String,Authenticator> authenticators
Custom mappings of login methods to authenticators
-
info
protected static final 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.
-
socketFactory
protected String socketFactory
The socket factory that will be used when asecure
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 interfaceService
- Overrides:
addConnector
in classStandardService
- 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, ornull
if the connector is supposed to bind to all addresses on this serverport
- Port number to listen tosecure
- true if the generated connector is supposed to be SSL-enabled, and false otherwise
-
createConnector
public Connector createConnector(InetAddress 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 hostappBase
- 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 interfaceService
- Overrides:
getInfo
in classStandardService
-
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)
-
addLifecycleListener
public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.- Specified by:
addLifecycleListener
in interfaceLifecycle
- Overrides:
addLifecycleListener
in classStandardService
- Parameters:
listener
- The listener to add
-
findLifecycleListeners
public List<LifecycleListener> findLifecycleListeners()
Gets the (possibly empty) list of lifecycle listeners associated with this Embedded instance.- Specified by:
findLifecycleListeners
in interfaceLifecycle
- Overrides:
findLifecycleListeners
in classStandardService
-
removeLifecycleListener
public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.- Specified by:
removeLifecycleListener
in interfaceLifecycle
- Overrides:
removeLifecycleListener
in classStandardService
- 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 afterconfigure()
, and before any of the public methods of the component are utilized.- Specified by:
start
in interfaceLifecycle
- Overrides:
start
in classStandardService
- 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 interfaceLifecycle
- Overrides:
stop
in classStandardService
- Throws:
LifecycleException
- if this component detects a fatal error that needs to be reported
-
destroy
public void destroy() throws LifecycleException
- Overrides:
destroy
in classStandardService
- Throws:
LifecycleException
-
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.
-
-