Top Description Fields Methods
org.apache.catalina

public Interface Container

extends Lifecycle
Known Direct Subinterfaces
org.apache.catalina.Context, org.apache.catalina.Engine, org.apache.catalina.Host, org.apache.catalina.Wrapper
Known Direct Implementers
org.apache.catalina.core.ContainerBase
Imports
java.beans.PropertyChangeListener, java.io.File, javax.management.ObjectName, org.apache.catalina.connector.Request, .Response, org.apache.juli.logging.Log
A Container is an object that can execute requests received from a client, and return responses based on those requests. A Container may optionally support a pipeline of Valves that process the request in an order configured at runtime, by implementing the Pipeline interface as well.

Containers will exist at several conceptual levels within Catalina. The following examples represent common cases:

A given deployment of Catalina need not include Containers at all of the levels described above. For example, an administration application embedded within a network device (such as a router) might only contain a single Context and a few Wrappers, or even a single Wrapper if the application is relatively small. Therefore, Container implementations need to be designed so that they will operate correctly in the absence of parent Containers in a given deployment.

A Container may also be associated with a number of support components that provide functionality which might be shared (by attaching it to a parent Container) or individually customized. The following support components are currently recognized:

Authors
Craig R. McClanahan, Remy Maucherat

Field Summary

Modifier and TypeField and Description
public static final String
ADD_CHILD_EVENT

The ContainerEvent event type sent when a child container is added by addChild().

public static final String
ADD_VALVE_EVENT

The ContainerEvent event type sent when a valve is added by addValve(), if this Container supports pipelines.

public static final String
REMOVE_CHILD_EVENT

The ContainerEvent event type sent when a child container is removed by removeChild().

public static final String
REMOVE_VALVE_EVENT

The ContainerEvent event type sent when a valve is removed by removeValve(), if this Container supports pipelines.

Inherited from org.apache.catalina.Lifecycle:
AFTER_DESTROY_EVENTAFTER_INIT_EVENTAFTER_START_EVENTAFTER_STOP_EVENTBEFORE_DESTROY_EVENTBEFORE_INIT_EVENTBEFORE_START_EVENTBEFORE_STOP_EVENTCONFIGURE_START_EVENTCONFIGURE_STOP_EVENTPERIODIC_EVENTSTART_EVENTSTOP_EVENT

Method Summary

Modifier and TypeMethod and Description
public void
addChild(Container
New child Container to be added
child)

Add a new child Container to those associated with this Container, if supported.

public void
addContainerListener(ContainerListener
The listener to add
listener)

Add a container event listener to this component.

public void
addPropertyChangeListener(PropertyChangeListener
The listener to add
listener)

Add a property change listener to this component.

public void
backgroundProcess()

Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container.

public Container

Returns:

The child Container with the given name or null if no such child exists.
findChild(String
Name of the child Container to be retrieved
name)

Obtain a child Container by name.

public Container[]

Returns:

An array containing all children of this container. If this Container has no children, a zero-length array is returned.
findChildren()

Obtain the child Containers associated with this Container.

public ContainerListener[]

Returns:

An array containing the container listeners associated with this Container. If this Container has no registered container listeners, a zero-length array is returned.
findContainerListeners()

Obtain the container listeners associated with this Container.

public void
fireContainerEvent(String
Event type
type, Object
Event data
data)

Notify all container event listeners that a particular event has occurred for this Container.

public AccessLog

Returns:

The AccessLog to use for a request/response destined for this container
getAccessLog()

Obtain the AccessLog to use to log a request/response that is destined for this container.

public int

Returns:

The delay between the invocation of the backgroundProcess method on this container and its children. A non-positive value indicates that background processing will be managed by the parent.
getBackgroundProcessorDelay()

Get the delay between the invocation of the backgroundProcess method on this container and its children.

public File

Returns:

The location of CATALINA_BASE.
getCatalinaBase()

Obtain the location of CATALINA_BASE.

public File

Returns:

The location of CATALINA_HOME.
getCatalinaHome()

Obtain the location of CATALINA_HOME.

public Cluster

Returns:

The Cluster with which this Container is associated. If there is no associated Cluster, return the Cluster associated with our parent Container (if any); otherwise return null.
getCluster()

Get the Cluster for this container.

public static String

Returns:

the configuration path
getConfigPath(Container
The container
container, String
The resource file name
resourceName)

