webapps/docs/aio.xml - tomcat - Git at Google

 <?xml version="1.0" encoding="UTF-8"?>
 <!--
   Licensed to the Apache Software Foundation (ASF) under one or more
   contributor license agreements.  See the NOTICE file distributed with
   this work for additional information regarding copyright ownership.
   The ASF licenses this file to You under the Apache License, Version 2.0
   (the "License"); you may not use this file except in compliance with
   the License.  You may obtain a copy of the License at

       http://www.apache.org/licenses/LICENSE-2.0

   Unless required by applicable law or agreed to in writing, software
   distributed under the License is distributed on an "AS IS" BASIS,
   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
   See the License for the specific language governing permissions and
   limitations under the License.
 -->
 <!DOCTYPE document [
   <!ENTITY project SYSTEM "project.xml">
 ]>
 <document url="aio.html">

     &project;

   <properties>
     <title>Advanced IO and Tomcat</title>
     <author>Remy Maucherat</author>
   </properties>

 <body>

 <section name="Table of Contents">
 <toc/>
 </section>

   <section name="Introduction">

   <p>
     <b>IMPORTANT NOTE: Usage of these features requires using the
     HTTP connectors. The AJP connectors do not support them.</b>
   </p>

   </section>

   <section name="Asynchronous writes">

   <p>
     When using HTTP connectors (based on APR or NIO/NIO2),
     Tomcat supports using sendfile to send large static files.
     These writes, as soon as the system load increases, will be performed
     asynchronously in the most efficient way. Instead of sending a large response using
     blocking writes, it is possible to write content to a static file, and write it
     using a sendfile code. A caching valve could take advantage of this to cache the
     response data in a file rather than store it in memory. Sendfile support is
     available if the request attribute <code>org.apache.tomcat.sendfile.support</code>
     is set to <code>Boolean.TRUE</code>.
   </p>

   <p>
     Any servlet can instruct Tomcat to perform a sendfile call by setting the appropriate
     request attributes. It is also necessary to correctly set the content length
     for the response. When using sendfile, it is best to ensure that neither the
     request or response have been wrapped, since as the response body will be sent later
     by the connector itself, it cannot be filtered. Other than setting the 3 needed
     request attributes, the servlet should not send any response data, but it may use
     any method which will result in modifying the response header (like setting cookies).
   </p>

   <ul>
   <li><code>org.apache.tomcat.sendfile.filename</code>: Canonical filename of the file which will be sent as
       a String</li>
   <li><code>org.apache.tomcat.sendfile.start</code>: Start offset as a Long</li>
   <li><code>org.apache.tomcat.sendfile.end</code>: End offset as a Long</li>
   </ul>
   <p>
     In addition to setting these parameters it is necessary to set the content-length header.
     Tomcat will not do that for you, since you may have already written data to the output stream.
   </p>

   <p>
     Note that the use of sendfile will disable any compression that Tomcat may
     otherwise have performed on the response.
   </p>

   </section>

 </body>
 </document>
	<?xml version="1.0" encoding="UTF-8"?>
	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->
	<!DOCTYPE document [
	<!ENTITY project SYSTEM "project.xml">
	]>
	<document url="aio.html">

	&project;

	<properties>
	<title>Advanced IO and Tomcat</title>
	<author>Remy Maucherat</author>
	</properties>

	<body>

	<section name="Table of Contents">
	<toc/>
	</section>

	<section name="Introduction">

	<p>
	<b>IMPORTANT NOTE: Usage of these features requires using the
	HTTP connectors. The AJP connectors do not support them.</b>
	</p>

	</section>

	<section name="Asynchronous writes">

	<p>
	When using HTTP connectors (based on APR or NIO/NIO2),
	Tomcat supports using sendfile to send large static files.
	These writes, as soon as the system load increases, will be performed
	asynchronously in the most efficient way. Instead of sending a large response using
	blocking writes, it is possible to write content to a static file, and write it
	using a sendfile code. A caching valve could take advantage of this to cache the
	response data in a file rather than store it in memory. Sendfile support is
	available if the request attribute <code>org.apache.tomcat.sendfile.support</code>
	is set to <code>Boolean.TRUE</code>.
	</p>

	<p>
	Any servlet can instruct Tomcat to perform a sendfile call by setting the appropriate
	request attributes. It is also necessary to correctly set the content length
	for the response. When using sendfile, it is best to ensure that neither the
	request or response have been wrapped, since as the response body will be sent later
	by the connector itself, it cannot be filtered. Other than setting the 3 needed
	request attributes, the servlet should not send any response data, but it may use
	any method which will result in modifying the response header (like setting cookies).
	</p>

	<ul>
	<li><code>org.apache.tomcat.sendfile.filename</code>: Canonical filename of the file which will be sent as
	a String</li>
	<li><code>org.apache.tomcat.sendfile.start</code>: Start offset as a Long</li>
	<li><code>org.apache.tomcat.sendfile.end</code>: End offset as a Long</li>
	</ul>
	<p>
	In addition to setting these parameters it is necessary to set the content-length header.
	Tomcat will not do that for you, since you may have already written data to the output stream.
	</p>

	<p>
	Note that the use of sendfile will disable any compression that Tomcat may
	otherwise have performed on the response.
	</p>

	</section>

	</body>
	</document>