CometEvent


1   /*
2    * Licensed to the Apache Software Foundation (ASF) under one or more
3    * contributor license agreements.  See the NOTICE file distributed with
4    * this work for additional information regarding copyright ownership.
5    * The ASF licenses this file to You under the Apache License, Version 2.0
6    * (the "License"); you may not use this file except in compliance with
7    * the License.  You may obtain a copy of the License at
8    * 
9    *      http://www.apache.org/licenses/LICENSE-2.0
10   * 
11   * Unless required by applicable law or agreed to in writing, software
12   * distributed under the License is distributed on an "AS IS" BASIS,
13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14   * See the License for the specific language governing permissions and
15   * limitations under the License.
16   */
17  
18  
19  package org.apache.catalina;
20  
21  import java.io.IOException  ;
22  
23  import javax.servlet.ServletException  ;
24  import javax.servlet.http.HttpServletRequest  ;
25  import javax.servlet.http.HttpServletResponse  ;
26  
27  /**
28   * The CometEvent interface.
29   * 
30   * @author Filip Hanik
31   * @author Remy Maucherat
32   */
33  public interface CometEvent {
34  
35      /**
36       * Enumeration describing the major events that the container can invoke 
37       * the CometProcessors event() method with
38       * BEGIN - will be called at the beginning 
39       *  of the processing of the connection. It can be used to initialize any relevant 
40       *  fields using the request and response objects. Between the end of the processing 
41       *  of this event, and the beginning of the processing of the end or error events,
42       *  it is possible to use the response object to write data on the open connection.
43       *  Note that the response object and depedent OutputStream and Writer are still 
44       *  not synchronized, so when they are accessed by multiple threads, 
45       *  synchronization is mandatory. After processing the initial event, the request 
46       *  is considered to be committed.
47       * READ - This indicates that input data is available, and that one read can be made
48       *  without blocking. The available and ready methods of the InputStream or
49       *  Reader may be used to determine if there is a risk of blocking: the servlet
50       *  should read while data is reported available, and can make one additional read
51       *  without blocking. When encountering a read error or an EOF, the servlet MUST
52       *  report it by either returning false or throwing an exception such as an 
53       *  IOException. This will cause the error event to be invoked, and the connection
54       *  will be closed. It is not allowed to attempt reading data from the request object
55       *  outside of the execution of this method.
56       * END - End may be called to end the processing of the request. Fields that have
57       *  been initialized in the begin method should be reset. After this event has
58       *  been processed, the request and response objects, as well as all their dependent
59       *  objects will be recycled and used to process other requests.
60       * ERROR - Error will be called by the container in the case where an IO exception
61       *  or a similar unrecoverable error occurs on the connection. Fields that have
62       *  been initialized in the begin method should be reset. After this event has
63       *  been processed, the request and response objects, as well as all their dependent
64       *  objects will be recycled and used to process other requests.
65       */
66      public enum EventType {BEGIN, READ, END, ERROR}
67      
68      
69      /**
70       * Event details
71       * TIMEOUT - the connection timed out (sub type of ERROR); note that this ERROR type is not fatal, and
72       *   the connection will not be closed unless the servlet uses the close method of the event
73       * CLIENT_DISCONNECT - the client connection was closed (sub type of ERROR)
74       * IOEXCEPTION - an IO exception occurred, such as invalid content, for example, an invalid chunk block (sub type of ERROR)
75       * WEBAPP_RELOAD - the webapplication is being reloaded (sub type of END)
76       * SERVER_SHUTDOWN - the server is shutting down (sub type of END)
77       * SESSION_END - the servlet ended the session (sub type of END)
78       */
79      public enum EventSubType { TIMEOUT, CLIENT_DISCONNECT, IOEXCEPTION, WEBAPP_RELOAD, SERVER_SHUTDOWN, SESSION_END }
80      
81      
82      /**
83       * Returns the HttpServletRequest.
84       * 
85       * @return HttpServletRequest
86       */
87      public HttpServletRequest   getHttpServletRequest();
88      
89      /**
90       * Returns the HttpServletResponse.
91       * 
92       * @return HttpServletResponse
93       */
94      public HttpServletResponse   getHttpServletResponse();
95      
96      /**
97       * Returns the event type.
98       * 
99       * @return EventType
100      */
101     public EventType getEventType();
102     
103     /**
104      * Returns the sub type of this event.
105      * 
106      * @return EventSubType
107      */
108     public EventSubType getEventSubType();
109     
110     /**
111      * Ends the Comet session. This signals to the container that 
112      * the container wants to end the comet session. This will send back to the
113      * client a notice that the server has no more data to send as part of this
114      * request. The servlet should perform any needed cleanup as if it had recieved
115      * an END or ERROR event. 
116      * 
117      * @throws IOException if an IO exception occurs
118      */
119     public void close() throws IOException  ;
120     
121     /**
122      * Sets the timeout for this Comet connection. Please NOTE, that the implementation 
123      * of a per connection timeout is OPTIONAL and MAY NOT be implemented.<br/>
124      * This method sets the timeout in milliseconds of idle time on the connection.
125      * The timeout is reset every time data is received from the connection or data is flushed
126      * using <code>response.flushBuffer()</code>. If a timeout occurs, the 
127      * <code>error(HttpServletRequest, HttpServletResponse)</code> method is invoked. The 
128      * web application SHOULD NOT attempt to reuse the request and response objects after a timeout
129      * as the <code>error(HttpServletRequest, HttpServletResponse)</code> method indicates.<br/>
130      * This method should not be called asynchronously, as that will have no effect.
131      * 
132      * @param timeout The timeout in milliseconds for this connection, must be a positive value, larger than 0
133      * @throws IOException An IOException may be thrown to indicate an IO error, 
134      *         or that the EOF has been reached on the connection
135      * @throws ServletException An exception has occurred, as specified by the root
136      *         cause
137      * @throws UnsupportedOperationException if per connection timeout is not supported, either at all or at this phase
138      *         of the invocation.
139      */
140     public void setTimeout(int timeout)
141         throws IOException  , ServletException  , UnsupportedOperationException  ;
142 
143 }
144
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags