配置 Tapestry

配置 Tapestry

• Web 部署描述符
• 应用属性来源(Application Property Source )
• 全局属性来源(Global Property Source)
• 可配置属性(Configuration Properties)
• 应用扩展(Application extensions)

警告

Tapestry 3.0 和Tapestry 4.0 在配置方面有极大的不同. Tapestry 4.0 使用了具有丰富的服务和配置功能的 HiveMind 进行重构。. [译者注：Tapestry的灵活性远不止本问提到的这些，使用HiveMind可以获得更高级的扩展能力]

Tapestry设计为可以在多种不同的JVM和不容的Java Servlet API版本上运行。下面你可以看到一个它所支持的环境列表和测试配置：

Java 1.2.2

正常运行。类路径上需要有Xerces parser (通常由servlet容器提供).

Java 1.3.x

正常运行。类路径上需要有Xerces parser (通常由servlet容器提供).

Java 1.4.x (推荐)

正常运行。

支持的 Java Servlet API 版本:

Java Servlet API 2.2

正常运行但是有一点微小的异常。归因于Servlet API 版本对请求字符编码的限制。

Java Servlet API 2.3 (推荐)

正常运行。

Web 部署描述符

Tapestry应用都使用ApplicationServlet作为它们的servlet， 很少有必要为它创建一个子类。典型的 web.xml 配置会将该 servlet 映射到 /app 路径，并添加一个 servlet 过滤器（稍后讨论）。：

<?xml version="1.0"?> 
<!DOCTYPE web-app PUBLIC "-//Sun Microsystems, Inc.//DTD Web Application 2.3//EN"  "http://java.sun.com/dtd/web-app_2_3.dtd"> 
<web-app> 
  <display-name>My Application</display-name> 
  <servlet> 
    <servlet-name>myapp</servlet-name> 
    <servlet-class>org.apache.tapestry.ApplicationServlet</servlet-class>  
    <load-on-startup>0</load-on-startup> 
  </servlet> 
   
  <servlet-mapping> 
    <servlet-name>myapp</servlet-name> 
    <url-pattern>/app</url-pattern>  
  </servlet-mapping> 
   
  <filter>  
    <filter-name>redirect</filter-name> 
    <filter-class>org.apache.tapestry.RedirectFilter</filter-class> 
  </filter> 
	 
  <filter-mapping> 
    <filter-name>redirect</filter-name> 
    <url-pattern>/</url-pattern> 
  </filter-mapping> 
 
  <session-config> 
  	<session-timeout>15</session-timeout> 
  </session-config> 
     
  <welcome-file-list> 
    <welcome-file>index.html</welcome-file> 
  </welcome-file-list> 
</web-app> 
 

< servlet-class>任何时候都应该是ApplicationServlet。几乎没有太多的必要创建子类；Tapestry有非常多的钩子用于扩展应用程序。

定义一个<load-on-startup>通常是非常有用的，这使servlet容器在启动时就会初始化应用程序的servlet，因此此时便会读取Tapestry应用程序的说明文件。很多常见的部署错误立刻便会报告，而不用等到应用第一次被请求时。

这个 servlet 被映射在 context 内的 /app 路径下。context自身有一个路径，由应用服务器和WAR文件的名称确定。web浏览器可以通过 http://host/war-name/app 访问到该应用。

使用 /app 作为URL只是创建Tapestry应用程序的一个惯例，而不是限定。如果你需要使用其它的URL，你还得记得覆盖 org.apache.tapestry.servlet-path 属性。

当请求路径为web应用的context时，RedirectFilter 过滤器会为用户发出一个重定位请求，将请求直接转到应用程序的servlet。这样，应用程序的“共有” URL 可以为 http://myserver/mycontext/，而实际访问的地址是 http://myserver/mycontext/app。

在初始化时，Tapestry 的 servlet 会查找应用说明（specification）；该说明定义了应用程序的详细信息，包括应用中使用的页面和组件，以及所有使用的库文件。Tapestry 提供了一个非常灵活的说明文件存储策略；简单的 Tapestry 应用可以不需要程序说明文件。

提醒 (HLS)

