Links User Guide Reference Apache Tomcat Development | Introduction |
With usage of APR or NIO APIs as the basis of its connectors, Tomcat is
able to provide a number of extensions over the regular blocking IO
as provided with support for the Servlet API.
IMPORTANT NOTE: Usage of these features requires using the APR or NIO
HTTP connectors. The classic java.io HTTP connector and the AJP connectors
do not support them.
|
Comet support |
Comet support allows a servlet to process IO aynchronously, recieving
events when data is available for reading on the connection (rather than
always using a blocking read), and writing data back on connections
asychnonously (most likely responding to some event raised from some
other source).
CometEvent |
Servlets which implement the org.apache.catalina.CometProcessor
interface will have their event method invoked rather than the usual service
method, according to the event which occurred. The event object gives
access to the usual request and response objects, which may be used in the
usual way. The main difference is that those objects remain valid and fully
functional at any time between processing of the BEGIN event until processing
an END or ERROR event.
The following event types exist:
- EventType.BEGIN: will be called at the beginning
of the processing of the connection. It can be used to initialize any relevant
fields using the request and response objects. Between the end of the processing
of this event, and the beginning of the processing of the end or error events,
it is possible to use the response object to write data on the open connection.
Note that the response object and depedent OutputStream and Writer are still
not synchronized, so when they are accessed by multiple threads,
synchronization is mandatory. After processing the initial event, the request
is considered to be committed.
- EventType.READ: This indicates that input data is available, and that one read can be made
without blocking. The available and ready methods of the InputStream or
Reader may be used to determine if there is a risk of blocking: the servlet
should read while data is reported available, and can make one additional read
without blocking. When encountering a read error or an EOF, the servlet MUST
report it by either returning false or throwing an exception such as an
IOException. This will cause the error event to be invoked, and the connection
will be closed. It is not allowed to attempt reading data from the request object
outside of the execution of this method.
- EventType.END: End may be called to end the processing of the request. Fields that have
been initialized in the begin method should be reset. After this event has
been processed, the request and response objects, as well as all their dependent
objects will be recycled and used to process other requests.
- EventType.ERROR: Error will be called by the container in the case where an IO exception
or a similar unrecoverable error occurs on the connection. Fields that have
been initialized in the begin method should be reset. After this event has
been processed, the request and response objects, as well as all their dependent
objects will be recycled and used to process other requests.
As described above, the typical lifecycle of a Comet request will consist in a series of
events such as: BEGIN -> READ -> READ -> READ -> ERROR/TIMEOUT. At any time, the servlet
may end processing of the request by using the close method of the event object.
|
CometFilter |
Similar to regular filters, a filter chain is invoked when comet events are processed.
These filters should implement the CometFilter interface (which works in the same way as
the regular Filter interface), and should be declared and mapped in the deployment
descriptor in the same way as a regular filter. The filter chain when processing an event
will only include filters which match all the usual mapping rules, and also implement
the CometFiler interface.
|
|
Asynchronous writes |
When APR is enabled, 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 org.apache.tomcat.sendfile.support
is set to Boolean.TRUE .
Any servlet can instruct Tomcat to perform a sendfile call by setting the appropriate
response attributes. 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
response 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).
- org.apache.tomcat.sendfile.filename: Canonical filename of the file which will be sent as
a String
- org.apache.tomcat.sendfile.start: Start offset as a Long
- org.apache.tomcat.sendfile.start: End offset as a Long
|
|