View Javadoc
1   /*
2    * ====================================================================
3    * Licensed to the Apache Software Foundation (ASF) under one
4    * or more contributor license agreements.  See the NOTICE file
5    * distributed with this work for additional information
6    * regarding copyright ownership.  The ASF licenses this file
7    * to you under the Apache License, Version 2.0 (the
8    * "License"); you may not use this file except in compliance
9    * with the License.  You may obtain a copy of the License at
10   *
11   *   http://www.apache.org/licenses/LICENSE-2.0
12   *
13   * Unless required by applicable law or agreed to in writing,
14   * software distributed under the License is distributed on an
15   * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
16   * KIND, either express or implied.  See the License for the
17   * specific language governing permissions and limitations
18   * under the License.
19   * ====================================================================
20   *
21   * This software consists of voluntary contributions made by many
22   * individuals on behalf of the Apache Software Foundation.  For more
23   * information on the Apache Software Foundation, please see
24   * <http://www.apache.org/>.
25   *
26   */
27  
28  package org.apache.hc.core5.reactor;
29  
30  import java.net.SocketAddress;
31  import java.nio.channels.ByteChannel;
32  
33  import org.apache.hc.core5.io.GracefullyCloseable;
34  import org.apache.hc.core5.util.Identifiable;
35  
36  /**
37   * IOSession interface represents a sequence of logically related data exchanges
38   * between two end points.
39   * <p>
40   * The channel associated with implementations of this interface can be used to
41   * read data from and write data to the session.
42   * <p>
43   * I/O sessions are not bound to an execution thread, therefore one cannot use
44   * the context of the thread to store a session's state. All details about
45   * a particular session must be stored within the session itself, usually
46   * using execution context associated with it.
47   * <p>
48   * Implementations of this interface are expected to be threading safe.
49   *
50   * @since 4.0
51   */
52  public interface IOSession extends GracefullyCloseable, Identifiable {
53  
54      int ACTIVE       = 0;
55      int CLOSING      = 1;
56      int CLOSED       = Integer.MAX_VALUE;
57  
58      /**
59       * Returns the event handler for this session.
60       *
61       * @since 5.0
62       */
63      IOEventHandler getHandler();
64  
65      /**
66       * Sets the event handler for this session.
67       *
68       * @since 5.0
69       */
70      void setHandler(IOEventHandler handler);
71  
72      /**
73       * Inserts {@link Command} at the end of the command queue.
74       *
75       * @since 5.0
76       */
77      void addLast(Command command);
78  
79      /**
80       * Inserts {@link Command} at the front of the command queue.
81       *
82       * @since 5.0
83       */
84      void addFirst(Command command);
85  
86      /**
87       * Retrieves and removes first {@link Command} from the command queue.
88       *
89       * @since 5.0
90       */
91      Command getCommand();
92  
93      /**
94       * Returns the underlying I/O channel associated with this session.
95       *
96       * @return the I/O channel.
97       */
98      ByteChannel channel();
99  
100     /**
101      * Returns address of the remote peer.
102      *
103      * @return socket address.
104      */
105     SocketAddress getRemoteAddress();
106 
107     /**
108      * Returns local address.
109      *
110      * @return socket address.
111      */
112     SocketAddress getLocalAddress();
113 
114     /**
115      * Returns mask of I/O evens this session declared interest in.
116      *
117      * @return I/O event mask.
118      */
119     int getEventMask();
120 
121     /**
122      * Declares interest in I/O event notifications by setting the event mask
123      * associated with the session
124      *
125      * @param ops new I/O event mask.
126      */
127     void setEventMask(int ops);
128 
129     /**
130      * Declares interest in a particular I/O event type by updating the event
131      * mask associated with the session.
132      *
133      * @param op I/O event type.
134      */
135     void setEvent(int op);
136 
137     /**
138      * Clears interest in a particular I/O event type by updating the event
139      * mask associated with the session.
140      *
141      * @param op I/O event type.
142      */
143     void clearEvent(int op);
144 
145     /**
146      * Terminates the session gracefully and closes the underlying I/O channel.
147      * This method ensures that session termination handshake, such as the one
148      * used by the SSL/TLS protocol, is correctly carried out.
149      */
150     @Override
151     void close();
152 
153     /**
154      * Returns status of the session:
155      * <p>
156      * {@link #ACTIVE}: session is active.
157      * <p>
158      * {@link #CLOSING}: session is being closed.
159      * <p>
160      * {@link #CLOSED}: session has been terminated.
161      *
162      * @return session status.
163      */
164     int getStatus();
165 
166     /**
167      * Determines if the session has been terminated.
168      *
169      * @return {@code true} if the session has been terminated,
170      *   {@code false} otherwise.
171      */
172     boolean isClosed();
173 
174     /**
175      * Returns value of the socket timeout in milliseconds. The value of
176      * {@code 0} signifies the session cannot time out.
177      *
178      * @return socket timeout.
179      */
180     int getSocketTimeout();
181 
182     /**
183      * Sets value of the socket timeout in milliseconds. The value of
184      * {@code 0} signifies the session cannot time out.
185      *
186      * @param timeout socket timeout.
187      */
188     void setSocketTimeout(int timeout);
189 
190     /**
191      * Returns timestamp of the last read event.
192      *
193      * @return timestamp.
194      */
195     long getLastReadTime();
196 
197     /**
198      * Returns timestamp of the last write event.
199      *
200      * @return timestamp.
201      */
202     long getLastWriteTime();
203 
204     /**
205      * Updates the timestamp of the last read event
206      */
207     void updateReadTime();
208 
209     /**
210      * Updates the timestamp of the last write event
211      */
212     void updateWriteTime();
213 
214 }