tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r...@apache.org
Subject svn commit: r550556 - in /tomcat/sandbox/comet/java/org/apache/comet: ./ CometEvent.java CometFilter.java CometFilterChain.java CometProcessor.java CometServlet.java
Date Mon, 25 Jun 2007 17:29:59 GMT
Author: remm
Date: Mon Jun 25 10:29:58 2007
New Revision: 550556

URL: http://svn.apache.org/viewvc?view=rev&rev=550556
Log:
- Use a new package as suggested by Costin (maybe o.a.servlets.comet ?). This also has benefits
for the documentation.
- Consider a HttpServlet-like CometServlet abstract class rather than the CometProcessor interface.

Added:
    tomcat/sandbox/comet/java/org/apache/comet/
    tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java   (with props)
    tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java   (with props)
    tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java   (with props)
    tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java   (with props)
    tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java   (with props)

Added: tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java?view=auto&rev=550556
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java (added)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java Mon Jun 25 10:29:58 2007
@@ -0,0 +1,176 @@
+/*
+ * 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.
+ */
+
+
+package org.apache.comet;
+
+import java.io.IOException;
+
+import javax.servlet.http.HttpServletRequest;
+import javax.servlet.http.HttpServletResponse;
+
+/**
+ * The CometEvent interface.
+ * 
+ * @author Filip Hanik
+ * @author Remy Maucherat
+ */
+public interface CometEvent {
+
+    /**
+     * Enumeration describing the major events that the container can invoke 
+     * the CometProcessor 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 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.</li>
+     * <li>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. 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 execution of this method.</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.</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.
+     *  This allows you get an event instantly, and you can perform IO actions
+     *  or close the Comet connection.</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.</li>
+     * </ul>
+     */
+    public enum EventType {BEGIN, READ, END, ERROR, WRITE, EVENT}
+    
+    
+    /**
+     * Event details:
+     * <ul>
+     * <li>TIMEOUT - the connection timed out (sub type of ERROR); note that this ERROR
type is not fatal, and
+     *   the connection will not be closed unless the servlet uses the close method of the
event</li>
+     * <li>CLIENT_DISCONNECT - the client connection was closed (sub type of ERROR)</li>
+     * <li>IOEXCEPTION - an IO exception occurred, such as invalid content, for example,
an invalid chunk block (sub type of ERROR)</li>
+     * <li>WEBAPP_RELOAD - the webapplication is being reloaded (sub type of END)</li>
+     * <li>SERVER_SHUTDOWN - the server is shutting down (sub type of END)</li>
+     * <li>SESSION_END - the servlet ended the session (sub type of END)</li>
+     * </ul>
+     */
+    public enum EventSubType { TIMEOUT, CLIENT_DISCONNECT, IOEXCEPTION, WEBAPP_RELOAD, SERVER_SHUTDOWN,
SESSION_END }
+    
+    
+    /**
+     * 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 getEventType();
+    
+    /**
+     * Returns the sub type of this event.
+     * 
+     * @return EventSubType
+     * @see #EventSubType
+     */
+    public EventSubType getEventSubType();
+
+    /**
+     * Ends the Comet session. This signals to the container that 
+     * the container wants to end the comet session. This will send back to the
+     * client a notice that the server has no more data to send as part of this
+     * request. The servlet should perform any needed cleanup as if it had recieved
+     * an END or ERROR event. 
+     * 
+     * @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 or data is flushed
+     * using <code>response.flushBuffer()</code>. If a timeout occurs, the 
+     * servlet will receive an ERROR/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 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 recieve a write event.<br/>
+     * 
+     * Note: If the servlet is not using ready, and is writing its output inside the
+     * container threads, using this method is not mandatory, but any incomplete writes will
be
+     * performed again in blocking mode.
+     * 
+     * @return boolean true if you can write to the response 
+     */
+    public boolean ready();
+
+    /**
+     * Suspend processing of the connection until the configured timeout occurs, or resume()
is called. In
+     * parctice, this means the servlet will no longer recieve read events. Reading should
always be
+     * performed synchronously in the Tomcat threads unless the connection has been suspended.
+     */
+    public void suspend();
+
+    /**
+     * Will ask 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 had been disabled using
suspend (it is possible
+     * to call suspend again). It is possible to call resume without calling suspend before.
+     */
+    public void resume();
+
+}

