KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > org > xsocket > datagram > IEndpoint


1 // $Id: IEndpoint.java 1545 2007-07-23 05:32:48Z 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.datagram;
23
24
25 import java.io.Closeable JavaDoc;
26 import java.io.IOException JavaDoc;
27 import java.net.InetAddress JavaDoc;
28 import java.net.SocketAddress JavaDoc;
29 import java.net.SocketTimeoutException JavaDoc;
30 import java.util.Map JavaDoc;
31
32
33 import org.xsocket.ClosedConnectionException;
34 import org.xsocket.IWorkerPool;
35
36
37
38 /**
39  * An endpoint, which can be used to send and receive {@link UserDatagram}. E.g.
40  *
41  * <pre>
42  *
43  * // without datagram handler
44  * ...
45  * IEndpoint endpoint = new Endpoint(packageSize);
46  *
47  * UserDatagram request = new UserDatagram(remoteHostname, remotePort, packageSize);
48  * request.write("Hello peer, how are you?");
49  *
50  * endpoint.send(request);
51  * UserDatagram response = endpoint.receive(1000); // receive (timeout 1 sec)
52  *
53  * endpoint.close();
54  * ...
55  *
56  *
57  * // by using a handler
58  * ...
59  * MyHandler hdl = new MyHandler();
60  * IEndpoint endpoint = new Endpoint(packageSize, hdl);
61  *
62  * UserDatagram request = new UserDatagram(remoteHostname, remotePort, packageSize);
63  * request.write("Hello peer, how are you?");
64  *
65  * endpoint.send(request);
66  * // response will be handled by MyHandler
67  *
68  * // wait
69  * ...
70  * endpoint.close();
71  *
72  *
73  * class MyHandler implements IDatagramHandler {
74  *
75  * public boolean onDatagram(IEndpoint localEndpoint) throws IOException {
76  * UserDatagram datagram = localEndpoint.receive(); // get the datagram
77  * ...
78  * return true;
79  * }
80  * }
81  * </pre>
82  *
83  * @author grro@xsocket.org
84  */
85 public interface IEndpoint extends Closeable JavaDoc {
86     
87     public static final String JavaDoc SO_SNDBUF = "SOL_SOCKET.SO_SNDBUF";
88     public static final String JavaDoc SO_RCVBUF = "SOL_SOCKET.SO_RCVBUF";
89     public static final String JavaDoc SO_REUSEADDR = "SOL_SOCKET.SO_REUSEADDR";
90     public static final String JavaDoc SO_BROADCAST = "SOL_SOCKET.SO_BROADCAST";
91     public static final String JavaDoc IP_TOS = "IPPROTO_IP.IP_TOS";
92     public static final String JavaDoc IP_MULTICAST_TTL = "IPPROTO_IP.IP_MULTICAST_TTL";
93     public static final String JavaDoc IP_MULTICAST_LOOP = "IPPROTO_IP.IP_MULTICAST_LOOP";
94     
95     
96     /**
97      * returns, if the endpoint is open
98      *
99      *
100      * @return true if the endpoint is open
101      */
102     public boolean isOpen();
103
104     
105
106     
107     
108     /**
109      * returns the socket address of the endpoint
110      *
111      * @return the socket address
112      */
113     public SocketAddress JavaDoc getLocalSocketAddress();
114     
115     
116     /**
117      * returns the address of the endpoint
118      *
119      * @return the address
120      */
121     public InetAddress JavaDoc getLocalAddress();
122     
123     
124     /**
125      * returns the port of the endpoint
126      *
127      * @return the port
128      */
129     public int getLocalPort();
130
131     
132     /**
133      * sets the default encoding used by this endpoint
134      *
135      * @param encoding the default encoding
136      */
137     public void setDefaultEncoding(String JavaDoc encoding);
138     
139     
140     /**
141      * gets the default encoding used by this endpoint
142      *
143      * @return the default encoding
144      */
145     public String JavaDoc getDefaultEncoding();
146     
147     
148     /**
149      * send a datagram to the remote endpoint
150      *
151      * @param datagram the datagram to send
152      * @throws IOException If some other I/O error occurs
153      * @throws ClosedConnectionException if the underlying channel is closed
154      */
155     public void send(UserDatagram datagram) throws IOException JavaDoc;
156
157     
158     /**
159      * set the size of the datagram that will be received
160      *
161      * @param receiveSize the receive size
162      */
163     public void setReceiveSize(int receiveSize);
164
165
166     /**
167      * get the size of the datagram that will be received
168      * @return the receive size
169      */
170     public int getReceiveSize();
171     
172     
173     /**
174      * receive a datagram packet (receive timeout = 0)
175      *
176      * @return the received datagram packet or null if no datagram is available
177      * @throws IOException If some other I/O error occurs
178      */
179     public UserDatagram receive() throws IOException JavaDoc;
180
181     
182     
183     /**
184      * receive a datagram packet
185      *
186      * @param timeoutMillis the receive timeout in millis
187      * @return the received datagram packet
188      * @throws SocketTimeoutException If the receive timeout has been reached
189      * @throws IOException If some other I/O error occurs
190      */
191     public UserDatagram receive(long timeoutMillis) throws IOException JavaDoc, SocketTimeoutException JavaDoc;
192     
193     
194
195     /**
196      * @deprecated
197      */
198     public void setWorkerPool(IWorkerPool workerPool);
199     
200
201     
202     /**
203      * return the endpoint id
204      * @return the endpoint id
205      */
206     public String JavaDoc getId();
207     
208         
209     
210     /**
211      * returns the vlaue of a option
212      *
213      * @param name the name of the option
214      * @return the value of the option
215      * @throws IOException In an I/O error occurs
216      */
217     public Object JavaDoc getOption(String JavaDoc name) throws IOException JavaDoc;
218     
219     
220     
221     /**
222      * Returns an unmodifiable map of the options supported by this endpont.
223      *
224      * The key in the returned map is the name of a option, and its value
225      * is the type of the option value. The returned map will never contain null keys or values.
226      *
227      * @return An unmodifiable map of the options supported by this channel
228      */
229     public Map JavaDoc<String JavaDoc,Class JavaDoc> getOptions();
230 }
231
Popular Tags