<document>
<header>
<product>resin</product>
<title>Performance Scrapbook</title>
<version>Resin 3.0</version>
<description>
<p>A repository of notes and comments that will
eventually make their way into the documentation.  Please
treat the information here with caution, it has often not been
verified.</p>
</description>
</header>

<body>
<summary objsummary='localtoc'/>

<section title="General">

<faq title="What are the best things to tune for better performance?">
<description>
</description>
<p>The main configuration item is the <a config-tag="dependency-check-interval"/> especially
for Windows.  For deployment, you should set it something high like 60s
or larger.</p>

<p>You can also change the <a config-tag='cache-mapping'/> values, especially for stuff
like *.gif files that don't change.  Higher values mean that the
browsers won't need to go back to the server.</p>

<p>Other than that, most of the default configuration values are pretty
good, so you normally won't need to touch them.

<p>The most important performance tweak you can make is to set Expires or
better Last-Modified and/or ETag values on your servlet/JSP output.  If
the servlet/JSP output only changes every 15 minutes, as for a news
page, then caching it can be a big performance win.</p>

<p>Of course, for stuff like shopping carts and stuff that's personalized,
that won't help.  But for many sites, the most heavily hit pages can be
cached.</p>
</faq>


<faq title="Is Apache faster than Resin Standalone?">
<description>
</description>
<p>For small files, Resin is about 10-20% faster.  For large files 
(1M), they're essentially identical.  (It's possible that the very 
latest Apache has improved performance.)</p>

<p>For JSP and Servlets, Resin standalone is certainly faster than 
Resin/Apache.  Because of the extra overhead of the Resin/Apache 
connection, the Resin/Apache configuration is necessarily slower than 
Resin standalone.</p>

<p>It's only static files where Apache could be faster.  Well, there's an 
exception for SSL.  It's conceivable that Apache/Resin with SSL would be 
faster that Resin with SSL.</p>
</faq>

<faq title="What is the performance loss with a Servlet or JSP comparted to a static file?">
<description>
</description>
<p>With Resin standalone, JSP files are essentially as fast as
static files (as long as you don't actually do any
processing. :-)</p>

<p>If Resin is behind another web server, like IIS or Apache,
there is a performance decrease with JSP and Servlet files,
which comes from the overhead needed for the communication
between the other web server and Resin.</p>
</faq>
</section>

<section title="Caching">
<faq title="what get's cached when a servlet does a forward?">
<description>
<p>
I'm a bit unclear as to how to ensure that a servlet that forward to a JSP
page caches its output. Of course at the top of my JSP page (and any of its
&lt;jsp:include&gt;s) I put &lt;%@ page session=false %&gt;. Now, what do I need to do
about cache-mapping? Do I need to explicitly map the servlet, or will
resin.conf's suggested &lt;cache-mapping url-pattern='/' expires='15m'/&gt; work?
</p>
</description>

<p>The only thing that matters is the HTTP headers.  So if you telnet to 
the server, you should be able to see whether the headers are properly 
set or not.</p>

<p>In the case of a forward, you should be able to just set the headers 
without needing to modify the JSP itself.</p>
        
<p>One thing to be aware of: the caching is based on the original URL.  So 
if your forwarding servlet varies it's output based on some request 
headers (like User-Agent), it needs to set the Vary header.</p>

<p>&lt;cache-mapping&gt; is a related but somewhat separate issue, and I think we 
haven't explained it properly. </p>

<p>&lt;cache-mapping&gt; only works on cacheable responses which have not set the 
Expires header.  If you're missing the Expires header, &lt;cache-mapping&gt; 
will set it for you.  </p>

<p>Cacheable means:</p>

<ol>
<li>either ETag or Last-Modified must be set in the response (ETag is 
better).  The servlet will normally set that value.
<li>no cache-control is set in the response headers
<li>no Vary tag is set (Resin doesn't completely implement Vary.)
</ol>

<p>So your servlet still needs to do some work.  &lt;cache-mapping&gt; isn't all 
that you need.  The reason that &lt;cache-mapping&gt; works with  normal files 
is that Resin's FileServlet sets the Last-Modified and ETag headers, but 
does not set the Expires header.
</p>
</faq>
<faq title="What if while the cache is being filled, another request comes?">

<description><p>I've tried several other server-side caching mechanisms, and
I've found that all of them are somewhat deficient when it comes
to refreshing expired caches.  The problem that usually arises is
that when the cache expires, every request then tries to take
responsibility for refreshing that cache - until one of them
finally completes and subsequent requests see the cache is up to
date.  If the page takes a long time to finish execution on a
busy site, this results in hundreds of requests piling up, all
executing the original page to refresh the cache.</p></description>

<p>Resin 'fills a cache' the first time a request comes in.  If
another request comes in and Resin has not finished filling the cache,
the second request will be treated as uncachable.  This means that
until the cache is filled, requests will miss the cache and get
serviced directly.</p>

<p>This is also what happens when the
cache expires.  The first request to come in after the expiry
time invalidates it, and while it is being filled the other
requests pass through to the resource being cached.</p>

<p>This behaviour may be changed in Resin 3.0, updates are available
<a
href="http://www.caucho.com/quercus/bugtrack/view.xtp?bugreport_id=1135">here</a>.</p>

</faq>
</section>
</body>
</document>
