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.http.nio.reactor;
29
30 import java.net.SocketAddress;
31 import java.nio.channels.ByteChannel;
32
33 /**
34 * IOSession interface represents a sequence of logically related data exchanges
35 * between two end points.
36 * <p>
37 * The channel associated with implementations of this interface can be used to
38 * read data from and write data to the session.
39 * <p>
40 * I/O sessions are not bound to an execution thread, therefore one cannot use
41 * the context of the thread to store a session's state. All details about
42 * a particular session must be stored within the session itself, usually
43 * using execution context associated with it.
44 * <p>
45 * Implementations of this interface are expected to be threading safe.
46 *
47 * @since 4.0
48 */
49 public interface IOSession {
50
51 /**
52 * Name of the context attribute key, which can be used to obtain the
53 * session attachment object.
54 */
55 String ATTACHMENT_KEY = "http.session.attachment";
56
57 int ACTIVE = 0;
58 int CLOSING = 1;
59 int CLOSED = Integer.MAX_VALUE;
60
61 /**
62 * Returns the underlying I/O channel associated with this session.
63 *
64 * @return the I/O channel.
65 */
66 ByteChannel channel();
67
68 /**
69 * Returns address of the remote peer.
70 *
71 * @return socket address.
72 */
73 SocketAddress getRemoteAddress();
74
75 /**
76 * Returns local address.
77 *
78 * @return socket address.
79 */
80 SocketAddress getLocalAddress();
81
82 /**
83 * Returns mask of I/O evens this session declared interest in.
84 *
85 * @return I/O event mask.
86 */
87 int getEventMask();
88
89 /**
90 * Declares interest in I/O event notifications by setting the event mask
91 * associated with the session
92 *
93 * @param ops new I/O event mask.
94 */
95 void setEventMask(int ops);
96
97 /**
98 * Declares interest in a particular I/O event type by updating the event
99 * mask associated with the session.
100 *
101 * @param op I/O event type.
102 */
103 void setEvent(int op);
104
105 /**
106 * Clears interest in a particular I/O event type by updating the event
107 * mask associated with the session.
108 *
109 * @param op I/O event type.
110 */
111 void clearEvent(int op);
112
113 /**
114 * Terminates the session gracefully and closes the underlying I/O channel.
115 * This method ensures that session termination handshake, such as the one
116 * used by the SSL/TLS protocol, is correctly carried out.
117 */
118 void close();
119
120 /**
121 * Terminates the session by shutting down the underlying I/O channel.
122 */
123 void shutdown();
124
125 /**
126 * Returns status of the session:
127 * <p>
128 * {@link #ACTIVE}: session is active.
129 * <p>
130 * {@link #CLOSING}: session is being closed.
131 * <p>
132 * {@link #CLOSED}: session has been terminated.
133 *
134 * @return session status.
135 */
136 int getStatus();
137
138 /**
139 * Determines if the session has been terminated.
140 *
141 * @return {@code true} if the session has been terminated,
142 * {@code false} otherwise.
143 */
144 boolean isClosed();
145
146 /**
147 * Returns value of the socket timeout in milliseconds. The value of
148 * {@code 0} signifies the session cannot time out.
149 *
150 * @return socket timeout.
151 */
152 int getSocketTimeout();
153
154 /**
155 * Sets value of the socket timeout in milliseconds. The value of
156 * {@code 0} signifies the session cannot time out.
157 *
158 * @param timeout socket timeout.
159 */
160 void setSocketTimeout(int timeout);
161
162 /**
163 * Quite often I/O sessions need to maintain internal I/O buffers in order
164 * to transform input / output data prior to returning it to the consumer or
165 * writing it to the underlying channel. Memory management in HttpCore NIO
166 * is based on the fundamental principle that the data consumer can read
167 * only as much input data as it can process without having to allocate more
168 * memory. That means, quite often some input data may remain unread in one
169 * of the internal or external session buffers. The I/O reactor can query
170 * the status of these session buffers, and make sure the consumer gets
171 * notified correctly as more data gets stored in one of the session
172 * buffers, thus allowing the consumer to read the remaining data once it
173 * is able to process it
174 * <p>
175 * I/O sessions can be made aware of the status of external session buffers
176 * using the {@link SessionBufferStatus} interface.
177 */
178 void setBufferStatus(SessionBufferStatus status);
179
180 /**
181 * Determines if the input buffer associated with the session contains data.
182 *
183 * @return {@code true} if the session input buffer contains data,
184 * {@code false} otherwise.
185 */
186 boolean hasBufferedInput();
187
188 /**
189 * Determines if the output buffer associated with the session contains
190 * data.
191 *
192 * @return {@code true} if the session output buffer contains data,
193 * {@code false} otherwise.
194 */
195 boolean hasBufferedOutput();
196
197 /**
198 * This method can be used to associate a particular object with the
199 * session by the given attribute name.
200 * <p>
201 * I/O sessions are not bound to an execution thread, therefore one cannot
202 * use the context of the thread to store a session's state. All details
203 * about a particular session must be stored within the session itself.
204 *
205 * @param name name of the attribute.
206 * @param obj value of the attribute.
207 */
208 void setAttribute(String name, Object obj);
209
210 /**
211 * Returns the value of the attribute with the given name. The value can be
212 * {@code null} if not set.
213 * <p>
214 * The value of the session attachment object can be obtained using
215 * {@link #ATTACHMENT_KEY} name.
216 *
217 * @see #setAttribute(String, Object)
218 *
219 * @param name name of the attribute.
220 * @return value of the attribute.
221 */
222 Object getAttribute(String name);
223
224 /**
225 * Removes attribute with the given name.
226 *
227 * @see #setAttribute(String, Object)
228 *
229 * @param name name of the attribute to be removed.
230 * @return value of the removed attribute.
231 */
232 Object removeAttribute(String name);
233
234 }