考虑到HiveMind的应素，这个文档已经过时。在 4.0 里 servlet 将创建和初始化一个 HiveMind Registry.

通常说明文件(application specification)保存在WEB-INF下。实际上，Tapestry会执行一个搜索去查找说明文件：

• 在类路径，使用org.apache.tapestry.application-specification在配置扩展点定义(configuration property)。
• 类似 /WEB-INF/name/name.application的路径。 name是servlet的名字，这种位置只在极少的情况下使用，比如一个WAR文件包含多个 Tapestry 应用。
• 类似 /WEB-INF/name.application的路径。同样，name是 servlet 名字。这是一个标准的位置。

如果这些情况下还是无法找到应用说明文件，将会使用一个空的“占位”的应用说明。这种方法效果很好。一个应用只有在使用组件包或者是某种只能在说明文件中申明的用户定义时才是必须的。

应用属性来源（ Application Property Source ）

Tapestry 偶尔也需从配置属性中获取数据。这些配置属性通常是可选的，并且也不属于任一特定的说明。许多是和运行环境相关的，比如用哪一个类来初始化Visit对象。

Tapestry获取这些属性的方法非常灵活。通常，搜索配置属性的路径是：

• <application> 里的 <meta> 属性（如果应用使用了应用说明，则在该说明中。）
• servlet 的 <init-parameter>。在web应用的部署描述符中。
• servlet context的 <init-parameter>，同样也是在web应用的部署描述符中。
• JVM 的系统属性。
• 对某些属性可以使用硬编码的默认"工厂"，它们被作为HiveMind的标示使用。

很多属性实际都不会在任何位置定义，这些属性会返回一个空值。

应用程序同样可以随意的扩展这个搜索机制。

提醒 (HLS)

这里需要涉及到 ApplicationPropertySource, GlobalPropertySource 和 ComponentPropertySource。

应用程序可能也会希望改变或扩展默认的搜索路径；这点可以通过覆盖AbstractEngine的createPropertySource()函数。比方说，一些配置数据可以从数据库中提取。

提醒 (HLS)

上一段已经过时；扩展的搜索路径应该包括 HiveMind 的配置信息(contribution)。需要提供更详细的说明。

全局属性来源 (Global Property Source)

在有些情况下，会使用一个略微有些不同的来源，全局属性来源。

• servlet 的 <init-parameter>。在web应用的部署描述符中。
• servlet context的 <init-parameter>，同样也是在web应用的部署描述符中。
• JVM 的系统属性。
• 对某些属性可以使用硬编码的默认"工厂"，它们被作为HiveMind的符号使用。

可配置属性(Configuration Properties)

下面是 Tapestry 现在可使用的所有可配置的属性：

