Apache Tomcat 5.5 Servlet/JSP 容器

SSI How To

SSI (Server Side Includes)是放置在HTML页面里的指令(directives)，在HTML页面被使用的 同时在服务器上被评估。这样可以让你把新产生的内容添加到现存的HTML页面上，而不需要同过CGI程序， 或其他动态的技术来产生整个页面。

当你使用Tomcat作为你的HTTP服务器，并要求有SSI支持，你可以把SSI支持添加到Tomcat里面。 通常在你不想要运行一个象Apache的web服务器的开发过程中它就被完成了。

Tomcat SSI 支持实施与Apache相同的指令。关于使用SSI指令的信息， 请参看 Apache Introduction to SSI 。

Tomcat里面SSI的支持是通过使用Servlet或过滤器来完成的。你必须选择其中一个来支持你的SSI， 而不能同时使用两个。

基于Servlet的SSI是通过实现 org.apache.catalina.ssi.SSIServlet来完成的。按照SSI的习惯，这个Servlet 然后被映射成以 "*.shtml" 结尾的 URL。

基于过滤器的 SSI 是通过实现 org.apache.catalina.ssi.SSIFilter来完成的。 按规矩, 这个过滤器过滤所有 以"*.shtml"结尾的 URL，你也可以用 "*" 映射，让它过滤所有URL，但它会根据 不同的文件种类 （mime types）来决定是否启用SSI。使用初始值 contentType 可以让你决定是否要用 SSI 来处理 JSP， Javascript 或其他内容的网页。

在缺省情况下设置是 Tomcat 不自动启用 SSI。

警告——SSI指令可以用于执行Tomcat JVM外部的程序。如果你在使用 Java SecurityManager，它可以绕过你的catalina.policy里的安全政策配置。

把$CATALINA_BASE/server/lib/servlets-ssi.renametojar 改名为 $CATALINA_BASE/server/lib/servlets-ssi.jar 。

如果选择使用基于Servlet的SSI，请把$CATALINA_BASE/conf/web.xml里面被 注释掉的关于SSI 的 servlet 和 servlet-mapping 定义重新激活。

如果选择基于过滤器的 SSI， 清激活 $CATALINA_BASE/conf/web.xml 关于 SSI 的 filter 和 filter-mapping的设置。 .

有几个servlet起始参数可以用来配置SSI servlet的行为。

• buffered - 这个servlet的输出是不是应该被缓冲？(0=false, 1=true) 默认是 0 (false).
• debug - 由这个servlet日志的排错消息的详细程度。默认是0。
• expires - 带有SSI指令的页面失效之前的秒数。默认行为是对于每一个请求都要评估所用的SSI指令。
• isVirtualWebappRelative - “虚拟”SSI指令路径是否应该被解释为 相对于context root，而不是server root。 (0=false, 1=true) 默认是 0 (false)。
• inputEncoding - 如果无法决定所调用资源的文字编码，SSI应该使用的编码。 缺省数值是系统的文字编码。
• outputEncoding - 输出结果的文字编码，缺省值是 UTF-8。

过滤器的性能可通过修改几个不同的初始值来调整。

• contentType - 用一个正则表达式来就定那种网页类型应该调用 SSI。在 决定正则表达式时，不要忘记在网页内容种类的定义里可以有文字编码的选项， 它的标准是："mime/type; charset=set"，其中 charset=set 是选择项。 contentType的缺省值是："text/x-server-parsed-html(;.*)?".
• debug - 由这个servlet日志的排错消息的详细程度。默认是0。
• expires - 带有SSI指令的页面失效之前的秒数。默认行为是对于每一个请求都要评估所有的SSI指令。
• isVirtualWebappRelative - “虚拟”SSI指令路径是不是应该被解释为相对于 context root相关，还是相对于server root (0=false, 1=true) 默认是 0 (false)。

SSI是通过 嵌入在 HTML的指令来完成的实现动态网页的。这些指令在HTML里面如同HTML的注释，在 运行Tomcat会把它替换为响应的内容。这些指令的标准格式是：

<!--#directive [parm=value] -->

有效指令有：

• config - <!--#config timefmt="%B %Y" --> 用来指定SSI输出的时间日期或其他内容的格式
• echo - <!--#echo var="VARIABLE_NAME" --> 替换所指定的数值
• exec - 运行所在系统的命令
• include - <!--#include virtual="file-name" --> 插入内容
• flastmod - <!--#flastmod file="filename.shtml" --> 文件最后修改时间
• fsize - <!--#fsize file="filename.shtml" --> 文件大小
• printenv - <!--#printenv --> 打印所有环境变量
• set - <!--#set var="foo" value="Bar" --> 用来为用户定义变量赋值
• if elif endif else - 用于条件判断，例如：
<!--#config timefmt="%A" -->
<!--#if expr="$DATE_LOCAL = /Monday/" -->
<p>Meeting at 10:00 on Mondays</p>
<!--#elif expr="$DATE_LOCAL = /Friday/" -->
<p>Turn in your time card</p>
<!--#else -->
<p>Yoga class at noon.</p>
<!--#endif -->

阅读更多SSI相关内容：

Apache SSI入门

SSI Servlet 现在支持下列变量：

变量名称	描述
AUTH_TYPE	用来验证用户的方法，可以是：BASIC, FORM, 等
CONTENT_LENGTH	从FORM传来的数据长度，单位是 bytes 或字符的个数
CONTENT_TYPE	MIME种类, 例如 "text/html"
DATE_GMT	现在的国际标准时间 GMT
DATE_LOCAL	当地时间
DOCUMENT_NAME	调用的文件名
DOCUMENT_URI	文件的虚拟路径
GATEWAY_INTERFACE	服务器如果激活了 CGI 的话，显示支持的 CGI 版本，如 "CGI/1.1"
HTTP_ACCEPT	所有允许的 MIME 种类
HTTP_ACCEPT_ENCODING	列出所有客户端允许的压缩方式
HTTP_ACCEPT_LANGUAGE	列出所有客户端接受的语言
HTTP_CONNECTION	客户端接受的连接管理方法，如 "Close" or "Keep-Alive"
HTTP_HOST	用户请求访问的网站
HTTP_REFERER	连接到本网页的网页地址，用户来自于的网页网页
HTTP_USER_AGENT	浏览器的名称
LAST_MODIFIED	当前文件的最后修改时间
PATH_INFO	传给服务器的路径信息
PATH_TRANSLATED	经过转换的 PATH_INFO 路径
QUERY_STRING	浏览器地址栏里 "?" 之后的值
QUERY_STRING_UNESCAPED	Undecoded query string with all shell metacharacters escaped with "\"
REMOTE_ADDR	用户的IP地址
REMOTE_HOST	用户的网址
REMOTE_PORT	用户所用的端口号码
REMOTE_USER	经确认的用户名字
REQUEST_METHOD	用户请求访问所使用的方法，如 "GET", "POST" 等
REQUEST_URI	用户所要求访问的网址
SCRIPT_FILENAME	目前用户实际访问的网页在服务器上的文件名
SCRIPT_NAME	网页的文件名
SERVER_ADDR	服务器的IP地址
SERVER_NAME	服务器电脑的名称或IP
SERVER_PORT	服务器等待用户访问的端口
SERVER_PROTOCOL	服务器使用的协议，如： "HTTP/1.1"
SERVER_SOFTWARE	服务器所使用的软件名称和版本数
UNIQUE_ID	服务器与用户目前如果开始会话的特有ID