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