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  import java.util.concurrent.locks.Lock;
33  
34  import org.apache.hc.core5.io.ModalCloseable;
35  import org.apache.hc.core5.util.Identifiable;
36  import org.apache.hc.core5.util.Timeout;
37  
38  /**
39   * IOSession interface represents a sequence of logically related data exchanges
40   * between two end points.
41   * <p>
42   * The channel associated with implementations of this interface can be used to
43   * read data from and write data to the session.
44   * <p>
45   * I/O sessions are not bound to an execution thread, therefore one cannot use
46   * the context of the thread to store a session's state. All details about
47   * a particular session must be stored within the session itself, usually
48   * using execution context associated with it.
49   * <p>
50   * Implementations of this interface are expected to be threading safe.
51   *
52   * @since 4.0
53   */
54  public interface IOSession extends ModalCloseable, Identifiable {
55  
56      int ACTIVE       = 0;
57      int CLOSING      = 1;
58      int CLOSED       = Integer.MAX_VALUE;
59  
60      /**
61       * Returns session lock that should be used by I/O event handlers
62       * to synchronize access to the session.
63       *
64       * @since 5.0
65       */
66      Lock lock();
67  
68      /**
69       * Inserts {@link Command} at the end of the command queue.
70       *
71       * @since 5.0
72       */
73      void enqueue(Command command, Command.Priority priority);
74  
75      /**
76       * Tests if there enqueued commands pending execution.
77       *
78       * @since 5.0
79       */
80      boolean hasCommands();
81  
82      /**
83       * Removes first {@link Command} from the command queue if available.
84       *
85       * @since 5.0
86       */
87      Command poll();
88  
89      /**
90       * Returns the underlying I/O channel associated with this session.
91       *
92       * @return the I/O channel.
93       */
94      ByteChannel channel();
95  
96      /**
97       * Returns address of the remote peer.
98       *
99       * @return socket address.
100      */
101     SocketAddress getRemoteAddress();
102 
103     /**
104      * Returns local address.
105      *
106      * @return socket address.
107      */
108     SocketAddress getLocalAddress();
109 
110     /**
111      * Returns mask of I/O evens this session declared interest in.
112      *
113      * @return I/O event mask.
114      */
115     int getEventMask();
116 
117     /**
118      * Declares interest in I/O event notifications by setting the event mask
119      * associated with the session
120      *
121      * @param ops new I/O event mask.
122      */
123     void setEventMask(int ops);
124 
125     /**
126      * Declares interest in a particular I/O event type by updating the event
127      * mask associated with the session.
128      *
129      * @param op I/O event type.
130      */
131     void setEvent(int op);
132 
133     /**
134      * Clears interest in a particular I/O event type by updating the event
135      * mask associated with the session.
136      *
137      * @param op I/O event type.
138      */
139     void clearEvent(int op);
140 
141     /**
142      * Terminates the session gracefully and closes the underlying I/O channel.
143      * This method ensures that session termination handshake, such as the one
144      * used by the SSL/TLS protocol, is correctly carried out.
145      */
146     @Override
147     void close();
148 
149     /**
150      * Returns status of the session:
151      * <p>
152      * {@link #ACTIVE}: session is active.
153      * <p>
154      * {@link #CLOSING}: session is being closed.
155      * <p>
156      * {@link #CLOSED}: session has been terminated.
157      *
158      * @return session status.
159      */
160     int getStatus();
161 
162     /**
163      * Determines if the session has been terminated.
164      *
165      * @return {@code true} if the session has been terminated,
166      *   {@code false} otherwise.
167      */
168     boolean isClosed();
169 
170     /**
171      * Returns value of the socket timeout in milliseconds. The value of
172      * {@code 0} signifies the session cannot time out.
173      *
174      * @return socket timeout.
175      */
176     Timeout getSocketTimeout();
177 
178     /**
179      * Sets value of the socket timeout in milliseconds. The value of
180      * {@code 0} signifies the session cannot time out.
181      *
182      * @param timeout socket timeout.
183      */
184     void setSocketTimeout(Timeout timeout);
185 
186     /**
187      * Returns timestamp of the last read event.
188      *
189      * @return timestamp.
190      */
191     long getLastReadTime();
192 
193     /**
194      * Returns timestamp of the last write event.
195      *
196      * @return timestamp.
197      */
198     long getLastWriteTime();
199 
200     /**
201      * Updates the timestamp of the last read event
202      */
203     void updateReadTime();
204 
205     /**
206      * Updates the timestamp of the last write event
207      */
208     void updateWriteTime();
209 
210 }