KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xsocket > stream > IDataHandler


1 // $Id: IDataHandler.java 1534 2007-07-17 14:41:06Z 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;
23
24 import java.io.IOException JavaDoc;
25 import java.nio.BufferUnderflowException JavaDoc;
26
27 import org.xsocket.MaxReadSizeExceededException;
28
29
30
31
32
33
34
35
36 /**
37  * Reads and processes the incoming data. This method will be called
38  * each time when data is available. Because this depends on the
39  * underlying tcp protocol, it is not predictable how often and
40  * when this method will be call. Furthermore the call of this
41  * method is independent of the received data size. The data handler
42  * is responsible to extract the application specific data packages
43  * (like HTTP request or SMTP commands) based on the received data.
44  * Calling a read method on the given connection instance like
45  * connection.readLong() or connection.readStringByDelimiter(…)
46  * will throw a <code>BufferUnderflowException</code> exception
47  * if the required data isn’t available . <br><br>
48  *
49  * <pre>
50  * public final class MyHandler implements IDataHandler, IConnectionScoped {
51  * ...
52  * public boolean onData(INonBlockingConnection connection) throws IOException, BufferUnderflowException, MaxReadSizeExceededException {
53  * ...
54  * // BufferUnderflowException will been thrown if delimiter hasn't been found.
55  * // A MaxReadSizeExceededException will be thrown if the max read size has been exceeded. Unhandling this exception causes
56  * // that the server closes the underlying connection
57  * String command = connection.readStringByDelimiter("\r\n", "US-ASCII", 5000);
58  * ...
59  * connection.write(resonse, "US-ASCII");
60  * return true;
61  * }
62  * }
63  * </pre>
64  *
65  * @author grro@xsocket.org
66  */
67 public interface IDataHandler extends IHandler {
68     
69     /**
70      * processes the incomming data based on the given connection. <br><br>
71      *
72      * Please note, that the <code>onData</code> callback method could also be called
73      * for an already closed connection. This occurs when data has been received
74      * (and buffered internally) and the connection has been closed by the peer,
75      * immediately. In this case the <oce>isOpen</code> call within the <code>onData</code>
76      * Method will return false. Reading of already received data wouldn't fail.
77      * To detect if a connection has been closed the callback method <code>onDisconnect</code>
78      * should be implemented. The correct callback order will be managed by the xSocket.
79      *
80      * @param connection the underlying connection
81      * @return true for positive result of handling, false for negative result of handling.
82      * The return value will be used by the {@link HandlerChain} to interrupted
83      * the chaining (if result is true)
84      * @throws IOException If some other I/O error occurs. Throwing this exception causes that the underlying connection will be closed.
85      * @throws BufferUnderflowException if more incoming data is required to process. The BufferUnderflowException will be swallowed by the framework
86      * @throws MaxReadSizeExceededException if the max read size has been reached (e.g. by calling method {@link INonBlockingConnection#readStringByDelimiter(String, int)}).
87      * Throwing this exception causes that the underlying connection will be closed.
88      */
89     public boolean onData(INonBlockingConnection connection) throws IOException JavaDoc, BufferUnderflowException JavaDoc, MaxReadSizeExceededException;
90 }
91
Popular Tags