Find the configuration path where a configuration resource is located.

public String

Returns:

The JMX domain name
getDomain()

Obtain the JMX domain under which this container will be / has been registered.

public Log

Returns:

The Logger with which this Container is associated. If there is no associated Logger, return the Logger associated with the parent Container (if any); otherwise return null.
getLogger()

Obtain the log to which events for this container should be logged.

public String

Returns:

the abbreviated name of this container for logging messages
getLogName()

Return the logger name that the container will use.

public String

Returns:

A string suitable for appending to the ObjectName
getMBeanKeyProperties()

Calculate the key properties string to be added to an object's ObjectName to indicate that it is associated with this container.

public String

Returns:

The human readable name of this container.
getName()

Return a name string (suitable for use by humans) that describes this Container.

public ObjectName

Returns:

the JMX name associated with this container.
getObjectName()

Obtain the JMX name for this container.

public Container

Returns:

Return the Container for which this Container is a child, if there is one. If there is no defined parent, return null.
getParent()

Get the parent container.

public ClassLoader

Returns:

the parent class loader for this component. If not set, return getParent().getParentClassLoader(). If no parent has been set, return the system class loader.
getParentClassLoader()

Get the parent class loader.

public Pipeline

Returns:

The Pipeline
getPipeline()

Return the Pipeline object that manages the Valves associated with this Container.

public Realm

Returns:

The associated Realm; if there is no associated Realm, the Realm associated with the parent Container (if any); otherwise return null.
getRealm()

Obtain the Realm with which this Container is associated.

public static Service

Returns:

the Service, or null if not found
getService(Container
The container to start from
container)

Return the Service to which this container belongs.

public int

Returns:

The currently configured number of threads used to start/stop children associated with this container
getStartStopThreads()

Obtain the number of threads available for starting and stopping any children associated with this container.

public void
logAccess(Request
Request (associated with the response) to log
request, Response
Response (associated with the request) to log
response, long
Time taken to process the request/response in milliseconds (use 0 if not known)
time, boolean
Flag that indicates that the request/response should be logged in the engine's default access log
useDefault)

Log a request/response that was destined for this container but has been handled earlier in the processing chain so that the request/response still appears in the correct access logs.

public void
removeChild(Container
Existing child Container to be removed
child)

Remove an existing child Container from association with this parent Container.

public void
removeContainerListener(ContainerListener
The listener to remove
listener)

Remove a container event listener from this component.

public void
removePropertyChangeListener(PropertyChangeListener
The listener to remove
listener)

Remove a property change listener from this component.

public void
setBackgroundProcessorDelay(int
The delay in seconds between the invocation of backgroundProcess methods
delay)

Set the delay between the invocation of the execute method on this container and its children.

public void
setCluster(Cluster
the Cluster with which this Container is associated.
cluster)

Set the Cluster with which this Container is associated.

public void
setName(String
New name of this container
name)

Set a name string (suitable for use by humans) that describes this Container.

public void
setParent(Container
Container to which this Container is being added as a child
container)

Set the parent Container to which this Container is being added as a child.

public void
setParentClassLoader(ClassLoader
The new parent class loader
parent)

Set the parent class loader for this component.

public void
setRealm(Realm
The newly associated Realm
realm)

Set the Realm with which this Container is associated.

public void
setStartStopThreads(int
The new number of threads to be used
startStopThreads)

Sets the number of threads available for starting and stopping any children associated with this container.

Inherited from org.apache.catalina.Lifecycle:
addLifecycleListenerdestroyfindLifecycleListenersgetStategetStateNameinitremoveLifecycleListenerstartstop

Field Detail

ADD_CHILD_EVENTback to summary
public static final String ADD_CHILD_EVENT

The ContainerEvent event type sent when a child container is added by addChild().

ADD_VALVE_EVENTback to summary
public static final String ADD_VALVE_EVENT

The ContainerEvent event type sent when a valve is added by addValve(), if this Container supports pipelines.

REMOVE_CHILD_EVENTback to summary
public static final String REMOVE_CHILD_EVENT

The ContainerEvent event type sent when a child container is removed by removeChild().

REMOVE_VALVE_EVENTback to summary
public static final String REMOVE_VALVE_EVENT

The ContainerEvent event type sent when a valve is removed by removeValve(), if this Container supports pipelines.

