source: nutchez-0.1/tomcat/webapps/docs/ssi-howto.html @ 114

Last change on this file since 114 was 66, checked in by waue, 16 years ago

NutchEz - an easy way to nutch
File size: 15.1 KB
Line 
1<html><head><META http-equiv="Content-Type" content="text/html; charset=iso-8859-1"><title>Apache Tomcat 6.0 - SSI How To</title><meta value="Glenn L. Nielsen" name="author"><meta value="glenn@apache.org" name="email"></head><body vlink="#525D76" alink="#525D76" link="#525D76" text="#000000" bgcolor="#ffffff"><table cellspacing="0" width="100%" border="0"><!--PAGE HEADER--><tr><td><!--PROJECT LOGO--><a href="http://tomcat.apache.org/"><img border="0" alt="
2      The Apache Tomcat Servlet/JSP Container
3    " align="right" src="./images/tomcat.gif"></a></td><td><font face="arial,helvetica,sanserif"><h1>Apache Tomcat 6.0</h1></font></td><td><!--APACHE LOGO--><a href="http://www.apache.org/"><img border="0" alt="Apache Logo" align="right" src="./images/asf-logo.gif"></a></td></tr></table><table cellspacing="4" width="100%" border="0"><!--HEADER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><tr><!--LEFT SIDE NAVIGATION--><td nowrap="true" valign="top" width="20%"><p><strong>Links</strong></p><ul><li><a href="index.html">Docs Home</a></li><li><a href="http://wiki.apache.org/tomcat/FAQ">FAQ</a></li></ul><p><strong>User Guide</strong></p><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="realm-howto.html">6) Realms and AAA</a></li><li><a href="security-manager-howto.html">7) Security Manager</a></li><li><a href="jndi-resources-howto.html">8) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">9) JDBC DataSources</a></li><li><a href="class-loader-howto.html">10) Classloading</a></li><li><a href="jasper-howto.html">11) JSPs</a></li><li><a href="ssl-howto.html">12) SSL</a></li><li><a href="ssi-howto.html">13) SSI</a></li><li><a href="cgi-howto.html">14) CGI</a></li><li><a href="proxy-howto.html">15) Proxy Support</a></li><li><a href="mbeans-descriptor-howto.html">16) MBean Descriptor</a></li><li><a href="default-servlet.html">17) Default Servlet</a></li><li><a href="cluster-howto.html">18) Clustering</a></li><li><a href="balancer-howto.html">19) Load Balancer</a></li><li><a href="connectors.html">20) Connectors</a></li><li><a href="monitoring.html">21) Monitoring and Management</a></li><li><a href="logging.html">22) Logging</a></li><li><a href="apr.html">23) APR/Native</a></li><li><a href="virtual-hosting-howto.html">24) Virtual Hosting</a></li><li><a href="aio.html">25) Advanced IO</a></li><li><a href="extras.html">26) Additional Components</a></li><li><a href="maven-jars.html">27) Mavenized</a></li></ul><p><strong>Reference</strong></p><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Javadocs</a></li><li><a href="http://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul><p><strong>Apache Tomcat Development</strong></p><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="http://wiki.apache.org/tomcat/TomcatVersions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="funcspecs/index.html">Functional Specs.</a></li></ul></td><!--RIGHT SIDE MAIN BODY--><td align="left" valign="top" width="80%"><table cellspacing="4" width="100%" border="0"><tr><td valign="top" align="left"><h1>Apache Tomcat 6.0</h1><h2>SSI How To</h2></td><td nowrap="true" valign="top" align="right"><small><a href="printer/ssi-howto.html"><img alt="Printer Friendly Version" border="0" src="./images/printer.gif"><br>print-friendly<br>version
4                    </a></small></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Introduction"><strong>Introduction</strong></a></font></td></tr><tr><td><blockquote>
5
6<p>SSI (Server Side Includes) are directives that are placed in HTML pages,
7and evaluated on the server while the pages are being served. They let you
8add dynamically generated content to an existing HTML page, without having
9to serve the entire page via a CGI program, or other dynamic technology.
10</p>
11
12<p>Within Tomcat SSI support can be added when using Tomcat as your
13HTTP server and you require SSI support.  Typically this is done
14during development when you don't want to run a web server like Apache.</p>
15
16<p>Tomcat SSI support implements the same SSI directives as Apache.  See the
17<a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
18Apache Introduction to SSI</a> for information on using SSI directives.</p>
19
20<p>SSI support is available as a servlet and as a filter. You should use one
21or the other to provide SSI support but not both.</p>
22
23<p>Servlet based SSI support is implemented using the class
24<code>org.apache.catalina.ssi.SSIServlet</code>.  Traditionally, this servlet
25is mapped to the URL pattern "*.shtml".</p>
26
27<p>Filter based SSI support is implemented using the class
28<code>org.apache.catalina.ssi.SSIFilter</code>.  Traditionally, this filter
29is mapped to the URL pattern "*.shtml", though it can be mapped to "*" as
30it will selectively enable/disable SSI processing based on mime types.  The
31contentType init param allows you to apply SSI processing to JSP pages,
32javascript, or any other content you wish.</p>
33<p>By default SSI support is disabled in Tomcat.</p>
34</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Installation"><strong>Installation</strong></a></font></td></tr><tr><td><blockquote>
35
36<p><strong>CAUTION</strong> - SSI directives can be used to execute programs
37external to the Tomcat JVM. If you are using the Java SecurityManager this
38will bypass your security policy configuration in <code>catalina.policy.</code>
39</p>
40
41<p>To use the SSI servlet, remove the XML comments from around the SSI servlet
42and servlet-mapping configuration in
43<code>$CATALINA_BASE/conf/web.xml</code>.</p>
44
45<p>To use the SSI filter, remove the XML comments from around the SSI filter
46and filter-mapping configuration in
47<code>$CATALINA_BASE/conf/web.xml</code>.</p>
48
49<p>Only Contexts which are marked as privileged may use SSI features (see the
50privileged property of the Context element).</p>
51
52</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Servlet Configuration"><strong>Servlet Configuration</strong></a></font></td></tr><tr><td><blockquote>
53
54<p>There are several servlet init parameters which can be used to
55configure the behaviour of the SSI servlet.
56<ul>
57<li><strong>buffered</strong> - Should output from this servlet be buffered?
58(0=false, 1=true) Default 0 (false).</li>
59<li><strong>debug</strong> - Debugging detail level for messages logged
60by this servlet. Default 0.</li>
61<li><strong>expires</strong> - The number of seconds before a page with SSI
62directives will expire. Default behaviour is for all SSI directives to be
63evaluated for every request.</li>
64<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
65paths be interpreted as relative to the context root, instead of the server
66root? (0=false, 1=true) Default 0 (false).</li>
67<li><strong>inputEncoding</strong> - The encoding to be assumed for SSI
68resources if one cannot be determined from the resource itself. Default is
69the default platform encoding.</li>
70<li><strong>outputEncoding</strong> - The encoding to be used for the result
71of the SSI processing. Default is UTF-8.</li>
72</ul>
73</p>
74
75</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Filter Configuration"><strong>Filter Configuration</strong></a></font></td></tr><tr><td><blockquote>
76
77<p>There are several filter init parameters which can be used to
78configure the behaviour of the SSI filter.
79<ul>
80<li><strong>contentType</strong> - A regex pattern that must be matched before
81SSI processing is applied. When crafting your own pattern, don't forget that a
82mime content type may be followed by an optional character set in the form
83"mime/type; charset=set" that you must take into account.  Default is
84"text/x-server-parsed-html(;.*)?".</li>
85<li><strong>debug</strong> - Debugging detail level for messages logged
86by this servlet. Default 0.</li>
87<li><strong>expires</strong> - The number of seconds before a page with SSI
88directives will expire. Default behaviour is for all SSI directives to be
89evaluated for every request.</li>
90<li><strong>isVirtualWebappRelative</strong> - Should "virtual" SSI directive
91paths be interpreted as relative to the context root, instead of the server
92root? (0=false, 1=true) Default 0 (false).</li>
93</ul>
94</p>
95
96</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Directives"><strong>Directives</strong></a></font></td></tr><tr><td><blockquote>
97<p>Server Side Includes are invoked by embedding SSI directives in an HTML document
98 whose type will be processed by the SSI servlet. The directives take the form of an HTML
99 comment. The directive is replaced by the results of interpreting it before sending the
100 page to the client. The general form of a directive is: </p>
101<p> <code>&lt;!--#directive [parm=value] --&gt;</code></p>
102<p>The directives are:
103<ul>
104<li>
105<strong>config</strong> - <code>&lt;!--#config timefmt="%B %Y" --&gt;</code>
106Used to set the format of dates and other items processed by SSI
107</li>
108<li>
109<strong>echo</strong> -   <code>&lt;!--#echo var="VARIABLE_NAME" --&gt;</code>
110will be replaced bt the value of the variable.
111</li>
112<li>
113<strong>exec</strong> -  Used to run commands on the host system.
114</li>
115<li>
116<strong>include</strong> -  <code>&lt;!--#include virtual="file-name" --&gt;</code>
117inserts the contents
118</li>
119<li>
120<strong>flastmod</strong> - <code>&lt;!--#flastmod file="filename.shtml" --&gt;</code>
121Returns the time that a file was lost modified.
122</li>
123<li>
124<strong>fsize</strong> - <code>&lt;!--#fsize file="filename.shtml" --&gt;</code>
125Returns the size of a file.
126</li>
127<li>
128<strong>printenv</strong> - <code>&lt;!--#printenv --&gt;</code>
129Returns the list of all the defined variables.
130</li>
131<li>
132<strong>set</strong> - <code>&lt;!--#set var="foo" value="Bar" --&gt;</code>
133is used to assign a value to a user-defind variable.
134</li>
135<li>
136<strong>if elif endif else</strong> - Used to create conditional sections. For example:</li>
137<code>&lt;!--#config timefmt="%A" --&gt;<br>
138  &lt;!--#if expr="$DATE_LOCAL = /Monday/" --&gt;<br>
139  &lt;p&gt;Meeting at 10:00 on Mondays&lt;/p&gt;<br>
140  &lt;!--#elif expr="$DATE_LOCAL = /Friday/" --&gt;<br>
141  &lt;p&gt;Turn in your time card&lt;/p&gt;<br>
142  &lt;!--#else --&gt;<br>
143  &lt;p&gt;Yoga class at noon.&lt;/p&gt;<br>
144  &lt;!--#endif --&gt;</code>
145 </ul>
146</p>
147See the
148<p> <a href="http://httpd.apache.org/docs/howto/ssi.html#basicssidirectives">
149Apache Introduction to SSI</a> for more information on using SSI directives.</p>
150</blockquote></td></tr></table><table cellpadding="2" cellspacing="0" border="0"><tr><td bgcolor="#525D76"><font face="arial,helvetica.sanserif" color="#ffffff"><a name="Variables"><strong>Variables</strong></a></font></td></tr><tr><td><blockquote>
151<p>The SSI servlet currently implements the following variables:
152</p>
153<table border="1">
154<tr>
155<th>Variable Name</th>
156<th>Description</th>
157</tr>
158
159<tr>
160<td>AUTH_TYPE</td>
161<td>
162  The type of authentication used for this user: BASIC, FORM, etc.</td>
163</tr>
164
165<tr>
166<td>CONTENT_LENGTH</td>
167<td>
168  The length of the data (in bytes or the number of
169  characters) passed from a form.</td>
170</tr>
171
172<tr>
173<td>CONTENT_TYPE</td>
174<td>
175  The MIME type of the query data, such as "text/html".</td>
176</tr>
177
178<tr>
179<td>DATE_GMT</td>
180<td>
181Current date and time in GMT</td>
182</tr>
183
184<tr>
185<td>DATE_LOCAL</td>
186<td>
187Current date and time in the local time zone</td>
188</tr>
189<tr>
190<td>DOCUMENT_NAME</td>
191<td>
192The current file</td>
193</tr>
194<tr>
195<td>DOCUMENT_URI</td>
196<td>
197Virtual path to the file</td>
198</tr>
199
200<tr>
201<td>GATEWAY_INTERFACE</td>
202<td>
203  The revision of the Common Gateway Interface that the
204  server uses if enabled: "CGI/1.1".</td>
205</tr>
206
207<tr>
208<td>HTTP_ACCEPT</td>
209<td>
210  A list of the MIME types that the client can accept.</td>
211</tr>
212
213<tr>
214<td>HTTP_ACCEPT_ENCODING</td>
215<td>
216  A list of the compression types that the client can accept.</td>
217</tr>
218
219<tr>
220<td>HTTP_ACCEPT_LANGUAGE</td>
221<td>
222  A list of the laguages that the client can accept.</td>
223</tr>
224<tr>
225<td>HTTP_CONNECTION</td>
226<td>
227  The way that the connection from the client is being managed:
228  "Close" or "Keep-Alive".</td>
229</tr>
230<tr>
231<td>HTTP_HOST</td>
232<td>
233  The web site that the client requested.</td>
234</tr>
235<tr>
236<td>HTTP_REFERER</td>
237<td>
238  The URL of the document that the client linked from.</td>
239</tr>
240<tr>
241<td>HTTP_USER_AGENT</td>
242<td>
243  The browser the client is using to issue the request.</td>
244</tr>
245<tr>
246<td>LAST_MODIFIED</td>
247<td>
248Last modification date and time for current file</td>
249</tr>
250<tr>
251<td>PATH_INFO</td>
252<td>
253  Extra path information passed to a servlet.</td>
254</tr>
255<tr>
256<td>PATH_TRANSLATED</td>
257<td>
258  The translated version of the path given by the
259  variable PATH_INFO.</td>
260</tr>
261<tr>
262<td>QUERY_STRING</td>
263<td>
264The query string that follows the "?" in the URL.
265</td>
266</tr>
267<tr>
268<td>QUERY_STRING_UNESCAPED</td>
269<td>
270Undecoded query string with all shell metacharacters escaped
271with "\"</td>
272</tr>
273<tr>
274<td>REMOTE_ADDR</td>
275<td>
276  The remote IP address of the user making the request.</td>
277</tr>
278<tr>
279<td>REMOTE_HOST</td>
280<td>
281  The remote hostname of the user making the request.</td>
282</tr>
283<tr>
284<td>REMOTE_PORT</td>
285<td>
286  The port number at remote IP address of the user making the request.</td>
287</tr>
288<tr>
289<td>REMOTE_USER</td>
290<td>
291  The authenticated name of the user.</td>
292</tr>
293<tr>
294<td>REQUEST_METHOD</td>
295<td>
296  The method with which the information request was
297  issued: "GET", "POST" etc.</td>
298</tr>
299<tr>
300<td>REQUEST_URI</td>
301<td>
302  The web page originally requested by the client.</td>
303</tr>
304<tr>
305<td>SCRIPT_FILENAME</td>
306<td>
307  The location of the current web page on the server.</td>
308</tr>
309<tr>
310<td>SCRIPT_NAME</td>
311<td>
312  The name of the web page.</td>
313</tr>
314<tr>
315<td>SERVER_ADDR</td>
316<td>
317  The server's IP address.</td>
318</tr>
319<tr>
320<td>SERVER_NAME</td>
321<td>
322  The server's hostname or IP address.</td>
323</tr>
324<tr>
325<td>SERVER_PORT</td>
326<td>
327  The port on which the server received the request.</td>
328</tr>
329<tr>
330<td>SERVER_PROTOCOL</td>
331<td>
332  The protocol used by the server. E.g. "HTTP/1.1".</td>
333</tr>
334<tr>
335<td>SERVER_SOFTWARE</td>
336<td>
337  The name and version of the server software that is
338  answering the client request.</td>
339</tr>
340<tr>
341<td>UNIQUE_ID</td>
342<td>
343  A token used to identify the current session if one
344  has been established.</td>
345</tr>
346</table>
347</blockquote></td></tr></table></td></tr><!--FOOTER SEPARATOR--><tr><td colspan="2"><hr size="1" noshade></td></tr><!--PAGE FOOTER--><tr><td colspan="2"><div align="center"><font size="-1" color="#525D76"><em>
348        Copyright &copy; 1999-2008, Apache Software Foundation
349        </em></font></div></td></tr></table></body></html>
Note: See TracBrowser for help on using the repository browser.