[jbossweb-commits] JBossWeb SVN: r694 - in trunk/java/org/jboss: servlet and 1 other directories.

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; + +}