Method Detail

addChildback to summary
public void addChild(Container child)

Add a new child Container to those associated with this Container, if supported. Prior to adding this Container to the set of children, the child's setParent() method must be called, with this Container as an argument. This method may thrown an IllegalArgumentException if this Container chooses not to be attached to the specified Container, in which case it is not added

Parameters
child:Container

New child Container to be added

Exceptions
IllegalArgumentException:
  • if this exception is thrown by the setParent() method of the child Container
  • if the new child does not have a name unique from that of existing children of this Container
IllegalStateException:
if this Container does not support child Containers
addContainerListenerback to summary
public void addContainerListener(ContainerListener listener)

Add a container event listener to this component.

Parameters
listener:ContainerListener

The listener to add

addPropertyChangeListenerback to summary
public void addPropertyChangeListener(PropertyChangeListener listener)

Add a property change listener to this component.

Parameters
listener:PropertyChangeListener

The listener to add

backgroundProcessback to summary
public void backgroundProcess()

Execute a periodic task, such as reloading, etc. This method will be invoked inside the classloading context of this container. Unexpected throwables will be caught and logged.

findChildback to summary
public Container findChild(String name)

Obtain a child Container by name.

Parameters
name:String

Name of the child Container to be retrieved

Returns:Container

The child Container with the given name or null if no such child exists.

findChildrenback to summary
public Container[] findChildren()

Obtain the child Containers associated with this Container.

Returns:Container[]

An array containing all children of this container. If this Container has no children, a zero-length array is returned.

findContainerListenersback to summary
public ContainerListener[] findContainerListeners()

Obtain the container listeners associated with this Container.

Returns:ContainerListener[]

An array containing the container listeners associated with this Container. If this Container has no registered container listeners, a zero-length array is returned.

fireContainerEventback to summary
public void fireContainerEvent(String type, Object data)

Notify all container event listeners that a particular event has occurred for this Container. The default implementation performs this notification synchronously using the calling thread.

Parameters
type:String

Event type

data:Object

Event data

getAccessLogback to summary
public AccessLog getAccessLog()

Obtain the AccessLog to use to log a request/response that is destined for this container. This is typically used when the request/response was handled (and rejected) earlier in the processing chain so that the request/response still appears in the correct access logs.

Returns:AccessLog

The AccessLog to use for a request/response destined for this container

getBackgroundProcessorDelayback to summary
public int getBackgroundProcessorDelay()

Get the delay between the invocation of the backgroundProcess method on this container and its children. Child containers will not be invoked if their delay value is positive (which would mean they are using their own thread). Setting this to a positive value will cause a thread to be spawned. After waiting the specified amount of time, the thread will invoke the backgroundProcess() method on this container and all children with non-positive delay values.

Returns:int

The delay between the invocation of the backgroundProcess method on this container and its children. A non-positive value indicates that background processing will be managed by the parent.

getCatalinaBaseback to summary
public File getCatalinaBase()

Obtain the location of CATALINA_BASE.

Returns:File

The location of CATALINA_BASE.

getCatalinaHomeback to summary
public File getCatalinaHome()

Obtain the location of CATALINA_HOME.

Returns:File

The location of CATALINA_HOME.

getClusterback to summary
public Cluster getCluster()

Get the Cluster for this container.

Returns:Cluster

The Cluster with which this Container is associated. If there is no associated Cluster, return the Cluster associated with our parent Container (if any); otherwise return null.

getConfigPathback to summary
public static String getConfigPath(Container container, String resourceName)

Find the configuration path where a configuration resource is located.

Parameters
container:Container

The container

resourceName:String

The resource file name

Returns:String

the configuration path

getDomainback to summary
public String getDomain()

Obtain the JMX domain under which this container will be / has been registered.

Returns:String

The JMX domain name

getLoggerback to summary
public Log getLogger()

Obtain the log to which events for this container should be logged.

Returns:Log

The Logger with which this Container is associated. If there is no associated Logger, return the Logger associated with the parent Container (if any); otherwise return null.

getLogNameback to summary
public String getLogName()

Return the logger name that the container will use.

Returns:String

the abbreviated name of this container for logging messages

getMBeanKeyPropertiesback to summary
public String getMBeanKeyProperties()

Calculate the key properties string to be added to an object's ObjectName to indicate that it is associated with this container.

Returns:String

