KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xsocket > stream > io > spi > IIoHandler


1 // $Id: IoHandlerBase.java 1315 2007-06-10 08:05:00Z grro $
2 /*
3  * Copyright (c) xsocket.org, 2006 - 2007. All rights reserved.
4  *
5  * This library is free software; you can redistribute it and/or
6  * modify it under the terms of the GNU Lesser General Public
7  * License as published by the Free Software Foundation; either
8  * version 2.1 of the License, or (at your option) any later version.
9  *
10  * This library is distributed in the hope that it will be useful,
11  * but WITHOUT ANY WARRANTY; without even the implied warranty of
12  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13  * Lesser General Public License for more details.
14  *
15  * You should have received a copy of the GNU Lesser General Public
16  * License along with this library; if not, write to the Free Software
17  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
18  *
19  * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
20  * The latest copy of this software may be found on http://www.xsocket.org/
21  */
22 package org.xsocket.stream.io.spi;
23
24 import java.io.IOException JavaDoc;
25 import java.net.InetAddress JavaDoc;
26 import java.nio.ByteBuffer JavaDoc;
27 import java.util.LinkedList JavaDoc;
28 import java.util.Map JavaDoc;
29
30 import org.xsocket.ClosedConnectionException;
31
32
33
34 /**
35  * The <code>IIoHandler</code> is responsible to perform the low level io operation of a
36  * {@link IConnection}. Each connection holds a dedicated io handler. There
37  * is always a 1:1 life cycle relationship between the connection instance and the io handler
38  * instance.
39  * Because a connection object is stateful, the io handler is (implicit) stateful, too.
40  * The io handler has to handle the read and write operations independently. There is no
41  * implicit call behaviour like request-response. <br>
42  * The io handler is responsible to notify io events by calling the assigned
43  * {@link IIoHandlerContext} reference. <br><br>
44  *
45  * The implementation needn't to be threadsafe
46  *
47  * <b>This class is experimental</b> and is subject to change
48  *
49  * @author grro@xsocket.org
50  */
51 public interface IIoHandler {
52     
53     
54     /**
55      * "starts" the handler. Callback methods will not be called before
56      * this method has been performed.
57      *
58      * @param callbackHandler the callback handler
59      */
60     public void init(IIoHandlerCallback callbackHandler) throws IOException JavaDoc;
61         
62     
63     
64     /**
65      * returns the local address of the underlying connection.
66      *
67      * @return the local address of the underlying connection
68      */
69     public InetAddress JavaDoc getLocalAddress();
70
71     
72     /**
73      * returns the local port of the underlying connection.
74      *
75      * @return the local port of the underlying connection
76      */
77     public int getLocalPort();
78     
79     
80     
81     /**
82      * returns the address of the remote host of the underlying connection.
83      *
84      * @return the address of the remote host of the underlying connection
85      */
86     public InetAddress JavaDoc getRemoteAddress();
87     
88     
89     /**
90      * returns the port of the remote host of the underlying connection.
91      *
92      * @return the port of the remote host of the underlying connection
93      */
94     public int getRemotePort();
95     
96     
97     
98     /**
99      * sets the idle timeout.
100      *
101      * @param timeout the idle timeout
102      */
103     public void setIdleTimeoutSec(int timeout);
104     
105     
106     
107     /**
108      * return a unique conection id
109      * @return unique conection is
110      */
111     public String JavaDoc getId();
112     
113     /**
114      * sets the connection timout.
115      *
116      * @param timeout the connection timeout
117      */
118     public void setConnectionTimeoutSec(int timeout);
119     
120      
121     /**
122      * returns the connection timeout.
123      *
124      * @return the connection timeout
125      */
126     public int getConnectionTimeoutSec();
127     
128     
129     /**
130      * returns the idle timeout.
131      *
132      * @return the idle timeout
133      */
134     public int getIdleTimeoutSec();
135     
136     
137     /**
138      * returns the vlaue of a option
139      *
140      * @param name the name of the option
141      * @return the value of the option
142      * @throws IOException In an I/O error occurs
143      */
144     public Object JavaDoc getOption(String JavaDoc name) throws IOException JavaDoc;
145     
146     
147     
148     /**
149      * Returns an unmodifiable map of the options supported by this endpont.
150      *
151      * The key in the returned map is the name of a option, and its value
152      * is the type of the option value. The returned map will never contain null keys or values.
153      *
154      * @return An unmodifiable map of the options supported by this channel
155      */
156     public Map JavaDoc<String JavaDoc,Class JavaDoc> getOptions();
157     
158     
159
160     /**
161      * set a option
162      *
163      * @param name the option name
164      * @param value the option value
165      * @throws IOException In an I/O error occurs
166      */
167     public void setOption(String JavaDoc name, Object JavaDoc value) throws IOException JavaDoc;
168     
169     
170     /**
171      * check, if the handler (underlying connection) is open.
172      *
173      * @return true, if the handler is open
174      */
175     public boolean isOpen();
176         
177     
178     /**
179      * non-blocking close of the handler. <br><br>
180      *
181      * The implementation has to be threadsafe
182      *
183      * @param immediate if true, close the connection immediate. If false remaining
184      * out buffers (collected by the writOutgoing methods) has
185      * to written before closing
186      * @throws IOException If some other I/O error occurs
187      */
188     public void close(boolean immediate) throws IOException JavaDoc;
189     
190
191     /**
192      * non-blocking write. Because the IIoHandler is free to write the given buffer within
193      * a backgound avtivity, the caller can't reuse the buffer, util the
194      * {@link IIoHandlerCallback#onWritten(IOException)} call back method has been called.
195      *
196      * @param buffer the data to add into the out buffer
197      * @throws ClosedConnectionException if the underlying connection is already closed
198      * @throws IOException If some other I/O error occurs
199      */
200     public void writeOutgoing(ByteBuffer JavaDoc buffer) throws ClosedConnectionException, IOException JavaDoc;
201     
202     
203     
204     /**
205      * non-blocking write. Because the IIoHandler is free to write the given buffers
206      * within a backgound avtivity, the caller can't reuse the buffers, util the
207      * {@link IIoHandlerCallback#onWritten(IOException)} call back method has been called.
208      *
209      * @param buffers the datas to add into the out buffer
210      * @throws ClosedConnectionException if the underlying connection is already closed
211      * @throws IOException If some other I/O error occurs
212      */
213     public void writeOutgoing(LinkedList JavaDoc<ByteBuffer JavaDoc> buffers) throws ClosedConnectionException, IOException JavaDoc;
214
215     
216
217     /**
218      * returns the size of the data which have already been written, but not
219      * yet transferred to the underlying socket.
220      *
221      * @return the size of the pending data to write
222      */
223     public int getPendingWriteDataSize();
224     
225     
226     
227     /**
228      * suspend reading data from the underlying subsystem
229      *
230      * @throws IOException If some other I/O error occurs
231      */
232     public void suspendRead() throws IOException JavaDoc;
233     
234
235     /**
236      * resume reading data from the underlying subsystem
237      *
238      * @throws IOException If some other I/O error occurs
239      */
240     public void resumeRead() throws IOException JavaDoc;
241     
242     /**
243      * drains the handler's read buffer. Because the buffers can be store temporally by
244      * the connection and accessed later, the passed over buffers are not subject of reuse.<br>
245      * This method will only be called within the same thread, which performs the
246      * {@link IIoHandlerCallback#onDataRead()} method.
247      * <pre>
248      * Example Stacktrace:
249      * [DataReaderThread]
250      * &lt;IIoHandler&gt;.drainIncomming()
251      * &lt;IIoHandlerCallback&gt;.onDataRead()
252      * ...
253      * </pre>
254      *
255      * @return the content of the handler's read buffer
256      */
257     public LinkedList JavaDoc<ByteBuffer JavaDoc> drainIncoming();
258 }
259
Popular Tags