属性	描述
org.apache.tapestry.accepted-locales	控制哪些 locals 被应用程序支持；详细信息可以参见 limiting accepted locales 。
org.apache.tapestry.bean-class-packages	一个用逗号隔开的列表，用来将受管理的 beans （使用 <bean> 元素定义的）的类名转化为一个合法的完整的类名。这个属性可以定义在所包含的库(liberary)或应用的说明(specification)中。
org.apache.tapestry.component-class-packages	一个使用逗号隔开的包含包名(package names)的列表。在搜索组件类文件是会使用。必须使用 <meta> 标签在应用说明或包说明中定义。
org.apache.tapestry.default-binding-prefix	在没有明确定义绑定规则时默认使用的绑定规则。通常定义在页面或组件内，或者定义在应用说明或包说明中(作用于所有的页面和组件)。如果定义，默认为"ognl"。
org.apache.tapestry.default-cookie-max-age	Tapestry生成cookies的最大默认有效期(秒级)，包括用于跟踪用户 locale 的 cookie。如果值为 -1 说明 cookie是会话 cookie，仅在用户退出浏览器前有效。默认值为一个星期。
org.apache.tapestry.default-page-class	页面如果省略掉了 class 属性(在它的<page-specification>里)将会默认的使用 BasePage 来实例化。如果不希望这样，可以通过给定一个合法的完整类型来扩展它。
org.apache.tapestry.disable-caching	如果定义为"true"，框架会在每个请求周期结束时抛弃所有缓存的数据（定义，模版，缓存对象等）   这会极大的降低请求响应的速度，但是在开发时非常有用。也就是说，在改变模板和说明之后立即就会生效。它对发现与管理页面持久化状态的问题也有帮助。     这个配置不应该在产品中出现；性能会受到极大的影响。不象其它的配置属性，这个必须作为 JVM 的系统属性设置。
org.apache.tapestry.enable-reset-service	如果不定义为"true"，重置服务(reset service)将不会工作。重置服务是用于强制将运行 Tapestry 应用的缓存属性清楚（包括模板，说明，缓存对象等）。它需要显示的打开，并且应该只在开发的过程中打开（在产品中打开，很容易受拒绝服务的攻击）。   不象其它的配置属性，这个必须作为 JVM 的系统属性设置。
org.apache.tapestry.engine-class	用于初始化应用引擎(engine)的合法的完整的类名。这个配置只在没有使用应用说明或没有在应用说明中定义时使用。如果没有定义，默认的将使用 BaseEngine。
org.apache.tapestry.enhance.disable-abstract-method-validation	用于弥补 IBM 的 JDK1.4.0 的问题。这个版本的 JDK 会将抽象类的所有方法报告为抽象方法，即便这些方法实际实际上是具体方法。这会造成虚假的未实现抽象方法的错误。定义为 true 可以屏蔽对未实现抽象方法的检查。 警告 4.0开始不支持这个属性。
org.apache.tapestry.global-class	用于初始化引擎全局属性的合法的完整的类名。Global对象和 Visit 对象非常相似，不同的只是它被所有引擎共享而不是属于某一个特定的会话(session)。如果没有定义，一个同步的Map对象将会使用。
org.apache.tapestry.home-page	用于被 home engine service 显示的页面名（当 URL中没有其它信息的时候将会该页面显示）。默认为"Home"。
org.apache.tapestry.jwcid-attribute-name	控制使用哪一个属性作为在组件模板中识别出所包含的组件。默认为"jwcid"。
org.apache.tapestry.messages-encoding	设置读取页面或组件信息目录（message catalog）所在的 properties 文件的编码格式。默认为ISO-8859-1。 在 message catalog localization discussion 中可以获得更多的信息。 [译者注：添加一个类似<meta key="org.apache.tapestry.messages-encoding_zh_CN" value="GBK"/>的配置属性，则可以不用将中文的 properties 文件转化为 UTF-8 的格式，直接写中文就可以了。而且各包有自己的作用域]
org.apache.tapestry.output-encoding	设置应用程序用于编码 HTTP 响应的编码格式。这也是应用程序在没有特别指定使用不同的 HTTP 请求的情况下用于假定用户浏览器使用的编码格式。 默认的设置是 UTF-8。一般情况下没有必要修改这个编码格式，因为 UTF-8 可以编码和显示几乎所有的字符。
org.apache.tapestry.page-class-packages	一个用逗号隔开的包路径列表，在搜索页面类文件是用到。它只能以<meta>标签的格式出现在包含页面的应用(application)或库(liberary)的说明中。
org.apache.tapestry.servlet-path	设置用于构造 URLs 的 servlet 的路径。默认为 /app。注意，这仅是一个servlet 路径。在很多情况下，应用将在一个 context 里，Tapestry 会自动的以该路径为前缀构造一个正确的路径。比如，workbench.war 将会默认的以部署在 /workbench 的 context 路径下，同时 Tapestry 会构造出 /workbench/app 形式的 URLs。
org.apache.tapestry.template-encoding	设置应用程序模板的编码格式。默认为 ISO-8859-1. 在 template localization discussion 里可以看更多信息。 [译者注：和 org.apache.tapestry.messages-encoding 很相似，也是可以通过后缀来指定对应编码格式指定的编码格式。Home.html 的中文板就可以是Home_zh_CN.html]
org.apache.tapestry.template-extension	覆盖用于定位页面或组件模板的模板文件扩展名。默认的扩展名是 "html"，这个扩展允许在合适的场合进行覆盖。比如，一个生成 WML 的应用就可能希望覆盖为"wml"。 这个配置不支持标准的搜索规则。<meta>必须定义在<page-specification> 或 <component-specification> 里。如果没有找到，将会直接搜索包含它们的<application> 或 <library-specification>。如果仍然没有找到，则会使用默认值。
org.apache.tapestry.607-patch	关于TAPESTRY-607问题的补丁, 与某些版本的 Tomcat5 响应的字符集有关。Tomcat 的 bug 是 37072. 这个补丁保证了 HttpServletResponse.setContentType() 只会调用一次,即使输出已经被重置 (比如, 跳转到 Tapestry 的异常页面)。这个属性必须使用 JVM 的系统参数设置为 true。
org.apache.tapestry.visit-class	初始化Visit 对象的合法的完整的类名。 如果没有指定，将会创建一个HashMap实例。 这个属性主要是用于为了和 Tapestry 3.0 兼容；用 Tapestry 4.0，你可能希望希望覆盖默认的应用状态对象（application state object）visit (或者简单的增加你自己的应用状态对象)。