A string suitable for appending to the ObjectName

getNameback to summary
public String getName()

Return a name string (suitable for use by humans) that describes this Container. Within the set of child containers belonging to a particular parent, Container names must be unique.

Returns:String

The human readable name of this container.

getObjectNameback to summary
public ObjectName getObjectName()

Obtain the JMX name for this container.

Returns:ObjectName

the JMX name associated with this container.

getParentback to summary
public Container getParent()

Get the parent container.

Returns:Container

Return the Container for which this Container is a child, if there is one. If there is no defined parent, return null.

getParentClassLoaderback to summary
public ClassLoader getParentClassLoader()

Get the parent class loader.

Returns:ClassLoader

the parent class loader for this component. If not set, return getParent().getParentClassLoader(). If no parent has been set, return the system class loader.

getPipelineback to summary
public Pipeline getPipeline()

Return the Pipeline object that manages the Valves associated with this Container.

Returns:Pipeline

The Pipeline

getRealmback to summary
public Realm getRealm()

Obtain the Realm with which this Container is associated.

Returns:Realm

The associated Realm; if there is no associated Realm, the Realm associated with the parent Container (if any); otherwise return null.

getServiceback to summary
public static Service getService(Container container)

Return the Service to which this container belongs.

Parameters
container:Container

The container to start from

Returns:Service

the Service, or null if not found

getStartStopThreadsback to summary
public int getStartStopThreads()

Obtain the number of threads available for starting and stopping any children associated with this container. This allows start/stop calls to children to be processed in parallel.

Returns:int

The currently configured number of threads used to start/stop children associated with this container

logAccessback to summary
public void logAccess(Request request, Response response, long time, boolean useDefault)

Log a request/response that was destined for this container but has been handled earlier in the processing chain so that the request/response still appears in the correct access logs.

Parameters
request:Request

Request (associated with the response) to log

response:Response

Response (associated with the request) to log

time:long

Time taken to process the request/response in milliseconds (use 0 if not known)

useDefault:boolean

Flag that indicates that the request/response should be logged in the engine's default access log

removeChildback to summary
public void removeChild(Container child)

Remove an existing child Container from association with this parent Container.

Parameters
child:Container

Existing child Container to be removed

removeContainerListenerback to summary
public void removeContainerListener(ContainerListener listener)

Remove a container event listener from this component.

Parameters
listener:ContainerListener

The listener to remove

removePropertyChangeListenerback to summary
public void removePropertyChangeListener(PropertyChangeListener listener)

Remove a property change listener from this component.

Parameters
listener:PropertyChangeListener

The listener to remove

setBackgroundProcessorDelayback to summary
public void setBackgroundProcessorDelay(int delay)

Set the delay between the invocation of the execute method on this container and its children.

Parameters
delay:int

The delay in seconds between the invocation of backgroundProcess methods

setClusterback to summary
public void setCluster(Cluster cluster)

Set the Cluster with which this Container is associated.

Parameters
cluster:Cluster

the Cluster with which this Container is associated.

setNameback to summary
public void setName(String name)

Set a name string (suitable for use by humans) that describes this Container. Within the set of child containers belonging to a particular parent, Container names must be unique.

Parameters
name:String

New name of this container

Exceptions
IllegalStateException:
if this Container has already been added to the children of a parent Container (after which the name may not be changed)
setParentback to summary
public void setParent(Container container)

Set the parent Container to which this Container is being added as a child. This Container may refuse to become attached to the specified Container by throwing an exception.

Parameters
container:Container

Container to which this Container is being added as a child

Exceptions
IllegalArgumentException:
if this Container refuses to become attached to the specified Container
setParentClassLoaderback to summary
public void setParentClassLoader(ClassLoader parent)

Set the parent class loader for this component. For Contexts this call is meaningful only before a Loader has been configured, and the specified value (if non-null) should be passed as an argument to the class loader constructor.

Parameters
parent:ClassLoader

The new parent class loader

setRealmback to summary
public void setRealm(Realm realm)

Set the Realm with which this Container is associated.

Parameters
realm:Realm

The newly associated Realm

setStartStopThreadsback to summary
public void setStartStopThreads(int startStopThreads)

Sets the number of threads available for starting and stopping any children associated with this container. This allows start/stop calls to children to be processed in parallel.

Parameters
startStopThreads:int

The new number of threads to be used