001: /*
002: * Copyright (c) xsocket.org, 2006 - 2008. All rights reserved.
003: *
004: * This library is free software; you can redistribute it and/or
005: * modify it under the terms of the GNU Lesser General Public
006: * License as published by the Free Software Foundation; either
007: * version 2.1 of the License, or (at your option) any later version.
008: *
009: * This library is distributed in the hope that it will be useful,
010: * but WITHOUT ANY WARRANTY; without even the implied warranty of
011: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
012: * Lesser General Public License for more details.
013: *
014: * You should have received a copy of the GNU Lesser General Public
015: * License along with this library; if not, write to the Free Software
016: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
017: *
018: * Please refer to the LGPL license at: http://www.gnu.org/copyleft/lesser.txt
019: * The latest copy of this software may be found on http://www.xsocket.org/
020: */
021: package org.xsocket.connection.spi;
022:
023: import java.io.IOException;
024: import java.net.InetAddress;
025: import java.nio.ByteBuffer;
026: import java.nio.channels.ClosedChannelException;
027: import java.util.Map;
028:
029: /**
030: * The <code>IIoHandler</code> is responsible to perform the low level io operation of a
031: * {@link IReadWriteableConnection}. Each connection holds a dedicated io handler. There
032: * is always a 1:1 life cycle relationship between the connection instance and the io handler
033: * instance.
034: * Because a connection object is stateful, the io handler is (implicit) stateful, too.
035: * The io handler has to handle the read and write operations independently. There is no
036: * implicit call behaviour like request-response. <br>
037: * The io handler is responsible to notify io events by calling the assigned
038: * {@link IIoHandlerCallback} reference. <br><br>
039: *
040: * The implementation needn`t to be threadsafe
041: *
042: * @author grro@xsocket.org
043: */
044: public interface IIoHandler {
045:
046: /**
047: * "starts" the handler. Callback methods will not be called before
048: * this method has been performed.
049: *
050: *
051: * @param callbackHandler the callback handler
052: */
053: public void init(IIoHandlerCallback callbackHandler)
054: throws IOException;
055:
056: /**
057: * return a unique conection id
058: * @return unique conection is
059: */
060: public String getId();
061:
062: /**
063: * returns the local address of the underlying connection.
064: *
065: * @return the local address of the underlying connection
066: */
067: public InetAddress getLocalAddress();
068:
069: /**
070: * returns the local port of the underlying connection.
071: *
072: * @return the local port of the underlying connection
073: */
074: public int getLocalPort();
075:
076: /**
077: * reset internal caches and buffers of the io handler
078: *
079: * @return true, is handler has been reset
080: */
081: public boolean reset();
082:
083: /**
084: * returns the address of the remote host of the underlying connection.
085: *
086: * @return the address of the remote host of the underlying connection
087: */
088: public InetAddress getRemoteAddress();
089:
090: /**
091: * returns the port of the remote host of the underlying connection.
092: *
093: * @return the port of the remote host of the underlying connection
094: */
095: public int getRemotePort();
096:
097: /**
098: * sets the idle timeout.
099: *
100: * @param timeout the idle timeout
101: */
102: public void setIdleTimeoutMillis(long timeout);
103:
104: /**
105: * returns the idle timeout.
106: *
107: * @return the idle timeout
108: */
109: public long getIdleTimeoutMillis();
110:
111: /**
112: * sets the connection timout.
113: *
114: * @param timeout the connection timeout
115: */
116: public void setConnectionTimeoutMillis(long timeout);
117:
118: /**
119: * returns the connection timeout.
120: *
121: * @return the connection timeout
122: */
123: public long getConnectionTimeoutMillis();
124:
125: /**
126: * returns the remaining time before a idle timeout occurs
127: *
128: * @return the remaining time
129: */
130: public long getRemainingMillisToIdleTimeout();
131:
132: /**
133: * returns the remaining time before a connection timeout occurs
134: *
135: * @return the remaining time
136: */
137: public long getRemainingMillisToConnectionTimeout();
138:
139: /**
140: * returns the value of a option
141: *
142: * @param name the name of the option
143: * @return the value of the option
144: * @throws IOException In an I/O error occurs
145: */
146: public Object getOption(String name) throws IOException;
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: @SuppressWarnings("unchecked")
157: public Map<String, Class> getOptions();
158:
159: /**
160: * set a option
161: *
162: * @param name the option name
163: * @param value the option value
164: * @throws IOException In an I/O error occurs
165: */
166: public void setOption(String name, Object value) throws IOException;
167:
168: /**
169: * check, if the handler (underlying connection) is open.
170: *
171: * @return true, if the handler is open
172: */
173: public boolean isOpen();
174:
175: /**
176: * non-blocking close of the handler. <br><br>
177: *
178: * The implementation has to be threadsafe
179: *
180: * @param immediate if true, close the connection immediate. If false remaining
181: * out buffers (collected by the writOutgoing methods) has
182: * to written before closing
183: * @throws IOException If some other I/O error occurs
184: */
185: public void close(boolean immediate) throws IOException;
186:
187: /**
188: * non-blocking write. Because the IIoHandler is free to write the given buffers
189: * within a backgound activity, the caller can`t reuse the buffers, until the
190: * {@link IIoHandlerCallback#onWritten(IOException)} call back method has been called.
191: *
192: * @param buffers the data to add into the out buffer
193: * @throws ClosedChannelException if the underlying connection is already closed
194: * @throws IOException If some other I/O error occurs
195: */
196: public void write(ByteBuffer[] buffers)
197: throws ClosedChannelException, IOException;
198:
199: /**
200: * returns the size of the data which have already been written, but not
201: * yet transferred to the underlying socket.
202: *
203: * @return the size of the pending data to write
204: */
205: public int getPendingWriteDataSize();
206:
207: /**
208: * returns if there are data to send
209: *
210: * @return true, if there are data to send
211: */
212: public boolean hasDataToSend();
213:
214: /**
215: * suspend reading data from the underlying subsystem
216: *
217: * @throws IOException If some other I/O error occurs
218: */
219: public void suspendRead() throws IOException;
220:
221: /**
222: * resume reading data from the underlying subsystem
223: *
224: * @throws IOException If some other I/O error occurs
225: */
226: public void resumeRead() throws IOException;
227: }
|