Propchange: tomcat/sandbox/comet/java/org/apache/comet/CometEvent.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java?view=auto&rev=550556
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java (added)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java Mon Jun 25 10:29:58 2007
@@ -0,0 +1,82 @@
+/*
+ * 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.
+ */
+
+
+package org.apache.comet;
+
+import java.io.IOException;
+
+import javax.servlet.Filter;
+import javax.servlet.ServletException;
+
+/**
+ * A Comet filter, similar to regular filters, performs filtering tasks on either 
+ * the request to a resource (a Comet servlet), or on the response from a resource, or both.
+ * <br><br>
+ * Filters perform filtering in the <code>doFilterEvent</code> method. Every
Filter has access to 
+ * a FilterConfig object from which it can obtain its initialization parameters, a
+ * reference to the ServletContext which it can use, for example, to load resources
+ * needed for filtering tasks.
+ * <p>
+ * Filters are configured in the deployment descriptor of a web application
+ * <p>
+ * Examples that have been identified for this design are<br>
+ * 1) Authentication Filters <br>
+ * 2) Logging and Auditing Filters <br>
+ * 3) Image conversion Filters <br>
+ * 4) Data compression Filters <br>
+ * 5) Encryption Filters <br>
+ * 6) Tokenizing Filters <br>
+ * 7) Filters that trigger resource access events <br>
+ * 8) XSL/T filters <br>
+ * 9) Mime-type chain Filter <br>
+ * <br>
+ * 
+ * @author Remy Maucherat
+ * @author Filip Hanik
+ */
+public interface CometFilter extends Filter {
+
+    
+    /**
+     * The <code>doFilterEvent</code> method of the CometFilter 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 CometFilterChain 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 CometEvent 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 CometEvent instance containing
+     * the wrapped request to the next filter<br>
+     * 4. a) <strong>Either</strong> invoke the next entity in the chain using
the CometFilterChain 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(CometEvent event, CometFilterChain chain)
+        throws IOException, ServletException;
+    
+
+}

Propchange: tomcat/sandbox/comet/java/org/apache/comet/CometFilter.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java?view=auto&rev=550556
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java (added)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java Mon Jun 25 10:29:58 2007
@@ -0,0 +1,46 @@
+/*
+ * 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.
+ */
+
+
+package org.apache.comet;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+
+/**
+ * A CometFilterChain 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 CometFilterChain 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.
+ * 
+ * @author Remy Maucherat
+ * @author Filip Hanik
+ */
+public interface CometFilterChain {
+
+    
+    /**
+     * 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(CometEvent event) throws IOException, ServletException;
+    
+
+}

Propchange: tomcat/sandbox/comet/java/org/apache/comet/CometFilterChain.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java?view=auto&rev=550556
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java (added)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java Mon Jun 25 10:29:58 2007
@@ -0,0 +1,46 @@
+/*
+ * 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.
+ */
+
+
+package org.apache.comet;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+import javax.servlet.Servlet;
+
+/**
+ * This interface should be implemented by servlets which would like to handle
+ * asynchronous IO, recieving 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 CometProcessor extends Servlet 
+{
+
+    /**
+     * Process the given Comet event.
+     * 
+     * @param event The Comet event that will be processed
+     * @throws IOException
+     * @throws ServletException
+     */
+    public void event(CometEvent event)
+        throws IOException, ServletException;
+
+}

Propchange: tomcat/sandbox/comet/java/org/apache/comet/CometProcessor.java
------------------------------------------------------------------------------
    svn:eol-style = native

Added: tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java
URL: http://svn.apache.org/viewvc/tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java?view=auto&rev=550556
==============================================================================
--- tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java (added)
+++ tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java Mon Jun 25 10:29:58 2007
@@ -0,0 +1,85 @@
+/*
+ * 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.
+ */
+
+
+package org.apache.comet;
+
+import java.io.IOException;
+
+import javax.servlet.ServletException;
+import javax.servlet.http.HttpServlet;
+
+/**
+ * This class should be extended by servlets which would like to handle
+ * asynchronous IO, recieving 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 abstract class CometServlet extends HttpServlet
+{
+
+    /**
+     * Process the given Comet event.
+     * 
+     * @param event The Comet event that will be processed
+     * @throws IOException
+     * @throws ServletException
+     */
+    public void event(CometEvent event)
+        throws IOException, ServletException {
+        if (event.getEventType() == CometEvent.EventType.BEGIN) {
+            doEventBegin(event);
+        } else if (event.getEventType() == CometEvent.EventType.END) {
+            doEventEnd(event);
+        } else if (event.getEventType() == CometEvent.EventType.ERROR) {
+            doEventError(event);
+        } else if (event.getEventType() == CometEvent.EventType.EVENT) {
+            doEventEvent(event);
+        } else if (event.getEventType() == CometEvent.EventType.READ) {
+            doEventRead(event);
+        } else if (event.getEventType() == CometEvent.EventType.WRITE) {
+            doEventWrite(event);
+        }
+    }
+
+    public void doEventBegin(CometEvent event) {
+        
+    }
+    
+    public void doEventEnd(CometEvent event) {
+        
+    }
+    
+    public void doEventError(CometEvent event) {
+        
+    }
+    
+    // ?
+    public void doEventEvent(CometEvent event) {
+        
+    }
+    
+    public void doEventRead(CometEvent event) {
+        
+    }
+    
+    public void doEventWrite(CometEvent event) {
+        
+    }
+    
+}

Propchange: tomcat/sandbox/comet/java/org/apache/comet/CometServlet.java
------------------------------------------------------------------------------
    svn:eol-style = native



---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org


Mime
View raw message