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}