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.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      public static final String ATTACHMENT_KEY = "http.session.attachment";
56  
57      public static final int ACTIVE       = 0;
58      public static final int CLOSING      = 1;
59      public static final 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</code> if the session has been terminated,
142      *   <code>false</code> otherwise.
143      */
144     boolean isClosed();
145 
146     /**
147      * Returns value of the socket timeout in milliseconds. The value of
148      * <code>0</code> 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</code> 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</code> if the session input buffer contains data,
184      *   <code>false</code> 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</code> if the session output buffer contains data,
193      *   <code>false</code> 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</code> 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 }