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