Author: remy.maucherat(a)jboss.com
Date: 2008-07-01 13:01:58 -0400 (Tue, 01 Jul 2008)
New Revision: 694
Added:
trunk/java/org/jboss/servlet/
trunk/java/org/jboss/servlet/http/
trunk/java/org/jboss/servlet/http/HttpEvent.java
trunk/java/org/jboss/servlet/http/HttpEventFilter.java
trunk/java/org/jboss/servlet/http/HttpEventFilterChain.java
trunk/java/org/jboss/servlet/http/HttpEventServlet.java
Log:
- Add "new" Comet API matching the proposal to the Servlet API (which will not
be accepted).
Added: trunk/java/org/jboss/servlet/http/HttpEvent.java
===================================================================
--- trunk/java/org/jboss/servlet/http/HttpEvent.java (rev 0)
+++ trunk/java/org/jboss/servlet/http/HttpEvent.java 2008-07-01 17:01:58 UTC (rev 694)
@@ -0,0 +1,178 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site:
http://www.fsf.org.
+ */
+
+package org.jboss.servlet.http;
+
+import java.io.IOException;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * The HttpEvent interface, which indicates the type of the event that is
+ * being processed, as well as provides useful callbacks and utility objects.
+ */
+public interface HttpEvent {
+
+ /**
+ * Enumeration describing the major events that the container can invoke
+ * the EventHttpServlet event() method with:
+ * <ul>
+ * <li>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 dependent OutputStream and Writer are
+ * not synchronized, so when they are accessed by multiple threads adequate
+ * synchronization is needed. After processing the initial event, the request
+ * is considered to be committed.</li>
+ * <li>EOF - The end of file of the input has been reached, and no further data
is
+ * available. This event is sent because it can be difficult to detect otherwise.
+ * Following the processing of this event and the processing of any subsequent
+ * event, the event will be suspended.</li>
+ * <li>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. In particular,
+ * this event will be called if the HTTP session associated with the connection
+ * times out, if the web application is reloaded, if the server is shutdown, or
+ * if the connection was closed asynchronously.</li>
+ * <li>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.</li>
+ * <li>EVENT - Event will be called by the container after the resume() method
is called,
+ * during which any operations can be performed, including closing the connection
+ * using the close() method.</li>
+ * <li>READ - This indicates that input data is available, and that at least
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
+ * must continue reading while data is reported available. When encountering a read
error,
+ * the Servlet should report it by propagating the exception properly. Throwing
+ * an exception will cause the error event to be invoked, and the connection
+ * will be closed.
+ * Alternately, it is also possible to catch any exception, perform clean up
+ * on any data structure the Servlet may be using, and using the close method
+ * of the event. It is not allowed to attempt reading data from the request
+ * object outside of the processing of this event, unless the suspend() method
+ * has been used.</li>
+ * <li>TIMEOUT - the connection timed out, but the connection will not be
closed unless
+ * the servlet uses the close method of the event</li>
+ * <li>WRITE - Write is sent if the Servlet is using the ready method. This
means that
+ * the connection is ready to receive data to be written out. This event will never
+ * be received if the Servlet is not using the ready() method, or if the ready()
+ * method always returns true.</li>
+ * </ul>
+ */
+ public enum EventType { BEGIN, END, ERROR, EVENT, READ, EOF, TIMEOUT, WRITE }
+
+
+ /**
+ * Returns the HttpServletRequest.
+ *
+ * @return HttpServletRequest
+ */
+ public HttpServletRequest getHttpServletRequest();
+
+ /**
+ * Returns the HttpServletResponse.
+ *
+ * @return HttpServletResponse
+ */
+ public HttpServletResponse getHttpServletResponse();
+
+ /**
+ * Returns the event type.
+ *
+ * @return EventType
+ * @see #EventType
+ */
+ public EventType getType();
+
+ /**
+ * Ends the request, which marks the end of the event stream. This will send
+ * back to the client a notice that the server has no more data to send
+ * as part of this request. An END event will be sent to the Servlet.
+ *
+ * @throws IOException if an IO exception occurs
+ */
+ public void close() throws IOException;
+
+ /**
+ * This method sets the timeout in milliseconds of idle time on the connection.
+ * The timeout is reset every time data is received from the connection. If a timeout
occurs, the
+ * Servlet will receive an TIMEOUT event which will not result in automatically
closing
+ * the event (the event may be closed using the close() method).
+ *
+ * @param timeout The timeout in milliseconds for this connection, must be a positive
value, larger than 0
+ */
+ public void setTimeout(int timeout);
+
+ /**
+ * Returns true when data may be read from the connection (the flag becomes false if
no data
+ * is available to read). When the flag becomes false, the Servlet can attempt to
read additional
+ * data, but it will block until data is available. This method is equivalent to
+ * (Reader.ready() > 0) and InputStream.available().
+ *
+ * @return boolean true if data can be read without blocking
+ */
+ public boolean isReadReady();
+
+ /**
+ * Returns true when data may be written to the connection (the flag becomes false
+ * when the client is unable to accept data fast enough). When the flag becomes
false,
+ * the Servlet must stop writing data. If there's an attempt to flush additional
data
+ * to the client and data still cannot be written immediately, an IOException will be
+ * thrown. If calling this method returns false, it will also
+ * request notification when the connection becomes available for writing again, and
the
+ * Servlet will receive a write event.
+ * <br>
+ * Note: If the Servlet is not using isWriteReady, and is writing its output inside
the
+ * container threads (inside the event() method processing, for example), using this
method
+ * is not mandatory, and writes will block until all bytes are written.
+ *
+ * @return boolean true if data can be written without blocking
+ */
+ public boolean isWriteReady();
+
+ /**
+ * Suspend processing of the connection until the configured timeout occurs,
+ * or resume() is called. In practice, this means the servlet will no longer
+ * receive read events. Reading should always be performed synchronously in
+ * the Tomcat threads unless the connection has been suspended.
+ */
+ public void suspend();
+
+ /**
+ * Resume will cause the Servlet container to send a generic event
+ * to the Servlet, where the request can be processed synchronously
+ * (for example, it is possible to use this to complete the request after
+ * some asynchronous processing is done). This also resumes read events
+ * if they have been disabled using suspend. It is then possible to call suspend
+ * again later. It is also possible to call resume without calling suspend before.
+ * This method must be called asynchronously.
+ */
+ public void resume();
+
+}
Added: trunk/java/org/jboss/servlet/http/HttpEventFilter.java
===================================================================
--- trunk/java/org/jboss/servlet/http/HttpEventFilter.java (rev
0)
+++ trunk/java/org/jboss/servlet/http/HttpEventFilter.java 2008-07-01 17:01:58 UTC (rev
694)
@@ -0,0 +1,66 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site:
http://www.fsf.org.
+ */
+
+package org.jboss.servlet.http;
+
+import java.io.IOException;
+
+import javax.servlet.Filter;
+import javax.servlet.ServletException;
+
+/**
+ * An event filter, similar to regular filters, performs filtering tasks on either
+ * the request to a resource (an event driven Servlet), or on the response from a
resource, or both.
+ */
+public interface HttpEventFilter extends Filter {
+
+
+ /**
+ * The <code>doFilterEvent</code> method of the HttpEventFilter is called
by the container
+ * each time a request/response pair is passed through the chain due
+ * to a client event for a resource at the end of the chain. The HttpEventFilterChain
passed in to this
+ * method allows the Filter to pass on the event to the next entity in the
+ * chain.<p>
+ * A typical implementation of this method would follow the following pattern:-
<br>
+ * 1. Examine the request<br>
+ * 2. Optionally wrap the request object contained in the event with a custom
implementation to
+ * filter content or headers for input filtering and pass a HttpEvent instance
containing
+ * the wrapped request to the next filter<br>
+ * 3. Optionally wrap the response object contained in the event with a custom
implementation to
+ * filter content or headers for output filtering and pass a HttpEvent instance
containing
+ * the wrapped request to the next filter<br>
+ * 4. a) <strong>Either</strong> invoke the next entity in the chain
using the HttpEventFilterChain
+ * object (<code>chain.doFilterEvent()</code>), <br>
+ * 4. b) <strong>or</strong> not pass on the request/response pair to the
next entity in the
+ * filter chain to block the event processing<br>
+ * 5. Directly set fields on the response after invocation of the next entity in the
filter chain.
+ *
+ * @param event the event that is being processed. Another event may be passed along
the chain.
+ * @param chain
+ * @throws IOException
+ * @throws ServletException
+ */
+ public void doFilterEvent(HttpEvent event, HttpEventFilterChain chain)
+ throws IOException, ServletException;
+
+
+}
Added: trunk/java/org/jboss/servlet/http/HttpEventFilterChain.java
===================================================================
--- trunk/java/org/jboss/servlet/http/HttpEventFilterChain.java
(rev 0)
+++ trunk/java/org/jboss/servlet/http/HttpEventFilterChain.java 2008-07-01 17:01:58 UTC
(rev 694)
@@ -0,0 +1,47 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site:
http://www.fsf.org.
+ */
+
+package org.jboss.servlet.http;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+
+/**
+ * A HttpEventFilterChain is an object provided by the Servlet container to the
developer
+ * giving a view into the invocation chain of a filtered event for a resource. Filters
+ * use the HttpEventFilterChain to invoke the next filter in the chain, or if the calling
filter
+ * is the last filter in the chain, to invoke the resource at the end of the chain.
+ */
+public interface HttpEventFilterChain {
+
+
+ /**
+ * Causes the next filter in the chain to be invoked, or if the calling filter is the
last filter
+ * in the chain, causes the resource at the end of the chain to be invoked.
+ *
+ * @param event the event to pass along the chain.
+ */
+ public void doFilterEvent(HttpEvent event) throws IOException, ServletException;
+
+
+}
Added: trunk/java/org/jboss/servlet/http/HttpEventServlet.java
===================================================================
--- trunk/java/org/jboss/servlet/http/HttpEventServlet.java (rev
0)
+++ trunk/java/org/jboss/servlet/http/HttpEventServlet.java 2008-07-01 17:01:58 UTC (rev
694)
@@ -0,0 +1,50 @@
+/*
+ * JBoss, Home of Professional Open Source
+ * Copyright 2008, JBoss Inc., and individual contributors as indicated
+ * by the @authors tag. See the copyright.txt in the distribution for a
+ * full listing of individual contributors.
+ *
+ * This is free software; you can redistribute it and/or modify it
+ * under the terms of the GNU Lesser General Public License as
+ * published by the Free Software Foundation; either version 2.1 of
+ * the License, or (at your option) any later version.
+ *
+ * This software is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this software; if not, write to the Free
+ * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
+ * 02110-1301 USA, or see the FSF site:
http://www.fsf.org.
+ */
+
+package org.jboss.servlet.http;
+
+import java.io.IOException;
+
+import javax.servlet.Servlet;
+import javax.servlet.ServletException;
+
+/**
+ * This interface should be implemented by Servlets which would like to handle
+ * asynchronous IO, receiving events when data is available for reading, and
+ * being able to output data without the need for being invoked by the container.
+ * Note: When this interface is implemented, the service method of the Servlet will
+ * never be called, and will be replaced with a begin event.
+ */
+public interface HttpEventServlet extends Servlet
+{
+
+ /**
+ * Process the given IO event.
+ *
+ * @param event The event that will be processed
+ * @throws IOException
+ * @throws ServletException
+ */
+ public void event(HttpEvent event)
+ throws IOException, ServletException;
+
+}