Catalina Functional Specifications

Tomcat MBean Names

We will be using JMX MBeans as the technology for implementing manageability of Tomcat.

One of the key concepts of JMX (and JSR-77) is that each management bean has a unique name in the MBeanServer's registry, and that management applications can utilize these names to retrieve the MBean of interest to them for a particular management operation. This document proposes a naming convention for MBeans that allows easy calculation of the name for a particular MBean. For background information on JMX MBean names, see the Java Management Extensions Instrumentation and Agent Specification, version 1.0, section 6. In particular, we will be discussing the String Representation of ObjectName instances.

Tomcat's servlet container implementation, called Catalina, can be represented as a hierarchy of objects that contain references to each other. The object hierarchy can be represented as a tree, or (isomorphically) based on the nesting of configuration elements in the conf/server.xml file that is traditionally used to configure Tomcat stand-alone.

The valid component nestings for Catalina are depicted in the following table, with columns that contain the following values:

• Pattern - Nesting pattern of XML elements (in the conf/server.xml file) used to configure this component.
• Cardinality - Minimum and maximum number of occurrences of this element at this nesting position, which also corresponds to the minimum and maximum number of Catalina components.
• Identifier - Name of the JavaBeans property of this component that represents the unique identifier (within the nested hierarchy), if any.
• MBean ObjectName - The portion of the MBean object name that appears after the domain name. For now, it should be assumed that all of these MBeans appear in the default JMX domain.

In the MBean ObjectName descriptions, several types of symbolic expressions are utilized to define variable text that is replaced by corresponding values:

