001/* 002 * ==================================================================== 003 * Licensed to the Apache Software Foundation (ASF) under one 004 * or more contributor license agreements. See the NOTICE file 005 * distributed with this work for additional information 006 * regarding copyright ownership. The ASF licenses this file 007 * to you under the Apache License, Version 2.0 (the 008 * "License"); you may not use this file except in compliance 009 * with the License. You may obtain a copy of the License at 010 * 011 * http://www.apache.org/licenses/LICENSE-2.0 012 * 013 * Unless required by applicable law or agreed to in writing, 014 * software distributed under the License is distributed on an 015 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 016 * KIND, either express or implied. See the License for the 017 * specific language governing permissions and limitations 018 * under the License. 019 * ==================================================================== 020 * 021 * This software consists of voluntary contributions made by many 022 * individuals on behalf of the Apache Software Foundation. For more 023 * information on the Apache Software Foundation, please see 024 * <http://www.apache.org/>. 025 * 026 */ 027 028package org.apache.http.nio.reactor; 029 030import java.net.SocketAddress; 031import java.nio.channels.ByteChannel; 032 033/** 034 * IOSession interface represents a sequence of logically related data exchanges 035 * between two end points. 036 * <p> 037 * The channel associated with implementations of this interface can be used to 038 * read data from and write data to the session. 039 * <p> 040 * I/O sessions are not bound to an execution thread, therefore one cannot use 041 * the context of the thread to store a session's state. All details about 042 * a particular session must be stored within the session itself, usually 043 * using execution context associated with it. 044 * <p> 045 * Implementations of this interface are expected to be threading safe. 046 * 047 * @since 4.0 048 */ 049public interface IOSession { 050 051 /** 052 * Name of the context attribute key, which can be used to obtain the 053 * session attachment object. 054 */ 055 public static final String ATTACHMENT_KEY = "http.session.attachment"; 056 057 public static final int ACTIVE = 0; 058 public static final int CLOSING = 1; 059 public static final int CLOSED = Integer.MAX_VALUE; 060 061 /** 062 * Returns the underlying I/O channel associated with this session. 063 * 064 * @return the I/O channel. 065 */ 066 ByteChannel channel(); 067 068 /** 069 * Returns address of the remote peer. 070 * 071 * @return socket address. 072 */ 073 SocketAddress getRemoteAddress(); 074 075 /** 076 * Returns local address. 077 * 078 * @return socket address. 079 */ 080 SocketAddress getLocalAddress(); 081 082 /** 083 * Returns mask of I/O evens this session declared interest in. 084 * 085 * @return I/O event mask. 086 */ 087 int getEventMask(); 088 089 /** 090 * Declares interest in I/O event notifications by setting the event mask 091 * associated with the session 092 * 093 * @param ops new I/O event mask. 094 */ 095 void setEventMask(int ops); 096 097 /** 098 * Declares interest in a particular I/O event type by updating the event 099 * 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}