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，獲取更多配置方面的信息。]