• ${GROUP} - One of the standard MBean names of the specified "group" category. For example, the expression ${REALM} represents the values like JDBCRealm and JAASRealm that identify the various MBeans for possible Realm components.
• ${name} - Replaced by the value of property name from the current component.
• ${parent.name} - Replaced by the value of property name from a parent of the current component, with the parent's type identified by parent.
• ${###} - An arbitrary numeric identifier that preserves order but has no other particular meaning. In general, the server will assign numeric values to existing instances with large gaps into which new items can be configured if desired.

模式	Cardinality	Identifier	MBean ObjectName
<Server>	1..1	(none)	type=${SERVER}
Server / Listener	0..n	(none)	type=${LISTENER}, sequence=${###}
Server / Service	1..n	name(名称)	type=${SERVICE}, name=${name}
Server / Service / Connector	1..n	address, port	type=${CONNECTOR}, service=${service}, port=${port}, address=${address}
Server / Service / Connector / Factory	0..1	(none)	(Only defined explicitly for an SSL connector, but can be treated as part of the connector component)
Server / Service / Connector / Listener	0..n	(none)	type=${LISTENER}, sequence=${###}, service=${service}, port=${connector.port}, address=${connector.address}
Server / Service / Engine	1..1	(none)	type=${ENGINE}, service=${service.name}
Server / Service / Engine / Host	1..n	name(名称)	type=${HOST}, host=${name}, service=${service.name}
Server / Service / Engine / Host / Context	1..n	路径	type=${CONTEXT}, path=${path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / InstanceListener	0..n	(none)	type=${INSTANCE-LISTENER}, sequence=${###}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Listener	0..n	(none)	type=${LISTENER}, sequence=${###}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Loader	0..1	(none)	type=${LOADER}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Manager	0..1	(none)	type=${MANAGER}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Realm	0..1	(none)	type=${REALM}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Resources	0..1	(none)	type=${RESOURCES}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Valve	0..n	(none)	type=${VALVE}, sequence=${###}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / Wrapper	0..n	(none)	j2eeType=Servlet,name=${name}, WebModule=//${host.name}/${context.name}, J2EEApplication=${context.J2EEApplication}, J2EEServer=${context.J2EEServer}
Server / Service / Engine / Host / Context / WrapperLifecycle	0..n	(none)	type=${WRAPPER-LIFECYCLE}, sequence=${###}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Context / WrapperListener	0..n	(none)	type=${WRAPPER-LISTENER}, sequence=${###}, path=${context.path}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Listener	0..n	(none)	type=${LISTENER}, sequence=${###}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Realm	0..1	(none)	type=${REALM}, host=${host.name}, service=${service.name}
Server / Service / Engine / Host / Valve	0..n	(none)	type=${VALVE}, sequence=${###}, host=${host.name}, service=${service.name}
Server / Service / Engine / Listener	0..n	(none)	type=${LISTENER}, sequence=${###} (FIXME - disambiguate from Server / Service / Listener)
Server / Service / Engine / Realm	0..1	(none)	type=${REALM}, service=${service.name}
Server / Service / Engine / Valve	0..n	(none)	type=${VALVE}, sequence=${###}, service=${service.name}
Server / Service / Listener	0..n	(none)	type=${LISTENER}, sequence=${###} (FIXME - disambiguate from Server / Service / Engine / Listener)

The following MBean names shall be defined in the resource file /org/apache/catalina/mbeans/mbeans-descriptors.xml (and therefore available for use within the Administration/Configuration web application for Tomcat):

MBean Name	Group Name	Catalina Interface	Implementation Class
AccessLogValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.AccessLogValve
BasicAuthenticator	VALVE	org.apache.catalina.Valve	org.apache.catalina.authenticator.BasicAuthenticator
CertificatesValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.CertificatesValve
ContextConfig	监听器	org.apache.catalina.LifecycleListener	org.apache.catalina.startup.ContextConfig
ContextEnvironment	资源	org.apache.catalina.deploy.ContextEnvironment	org.apache.catalina.deploy.ContextEnvironment
ContextResource	资源	org.apache.catalina.deploy.ContextResource	org.apache.catalina.deploy.ContextResource
ContextResourceLink	资源	org.apache.catalina.deploy.ContextResourceLink	org.apache.catalina.deploy.ContextResourceLink
CoyoteConnector	connector	org.apache.catalina.Connector	org.apache.coyote.tomcat4.CoyoteConnector
DigestAuthenticator	VALVE	org.apache.catalina.Valve	org.apache.catalina.authenticator.DigestAuthenticator
EngineConfig	监听器	org.apache.catalina.LifecycleListener	org.apache.catalina.startup.EngineConfig
ErrorReportValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.ErrorReportValve
ErrorDispatcherValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.ErrorDispatcherValve
FormAuthenticator	VALVE	org.apache.catalina.Valve	org.apache.catalina.authenticator.FormAuthenticator
组	组	org.apache.catalina.Group	org.apache.catalina.Group
HostConfig	监听器	org.apache.catalina.LifecycleListener	org.apache.catalina.startup.HostConfig
HttpConnector10	connector	org.apache.catalina.Connector	org.apache.catalina.connector.http10.HttpConnector
HttpConnector11	connector	org.apache.catalina.Connector	org.apache.catalina.connector.http.HttpConnector
JAASRealm	<Realm>	org.apache.catalina.Realm	org.apache.catalina.realm.JAASRealm
JDBCRealm	<Realm>	org.apache.catalina.Realm	org.apache.catalina.realm.JDBCRealm
JDBCUserDatabase	USERDATABASE	org.apache.catalina.users.JDBCUserDatabase	org.apache.catalina.users.JDBCUserDatabase
JNDIRealm	<Realm>	org.apache.catalina.Realm	org.apache.catalina.realm.JNDIRealm
MBeanFactory			org.apache.catalina.mbeans.MBeanFactory
MemoryRealm	<Realm>	org.apache.catalina.Realm	org.apache.catalina.realm.MemoryRealm
MemoryUserDatabase	USERDATABASE	org.apache.catalina.users.MemoryUserDatabase	org.apache.catalina.users.MemoryUserDatabase
NamingContextListener	监听器	org.apache.catalina.LifecycleListener	org.apache.catalina.core.NamingContextListener
NamingResources	资源	org.apache.catalina.deploy.NamingResources	org.apache.catalina.deploy.NamingResources
NonLoginAuthenticator	VALVE	org.apache.catalina.Valve	org.apache.catalina.authenticator.NonLoginAuthenticator
PersistentManager	管理者	org.apache.catalina.Manager	org.apache.catalina.session.PersistentManager
RemoteAddrValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.RemoteAddrValve
RemoteHostValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.RemoteHostValve
RequestDumperValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.RequestDumperValve
角色	角色	org.apache.catalina.Role	org.apache.catalina.Role
SingleSignOn	VALVE	org.apache.catalina.Valve	org.apache.catalina.valves.SingleSignOn
SSLAuthenticator	VALVE	org.apache.catalina.Valve	org.apache.catalina.authenticator.SSLAuthenticator
StandardContext	<Context>	org.apache.catalina.Context	org.apache.catalina.core.StandardContext
StandardContextValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.core.StandardContextValve
StandardEngine	<Engine>	org.apache.catalina.Engine	org.apache.catalina.core.StandardEngine
StandardEngineValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.core.StandardEngineValve
StandardHost	<Host>	org.apache.catalina.Host	org.apache.catalina.core.StandardHost
StandardHostValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.core.StandardHostValve
StandardManager	管理者	org.apache.catalina.Manager	org.apache.catalina.session.StandardManager
StandardServer	<Server>	org.apache.catalina.Server	org.apache.catalina.core.StandardServer
StandardService	<Service>	org.apache.catalina.Service	org.apache.catalina.core.StandardService
StandardWrapper	包?	org.apache.catalina.Wrapper	org.apache.catalina.core.StandardWrapper
StandardWrapperValve	VALVE	org.apache.catalina.Valve	org.apache.catalina.core.StandardWrapperValve
用户	用户	org.apache.catalina.User	org.apache.catalina.User
UserDatabaseRealm	<Realm>	org.apache.catalina.Realm	org.apache.catalina.realm.UserDatabaseRealm
WebappLoader	载入器	org.apache.catalina.Loader	org.apache.catalina.loader.WebappLoader

The managed objects in the JSR-77 object hierarchy correspond to the specified MBean names or groups as follows:

JSR-77 Managed Object	MBean Name or Group	评论，建议
J2EEServer	<Service>
Node	<Service>	Tomcat supports a single node only.
port(端口)	connector
Servlet	包?
WebModule	<Context>

The deployment objects in the JSR-88 API object hierarchy correspond to the specified MBean names or groups as follows:

JSR-88 API Object	MBean Name or Group	评论，建议
DeployableObject	<Context>	Context deployment info plus the corresponding WAR file
目标	<Host>