tomcat-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Filip Hanik - Dev Lists <devli...@hanik.com>
Subject Re: 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 19:13:07 GMT
I would suggest org.apache.tomcat.comet, pretty much standard across ASF 
java projects to have org.apache.<project>.<subproject>

no reason to create even more divergence in Tomcat, rather start 
consolidating it

Filip

remm@apache.org wrote:
> 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
>
>
>   


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


Mime
View raw message