Tomcat翻译--The Host Container

原文：http://tomcat.apache.org/tomcat-7.0-doc/config/host.html

Introduction(介绍)

The Host element represents a virtual host, which is an association of a network name for a server (such as "www.mycompany.com" with the particular server on which Tomcat is running. For clients to be able to connect to a Tomcat server using its network name, this name must be registered in the Domain Name Service (DNS) server that manages the Internet domain you belong to - contact your Network Administrator for more information.

[Host元素代表一个虚拟主机，虚拟主机是指与一个服务器相关联的网络名。为了使客户端能够通过网络名连接上Tomcat服务器，因此该网络名必须在DNS中注册。]

In many cases, System Administrators wish to associate more than one network name (such as www.mycompany.com and company.com) with the same virtual host and applications. This can be accomplished using the Host Name Aliases feature discussed below.

[在许多情况下，系统管理员都会希望同一个虚拟主机和应用关联多个网络名(比如www.mycompany.com和company.com)，这个功能可以通过下面讨论的Host Name Alises特性实现。]

One or more Host elements are nested inside an Engine element. Inside the Host element, you can nest Context elements for the web applications associated with this virtual host. Exactly one of the Hosts associated with each Engine MUST have a name matching the defaultHost attribute of that Engine.

[一个Engine元素中可以嵌套多个Host元素，在Host元素中，你可以嵌套多个Context元素。嵌套的多个Host元素中，只能有一个Host的名称与Engine元素中的defaultHost属性相同。]

Clients normally use host names to identify the server they wish to connect to. This host name is also included in the HTTP request headers. Tomcat extracts the host name from the HTTP headers and looks for a Host with a matching name. If no match is found, the request is routed to the default host. The name of the default host does not have to match a DNS name (although it can) since any request where the DNS name does not match the name of a Host element will be routed to the default host.

[客户端通常会使用主机名来识别它想要连接的服务器。HTTP请求头中也包含主机名，Tomcat从HTTP头中解析出主机名并寻找匹配的Host元素，如果没有找到，则请求被路由到默认主机。默认主机的名称不需要匹配一个DNS名称(尽管可以这么做)，因为所有不与Host元素名称相匹配的DNS名称的请求都会被路由到该默认主机。]

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have not configured Tomcat for multiple instances by setting a CATALINA_BASE directory, then $CATALINA_BASE will be set to the value of $CATALINA_HOME, the directory into which you have installed Tomcat.

[下文中，大多数相对路径都是以$CATALINA_BASE为基目录。如果你没有通过设置CATALINA_BASE目录来配置多个Tomcat实例，则其值和Tomcat的安装目录$CATALINA_HOME是相同的。]

Attributes(属性)

Common Attributes(公共属性)

All implementations of Host support the following attributes:

[所有Host实现都支持如下属性：

这里只列举出了我可能会用到的属性，其他属性见Tomcat中相应的文档。]

属性	描述
appBase	The Application Base directory for this virtual host. This is the pathname of a directory that may contain web applications to be deployed on this virtual host. You may specify an absolute pathname, or a pathname that is relative to the $CATALINA_BASE directory. See Automatic Application Deployment for more information on automatic recognition and deployment of web applications. If not specified, the default of webapps will be used. [该虚拟主机的应用程序基目录(Application Base directory)。该路径名或者目录中包含有待部署到该虚拟主机上的web应用，可以使用绝对路径名，或者是相对于$CATALINA_BASE目录的相对路径名。参考Automatic Application Deployment来获取关于自动识别和部署web应用的更多信息。如果没有指定该参数，则使用缺省值webapps。]
xmlBase	The XML Base directory for this virtual host. This is the pathname of a directory that may contain context XML descriptors to be deployed on this virtual host. You may specify an absolute pathname for this directory, or a pathname that is relative to the $CATALINA_BASE directory. See Automatic Application Deployment for more information on automatic recognition and deployment of web applications. If not specified the default of conf/<engine_name>/<host_name> will be used. [该虚拟主机的XML基目录(XML Base directory)。该路径名或目录中包含有待部署到该虚拟主机上的web应用中的xml描述文件(context XML descriptor)，可以使用绝对路径名，或者是相对于$CATALINA_BASE目录的相对路径名。参考Automatic Application Deployment来获取关于自动识别和部署web应用的更多信息。如果没有指定该参数，则使用缺省值conf/<engine_name>/<host_name>。]
createDirs	If set to true, Tomcat will attempt to create the directories defined by the attributes appBase and xmlBase during the startup phase. The default value is true. If set to true, and directory creation fails, an error message will be printed out but will not halt the startup sequence. [如果设为true，Tomcat会在启动阶段尝试创建在appBase和xmlBase属性中定义的目录，如果创建失败，错误信息将会被打印出，但启动程序不会被中止。该属性的缺省值是true。]
autoDeploy	This flag value indicates if Tomcat should check periodically for new or updated web applications while Tomcat is running. If true, Tomcat periodically checks the appBase and xmlBase directories and deploys any new web applications or context XML descriptors found. Updated web applications or context XML descriptors will trigger a reload of the web application. The flag's value defaults to true. See Automatic Application Deployment for more information. [该标志值用来让Tomcat在运行时周期性的检查是否有新的web应用被加入到服务器，或者web应用是否有更新。如果设为true，则Tomcat会周期性的检查appBase和xmlBase目录，并部署新的web应用，或者部署找到的xml描述文件(context XML descriptor)。更新web应用或者应用的xml描述文件将会触发应用的重载。该属性缺省值为true。参考Automatic Application Deployment来获取更多信息。]
className	Java class name of the implementation to use. This class must implement the org.apache.catalina.Host interface. If not specified, the standard value (defined below) will be used. [Host实现所使用的Java类名，该类必须实现org.apache.catalina.Host接口。如果没有指定，则使用标准值(定义在下面)。]
deployIgnore	A regular expression defining paths to ignore when autoDeploy and deployOnStartup are set. This allows you to keep your configuration in a version control system, for example, and not deploy a .svn or CVS folder that happens to be in the appBase. [正则表达式，用来表示当autoDeploy和deployOnStartUp被设为true时要忽略的路径。该属性允许将配置保存在一个版本管理系统中，比如，对于appBase中的.svc和CVS文件不进行部署。] This regular expression is relative to appBase. It is also anchored, meaning the match is performed against the entire file/directory name. So, foo matches only a file or directory named foo but not foo.war, foobar, or myfooapp. To match anything with "foo", you could use .*foo.*. [该正则表达式是相对于appBase而言的，并且是固定的，也就是说匹配的是整个文件或者目录的名字。因此，foo匹配的是一个名为foo的文件或目录，而不是foo.war，foobar，或者myfooapp。如果要匹配带foo的任何文件或目录，应该使用.*foo.*。] See Automatic Application Deployment for more information. [参看Automatic Application Deployment获取更多信息。]
deployOnStartup	This flag value indicates if web applications from this host should be automatically deployed when Tomcat starts. The flag's value defaults to true. See Automatic Application Deployment for more information. [该标志值用来设置当Tomcat启动时，该主机下的web应用是否被自动部署。缺省值为true。参看Automatic Application Deployment获取更多信息。]
name	Usually the network name of this virtual host, as registered in your Domain Name Service server. Regardless of the case used to specify the host name, Tomcat will convert it to lower case internally. One of the Hosts nested within an Engine MUST have a name that matches the defaultHost setting for that Engine. See Host Name Aliases for information on how to assign more than one network name to the same virtual host. [通常用来标识在DNS中注册的该虚拟主机的网络名称。无论该主机名称是大写还是小写，Tomcat都会在内部将其转换成小写。所有Host元素中的某个name属性值必须等于Engine元素中的defaultHost属性。参考Host Name Aliases获取更多关于给一个虚拟主机分配多个网络名称的信息。]

Standard Implementation(标准实现)

The standard implementation of Host is org.apache.catalina.core.StandardHost. It supports the following additional attributes (in addition to the common attributes listed above):

[Host的标准实现是org.apache.catalina.core.StandardHost，它还支持如下的附加属性：

仅列出了我可能会用到的属性，其他属性请参考Tomcat文档。]

属性	描述
copyXML	Set to true if you want a context XML descriptor embedded inside the application (located at /META-INF/context.xml) to be copied to xmlBase when the application is deployed. On subsequent starts, the copied context XML descriptor will be used in preference to any context XML descriptor embedded inside the application even if the descriptor embedded inside the application is more recent. The flag's value defaults to false. Note if deployXML is false, this attribute will have no effect. [如果设为true，则web应用被部署时，该应用中的/META-INF/context.xml文件会被拷贝到xmlBase。第二次启动Tomcat时，被复制的context xml描述文件(context xml descriptor)会优先于web应用中的/META-INF/context.xml被使用，即便/META-INF/context.xml更新。该属性的缺省值为false。注意，如果deployXML属性设为false，则该属性不会起作用。]
deployXML	Set to false if you want to disable parsing the context XML descriptor embedded inside the application (located at /META-INF/context.xml). Security conscious environments should set this to false to prevent applications from interacting with the container's configuration. The administrator will then be responsible for providing an external context configuration file, and putting it in the location defined by the xmlBase attribute. If this flag is false, a descriptor is located at /META-INF/context.xml and no descriptor is present in xmlBase then the context will fail to start in case the descriptor contains necessary configuration for secure deployment (such as a RemoteAddrValve) which should not be ignored. The flag's value defaults to true unless a security manager is enabled when the default is false. [如果设为false，则应用中/META-INF/context.xml不会被解析。对于安全性要求高的环境，应该将其设置为false来防止应用与容器的配置进行交互，此时，管理员应该提供一个外部的context配置文件，并将其放到xmlBase属性定义的目录中。如果该属性为false，且该应用只有/META-INF/context.xml文件，在xmlBase目录下没有context xml描述文件，则该应用会启动失败，以防止/META-INF/context.xml文件中包含安全部署的配置信息(比如RemoteAddrValve)。该属性缺省值为true。]
unpackWARs	Set to true if you want web applications that are placed in the appBase directory as web application archive (WAR) files to be unpacked into a corresponding disk directory structure, false to run such web applications directly from a WAR file. WAR files located outside of the Host's appBase will not be expanded. See Automatic Application Deployment for more information. [如果设为true，则appBase目录下的WAR文件会被自动解压。参考Automatic Application Deployment获取更多信息。]
workDir	Pathname to a scratch directory to be used by applications for this Host. Each application will have its own sub directory with temporary read-write use. Configuring a Context workDir will override use of the Host workDir configuration. This directory will be made visible to servlets in the web application by a servlet context attribute (of type java.io.File) named javax.servlet.context.tempdir as described in the Servlet Specification. If not specified, a suitable directory underneath $CATALINA_BASE/work will be provided. [该主机下的应用使用的临时目录的路径名。每个应用都有自己的子目录用于临时的读写。如果配置了Context元素中的workDir属性，则Host元素中的workDir属性会被覆盖。web应用中的servlet可以使用servlet context属性javax.servlet.context.tempdir来访问该目录。如果没有指定，则使用$CATALINA_BASE/work下的一个合适的目录。]

Nested Components(嵌套组件)

You can nest one or more Context elements inside this Host element, each representing a different web application associated with this virtual host.

[可以在Host元素中嵌套多个Context元素，每一个Context元素都代表在该虚拟主机下的一个web应用。]

You can nest at most one instance of the following utility components by nesting a corresponding element inside your Host element:

[可以在Host元素汇总嵌套如下的工具组件，但至多只能嵌套一个。]

Realm - Configure a realm that will allow its database of users, and their associated roles, to be shared across all Contexts nested inside this Host (unless overridden by a Realm configuration at a lower level).

[Realm - 配置realm，该realm的用户数据库以及相关的角色，可以被该Host元素下的所有Context共享(除非在低层次中覆盖了Reaml配置)。]

Special Features(专有特征)

Access Logs(访问日志)

When you run a web server, one of the output files normally generated is an access log, which generates one line of information for each request processed by the server, in a standard format. Catalina includes an optional Valve implementation that can create access logs in the same standard format created by web servers, or in any number of custom formats.

[正常情况下，运行web服务器会生成访问日志，该日志以标准格式为每个请求输出一行信息。Catalina包含一个可选的Valve实现，该实现可以用web服务器创建的标准格式或者用户自定义的格式生成访问日志。]

You can ask Catalina to create an access log for all requests processed by an Engine, Host, or Context by nesting a Valve element like this:

[通过在Engine、Host或者Context中嵌套一个Valve元素，Catalina会为该容器处理的所有请求创建访问日志，如下所示：]

 

See Access Logging Valves for more information on the configuration attributes that are supported.

[参考Access Loggin Valves，以获得更多配置属性的信息。]

Automatic Appication Deployment(应用的自动部署)

If you are using the standard Host implementation with default settings then applications in the appBase or with context files in the configBase are automatically deployed when Tomcat starts (the deployOnStartup property defaults to true) and reloaded or redeployed (as appropriate) when a change is detected while Tomcat is running (the autoDeploy attribute also defaults to true).

[如果你使用的是采用默认设置的标准Host实现，则当Tomcat启动时(deployOnStartUp属性缺省值为true)，或者当Tomcat运行中(autoDeploy属性缺省值也为true)，检测到应用发生改变而重新部署该应用时，appBase目录中的应用以及configBase中的context文件会自动被部署。]

deployOnStartup and autoDeploy trigger execution of exactly the same code so the behaviour is very similar. However, there is one key difference. When Tomcat starts it has no knowledge of which files are the same, which have been changed and which are new. It therefore treats all files as new. While Tomcat is running, it can differentiate between unchanged, modified and new files. This leads to some differences in behaviour between files being modified while Tomcat is running and files being modified while Tomcat is stopped.

[deployOnStartup和autoDeploy触发执行的是相同的代码，因此它们的行为十分相似，但有一点非常重要的区别。当Tomcat启动时，它不知道哪些文件是相同的，哪些被修改过，哪些是新的，因此它把所有的文件都视为新文件；而当Tomcat运行时，它可以区别文件是否被修改过，以及是否是新文件。这点差异会导致Tomcat在运行时和结束时对于被修改的文件采取不同的行为。]

When you use automatic deployment, related files (a web application may have a context.xml file, a WAR and a directory) that exist in the Host's appBase and/or configBase must conform to the expected naming convention. In short, this means files for the same web application must share the same base name.

[当使用自动部署时，在Host的appBase或者configBase下的相关的文件(一个web应用可能有一个context.xml文件，一个WAR文件和一个目录)必须符合相应的命名规范(参考Context Container中的name convention章节)。简而言之就是相同web应用的文件必须有相同的基名。]

The automatic deployment process identifies new and/or modified web applications using the following search order:

[自动部署进行按照如下的搜索顺序辨别新的和修改过的web应用：]

Web applications with a context.xml file located in the Host's configBase.

Web applications with a WAR file located in the Host's appBase that have not already been identified during the scan for context.xml files.

Web applications with a directory located in the Host's appBase that have not already been identified during the scans for context.xml and/or WAR files.

[在Host的configBase下的context.xml文件。

在Host的appBase下的WAR文件，且在扫描context.xml文件时没有识别到该WAR文件。

在Host的appBase下的目录，且在扫描context.xml文件和WAR文件时没有识别到该目录。]

When autoDeploy is true, the automatic deployment process will monitor the deployed web applications for changes. Depending on exactly what changes, the web application will either be re-deployed or reloaded. Re-deployment involves the creation of a new web application and, if using the standard session manager, user sessions will not be retained. Reloading uses the existing web application but re-parses the web.xml and reloads any classes. If using the standard session manager, user sessions will be persisted.

[当autoDeploy设为true，自动部署进程进行会监控已部署的web应用是否发生改变。根据web应用发生何种改变，Tomcat会重新部署或重新加载该web应用。重新部署会创建一个新的web应用，并且如果使用的是标准的session manager，用户的session会丢失。重新加载使用的已存在的wb应用，但会重新解析web.xml文件以及重新加载类文件，如果使用的是标准的session manager，用户session不会丢失。]

Users may add to the files that the automatic deployment process monitors for reloading (i.e. any change to one of these files triggers a reload of the web application) by adding a WatchedResources element to the context.xml file. See the Context documentation for further details.

[可以在context.xml文件中增加一个WatchedResource元素，自动部署进程会监视这些文件并重载web应用(比如，这些文件中的任何一个发生改变都会触发web应用的重新加载)。参考Context文档获取更多详细细节。]

When using automatic deployment, the docBase defined by an XML Context file should be outside of the appBase directory. If this is not the case, difficulties may be experienced deploying the web application or the application may be deployed twice. The deployIgnore attribute can be used to avoid this situation.

[当使用自动部署时，在XML Context文件中定义的docBase应该在appBase目录之外，如果不这样做的话，部署该web应用时可能发生问题，或者该应用可能被部署两次。可以使用deployIgnore属性来避免这个问题。]

Note that if you are defining contexts explicitly in server.xml, you should probably turn off automatic application deployment or specify deployIgnore carefully. Otherwise, the web applications will each be deployed twice, and that may cause problems for the applications.

[注意，如果在server.xml中显式地定义了context，则应该取消应用的自动部署，或者指定deployIgnore参数。否则，每个web应用都会被部署两次，这样可能会导致应用发生问题。]

Host Name Aliases(主机别名)

In many server environments, Network Administrators have configured more than one network name (in the Domain Name Service (DNS) server), that resolve to the IP address of the same server. Normally, each such network name would be configured as a separate Host element in conf/server.xml, each with its own set of web applications.

[在很多服务器环境中，网络管理员会配置多个网络名称(在DNS服务器中)，这些网络名称被解析后的IP地址指向的是同一个服务器。正常情况下，每一个这样的网络名称都会被配置成conf/server.xml中的一个Host元素。]

However, in some circumstances, it is desirable that two or more network names should resolve to the same virtual host, running the same set of applications. A common use case for this scenario is a corporate web site, where it is desirable that users be able to utilize either www.mycompany.com or company.com to access exactly the same content and applications.

[但在一些环境中，希望多个网络名称被解析成相同的虚拟主机，运行相同的应用系列。企业网站就是一个常见场景，它希望用户使用www.mycompany.com或者company.com访问的都是相同的内容。]

This is accomplished by utilizing one or more Alias elements nested inside your Host element. For example:

[在Host元素中嵌套一个或多个Alias元素可以实现以上功能，比如：]

 

In order for this strategy to be effective, all of the network names involved must be registered in your DNS server to resolve to the same computer that is running this instance of Catalina.

[为了是这种策略生效，所有涉及到的网络名称必须在DNS服务器中注册，以便将其解析为同一个电脑(该电脑运行该Catalina实例)。]

Lifecycle Listeners(生命周期监听器)

If you have implemented a Java object that needs to know when this Host is started or stopped, you can declare it by nesting a Listener element inside this element. The class name you specify must implement the org.apache.catalina.LifecycleListener interface, and it will be notified about the occurrence of the corresponding lifecycle events. Configuration of such a listener looks like this:

[如果一个Java对象需要知道该Host何时启动，何时停止，则可以在该Host元素中嵌套一个Listener元素。指定的类名必须要实现org.apache.cataline.LifecycleListener接口，这样，在发生对应的生命周期事件时就会通知该监听器。可以按照如下方法配置一个监听器：]

 

Note that a Listener can have any number of additional properties that may be configured from this element. Attribute names are matched to corresponding JavaBean property names using the standard property method naming patterns.

[注意，一个监听器可以配置任意多的附加属性，属性名与JavaBean的属性名相对应，且要使用标准的属性命名方法。]

Request Filters(请求过滤器)

You can ask Catalina to check the IP address, or host name, on every incoming request directed to the surrounding Engine, Host, or Context element. The remote address or name will be checked against configured "accept" and/or "deny" filters, which are defined using java.util.regex Regular Expression syntax. Requests that come from locations that are not accepted will be rejected with an HTTP "Forbidden" error. Example filter declarations:

[对于每个发送到Engine、Host、或者Context的请求，可以要求Catalina检查IP地址或主机名，Catalina会使用一系列配置好的"accept"和"deny"过滤器对远程地址或主机名进行检查。过滤器使用java.util.regex中的正则表达式语法定义。不被接受的请求会返回一个HTPP "Forbidden"错误。过滤器声明的例子如下：]

 

see Remote Address Filter and Remote Host Filter for more information about the configuration options that are supported.

[参考Remote Address Filter和Remote Host Filter，获取更多配置方面的信息。]