不建议直接在 server.xml 文件中放置 <Context> 元素。
这是因为修改
Context
配置会更具侵入性,因为无法在不重新启动 Tomcat 的情况下重新加载主
conf/server.xml
文件。默认
Context
元素(见下文)还将
覆盖
直接放置在 server.xml 中的任何 <Context> 元素的配置。为防止这种情况,应将 server.xml 中定义的 <Context> 元素的
override
属性设置为
true
。
可以明确定义各个
Context
元素
在应用程序文件中的
/META-INF/context.xml
中的单个文件中。根据主机的 copyXML 属性,可以将其复制到
$CATALINA_BASE/conf/[enginename]/[hostname]/
并重命名为应用程序的基本文件名加上 ".xml" 扩展名。
在
$CATALINA_BASE/conf/[enginename]/[hostname]/
目录中的单个文件(带有 ".xml" 扩展名)中。上下文路径和版本将从文件的基名(文件名减去 .xml 扩展名)派生。此文件始终优先于打包在 Web 应用程序的 META-INF 目录中的任何 context.xml 文件。
在主
conf/server.xml
中的
Host
元素内。
可以定义适用于多个 Web 应用程序的默认
Context
元素。单个 Web 应用程序的配置将覆盖在其中一个默认值中配置的任何内容。在默认
Context
中定义的任何嵌套元素(例如 <Resource> 元素)将为应用默认值的每个
Context
创建一次。它们
不会
在
Context
元素之间共享。
在
$CATALINA_BASE/conf/context.xml
文件中:所有 Web 应用程序都将加载 Context 元素信息。
在
$CATALINA_BASE/conf/[enginename]/[hostname]/context.xml.default
文件中:所有该主机的 Web 应用程序都将加载 Context 元素信息。
除了 server.xml 之外,定义
Context
元素的文件只能定义一个
Context
元素。
除了明确指定的 Context 元素之外,还有几种技术可以自动为您创建 Context 元素。有关更多信息,请参阅
自动应用程序部署
和
用户 Web 应用程序
。
要定义使用单个 WAR 文件或目录的多个上下文,请使用上面
命名
部分中描述的选项之一,为
Context
创建一条与基本文件名无关的路径。
Context
的所有实现都支持以下属性
allowCasualMultipartParsing
当调用 HttpServletRequest.getPart* 或 HttpServletRequest.getParameter* 时,如果 Tomcat 应该自动解析 multipart/form-data 请求正文,即使目标 servlet 未标记为 @MultipartConfig 注释(有关详细信息,请参阅 Servlet 规范 3.0,第 3.2 节)。请注意,除了
false
之外的任何设置都会导致 Tomcat 以技术上不符合规范的方式运行。默认值为
false
。
allowMultipleLeadingForwardSlashInPath
Tomcat 将 URI 中的多个
/
字符序列规范化为单个
/
。这是为了与文件系统的行为保持一致,因为 URI 通常会转换为文件系统路径。因此,对于某些 URI,
HttpServletRequest#getContextPath()
的返回值应以多个
/
字符开头。如果将此值直接与
HttpServletResponse#sendRedirect()
一起使用,则会出现问题,因为以
//
开头的重定向路径被视为与协议相关的重定向。为了避免潜在问题,Tomcat 会将
HttpServletRequest#getContextPath()
返回值开头的多个前导
/
字符折叠为单个
/
。此属性的默认值为
false
,它启用折叠多个
/
字符。要禁用此行为,请将此属性设置为
true
。
altDDName
此上下文的备用部署描述符的绝对路径。这将覆盖位于
/WEB-INF/web.xml
的默认部署描述符。
alwaysAccessSession
如果此值为
true
,则与会话关联的每个请求都会导致会话的最后访问时间更新,无论请求是否明确访问会话。
如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
设置为
true
,则此设置的默认值为
true
,否则默认值为
false
。
backgroundProcessorDelay
此值表示在此上下文及其子容器(包括所有包装器)上调用 backgroundProcess 方法之间以秒为单位的延迟。如果其延迟值不为负(这意味着它们正在使用自己的处理线程),则不会调用子容器。将其设置为正值将导致生成一个线程。在等待指定的时间量后,该线程将在该主机及其所有子容器上调用 backgroundProcess 方法。上下文将使用后台处理来执行会话过期和类监视以进行重新加载。如果未指定,此属性的默认值为 -1,这意味着上下文将依赖其父主机的后台处理线程。
className
要使用的实现的 Java 类名。此类必须实现
org.apache.catalina.Context
接口。如果未指定,将使用标准值(如下定义)。
containerSciFilter
指定应过滤掉哪些容器提供的 SCI 并不用于此上下文的正则表达式。匹配使用
java.util.regex.Matcher.find()
,因此正则表达式只需匹配容器提供的 SCI 的完全限定类名的子字符串,即可将其过滤掉。如果未指定,则不应用任何过滤。
contextGetResourceRequiresSlash
如果为
true
,则传递给
ServletContext.getResource()
或
ServletContext.getResourceAsStream()
的路径必须以“/”开头。如果为
false
,则代码(如
getResource("myfolder/myresource.txt")
)将起作用,因为 Tomcat 会在提供的路径前加上“/”。
如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
设置为
true
,则此设置的默认值为
true
,否则默认值为
false
。
cookies
如果希望在客户端支持的情况下使用 cookie 进行会话标识符通信,则设置为
true
(这是默认设置)。如果希望禁用使用 cookie 进行会话标识符通信,并且仅依赖应用程序的 URL 重写,则设置为
false
。
createUploadTargets
如果 Tomcat 应尝试为 Servlet 创建
MultipartConfig
中指定的临时上传位置(如果该位置尚不存在),则设置为
true
。如果未指定,则使用默认值
false
。
crossContext
如果希望此应用程序中对
ServletContext.getContext()
的调用成功返回对在此虚拟主机上运行的其他 Web 应用程序的请求分派器,则设置为
true
。在注重安全的环境中设置为
false
(默认设置),以使
getContext()
始终返回
null
。
dispatcherWrapsSameObject
如果为
true
,则传递给应用程序分派器的任何包装请求或响应对象都将被检查,以确保它已包装原始请求或响应。
如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
设置为
true
,则此设置的默认值为
true
,否则默认值为
false
。
docBase
此 Web 应用程序的
文档根目录
(也称为
上下文根目录
),或 Web 应用程序归档文件(如果此 Web 应用程序直接从 WAR 文件执行)的路径名。您可以为此目录或 WAR 文件指定绝对路径名,或相对于所有者
Host
的
appBase
目录的路径名。
除非在 server.xml 中定义了 Context 元素,或者
docBase
不位于
Host
的
appBase
下,否则不得设置此字段的值。
如果对
docBase
使用符号链接,则对符号链接的更改仅在 Tomcat 重新启动或取消部署并重新部署上下文后才有效。上下文重新加载是不够的。
dispatchersUseEncodedPaths
控制在调用中用于获取请求分发器时是否需要对路径进行编码。这会影响 Tomcat 处理获取请求分发器的调用方式,以及 Tomcat 在内部生成用于获取请求分发器的路径方式。如果未指定,则使用默认值
true
。在对请求分发器的路径进行编码/解码时,始终使用 UTF-8。
failCtxIfServletStartFails
设置为
true
,如果任何 load-on-startup >=0 的 servlet 无法启动,则让上下文启动失败。
如果未指定,则使用父级 Host 配置中同名属性(如果已指定)。否则,使用默认值
false
。
fireRequestListenersOnForwards
设置为
true
,当 Tomcat 转发请求时触发任何已配置的 ServletRequestListeners。这主要适用于使用 ServletRequestListeners 来为请求配置必要环境的 CDI 框架用户。如果未指定,则使用默认值
false
。
logEffectiveWebXml
如果希望在应用程序启动时记录用于 Web 应用程序的有效 web.xml(在 INFO 级别),则设置为
true
。有效 web.xml 是将应用程序的 web.xml 与 Tomcat 配置的任何默认值以及发现的任何 web-fragment.xml 文件和注释相结合的结果。如果未指定,则使用默认值
false
。
mapperContextRootRedirectEnabled
如果启用,则 Mapper 而不是默认 Servlet 将根据需要重定向 Web 应用程序上下文根的请求(添加尾部斜杠)。这效率更高,但会产生确认上下文路径存在的副作用。如果未指定,则使用默认值
true
。
mapperDirectoryRedirectEnabled
如果启用,则 Mapper 而不是默认 Servlet 将根据需要重定向 Web 应用程序目录的请求(添加尾部斜杠)。这效率更高,但会产生确认目录存在的副作用。如果未指定,则使用默认值
false
。
override
设置为
true
以忽略全局或
Host
默认上下文中的任何设置。默认情况下,将使用默认上下文中的设置,但可以通过明确为 Context 设置相同的属性来覆盖这些设置。
parallelAnnotationScanning
设置为
true
时,将使用实用程序执行器执行注释扫描。它允许并行处理扫描,这可能会以更高的服务器负载为代价提高部署类型。如果未指定,则使用默认值
false
。
此 Web 应用程序的
上下文路径
,它与每个请求 URI 的开头进行匹配,以选择要处理的适当 Web 应用程序。特定
主机
中的所有上下文路径必须唯一。如果您指定一个空字符串 ("") 的上下文路径,则您正在定义此主机的
默认
Web 应用程序,它将处理未分配给其他上下文的请求。
此属性只能在 server.xml 中静态定义上下文时使用。在所有其他情况下,路径将从用于 .xml 上下文文件或
docBase
的文件名推断出来。
即使在 server.xml 中静态定义上下文时,也必须不设置此属性,除非
docBase
不位于
主机
的
appBase
下,或者
deployOnStartup
和
autoDeploy
都是
false
。如果不遵循此规则,则可能会导致重复部署。
preemptiveAuthentication
设置为
true
,并且用户为不受安全约束保护的资源提供凭据时,如果验证器支持抢先验证(Tomcat 提供的标准验证器支持),则将处理用户的凭据。如果未指定,则使用默认值
false
。
privileged
设置为
true
以允许此上下文使用容器 servlet,例如管理器 servlet。使用
privileged
属性会将上下文的父类加载器更改为
服务器
类加载器,而不是
共享
类加载器。请注意,在默认安装中,
公共
类加载器用于
服务器
和
共享
类加载器。
reloadable
如果您希望 Catalina 监视
/WEB-INF/classes/
和
/WEB-INF/lib
中的类是否有更改,并在检测到更改时自动重新加载 Web 应用程序,则将其设置为
true
。此功能在应用程序开发期间非常有用,但它需要大量的运行时开销,不建议在已部署的生产应用程序上使用。这就是此属性的默认设置为
false
的原因。但是,您可以使用
管理器
Web 应用程序按需触发已部署应用程序的重新加载。
resourceOnlyServlets
以逗号分隔的 Servlet 名称列表(如
/WEB-INF/web.xml
中所用),这些名称期望存在资源。确保与期望存在资源的 Servlet(例如 JSP Servlet)关联的欢迎文件在不存在资源时不会被使用。这避免了 Servlet 3.0 规范第 10.10 节中欢迎文件映射说明所导致的问题。如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
系统属性
设置为
true
,此属性的默认值将为空字符串,否则默认值为
jsp
。
sendRedirectBody
如果为
true
,重定向响应将包括一个简短的响应正文,其中包含 RFC 2616 推荐的重定向详细信息。默认情况下禁用此功能,因为包括响应正文可能会导致某些应用程序组件(例如压缩过滤器)出现问题。
sessionCookieDomain
用于此上下文创建的所有会话 Cookie 的域。如果设置,这将覆盖 Web 应用程序设置的任何域。如果未设置,将使用 Web 应用程序(如果有)指定的值。
sessionCookieName
用于此上下文创建的所有会话 Cookie 的名称。如果设置,这将覆盖 Web 应用程序设置的任何名称。如果未设置,将使用 Web 应用程序(如果有)指定的值,或者如果 Web 应用程序未明确设置一个名称,则使用名称
JSESSIONID
。
sessionCookiePath
用于此上下文创建的所有会话 Cookie 的路径。如果设置,这将覆盖 Web 应用程序设置的任何路径。如果未设置,将使用 Web 应用程序指定的值,或者如果 Web 应用程序未明确设置一个路径,则使用上下文路径。要配置所有 Web 应用程序以使用空路径(这对于端口小程序规范实现可能很有用),请在全局
CATALINA_BASE/conf/context.xml
文件中将此属性设置为
/
。
注意:一旦使用
sessionCookiePath="/"
的 Web 应用程序获得会话,则在同一主机中任何其他 Web 应用程序的所有后续会话(也配置了
sessionCookiePath="/"
)也将始终使用相同的会话 ID。即使会话无效并创建了新会话,这一点也成立。这使得会话固定保护变得更加困难,并且需要自定义的特定于 Tomcat 的代码来更改多个应用程序共享的会话 ID。
sessionCookiePathUsesTrailingSlash
某些浏览器,例如 Internet Explorer、Safari 和 Edge,会为路径为
/foo
的上下文发送会话 cookie,并违反 RFC6265 向
/foobar
发出请求。这可能会将部署在
/foo
中的应用程序的会话 ID 暴露给部署在
/foobar
中的应用程序。如果部署在
/foobar
中的应用程序不受信任,则可能会产生安全风险。但是,应注意 RFC 6265 第 8.5 节明确指出,仅凭路径不足以防止不受信任的应用程序访问其他应用程序中的 cookie。为了减轻此风险,可以将此属性设置为
true
,Tomcat 会将尾部斜杠添加到与会话 cookie 关联的路径中,因此,在上述示例中,cookie 路径变为 /foo/。但是,对于 cookie 路径 /foo/,浏览器将不再使用请求向 /foo 发送 cookie。除非 servlet 映射到 /*,否则这不会成为问题。在这种情况下,需要将此属性设置为
false
以禁用此功能。此属性的默认值为
false
。
suspendWrappedResponseAfterForward
如果此标志的值为
true
,Catalina 会在转发后暂停包装的响应,而不是关闭它们。如果未指定,则该标志的默认值为
false
。
swallowAbortedUploads
如果 Tomcat
不
应该读取已中止上传的任何其他请求正文数据,而应该中止客户端连接,则将其设置为
false
。此设置用于以下情况
请求正文的大小大于连接器中配置的
maxPostSize
达到多部分上传的大小限制
servlet 将响应状态设置为 413(请求实体过大)
不读取其他数据将更快地释放请求处理线程。遗憾的是,如果 HTTP 客户端无法写入完整请求,则大多数客户端将不会读取响应。
默认值为
true
,因此将读取其他数据。
请注意,如果在触发 5xx 响应的请求处理期间发生错误,则将始终忽略任何未读请求数据,并且一旦写入错误响应,客户端连接将关闭。
swallowOutput
如果此标志的值为
true
,则 Web 应用程序输出到 System.out 和 System.err 的字节将重定向到 Web 应用程序日志记录器。如果未指定,则该标志的默认值为
false
。
tldValidation
如果此标志的值为
true
,则 TLD 文件将在上下文启动时通过 XML 验证。如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
系统属性
设置为
true
,则此属性的默认值将为
true
,否则默认值为
false
。将此属性设置为
true
会导致性能下降。
useBloomFilterForArchives
已弃用:如果为
true
,则将使用布隆过滤器来加速归档查找。对于包含大量 JAR 的 Web 应用程序,这有助于提高部署速度。
如果未指定,则将使用默认值
false
。
此值可被
资源
中的 archiveIndexStrategy 覆盖
useHttpOnly
是否应在会话 Cookie 上设置 HttpOnly 标志以防止客户端脚本访问会话 ID?默认为
true
。
usePartitioned
是否应在会话 Cookie 上设置 Partitioned 标志?默认为
false
。
注意:用于表示分区 Cookie 的属性名称作为
CHIPS
的一部分尚未由 RFC 定义,并且一旦 RFC 中包含等效功能,可能会以不向后兼容的方式进行更改。
useRelativeRedirects
控制由对
jakarta.servlet.http.HttpServletResponse#sendRedirect(String)
的调用生成的 HTTP 1.1 及更高版本的 location 标头是否将使用相对或绝对重定向。相对重定向更有效,但可能无法与更改上下文路径的反向代理配合使用。需要注意的是,不建议使用反向代理来更改上下文路径,因为它会产生多个问题。绝对重定向应该可以与更改上下文路径的反向代理配合使用,但如果过滤器更改了方案和/或端口,则可能会导致
org.apache.catalina.filters.RemoteIpFilter
出现问题。如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
系统属性
设置为
true
,则此属性的默认值将为
false
,否则默认值为
true
。
validateClientProvidedNewSessionId
当客户端提供新会话的 ID 时,此属性控制是否验证该 ID。使用客户端提供的会话 ID 的唯一用例是在多个 Web 应用程序中使用一个公共会话 ID。因此,任何客户端提供的会话 ID 都应该已经存在于另一个 Web 应用程序中。如果启用此检查,则仅当会话 ID 至少存在于当前主机的另一个 Web 应用程序中时,才会使用客户端提供的会话 ID。请注意,始终应用以下附加测试,无论此设置如何
会话 ID 由 Cookie 提供
会话 Cookie 的路径为 {@code /}
如果未指定,将使用默认值
true
。
wrapperClass
此 Context 管理的 Servlet 将使用的
org.apache.catalina.Wrapper
实现类的 Java 类名。如果未指定,将使用标准默认值。
xmlBlockExternal
如果此标志的值为
true
,则此 Web 应用程序的
web.xml
、
web-fragment.xml
、
tomcat-web.xml
、
*.tld
、
*.jspx
、
*.tagx
和
tagPlugins.xml
文件的解析将不允许加载外部实体。如果未指定,将使用默认值
true
。
xmlNamespaceAware
如果此标志的值为
true
,则此 Web 应用程序的
web.xml
、
web-fragment.xml
和
tomcat-web.xml
文件的解析将支持命名空间。请注意,
*.tld
、
*.jspx
和
*.tagx
文件始终使用支持命名空间的解析器进行解析,并且
tagPlugins.xml
文件(如果存在)永远不会使用支持命名空间的解析器进行解析。另请注意,如果您打开此标志,您可能还应该打开
xmlValidation
。如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
系统属性
设置为
true
,则此属性的默认值为
true
,否则默认值为
false
。将此属性设置为
true
会产生性能损失。
xmlValidation
如果此标志的值为
true
,则此 Web 应用程序的
web.xml
、
web-fragment.xml
和
tomcat-web.xml
文件的解析将使用验证解析器。如果
org.apache.catalina.STRICT_SERVLET_COMPLIANCE
系统属性
设置为
true
,则此属性的默认值为
true
,否则默认值为
false
。将此属性设置为
true
会产生性能损失。
addWebinfClassesResources
此属性控制除了从 Web 应用程序 JAR 文件中的
META-INF/resources
提供静态资源外,是否还从
WEB-INF/classes/META-INF/resources
提供静态资源。这仅适用于主版本为 3 或更高版本的 Web 应用程序。由于这是 Servlet 3 规范的专有扩展,因此默认情况下禁用它。要启用此功能,请将属性设置为
true
。
antiResourceLocking
如果为
true
,Tomcat 将阻止任何文件锁定。这将显著影响应用程序的启动时间,但允许在可能发生文件锁定的平台或配置上完全部署和取消部署 Web 应用程序。如果未指定,则默认值为
false
。
请注意,将此项设置为
true
会产生一些副作用,包括禁用正在运行的服务器中的 JSP 重新加载:请参阅
Bugzilla 37668
。
请注意,在主机(默认情况下为
webapps
目录)的
appBase
之外的应用程序中将此标志设置为
true
将导致应用程序在 Tomcat 关闭时被
删除
。您可能不想这样做,因此在对位于其主机的
appBase
之外的 Web 应用程序设置 antiResourceLocking=true 之前三思而后行。
clearReferencesHttpClientKeepAliveThread
如果为
true
,并且此 Web 应用程序已启动
sun.net.www.http.HttpClient
保持活动计时器线程并且仍在运行,则 Tomcat 会将该线程的上下文类加载器从 Web 应用程序类加载器更改为 Web 应用程序类加载器的父级,以防止内存泄漏。请注意,保持活动计时器线程将在所有保持活动都过期后自行停止,但是,在繁忙的系统上,这可能需要一段时间。如果未指定,则将使用默认值
true
。
clearReferencesObjectStreamClassCaches
如果为
true
,则在停止 Web 应用程序时,Tomcat 会在用于序列化的
ObjectStreamClass
类中查找对 Web 应用程序加载的类的
SoftReference
,并清除它找到的任何
SoftReference
。此功能使用反射来识别
SoftReference
,因此需要设置命令行选项
-XaddExports:java.base/java.io=ALL-UNNAMED
。如果未指定,则将使用默认值
true
。
与
ObjectStreamClass
关联的内存泄漏已在 Java 19 及更高版本、Java 17.0.4 及更高版本和 Java 11.0.16 及更高版本中修复。在运行包含此修复程序的 Java 版本时,将禁用此检查。
clearReferencesRmiTargets
如果为
true
,则 Tomcat 会查找与 RMI 目标关联的内存泄漏,并清除它找到的任何泄漏。此功能使用反射来识别泄漏,因此需要设置命令行选项
-XaddExports:java.rmi/sun.rmi.transport=ALL-UNNAMED
。没有内存泄漏的应用程序应使用将此属性设置为
false
的方式正常运行。如果未指定,则将使用默认值
true
。
clearReferencesStopThreads
如果为
true
,Tomcat 将尝试终止 Web 应用程序已启动的线程。通过已弃用的(出于充分的理由)
Thread.stop()
方法停止线程,并且可能会导致不稳定。因此,启用此功能应被视为开发环境中的最后选择,不建议在生产环境中使用。如果未指定,将使用默认值
false
。如果启用此功能,Web 应用程序可能需要长达两秒的时间才能停止,因为执行器线程在对任何剩余线程调用
Thread.stop()
之前最多有两秒的时间可以正常停止。
clearReferencesStopTimerThreads
如果为
true
,Tomcat 将尝试终止 Web 应用程序已启动的
java.util.Timer
线程。与标准线程不同,计时器线程可以安全地停止,尽管应用程序仍可能存在副作用。如果未指定,将使用默认值
false
。
clearReferencesThreadLocals
如果为
true
,Tomcat 将尝试清除已使用 Web 应用程序加载的类填充的
java.lang.ThreadLocal
变量。如果未指定,将使用默认值
true
。
copyXML
如果希望将嵌入在应用程序中的上下文 XML 描述符(位于
/META-INF/context.xml
)在应用程序部署时复制到所有者
Host
的
xmlBase
,请将其设置为
true
。在后续启动时,将优先使用已复制的上下文 XML 描述符,而不是嵌入在应用程序中的任何上下文 XML 描述符,即使嵌入在应用程序中的描述符较新。默认值为
false
。请注意,如果所有者
Host
的
deployXML
属性为
false
,或者所有者
Host
的
copyXML
属性为
true
,则此属性将不起作用。
jndiExceptionOnFailedWrite
如果为
true
,则应用程序尝试通过调用 bind()、unbind()、createSubContext()、destroySubContext() 或 close() 来修改提供的 JNDI 上下文,将触发
javax.naming.OperationNotSupportedException
,如 Jakarta EE 规范的 EE.5.3.4 部分所要求的。可以通过将此属性设置为
false
来禁用此异常,在这种情况下,任何修改 JNDI 上下文的调用都将返回,
不会
进行任何更改,并且返回值的函数将返回
null
。如果未指定,将使用符合规范的默认值
true
。
renewThreadsWhenStoppingContext
如果为
true
,当此上下文停止时,Tomcat 会更新用于为该上下文提供服务的线程池中的所有线程。这也要求在
server.xml
中配置
ThreadLocalLeakPreventionListener
,并且
Executor
的
threadRenewalDelay
属性大于等于 0。如果未指定,将使用默认值
true
。
skipMemoryLeakChecksOnJvmShutdown
如果为
true
,如果 Web 应用程序作为 JVM 关闭的一部分停止,Tomcat 将不会在 Web 应用程序停止时执行通常的内存泄漏检查。如果未指定,将使用默认值
false
。
unloadDelay
容器将等待 servlet 卸载的毫秒数。如果未指定,默认值为
2000
毫秒。
unpackWAR
如果为
false
,将覆盖所有者
Host
的
unpackWARs
属性,并且不会解压 WAR 文件。如果为
true
,所有者
Host
的
unpackWARs
属性的值将决定是否解压 WAR。如果未指定,默认值为
true
。
useNaming
设置为
true
(默认值)以使 Catalina 为此 Web 应用程序启用与 Jakarta EE 平台约定兼容的 JNDI
InitialContext
。
workDir
此上下文提供的临时读写目录的路径名,供关联 Web 应用程序中的 servlet 临时使用。此目录将通过名为
jakarta.servlet.context.tempdir
的 servlet 上下文属性(类型为
java.io.File
)对 Web 应用程序中的 servlet 可见,如 Servlet 规范中所述。如果未指定,将提供
$CATALINA_BASE/work
下的合适目录。
Cookie 处理器
- 配置 HTTP cookie 标头的解析和生成。
加载器
- 配置将用于加载此 Web 应用程序的 servlet 和 bean 类的 Web 应用程序类加载器。通常,类加载器的默认配置就足够了。
管理器
- 配置将用于创建、销毁和持久化此 Web 应用程序的 HTTP 会话的会话管理器。通常,会话管理器的默认配置就足够了。
领域
- 配置一个领域,该领域将允许其用户数据库及其关联的角色仅用于此特定 Web 应用程序。如果未指定,此 Web 应用程序将利用与所有
主机
或
引擎
关联的领域。
资源
- 配置将用于访问与此 Web 应用程序关联的静态资源的资源管理器。通常,资源管理器的默认配置就足够了。
WatchedResource
- 自动部署器将监视 Web 应用程序的指定静态资源以进行更新,如果更新了资源,它将重新加载 Web 应用程序。此元素的内容必须是字符串。
JarScanner
- 配置将用于扫描 Web 应用程序以查找 JAR 文件和类文件目录的 Jar 扫描器。它通常在 Web 应用程序启动期间用于识别必须作为 Web 应用程序初始化的一部分进行处理的配置文件,例如 TLD 或 web-fragment.xml 文件。通常,默认的 Jar 扫描器配置就足够了。
上下文与
org.apache.catalina.core.ContainerBase.[enginename].[hostname].[path]
日志类别相关联。请注意,括号实际上是名称的一部分,不要省略它们。
当您运行 Web 服务器时,通常生成的一个输出文件是
访问日志
,它会为服务器处理的每个请求生成一行信息,采用标准格式。Catalina 包含一个可选的
阀
实现,它可以创建与 Web 服务器创建的相同标准格式的访问日志,或以任意数量的自定义格式创建访问日志。
您可以通过嵌套
阀
元素来要求 Catalina 为
引擎
、
主机
或
上下文
处理的所有请求创建访问日志,如下所示
<Context>
<Valve className="org.apache.catalina.valves.AccessLogValve"
prefix="localhost_access_log" suffix=".txt"
pattern="common"/>
</Context>
有关受支持的配置属性的更多信息,请参阅
访问日志阀
。
如果您尚未声明自己的
管理器
元素,则将配置标准会话管理器。
如果您尚未声明自己的
资源
元素,将配置标准资源管理器。
conf/web.xml
中列出的 Web 应用程序属性将作为此 Web 应用程序的默认值进行处理。这用于建立默认映射(例如将
*.jsp
扩展名映射到相应的 JSP servlet)以及适用于所有 Web 应用程序的其他标准功能。
如果此 Web 应用程序的
/WEB-INF/tomcat-web.xml
资源中列出了 Web 应用程序属性,将对其进行处理(如果此资源存在),优先于默认值。
如果此 Web 应用程序的
/WEB-INF/web.xml
资源中列出了 Web 应用程序属性,将对其进行处理(如果此资源存在)。
如果您的 Web 应用程序指定了可能需要用户身份验证的安全约束,将配置一个适当的 Authenticator 来实现您选择的登录方法。
上下文参数
您可以配置命名值,这些值将通过在此元素内嵌套
<Parameter>
元素作为 servlet 上下文初始化参数对 Web 应用程序可见。例如,您可以像这样创建一个初始化参数
<Context>
<Parameter name="companyName" value="My Company, Incorporated"
override="false"/>
</Context>
这等效于在 Web 应用程序部署描述符 (
/WEB-INF/web.xml
) 中包含以下元素
<context-param>
<param-name>companyName</param-name>
<param-value>My Company, Incorporated</param-value>
</context-param>
但
不需要
修改部署描述符来自定义此值。
<Parameter>
元素的有效属性如下
此上下文初始化参数的可选、人类可读说明。
要创建的上下文初始化参数的名称。
override
如果您
不
希望 Web 应用程序部署描述符中找到的具有相同参数名称的
<context-param>
覆盖此处指定的值,请将其设置为
false
。默认情况下,允许覆盖。
当通过调用
ServletContext.getInitParameter()
请求时,将向应用程序显示的参数值。
<env-entry-name>maxExemptions</env-entry-name>
<env-entry-value>10</env-entry-value>
<env-entry-type>java.lang.Integer</env-entry-type>
</env-entry>
但
不需要
修改部署描述符来自定义此值。
<Environment>
元素的有效属性如下
此环境条目的可选、人类可读说明。
相对于
java:comp/env
上下文创建的环境条目的名称。
override
如果您
不
希望 Web 应用程序部署描述符中找到的具有相同环境条目名称的
<env-entry>
覆盖此处指定的值,请将其设置为
false
。默认情况下,允许覆盖。
此环境条目要求 Web 应用程序提供的完全限定 Java 类名称。必须是 Web 应用程序部署描述符中
<env-entry-type>
的合法值。
从 JNDI 上下文请求时将显示给应用程序的参数值。此值必须可转换为
type
属性定义的 Java 类型。
生命周期侦听器
如果您已实现了一个需要知道此
Context
何时启动或停止的 Java 对象,则可以通过在此元素内嵌套一个
Listener
元素来声明它。您指定的类名称必须实现
org.apache.catalina.LifecycleListener
接口,并且该类必须打包到 jar 中并放置在
$CATALINA_HOME/lib
目录中。它将收到有关相应生命周期事件发生的通知。此类侦听器的配置如下所示
<Context>
<Listener className="com.mycompany.mypackage.MyListener" ... >
</Context>
请注意,侦听器可以具有任意数量的其他属性,这些属性可通过此元素进行配置。属性名称与相应的 JavaBean 属性名称匹配,使用标准属性方法命名模式。
请求过滤器
您可以要求 Catalina 在发送到周围
Engine
、
Host
或
Context
元素的每个传入请求中检查 IP 地址或主机名。将根据使用
java.util.regex
正则表达式语法定义的已配置“接受”和/或“拒绝”筛选器检查远程地址或名称。来自未接受的位置的请求将被拒绝,并显示 HTTP“禁止”错误。示例筛选器声明
<Context>
<Valve className="org.apache.catalina.valves.RemoteHostValve"
allow=".*\.mycompany\.com|www\.yourcompany\.com"/>
<Valve className="org.apache.catalina.valves.RemoteAddrValve"
deny="192\.168\.1\.\d+"/>
</Context>
有关所支持的配置选项的更多信息,请参阅
远程地址筛选器
和
远程主机筛选器
。
您可以声明为 Web 应用程序部署描述符中
<resource-ref>
和
<resource-env-ref>
元素的 JNDI 查找返回的资源的特征。您
必须
还将所需的资源参数定义为
Resource
元素的属性,以配置要使用的对象工厂(如果 Tomcat 尚未知道)以及用于配置该对象工厂的属性。
例如,您可以创建如下资源定义
<Context>
<Resource name="jdbc/EmployeeDB" auth="Container"
type="javax.sql.DataSource"
description="Employees Database for HR Applications"/>
</Context>
这等效于在 Web 应用程序部署描述符 (
/WEB-INF/web.xml
) 中包含以下元素
<resource-ref>
<description>Employees Database for HR Applications</description>
<res-ref-name>jdbc/EmployeeDB</res-ref-name>
<res-ref-type>javax.sql.DataSource</res-ref-type>
<res-auth>Container</res-auth>
</resource-ref>
但
不需要
修改部署描述符来自定义此值。
<Resource>
元素的有效属性如下
指定 Web 应用程序代码是否以编程方式登录到相应的资源管理器,或者容器是否代表应用程序登录到资源管理器。此属性的值必须为
Application
或
Container
。如果 Web 应用程序将在 Web 应用程序部署描述符中使用
<resource-ref>
元素,则此属性是
必需的
,但如果应用程序使用
<resource-env-ref>
,则此属性是可选的。
closeMethod
当不再需要单例资源时,调用该资源的零参数方法的名称。此方法旨在加快资源的清理速度,否则这些资源将作为垃圾回收的一部分进行清理。如果
singleton
属性为
false
,则忽略此属性。
对于实现
AutoCloseable
的
javax.sql.DataSource
和
javax.sql.XADataSource
资源(例如 Apache Commons DBCP 2 和默认的 Apache Tomcat 连接池),此属性默认为
close
。可以通过将该属性设置为一个空字符串来禁用此属性。对于所有其他资源类型,未定义任何默认值,并且默认情况下不会调用任何关闭方法。
此资源的可选人类可读描述。
要创建的资源的名称,相对于
java:comp/env
上下文。
指定是否可以通过此资源管理器共享获得的连接。此属性的值必须为
Shareable
或
Unshareable
。默认情况下,假定连接是可共享的。
指定此资源定义是否适用于单例资源,即资源只有一个实例。如果此属性为
true
,则对该资源的多个 JNDI 查找将返回同一个对象。如果此属性为
false
,则对该资源的多个 JNDI 查找将返回不同的对象。对于
javax.sql.DataSource
资源,此属性必须为
true
,才能启用 DataSource 的 JMX 注册。此属性的值必须为
true
或
false
。默认情况下,此属性为
true
。
Web 应用程序在查找此资源时预期的完全限定 Java 类名称。
Web 应用程序在查找此资源链接时预期的完全限定 Java 类名称。
创建这些对象的类的完全限定 Java 类名称。此类应实现
javax.naming.spi.ObjectFactory
接口。
当属性
factory="org.apache.naming.factory.DataSourceLinkFactory"
时,资源链接可以使用两个附加属性,以允许使用具有不同凭据的共享数据源。当这两个附加属性与
javax.sql.DataSource
类型结合使用时,不同的上下文可以使用具有不同凭据的全局数据源。从本质上讲,发生的情况是调用
getConnection()
仅仅被转换为在全局数据源上调用
getConnection(username, password)
。这是一种简便的方法,可以使代码对正在使用的模式透明,但仍能够在全局配置中控制连接(或池)。
username
在链接的全局 DataSource 上调用
getConnection(username, password)
的值。
password
在链接的全局 DataSource 上调用
getConnection(username, password)
的值。
共享数据源示例
警告:
此功能仅在全局 DataSource 支持
getConnection(username, password)
方法时才有效。Tomcat 默认使用的
Apache Commons DBCP 2
池不支持它。请参阅其
BasicDataSource
类的 Javadoc。
Apache Tomcat JDBC 池
确实支持它,但默认情况下此支持被禁用,可以通过
alternateUsernameAllowed
属性启用。有关详细信息,请参阅其文档。
<GlobalNamingResources>
<Resource name="sharedDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
factory="org.apache.tomcat.jdbc.pool.DataSourceFactory"
alternateUsernameAllowed="true"
username="bar"
password="barpass"
</GlobalNamingResources>
<Context path="/foo"...>
<ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
factory="org.apache.naming.factory.DataSourceLinkFactory"
username="foo"
password="foopass"
</Context>
<Context path="/bar"...>
<ResourceLink
name="appDataSource"
global="sharedDataSource"
type="javax.sql.DataSource"
</Context>
当在
/foo
上下文中发出
getConnection()
请求时,该请求将转换为
getConnection("foo","foopass")
,而
/bar
中的请求将直接通过。
您可以声明要为
java:comp/UserTransaction
的 JNDI 查找返回的 UserTransaction 的特征。您
必须
定义一个对象工厂类来实例化此对象以及所需的资源参数作为
Transaction
元素的属性,以及用于配置该对象工厂的属性。
<Transaction>
元素的有效属性如下
JNDI 对象工厂的类名。