1 \documentclass[twocolumn,a4paper]{article} % -*- latex -*-
5 {\tt http://www.complang.tuwien.ac.at/\char'176schani/}
7 \title{\texttt{java.net} in Cacao}
9 \newcommand{\globvarslabel}[1]{\mbox{\texttt{#1}}\hfil}
10 \newenvironment{globvars}
12 {\renewcommand{\makelabel}{\globvarslabel}%
17 \newcommand{\structdesclabel}[1]{\mbox{\texttt{#1}}\hfil}
18 \newenvironment{structdesc}
20 {\renewcommand{\makelabel}{\structdesclabel}%
25 \newcommand{\class}[1]{\subsection{\texttt{#1}}}
26 \newcommand{\method}[1]{\subsubsection*{\texttt{#1}}}
34 The \texttt{java.net} package provides an API for accessing the TCP/IP
35 protocol stack in Java 1.2.
37 \section{Native Methods}
39 Native method implementations reside in the directory
40 \texttt{native}. The classes in \texttt{java.net} requiring native
41 functions are: \texttt{DatagramPacket}, \texttt{InetAddress},
42 \texttt{InetAddressImpl}, \texttt{PlainDatagramSocketImpl},
43 \texttt{PlainSocketImpl}, \texttt{SocketInputStream} and
44 \texttt{SocketOutputStream}.
46 The implementation of the native methods uses the BSD Sockets API. For
47 a thorough description, see~\cite{stevens1}.
49 \textbf{Note:} Due to SUN Java 1.2's way of initializing native
50 libraries (it assumes they are available as shared libraries, searches
51 for them and fails initialization if they are not found) and the fact
52 that Cacao does not (yet?) support native methods through shared
53 libraries but instead links them statically, there must be a file
54 \texttt{/tmp/dummy} existent in order for \texttt{java.net} to work.
58 Since Cacao does not use native threads to implement Java threads, the
59 standard socket system calls can not be used directly since they
60 prevent thread switching. Therefore, we use the method for I/O
61 described in the Threads document.
63 \section{Native Methods}
65 All IP addresses passed over the native interface are in network byte
74 \class{InetAddressImpl}
76 \method{getHostByAddr}
78 Returns as a \texttt{String} the name of the host with the given IP
79 address. If the address cannot be resolved, raises an
80 \texttt{UnknowHostException}.
82 \method{getInetFamily}
84 Returns \texttt{AF\_INET}.
86 \method{getLocalHostName}
88 Returns as a \texttt{String} the name of the local host as determined
89 by \texttt{gethostname()} or, if that fails, returns
92 \method{lookupAllHostAddr}
94 Looks up all IP addresses of the given host name and returns them as
95 an array of byte arrays of length 4. The array has as many elements as
96 there are addresses. The index \texttt{[1][3]} contains the least
97 significant byte of the second address, for example. If the host name
98 cannot be resolved, raises an \texttt{UnknowHostException}.
100 \method{makeAnyLocalAddress}
102 Fills in the \texttt{address} and \texttt{family} instance variables
103 of \texttt{this} with the values \texttt{INADDR\_ANY} and
104 \texttt{AF\_INET}, respectively.
106 \class{DatagramPacket}
112 \class{PlainDatagramSocketImpl}
116 Binds the socket to the given port and IP address. Raises a
117 \texttt{SocketException} on failure.
119 \method{datagramSocketClose}
121 If the file descriptor of the socket is not \texttt{-1}, calls
122 \texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
123 fails, raises a \texttt{SocketException}.
125 \method{datagramSocketCreate}
127 Creates a new datagram socket and sets the file descriptor instance
128 variable to it. If creation fails, raises a \texttt{SocketException}.
132 Calls \texttt{getTimeToLive}.
134 \method{getTimeToLive}
136 Returns the time-to-live of the socket, as determined by
137 \texttt{getsockopt()}. If that fails, raises an \texttt{IOException}.
145 Adds membership of the multicast group with the given IP address.
149 Drops membership of the multicast group with the given IP address.
153 Sets the given \texttt{InetAddress}'s \texttt{address} instance
154 variable to the sender address of the next to be \texttt{receive}d
155 datagram packet and returns its length, possibly blocking the thread.
156 In case of failure, raises a \texttt{SocketException}.
160 Copies the next datagram packet into the \texttt{data} instance
161 variable of the \texttt{buf} instance variable of the given
162 packet. The length of this array is read from the \texttt{length}
163 instance variable of the packet. The length of the packet, the source
164 port and source IP address are copied into the \texttt{length},
165 \texttt{port} and \texttt{address} instance variables of the given
166 packet, respectively. May block the thread. Raises a
167 \texttt{SocketException} in case of failure.
171 Sends the given datagram packet. Raises a \texttt{SocketException} in
172 case of failure. May block the thread.
176 Calls \texttt{setTimeToLive}.
178 \method{setTimeToLive}
180 Sets the time-to-live of the socket to the given value using
181 \texttt{setsockopt()}. Raises an \texttt{IOException} in case of
184 \method{socketGetOption}
186 Determines one of the following socket options:
189 \begin{tabular}{|l|p{5cm}|} \hline
190 Value & Description \\ \hline
191 \texttt{0x1001} & Send buffer size \\
192 \texttt{0x1001} & Receive buffer size \\
193 \texttt{0x0010} & Interface for outgoing multicast packets as IP address \\
194 \texttt{0x000f} & IP address the socket is bound to \\ \hline
198 Returns the value of the option as a Java \texttt{int}, or raises a
199 \texttt{SocketException} in case of failure.
201 \method{socketSetOption}
203 Sets one of the following socket options:
206 \begin{tabular}{|l|p{3cm}|l|} \hline
207 Value & Description & Java type \\ \hline
208 \texttt{0x0004} & \texttt{SO\_REUSEADDR}, see~\cite{stevens1}, pages~194ff & \texttt{Integer} \\
209 \texttt{0x1001} & Send buffer size & \texttt{Integer} \\
210 \texttt{0x1001} & Receive buffer size & \texttt{Integer} \\
211 \texttt{0x0010} & Interface for outgoing multicast packets & \texttt{InetAddress} \\ \hline
215 The value to be set must be passed to the native method as a Java
216 object of the class specified in the table above. Raises a
217 \texttt{SocketException} in case of failure.
219 \class{PlainSocketImpl}
225 \method{socketAccept}
227 Calls \texttt{accept()} on the socket in \texttt{this} with the port
228 and address from the \texttt{localport} and \texttt{address} instance
229 variables of the first non-implicit parameter (a
230 \texttt{SocketImpl}). If successful, sets the socket of the
231 \texttt{SocketImpl} to the new socket, determines the address and port
232 of the peer and copies those into the \texttt{address} and
233 \texttt{port} instance variables of the \texttt{SocketImpl},
234 respectively. In case of failure (whether with \texttt{accept()} or
235 \texttt{getpeername()}), raises an \texttt{IOException}.
237 \method{socketAvailable}
239 Returns the number of bytes that can be read without blocking or
240 raises an \texttt{IOException} in case of failure.
244 Sets the \texttt{SO\_REUSEADDR} option on the socket and binds it to
245 the given address and port. Copies the address and the port bound to
246 into the \texttt{address} and \texttt{localport} instance variables of
247 \texttt{this}, respectively. In case of failure raises an
248 \texttt{IOException}.
252 If the file descriptor of the socket is not \texttt{-1}, calls
253 \texttt{close()} on it and sets it to \texttt{-1}. If \texttt{close()}
254 fails, raises a \texttt{IOException}.
256 \method{socketConnect}
258 Connects the socket to the given address and port. Copies the address,
259 the port and the new local port into the \texttt{address},
260 \texttt{port} and \texttt{localport} instance variables of this,
263 \method{socketCreate}
265 Creates a new stream socket if the \texttt{bool} parameter is
266 \texttt{true}, otherwise a datagram socket and sets the file
267 descriptor instance variable to it. If creation fails, raises an
268 \texttt{IOException}.
270 \method{socketGetOption}
272 Determines one of the following socket options:
275 \begin{tabular}{|l|p{5cm}|} \hline
276 Value & Description \\ \hline
277 \texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
278 If \texttt{l\_onoff} is \texttt{0}, returns \texttt{-1},
279 otherwise the value of \texttt{l\_linger}. \\
280 \texttt{0x0001} & Nagle algorithm disabled? \\
281 \texttt{0x1001} & Send buffer size \\
282 \texttt{0x1001} & Receive buffer size \\
283 \texttt{0x000f} & IP address the socket is bound to \\ \hline
287 Returns the value of the option as a Java \texttt{int}, or raises a
288 \texttt{SocketException} in case of failure.
290 \method{socketListen}
292 Calls \texttt{listen()} on the socket with the given backlog
293 parameter. Raises an \texttt{IOException} in case of failure.
295 \method{socketSetOption}
297 Sets one of the following socket options:
300 \begin{tabular}{|l|p{3cm}|l|} \hline
301 Value & Description & Java type \\ \hline
302 \texttt{0x0080} & \texttt{SO\_LINGER}, see~\cite{stevens1}, pages~187ff.
303 If the \texttt{bool} parameter is \texttt{true}, sets
304 \texttt{l\_onoff} to \texttt{1} and \texttt{l\_linger}
305 to the given value. Otherwise, sets \texttt{l\_onoff} to \texttt{0}. & \texttt{Integer} \\
306 \texttt{0x0001} & Disable Nagle algorithm? Uses only the \texttt{bool} parameter. & n/a \\
307 \texttt{0x1001} & Send buffer size & \texttt{Integer} \\
308 \texttt{0x1001} & Receive buffer size & \texttt{Integer} \\ \hline
312 The value to be set must be passed to the native method as a Java
313 object of the class specified in the table above. Raises a
314 \texttt{SocketException} in case of failure.
316 \class{SocketInputStream}
324 Receives at most the given number of bytes into the given array
325 beginning at the given offset. Returns the number of bytes read or
326 \texttt{-1} in case of EOF. May block the thread. Raises an
327 \texttt{IOException} in case of failure.
329 \class{SocketOutputStream}
337 Sends exactly the given number of butes from the given array beginning
338 at the given offset. May block the thread. In case of failure, returns
339 \texttt{IOException}.
342 \bibliographystyle{plain}