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

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

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