应用扩展（Application Extensions）

警告

应用程序扩展在 4.0 版不推荐使用。使用 HiveMind 的服务(services)或配置(contributions)消除了这种使用的必要性。

Tapestry 被设计的非常灵活；这些扩展不仅仅是简单的配置框架，而实际上是围绕着替代或扩展框架的实现。如果 Tapestry 没有做你需要的工作，有很多种方法扩展，改变和覆盖框架的标准行为。在有些情况下，你需要继承框架的类，以达到改变它们行为的目的，但更多的的，通过应用扩展就可以了。

应用扩展是定义在应用说明(application specification)里的 JavaBean 对象。每个扩展包含一个名称，一个 Java 类名，和一个可选择的配置（bean 可能需要设置的属性）。框架有有限的扩展点。如果扩展点的bean被正确的命名，它将会在扩展点实际被使用。

你的应用可能有与框架无关的，属于自己的扩展。比如，你可能有一个被多个页面使用完成某些通用功能的应用扩展，比方说一个 JNDI 的查找。

你可以通过引擎的说明获取应用扩展。比如：

 
IEngine engine = getEngine(); 
IApplicationSpecification specification = engine.getSpecification(); 
	 
MyExtension myExtension = (MyExtension) specification.getExtension("myExtension");	 

框架使用的每个应用扩展必须实现一个与该扩展点对应的特定接口。

扩展名	类型	描述
org.apache.tapestry.property-source	IPropertySource	这个扩展用于配置属性的搜索路径，在servlet context 之后，但是在 JVM 系统属性之前。典型的应用是通过数据库获取某些属性集合。
org.apache.tapestry.request-decoder	IRequestDecoder	一个请求的解码器，用于识别正确的服务名，服务端口，scheme 和 请求的请求 URI。在有些配置下，防火墙可能使由HttpServletRequest提供的数据变得无效（数据反映了由防火墙转交给内部服务器，而不是真正外部客户使用的数据）。请求解码器知道如何确定真正的数据。
org.apache.tapestry.monitor-factory	IMonitorFactory	用于创建 IMonitor 实例的对象。监听器会在处理一个请求的过程中当有应用事件发生时被通知（比如读取一个页面）。 这个工厂可以为每个请求创建一个新实例，也可以提供一个共享的实例。 如果没有指定，会使用一个默认的实现（DefaultMonitorFactory）。
org.apache.tapestry.specification-resolver-delegate	ISpecificationResolverDelegate	一个用于在默认规则无法查找到页面或组件说明(specification)时查找页面或组件说明。这种使用是没有限制的，但是一般会在非常高级的应用场合才很有用。比如说说明定义在应用外部（可能是数据库）或运行时创建。
org.apache.tapestry.template-source-delegate	ITemplateSourceDelegate	一个用于在默认规则无法查找到页面或组件模板(template)时查找页面或组件模板。这种使用是没有限制的，但是一般会在非常高级的应用场合才很有用。比如说模板定义在应用外部（可能是数据库）或运行时创建。
org.apache.tapestry.ognl-type-converter	ognl.TypeConverter	指定一个 ognl.TypeConverter 的实现，用于表达式绑定。可以在 OGNL 的Type Converter documentation 查看更多有关实现的细节。