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: [EMAIL PROTECTED]
For additional commands, e-mail: [EMAIL PROTECTED]
